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

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レベル - 最も詳細');
nodeblocksLogger.debug('Debugレベル - 開発情報');
nodeblocksLogger.info('Infoレベル - 一般情報');
nodeblocksLogger.warn('Warnレベル - 警告');
nodeblocksLogger.error('Errorレベル - エラー');
nodeblocksLogger.fatal('Fatalレベル - 致命的エラー');

---

🌐 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 Type

ロガー統合のためのTypeScript型：

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

const { Logger } = primitives;

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');

---

🔗 関連項目

• ハンドラーコンポーネント - ハンドラーでのロガー使用
• エラーハンドリング - エラーロギングパターン