logging-best-practices

ロギングのベストプラクティス

アプリ全体で Pino を使用して、構造化ログを出力します。

前提条件

まず、次のセットアップ手順を完了してください。

• Pino ロギングのセットアップ

ロギング

@/lib/logging/logger から logger をインポートします。最初にコンテキストオブジェクト、次にメッセージを渡します。エラーの場合は、コンテキストオブジェクトに err を含めます。

import { logger } from "@/lib/logging/logger";

logger.info({ port: 3000 }, "Server started");
logger.warn({ endpoint: "/api/chat" }, "Rate limit reached");
logger.debug({ key: "user:123" }, "Cache miss");
logger.error({ err, userId: "123", endpoint: "/api/chat" }, "Request failed");

レベル

レベル	使用する場面
trace	詳細なデバッグ（使用頻度は低い）
debug	開発時のトラブルシューティング
info	通常の操作、ビジネスイベント
warn	復旧可能な問題、非推奨に関する警告
error	対応が必要な障害
fatal	致命的な障害、アプリを継続できない場合

有効なログレベルのしきい値は LOG_LEVEL で設定します（デフォルトは info）。本番環境では warn を使用してください。

LOG_LEVEL="debug"

API ルート内

終了時に、タイミングのコンテキストを付けてログを出力します。

import { logger } from "@/lib/logging/logger";

export async function POST(request: Request) {
  const start = Date.now();
  try {
    const result = await processRequest(request);
    logger.info(
      { duration: Date.now() - start, status: 200 },
      "Request completed",
    );
    return Response.json(result);
  } catch (err) {
    logger.error({ err, duration: Date.now() - start }, "Request failed");
    return Response.json({ error: "Internal error" }, { status: 500 });
  }
}

ワークフロー内

ワークフローのランタイムでは Node モジュールをインポートできないため、ロガーを直接呼び出すことはできません。"use step" 関数でラップしてください。

// src/workflows/chat/steps/logger.ts
import { logger } from "@/lib/logging/logger";

export async function log(
  level: "info" | "warn" | "error" | "debug",
  message: string,
  data?: Record<string, unknown>,
): Promise<void> {
  "use step";

  if (data) {
    logger[level](data, message);
  } else {
    logger[level](message);
  }
}

import { log } from "./steps/logger";

export async function chatWorkflow({ chatId }) {
  "use workflow";

  await log("info", "Workflow started", { chatId });
}

---

参考資料

• Pino ドキュメント
• Pino のログレベル