テレメトリ

テレメトリとは

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

3 本柱

3 本柱を以下にまとめる。

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

OpenTelemetry

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' }],
  }],
});

構造化ログ

テレメトリの基盤となるログは、JSON 形式の構造化ログで出力する。フィールド単位でクエリ・集計が可能になり、CloudWatch Logs Insights でリクエスト ID やエラーコードを条件にした分析が行える。

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

テレメトリの設計指針

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

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