Skill: Observability Engineering（オブザーバビリティ設計・導入）

出力

Step 1: オブザーバビリティ成熟度評価（OMM）

組織の現状を OMM（Observability Maturity Model）の 5 能力で診断する。

1a. 5 能力の現状評価

各能力を「未着手 / 初期 / 発展 / 成熟」の 4 段階で評価する。

1b. 優先能力の特定

ビジネスインパクトが最大の能力を特定し、投資優先順位を決定する。

チェックリスト:

• 5 能力すべてを 4 段階で評価した
• ビジネスインパクト順に優先順位を付けた
• 現状の主要課題（アラート疲れ、デバッグ困難等）を明文化した
• ステークホルダーの合意を得た

Step 2: 構造化イベント設計

オブザーバビリティの基本単位である「任意幅の構造化イベント」を設計する。

2a. イベントスコープの定義

• 1 イベント = 1 サービスにおける 1 リクエストの処理全体
• リクエスト開始時に空マップを初期化し、処理中にコンテキストを蓄積

2b. フィールド設計

必須フィールド:

• リクエスト識別: trace_id, span_id, parent_id
• タイミング: timestamp, duration_ms
• サービス: service_name, span_name
• 結果: status_code, error_message

高カーディナリティフィールド（デバッグに最も有用）:

• user_id, session_id, request_id, shopping_cart_id
• build_id, hostname, instance_type, availability_zone

ビジネスコンテキストフィールド:

• app.api_key, app.dataset.id, app.team.id
• app.raw_size_bytes, app.sample_rate

2c. 既存ログからの移行パス

1. 非構造化ログ → 構造化ログ（JSON 形式）
2. 複数行ログ → 1 作業単位 = 1 イベントに統合
3. request_id 等の相関フィールドを追加
4. トレーシングフィールドを追加

チェックリスト:

• イベントのスコープ（1リクエスト/1サービス）を定義した
• 高カーディナリティフィールドを 10 個以上設計した
• ビジネスロジック固有のフィールドを含めた
• フィールド数の上限を設けていない（任意幅）
• 既存ログからの移行パスを検討した

Step 3: 分散トレーシング設計

イベントをトレースとしてステッチし、サービス間の関係を可視化する。

3a. スパン構造の設計

Root Span (API Gateway)
├── Child Span (Auth Service)
├── Child Span (User Service)
│   └── Child Span (Database Query)
└── Child Span (Notification Service)

• 各スパンに 5 つの必須フィールド: Trace ID, Span ID, Parent ID, Timestamp, Duration
• Service Name と Span Name で作業内容を識別

3b. トレースコンテキスト伝搬

• 標準: W3C TraceContext（推奨）または B3
• HTTP ヘッダで Trace ID と Parent Span ID を伝搬
• gRPC メタデータでも同様に伝搬

3c. カスタムスパンの追加

• CPU 集中処理の「ホットブロック」を個別スパンに分離
• バッチジョブの各チャンクにスパンを付与
• 非分散（モノリシック）コードでもトレーシングを活用

チェックリスト:

• サービス間のスパン親子関係を図示した
• トレースコンテキスト伝搬の標準を選択した（W3C / B3）
• クリティカルパスのカスタムスパンを特定した
• 非同期処理・バッチジョブのトレーシング方針を決定した

Step 4: OpenTelemetry 計装設計

OTel を使った 3 段階計装戦略を設計する。

4a. 自動計装の導入

• HTTP/gRPC フレームワーク統合で即座にスパン生成
• DB/Cache クライアントの自動計装でダウンストリーム可視化
• 言語ごとの導入方法:
  • Go: ラッパー/インターセプター（otelhttp, otelgrpc）
  • Java/.NET: ランタイムエージェントの自動登録
  • Python: opentelemetry-instrument CLI

4b. カスタム計装の追加

• スパン属性にビジネスロジックフィールドを追加
• パッケージ単位でトレーサーを定義: var tr = otel.Tracer("module_name")
• スパンの開始/終了を明示的に管理

// Example: custom span with business attributes
func processOrder(ctx context.Context, order Order) error {
    ctx, sp := tr.Start(ctx, "process_order")
    defer sp.End()

    sp.SetAttributes(
        attribute.String("order.id", order.ID),
        attribute.Float64("order.total", order.Total),
        attribute.String("order.customer_id", order.CustomerID),
    )
    // ... business logic ...
    return nil
}

4c. バックエンド連携

• 推奨: OTLP gRPC エクスポーター → OTel Collector → バックエンド
• 直接エクスポートも可能だが、Collector 経由が柔軟
• 移行期は複数エクスポーターで既存/新規ツールへ同時送信

チェックリスト:

• 自動計装の対象フレームワークを特定した
• カスタム計装の優先順位（クリティカルパス優先）を決めた
• ビジネスロジック固有の属性を計装に組み込んだ
• エクスポート先（Collector / 直接）を決定した
• 言語ごとの OTel SDK バージョンを確認した

Step 5: SLO ベースアラート設計

閾値アラートから SLO ベースアラートへ移行し、アラート疲れを解消する。

5a. SLI の定義（イベントベース）

各クリティカルユーザージャーニーに対して SLI を定義する。

# Example SLI definition