implementing-observability

OpenTelemetry による本番環境の可観測性

目的

2025年の業界標準である OpenTelemetry を使用して、本番環境に適した可観測性を実装します。3つの柱（メトリクス、ログ、トレース）、LGTM スタックのデプロイ、ログとトレースの重要な相関パターンについて説明します。

使用する場面

次の場合に使用します：

• パフォーマンスやエラーを可視化する必要がある本番システムを構築するとき
• 複数のサービスで構成される分散システムをデバッグするとき
• 監視、ログ記録、トレーシングのインフラを設定するとき
• トレースとの相関に対応した構造化ログを実装するとき
• 本番システム向けのアラートルールを設定するとき

次の場合は使用しないでください：

• 本番環境へのデプロイを伴わない概念実証を構築するとき
• システムのリクエスト数が 1 日あたり 100 件未満の場合（コンソールへのログ出力で十分なことがあります）

OpenTelemetry 標準（2025年）

OpenTelemetry は、可観測性を統一する CNCF の卒業プロジェクトです。

┌────────────────────────────────────────────────────────┐
│          OpenTelemetry: The Unified Standard           │
├────────────────────────────────────────────────────────┤
│                                                         │
│  ONE SDK for ALL signals:                              │
│  ├── Metrics (Prometheus-compatible)                   │
│  ├── Logs (structured, correlated)                     │
│  ├── Traces (distributed, standardized)                │
│  └── Context (propagates across services)              │
│                                                         │
│  Language SDKs:                                         │
│  ├── Python: opentelemetry-api, opentelemetry-sdk      │
│  ├── Rust: opentelemetry, tracing-opentelemetry        │
│  ├── Go: go.opentelemetry.io/otel                      │
│  └── TypeScript: @opentelemetry/api                    │
│                                                         │
│  Export to ANY backend:                                │
│  ├── LGTM Stack (Loki, Grafana, Tempo, Mimir)          │
│  ├── Prometheus + Jaeger                               │
│  ├── Datadog, New Relic, Honeycomb (SaaS)              │
│  └── Custom backends via OTLP protocol                 │
│                                                         │
└────────────────────────────────────────────────────────┘

Context7 リファレンス：/websites/opentelemetry_io（信頼度：高、スニペット：5,888、スコア：85.9）

可観測性の3つの柱

1. メトリクス（何が起きているか？）

時間の経過に伴うシステムの健全性とパフォーマンスを追跡します。

メトリクスの種類：カウンター（常に増加）、ゲージ（増減）、ヒストグラム（分布）、サマリー（パーセンタイル）。

簡単な例（Python）：

from opentelemetry import metrics

meter = metrics.get_meter(__name__)
http_requests = meter.create_counter("http.server.requests")
http_requests.add(1, {"method": "GET", "status": 200})

2. ログ（何が起きたか？）

コンテキストとともに個別のイベントを記録します。

重要：ログとトレースの相関のため、必ず trace_id と span_id を注入してください。

簡単な例（Python + structlog）：

import structlog
from opentelemetry import trace

logger = structlog.get_logger()
span = trace.get_current_span()
ctx = span.get_span_context()

logger.info(
    "processing_request",
    trace_id=format(ctx.trace_id, '032x'),
    span_id=format(ctx.span_id, '016x'),
    user_id=user_id
)

参照：完全な設定については references/structured-logging.md をご覧ください。

3. トレース（時間はどこにかかったか？）

分散サービスをまたぐリクエストの流れを追跡します。

主な概念：トレース（エンドツーエンドの処理経路）、スパン（個々の操作）、親子関係（ネストされた操作）。

簡単な例（Python + FastAPI）：

from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor

app = FastAPI()
FastAPIInstrumentor.instrument_app(app)  # Auto-traces all HTTP requests

参照：言語別の SDK インストール方法については references/opentelemetry-setup.md をご覧ください。

LGTM スタック（セルフホスト型の可観測性）

LGTM = Loki（ログ） + Grafana（可視化） + Tempo（トレース） + Mimir（メトリクス）

