ストーリー

非構造化ログ vs 構造化ログ

比較

// 非構造化ログ（アンチパターン）
console.log('Error: Payment failed for order 12345, amount 5000, user abc');
console.log(`[${new Date().toISOString()}] WARN: Retry attempt 3/5 for payment`);
console.error('Database connection timeout after 30s');

// 構造化ログ（推奨）
logger.error('Payment processing failed', {
  orderId: '12345',
  amount: 5000,
  currency: 'JPY',
  userId: 'abc',
  errorCode: 'PAYMENT_TIMEOUT',
  provider: 'stripe',
  traceId: 'abc-123-def-456',
  spanId: 'span-789',
});

構造化ログの実装

ロガーライブラリの設定

import pino from 'pino';

// ロガーの初期化
const logger = pino({
  level: process.env.LOG_LEVEL ?? 'info',
  formatters: {
    level: (label) => ({ level: label }),
    bindings: (bindings) => ({
      service: 'payment-service',
      version: process.env.APP_VERSION ?? 'unknown',
      environment: process.env.NODE_ENV ?? 'development',
      hostname: bindings.hostname,
      pid: bindings.pid,
    }),
  },
  timestamp: pino.stdTimeFunctions.isoTime,
  // 本番ではJSON、開発では整形表示
  transport: process.env.NODE_ENV === 'development'
    ? { target: 'pino-pretty' }
    : undefined,
});

// 出力例（本番JSON）:
// {
//   "level": "error",
//   "time": "2026-02-14T10:30:00.000Z",
//   "service": "payment-service",
//   "version": "1.2.0",
//   "environment": "production",
//   "hostname": "payment-pod-abc123",
//   "pid": 1,
//   "msg": "Payment processing failed",
//   "orderId": "12345",
//   "traceId": "abc-123-def-456"
// }

ログレベルの使い分け

Trace IDとの相関

import { context, trace } from '@opentelemetry/api';

// OpenTelemetryのTrace IDをログに自動付与するミドルウェア
function traceContextMiddleware(req: Request, res: Response, next: NextFunction): void {
  const activeSpan = trace.getSpan(context.active());
  const spanContext = activeSpan?.spanContext();

  // リクエストスコープのロガーを作成
  req.log = logger.child({
    traceId: spanContext?.traceId ?? 'no-trace',
    spanId: spanContext?.spanId ?? 'no-span',
    requestId: req.headers['x-request-id'] ?? crypto.randomUUID(),
    method: req.method,
    path: req.path,
    userAgent: req.headers['user-agent'],
  });

  req.log.info('Request started');

  res.on('finish', () => {
    req.log.info('Request completed', {
      statusCode: res.statusCode,
      responseTime: Date.now() - req.startTime,
    });
  });

  next();
}

ログ集約基盤

ELK Stack vs Grafana Loki

Loki設定例

# loki-config.yaml
auth_enabled: false

server:
  http_listen_port: 3100

common:
  path_prefix: /loki
  storage:
    s3:
      endpoint: s3.amazonaws.com
      bucketnames: loki-logs
      region: ap-northeast-1

schema_config:
  configs:
    - from: 2024-01-01
      store: tsdb
      object_store: s3
      schema: v13
      index:
        prefix: loki_index_
        period: 24h

limits_config:
  retention_period: 30d
  max_query_length: 24h
  max_entries_limit_per_query: 10000

# ログパイプラインでの加工
ruler:
  alertmanager_url: http://alertmanager:9093

LogQL（Lokiのクエリ言語）

# 基本的なログ検索
{service="payment-service"} |= "error"

# JSONパース + フィルタ
{service="payment-service"}
  | json
  | level = "error"
  | orderId != ""
  | line_format "{{.orderId}}: {{.msg}}"

# エラー率の計算（メトリクスクエリ）
sum(rate(
  {service="payment-service"} | json | level = "error" [5m]
))
/
sum(rate(
  {service="payment-service"} [5m]
))

# 特定のTrace IDに関連するログ
{service=~".*"} | json | traceId = "abc-123-def-456"

# 遅いリクエストのログ
{service="payment-service"}
  | json
  | responseTime > 3000
  | line_format "Slow request: {{.path}} took {{.responseTime}}ms"

ログ設計のベストプラクティス

ログに含めるべき情報

# 共通フィールド（全ログに含む）
common_fields:
  timestamp: "ISO 8601形式"
  level: "error/warn/info/debug"
  service: "サービス名"
  version: "アプリバージョン"
  environment: "production/staging/development"
  traceId: "OpenTelemetry Trace ID"
  spanId: "OpenTelemetry Span ID"
  requestId: "リクエスト固有ID"

# イベント固有フィールド
event_fields:
  http_request:
    - method
    - path
    - statusCode
    - responseTime
    - userAgent
    - clientIp
  payment:
    - orderId
    - amount
    - currency
    - provider
    - transactionId
  error:
    - errorCode
    - errorMessage
    - stackTrace

// 機密情報のマスキング例
function maskSensitiveData(data: Record<string, unknown>): Record<string, unknown> {
  const sensitiveFields = ['password', 'creditCard', 'ssn', 'token'];
  const masked = { ...data };

  for (const field of sensitiveFields) {
    if (field in masked) {
      masked[field] = '***MASKED***';
    }
  }

  return masked;
}

まとめ

チェックリスト

• 構造化ログと非構造化ログの違いを説明できる
• pinoを使った構造化ログの実装ができる
• Trace IDとログの相関付けを実装できる
• ELK/Lokiの特徴と選択基準を理解した
• LogQLで基本的なログ検索・集約クエリを記述できる

次のステップへ

次は「演習：オブザーバビリティ基盤を構築しよう」です。メトリクス、トレース、ログを統合したオブザーバビリティ基盤の設計と構築に挑戦しましょう。

推定読了時間: 40分