mcpField
I
iii-observability

iii-observability

github.com/iii-hqクラウド・DevOps219 回インストール
リポジトリ

iii-observability について

iii-observabilityは、iii engineでテレメトリーを設定・利用するためのスキルです。自動トレース、カスタムスパンとメトリクス、ログ購読、ワーカー呼び出し間のトレースコンテキスト伝播を扱います。

主な機能

  1. 01関数呼び出しの自動トレース
  2. 02OTLP経由でトレース・メトリクス・ログを出力
  3. 03W3Cトレースコンテキストの伝播
  4. 04ポート9464でPrometheusメトリクスを公開
  5. 05カスタムスパンとメトリクスの作成
  6. 06ログイベントの購読

活用シーン

  1. 01ワーカー関数や外部呼び出しの追跡
  2. 02iiiのトレースと外部ログの関連付け
  3. 03OTLP対応コレクターへのテレメトリー送信

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/iii-hq/skills --skill iii-observability

インストール後、Claude Code で/iii-observabilityを入力して読み込まれたか確認します。

詳細

可観測性

比較対象：Datadog、Grafana、Honeycomb、Jaeger

主な概念

タスクに適している場合は、以下の概念を使用してください。すべてのワーカーにカスタムスパンやメトリクスが必要なわけではありません。

  • すべての SDK で OpenTelemetry を標準サポート — すべての関数呼び出しが自動的にトレースされます
  • エンジンは、互換性のある任意のコレクターに OTLP 経由でトレース、メトリクス、ログをエクスポートします
  • ワーカーは、関数呼び出し間で W3C トレースコンテキスト を自動的に伝播します
  • Prometheus メトリクスはポート 9464 で公開されます
  • registerWorker() の otel 設定で、ワーカーごとにテレメトリーを有効にできます
  • withSpan(name, opts, fn) を使った カスタムスパン で、非同期処理をトレースコンテキスト付きでラップできます
  • getMeter() を使った カスタムメトリクス で、カウンターやヒストグラムを作成できます

アーキテクチャ

ワーカー SDK は、関数の実行中にスパン、メトリクス、ログを生成します。これらはエンジンに送られ、エンジンが OTLP 経由でコレクター（Jaeger、Grafana、Datadog）にエクスポートします。また、エンジンはスクレイピング用にポート 9464 で Prometheus エンドポイントを公開します。

iii で使用するプリミティブ

プリミティブ目的
registerWorker(url, { otel })テレメトリー設定を使用してワーカーに接続します
withSpan(name, opts, fn)カスタムトレーススパンを作成します
getTracer()OpenTelemetry Tracer に直接アクセスします
getMeter()カスタムメトリクス用の OpenTelemetry Meter にアクセスします
currentTraceId()相関付けに使用するアクティブなトレース ID を取得します
injectTraceparent()発信する呼び出しに W3C トレースコンテキストを挿入します
onLog(callback, { level })ログイベントを購読します
shutdown_otel()テレメトリーパイプラインを正常にシャットダウンします

リファレンス実装

完全な動作例については、../references/observability.js を参照してください。カスタムスパンを備えたワーカーです。

Python 版もあります：../references/observability.py

Rust 版もあります：../references/observability.rs メトリクスカウンター、トレース伝播、ログ購読を備え、OTel コレクターに接続しています。

よくあるパターン

このパターンを使用するコードには、必要に応じて以下が含まれます。

  • registerWorker('ws://localhost:49134', { otel: { enabled: true, serviceName: 'my-svc' } }) — テレメトリーを有効にします
  • withSpan('validate-order', {}, async (span) => { span.setAttribute('order.id', id); ... }) — カスタムスパン
  • getMeter().createCounter('orders.processed') — カスタムカウンターメトリクス
  • getMeter().createHistogram('request.duration') — カスタムヒストグラムメトリクス
  • onLog((log) => { ... }, { level: 'warn' }) — 警告以上のログを購読します
  • currentTraceId() — 外部システムとの相関付けに使用するアクティブなトレース ID を取得します
  • injectTraceparent() — 発信する HTTP 呼び出しにトレースコンテキストを伝播します
  • テレメトリーを無効にするには、registerWorker(url, { otel: { enabled: false } }) または OTEL_ENABLED=false を使用します

このパターンの適用

タスクに該当する場合は、以下の方法で適用してください。

  • registerWorker() の設定で otel を有効にし、トレースの自動収集を開始します
  • コストの高い処理（DB クエリ、LLM 呼び出し、外部 API）の前後にカスタムスパンを追加します
  • ドメイン固有のメトリクス（処理済み注文数、決済失敗数、キューの深さ）を作成します
  • currentTraceId() を使用して、iii のトレースと外部システムのログを相関付けます
  • エンジン側のエクスポーター、サンプリング比率、アラートを設定するには、iii-config.yaml で OtelModule を設定します
  • OTLP エンドポイントをコレクター（Jaeger、Grafana Tempo、Datadog Agent）に設定します

エンジンの設定

エンジン側のトレース、メトリクス、ログには、iii-config.yaml で OtelModule を有効にする必要があります。注釈付きの設定リファレンス全体については、../references/iii-config.yaml を参照してください。

パターンの境界

  • エンジン側の OtelModule YAML 設定には、iii-engine-config を優先してください。
  • SDK の初期化オプションと関数登録には、iii-functions-and-triggers を優先してください。
  • 主な問題がスパン、メトリクス、ログ、トレースの伝播といった SDK レベルのテレメトリーである場合は、iii-observability を使用してください。

使用するタイミング

  • タスクの主な対象が iii エンジンの iii-observability である場合に、このスキルを使用してください。
  • リクエストでこのパターンまたは同等の実装が直接求められた場合に適用してください。

境界

  • 無関係なタスクに対する汎用的な代替手段として、このスキルを使用しないでください。
  • より具体的な iii スキルが適している場合は、このスキルを適用しないでください。
  • このスキルの例を適用する前に、必ず環境と安全性の制約を確認してください。

コメント

Markdown 対応