テレメトリ

テレメトリとは

テレメトリ (Telemetry) は、システムの状態をメトリクス、ログ、トレースの 3 本柱 (Three Pillars of Observability) で収集 / 送信する仕組みである。計測する側 (アプリケーション) と受け取る側 (監視サービス) の間で作法を決めておかないと、監視サービスを乗り換えるたびに計装コードを書き直すことになる。この境界を仕様として切り出したのが OpenTelemetry で、公式サイトの記載では CNCF のガバナンスの下で仕様と各言語の SDK が開発されている。仕様の成熟度や導入手順は OpenTelemetry の項に譲る。

3 本柱

3 つは並列に見えるが、実務で差が出るのは種類の数ではなく粒度とコストである。メトリクスは集計済みの数値なので長く安く持てて異常の検知に向く。ログは 1 件ずつの事実なので原因の特定に効くが量が増える。トレースは 1 リクエストが通った経路を時間軸に並べたもので、どの処理で待たされたかを示す。検知はメトリクス、経路の絞り込みはトレース、確定はログという順に降りるのが基本形だ。

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

OpenTelemetry

計装のコードは、処理を span という単位で囲み、その span に属性と結果を付ける形になる。span を閉じ忘れると終わらないまま残るので、finally で必ず end を呼ぶのが定型だ。結果は生の数値ではなく列挙値 (SpanStatusCode) で表し、既定が UNSET、成功を明示するときが OK、失敗が ERROR である。

import { trace, SpanStatusCode } 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: SpanStatusCode.OK });
    return result;
  } catch (e) {
    span.setStatus({ code: SpanStatusCode.ERROR, message: String(e) });
    throw e;
  } finally {
    span.end();
  }
}

カスタムメトリクス

メトリクスは 3 本柱のうち最も安く長く保持できるので、業務上の意味を持つ数値 (注文が通った件数、決済が失敗した回数) を自分で送っておくと効く。ディメンションには後から切り分けたい軸だけを入れる。

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

const cw = new 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(),
}));