IT 技書の森

テレメトリ

システムの状態をメトリクス、ログ、トレースの 3 本柱で収集・送信する仕組み

オブザーバビリティ運用

テレメトリとは

テレメトリ (Telemetry) は、システムの状態をメトリクス、ログ、トレースの 3 本柱 (Three Pillars of Observability) で収集・送信する仕組みである。OpenTelemetry が業界標準。

3 本柱

柱 説明 AWS サービス
メトリクス 数値データ (CPU, レイテンシ, エラー率) CloudWatch Metrics
ログ イベントの記録 CloudWatch Logs
トレース リクエストの経路追跡 X-Ray

OpenTelemetry

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

const tracer = trace.getTracer('my-service');

export async function handleRequest(event: any) {
  const span = tracer.startSpan('handleRequest');
  try {
    span.setAttribute('user.id', event.userId);
    const result = await processOrder(event);
    span.setStatus({ code: 0 }); // OK
    return result;
  } catch (e) {
    span.setStatus({ code: 2, message: String(e) }); // ERROR
    throw e;
  } finally {
    span.end();
  }
}

カスタムメトリクス

import { CloudWatch } from '@aws-sdk/client-cloudwatch';

await cw.putMetricData({
  Namespace: 'MyApp',
  MetricData: [{
    MetricName: 'OrderProcessed',
    Value: 1,
    Unit: 'Count',
    Dimensions: [{ Name: 'Environment', Value: 'prod' }],
  }],
});

構造化ログ

// ❌ 非構造化ログ
console.log('Order processed: ' + orderId);

// ✅ 構造化ログ (JSON)
console.log(JSON.stringify({
  level: 'info',
  message: 'Order processed',
  orderId,
  duration: 150,
  timestamp: new Date().toISOString(),
}));

テレメトリの設計指針

メトリクスのディメンションにユーザー ID のような高カーディナリティの値を使うとコストが爆発するため注意する。全リクエストをトレースするとコスト増になるため、サンプリングを適用する。ログは JSON 形式で構造化し、相関 ID でログとトレースを紐付けて横断的に追跡できるようにする。

テレメトリの背景や設計思想は関連書籍に詳しい。

関連用語