バージョン: 0.9.0 (最新)

📝 ロギングユーティリティ

Nodeblocks SDKは、構造化ロギング用にPinoを使用した事前設定済みのロギングセットアップを提供します。これらのユーティリティは、きれいなフォーマットとHTTPリクエスト/レスポンスロギングで、アプリケーション全体で一貫したロギングを提供します。

🎯 概要

ロギングユーティリティは、高性能なNode.jsロガーであるPinoを使用した標準化されたロギングセットアップを提供します。開発用のきれいなフォーマットと、デプロイ用の本番対応ロギングを備えた構造化ロギングを提供します。

主な機能

事前設定済みロガー: きれいなフォーマット付きのすぐに使えるPinoロガー
HTTPロギング: 自動リクエスト/レスポンスロギングミドルウェア
構造化ロギング: 簡単な解析のためのJSONベースのロギング
パフォーマンス: 最小限のオーバーヘッドで高性能なロギング
TypeScriptサポート: ロガー統合の完全な型安全性

📝 基本的なロギング

`nodeblocksLogger`

きれいなフォーマットとカラー出力付きの事前設定済みPinoロガー。

import { utils } from '@nodeblocks/backend-sdk';

const { nodeblocksLogger } = utils;

// 基本的なロギング
nodeblocksLogger.info('Application started');
nodeblocksLogger.warn('Deprecated feature used');
nodeblocksLogger.error('An error occurred', { error: 'details' });

// 構造化ロギング
nodeblocksLogger.info({
  message: 'User created',
  userId: 'user-123',
  timestamp: new Date().toISOString()
});

ログレベル

import { utils } from '@nodeblocks/backend-sdk';

const { nodeblocksLogger } = utils;

// 利用可能なログレベル
nodeblocksLogger.trace('Trace level - most detailed');
nodeblocksLogger.debug('Debug level - development info');
nodeblocksLogger.info('Info level - general information');
nodeblocksLogger.warn('Warn level - warnings');
nodeblocksLogger.error('Error level - errors');
nodeblocksLogger.fatal('Fatal level - critical errors');

🌐 HTTPロギング

`nodeblocksHTTPLogger`

Expressアプリケーション用のHTTPリクエスト/レスポンスロギングミドルウェア。

import express from 'express';
import { utils } from '@nodeblocks/backend-sdk';

const { nodeblocksHTTPLogger } = utils;

const app = express();

// HTTPロギングミドルウェアを追加
app.use(nodeblocksHTTPLogger);

// ルート
app.get('/api/users', (req, res) => {
  res.json({ users: [] });
});

HTTPログ出力

HTTPロガーは自動的に以下をログに記録します：

リクエスト詳細: メソッド、URL、ヘッダー、ボディ
レスポンス詳細: ステータスコード、レスポンス時間
パフォーマンスメトリクス: リクエスト期間
エラー情報: リクエストが失敗した場合のエラー詳細

出力例:

{
  "req": {
    "id": "req-1",
    "method": "GET",
    "url": "/api/users",
    "headers": {
      "user-agent": "Mozilla/5.0...",
      "accept": "application/json"
    }
  },
  "res": {
    "statusCode": 200,
    "responseTime": 45
  },
  "msg": "request completed"
}

🔧 高度な使用法

カスタムロガー設定

import pino from 'pino';
import { utils } from '@nodeblocks/backend-sdk';

const { nodeblocksLogger } = utils;

// デフォルトロガーを拡張
const customLogger = nodeblocksLogger.child({
  service: 'user-service',
  version: '1.0.0'
});

// カスタムロガーを使用
customLogger.info('Service started', { 
  port: 3000, 
  environment: process.env.NODE_ENV 
});

ハンドラーでのロガー

import { utils } from '@nodeblocks/backend-sdk';

const { nodeblocksLogger } = utils;

const createUserHandler = async (payload: RouteHandlerPayload) => {
  const { params, logger } = payload;
  
  // ペイロードからロガーを使用するか、デフォルトにフォールバック
  const log = logger || nodeblocksLogger;
  
  log.info('Creating user', { 
    email: params.requestBody?.email,
    timestamp: new Date().toISOString()
  });
  
  try {
    // ハンドラーロジック
    const user = await createUser(params.requestBody);
    
    log.info('User created successfully', { 
      userId: user.id,
      email: user.email 
    });
    
    return ok(mergeData(payload, { user }));
  } catch (error) {
    log.error('Failed to create user', { 
      error: error.message,
      email: params.requestBody?.email 
    });
    
    throw error;
  }
};

条件付きロギング

import { utils } from '@nodeblocks/backend-sdk';

const { nodeblocksLogger } = utils;