┌────────────────────────────────────────────────────────┐
│                  LGTM Architecture                      │
├────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────────────────────────────────────┐      │
│  │           Grafana Dashboard (Port 3000)      │      │
│  │  Unified UI for Logs, Metrics, Traces       │      │
│  └──────┬──────────────┬─────────────┬─────────┘      │
│         │              │             │                 │
│         ▼              ▼             ▼                 │
│  ┌──────────┐   ┌──────────┐  ┌──────────┐            │
│  │   Loki   │   │  Tempo   │  │  Mimir   │            │
│  │  (Logs)  │   │ (Traces) │  │(Metrics) │            │
│  │Port 3100 │   │Port 3200 │  │Port 9009 │            │
│  └────▲─────┘   └────▲─────┘  └────▲─────┘            │
│       │              │             │                   │
│       └──────────────┴─────────────┘                   │
│                      │                                 │
│              ┌───────▼────────┐                        │
│              │ Grafana Alloy  │                        │
│              │  (Collector)   │                        │
│              │  Port 4317/8   │ ← OTLP gRPC/HTTP       │
│              └───────▲────────┘                        │
│                      │                                 │
│         OpenTelemetry Instrumented Apps                │
│                                                         │
└────────────────────────────────────────────────────────┘

クイックスタート：examples/lgtm-docker-compose/docker-compose.yml を実行すると、完全な LGTM スタックを利用できます。

参照：本番環境へのデプロイ方法については references/lgtm-stack.md をご覧ください。

重要なパターン：ログとトレースの相関

問題：ログとトレースは別々のシステムに保存されています。エラーログを見つけても、関連するトレースを見つけられません。

解決策：すべてのログレコードに trace_id と span_id を注入します。

Python（structlog）

import structlog
from opentelemetry import trace

logger = structlog.get_logger()
span = trace.get_current_span()
ctx = span.get_span_context()

logger.info(
    "request_processed",
    trace_id=format(ctx.trace_id, '032x'),  # 32-char hex
    span_id=format(ctx.span_id, '016x'),    # 16-char hex
    user_id=user_id
)

Rust（tracing）

use tracing::{info, instrument};

#[instrument(fields(user_id = %user_id))]
async fn process_request(user_id: u64) -> Result<Response> {
    // trace_id/span_id automatically included
    info!(user_id = user_id, "processing request");
    Ok(result)
}

参照：Go と TypeScript のパターンについては references/trace-context.md をご覧ください。

Grafana でのクエリ

{job="api-service"} |= "trace_id=4bf92f3577b34da6a3ce929d0e0e4736"

クイックセットアップガイド

1. スタックを選択する

判断基準：

• 新規構築：OpenTelemetry SDK + LGTM スタック（セルフホスト）または Grafana Cloud（マネージド）
• 既存の Prometheus 環境：Loki（ログ）+ Tempo（トレース）を追加
• Kubernetes：Helm 経由で LGTM を導入し、Alloy DaemonSet を使用
• 運用作業を最小限にする場合：マネージド SaaS（Grafana Cloud、Datadog、New Relic）

2. OpenTelemetry SDK をインストールする

ブートストラップスクリプト：

python scripts/setup_otel.py --language python --framework fastapi

手動でのインストール（Python）：

pip install opentelemetry-api opentelemetry-sdk \
    opentelemetry-instrumentation-fastapi \
    opentelemetry-exporter-otlp

参照：Rust、Go、TypeScript のインストール方法については references/opentelemetry-setup.md をご覧ください。

3. LGTM スタックをデプロイする

Docker Compose（開発環境）：

cd examples/lgtm-docker-compose
docker-compose up -d
# Grafana: http://localhost:3000 (admin/admin)
# OTLP: localhost:4317 (gRPC), localhost:4318 (HTTP)

参照：本番環境の Kubernetes へのデプロイ方法については references/lgtm-stack.md をご覧ください。

4. 構造化ログを設定する

参照：完全なセットアップ方法（Python、Rust、Go、TypeScript）については references/structured-logging.md をご覧ください。

5. アラートを設定する

参照：Prometheus と Loki のアラートパターンについては references/alerting-rules.md をご覧ください。

自動計装