const getConditionalLogger = (isDevelopment: boolean) => {
  if (isDevelopment) {
    return nodeblocksLogger.child({ level: 'debug' });
  }
  return nodeblocksLogger.child({ level: 'info' });
};

// 使用
const logger = getConditionalLogger(process.env.NODE_ENV === 'development');
logger.debug('Debug info only in development');

パフォーマンスロギング

import { utils } from '@nodeblocks/backend-sdk';

const { nodeblocksLogger } = utils;

const performanceHandler = async (payload: RouteHandlerPayload) => {
  const startTime = Date.now();
  const log = payload.logger || nodeblocksLogger;
  
  log.info('Starting performance-critical operation');
  
  try {
    // 高コストな操作
    const result = await expensiveOperation();
    
    const duration = Date.now() - startTime;
    log.info('Operation completed', { 
      duration,
      resultSize: result.length 
    });
    
    return ok(mergeData(payload, { result }));
  } catch (error) {
    const duration = Date.now() - startTime;
    log.error('Operation failed', { 
      duration,
      error: error.message 
    });
    
    throw error;
  }
};

📊 ロガー設定

デフォルト設定

nodeblocksLoggerは以下の設定で事前設定されています：

{
  enabled: true,
  level: 'trace',
  transport: {
    options: {
      colorize: true,
      singleLine: false,
      translateTime: 'SYS:standard',
    },
    target: 'pino-pretty',
  },
}

環境固有の設定

import pino from 'pino';

const getLoggerConfig = () => {
  const isDevelopment = process.env.NODE_ENV === 'development';
  
  if (isDevelopment) {
    return {
      level: 'debug',
      transport: {
        target: 'pino-pretty',
        options: {
          colorize: true,
          translateTime: 'SYS:standard',
        }
      }
    };
  }
  
  return {
    level: 'info',
    // 本番環境: きれいなフォーマットなし、構造化JSON
  };
};

const customLogger = pino(getLoggerConfig());

🔗 ロガー型

`Logger`型

ロガー統合用のTypeScript型：

import { utils } from '@nodeblocks/backend-sdk';

const { Logger } = utils;

const useLogger = (logger: Logger) => {
  logger.info('Using typed logger');
  logger.error('Error with logger', { error: 'details' });
};

// 使用
useLogger(nodeblocksLogger);

ペイロード内のロガー

ハンドラーはペイロード内でロガーを受け取ります：

interface RouteHandlerPayload {
  // ... その他のプロパティ
  logger?: Logger;
}

️📐 ベストプラクティス

1. 構造化ロギング

// ✅ 良い: コンテキスト付きの構造化ロギング
nodeblocksLogger.info({
  message: 'User action performed',
  userId: 'user-123',
  action: 'login',
  timestamp: new Date().toISOString(),
  metadata: { ip: '192.168.1.1' }
});

// ❌ 避ける: シンプルな文字列ロギング
nodeblocksLogger.info('User logged in'); // コンテキストが欠落

2. エラーロギング

// ✅ 良い: 包括的なエラーロギング
try {
  await riskyOperation();
} catch (error) {
  nodeblocksLogger.error({
    message: 'Operation failed',
    error: error.message,
    stack: error.stack,
    context: { userId: 'user-123' }
  });
  throw error;
}

// ❌ 避ける: 最小限のエラーロギング
try {
  await riskyOperation();
} catch (error) {
  nodeblocksLogger.error('Error'); // 詳細が欠落
}

3. パフォーマンスロギング

// ✅ 良い: パフォーマンス監視
const startTime = Date.now();
const result = await expensiveOperation();
const duration = Date.now() - startTime;

nodeblocksLogger.info({
  message: 'Operation completed',
  duration,
  resultSize: result.length,
  operation: 'expensiveOperation'
});

4. 条件付きロギング

// ✅ 良い: 環境を意識したロギング
const logLevel = process.env.NODE_ENV === 'development' ? 'debug' : 'info';
const logger = nodeblocksLogger.child({ level: logLevel });

logger.debug('Debug info only in development');
logger.info('Info in all environments');

🔗 関連項目

Handler Component - ハンドラーでのロガーの使用
Error Handling - エラーロギングパターン

🎯 概要​

主な機能​

📝 基本的なロギング​

nodeblocksLogger​

ログレベル​

🌐 HTTPロギング​

nodeblocksHTTPLogger​

HTTPログ出力​

🔧 高度な使用法​

カスタムロガー設定​

ハンドラーでのロガー​

条件付きロギング​

パフォーマンスロギング​

📊 ロガー設定​

デフォルト設定​

環境固有の設定​

🔗 ロガー型​

Logger型​

ペイロード内のロガー​

️📐 ベストプラクティス​

1. 構造化ロギング​

2. エラーロギング​

3. パフォーマンスロギング​

4. 条件付きロギング​

🔗 関連項目​