OpenTelemetry は、広く使われているフレームワークを自動計装できます。

from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor

app = FastAPI()
FastAPIInstrumentor.instrument_app(app)  # Auto-trace all HTTP requests

対応対象：FastAPI、Flask、Django、Express、Gin、Echo、Nest.js

参照：フレームワーク別の設定方法については references/opentelemetry-setup.md をご覧ください。

一般的なパターン

カスタムスパン

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("fetch_user_details") as span:
    span.set_attribute("user_id", user_id)
    user = await db.fetch_user(user_id)
    span.set_attribute("user_found", user is not None)

エラー追跡

from opentelemetry.trace import Status, StatusCode

with tracer.start_as_current_span("process_payment") as span:
    try:
        result = process_payment(amount, card_token)
        span.set_status(Status(StatusCode.OK))
    except PaymentError as e:
        span.set_status(Status(StatusCode.ERROR, str(e)))
        span.record_exception(e)
        raise

参照：バックグラウンドジョブのトレーシングとコンテキスト伝播については references/trace-context.md をご覧ください。

検証とテスト

# Test log-trace correlation
# 1. Make request to your app
# 2. Copy trace_id from logs
# 3. Query in Grafana: {job="myapp"} |= "trace_id=<TRACE_ID>"

# Validate metrics
python scripts/validate_metrics.py

他のスキルとの連携

• ダッシュボード：Grafana パネルの埋め込み、Prometheus メトリクスのクエリ
• フィードバック：アラートのルーティング（Slack、PagerDuty）、通知 UI
• データ可視化：時系列グラフ、トレースのウォーターフォール、レイテンシのヒートマップ

参照：完全な連携例は examples/fastapi-otel/ をご覧ください。

段階的な開示

セットアップガイド：

• references/opentelemetry-setup.md - SDK のインストール（Python、Rust、Go、TypeScript）
• references/structured-logging.md - structlog、tracing、slog、pino の設定
• references/lgtm-stack.md - LGTM のデプロイ（Docker、Kubernetes）
• references/trace-context.md - ログとトレースの相関パターン
• references/alerting-rules.md - Prometheus と Loki のアラートテンプレート

例：

• examples/fastapi-otel/ - FastAPI + OpenTelemetry + LGTM
• examples/axum-tracing/ - Rust Axum + tracing + LGTM
• examples/lgtm-docker-compose/ - 本番環境対応の LGTM スタック

スクリプト：

• scripts/setup_otel.py - OpenTelemetry SDK をブートストラップ
• scripts/generate_dashboards.py - Grafana ダッシュボードを生成
• scripts/validate_metrics.py - メトリクスの命名を検証

主要な原則

1. OpenTelemetry は唯一の標準です - ベンダー固有の SDK ではなく、OTel SDK を使用します
2. まず自動計装を行います - 手動のスパンよりも自動計装を優先します
3. ログとトレースは必ず相関させます - すべてのログに trace_id/span_id を挿入します
4. 構造化ロギングを使用します - JSON 形式で、一貫したフィールド名を使用します
5. セルフホストには LGTM スタックを使用します - 本番環境対応のオープンソーススタックです

よくある落とし穴

避けること：

• ベンダー固有の SDK を使用する（OpenTelemetry を使用します）
• trace_id/span_id のコンテキストなしでログを記録する
• 自動計装で対応できる処理を手動で計装する
• 複数のロギングライブラリを混在させる（structlog、tracing、slog、pino から 1 つを選びます）

行うこと：

• 自動計装から始めます
• ビジネス上重要な操作に限って手動スパンを追加します
• スパン属性にはセマンティック規約を使用します
• OTLP にエクスポートします（HTTP より gRPC を推奨します）
• 本番環境に移行する前に、LGTM docker-compose でローカルテストを行います

成功指標

1. リクエストコンテキスト内のすべてのログに trace_id が含まれる割合が 100%
2. 平均解決時間（MTTR）が 50% 超短縮される
3. 開発者が最初のデバッグツールとして Grafana を使用する
4. テレメトリの 80% 以上が自動計装によるもの
5. アラートの誤検知率が 5% 未満