otel-instrumentation

Kopai を使用した OpenTelemetry の計装

幅の広いイベントを出力し、その品質を検証します。

スパンは幅の広いイベントです。作業単位のコンテキスト全体を含む、フラットなレコードです。 Kopai はローカルホスト上で動作するため、計装を信頼するだけでリリースする必要はありません。アプリに自分でトラフィックを流し、届いたデータをアサートできます。validate-traces のすべてのアサーションに合格すると、ループは成功です。アサーションが 1 つでも失敗している間は、ここでの作業は完了ではありません。

分岐

該当する状況	開始箇所
テレメトリのないサービスをセットアップする	以下のワークフローのステップ 1
既存のコードベースに OTel を後付けする	まず context-propagation を確認します。作業の約 60％を占めます。その後、ワークフローに進みます
データが届かない原因を調べる	troubleshoot-no-data を確認し、次にワークフローのステップ 4 に進みます

ワークフロー

#	手順	完了条件
1	バックエンドを起動します — npx @kopai/app start	curl -s -o /dev/null -w '%{http_code}' -X POST http://localhost:4318/v1/traces -H 'Content-Type: application/json' -d '{"resourceSpans":[]}' が 2xx を返す
2	環境を設定します — setup-environment	OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_SERVICE_NAME、および validation.run_id のランタグがすべて、アプリを起動するシェルでエクスポートされている
3	計装します — 以下の言語 SDKにある該当する lang-<language> ルールに従い、続けて判定ルールに従います	SDK が読み込まれた状態でアプリが起動し、OTel のエクスポートエラーが出力されない
4	自分でトラフィックを流します — drive-traffic	発見したすべてのエントリーポイントに少なくとも 1 回アクセスし、意図的に発生させた失敗も少なくとも 1 回ある
5	検証します — validate-traces、続けて validate-logs、validate-metrics、validate-shutdown	すべてのアサーションに合格する。ループが成功している
6	修正します — 以下の修正方法にある該当する troubleshoot-* ルールに従います	手順 4 に戻って再度トラフィックを流します。アサーションが失敗したまま終了しないでください

手順 4〜6 は順番に進めるのではなく、ループとして実行します。同じ実行で手順 4 のトラフィックに対して手順 5 が成功した場合にのみ、計装が完了したと報告してください。

スパンを作成する基準

次の 2 つの問いで判断します。

1. 重要か？ — この処理は、リクエストのレイテンシや失敗率に意味のある影響を与えますか？
2. 集計できるか？ — 名前と属性でグループ化したとき、有用な傾向が得られますか？

両方とも「はい」なら、スパンを作成します。それ以外の場合は、既存のスパンに属性を追加します。

迷ったら、子スパンより属性を優先してください。親スパンの属性には JOIN が不要で、クエリの追加コストもなく、すぐにグループ化できます。判断表の全文と、よくある 3 つの失敗パターンについては、instrument-spans を参照してください。

コアパターン

1 つのスパン、豊富な属性、明示的なエラーステータスです。Node.js の例を示しますが、すべての言語で同じ形式に従います。詳しくは、以下の 言語 SDK で各言語のルールを確認してください。

import { trace, SpanStatusCode } from "@opentelemetry/api";

const tracer = trace.getTracer("checkout");

export async function processPayment(order: Order) {
  return tracer.startActiveSpan("process-payment", async (span) => {
    try {
      span.setAttributes({
        "order.id": order.id, // IDs are attributes, never span names
        "order.total": order.total,
        "payment.provider": order.provider,
      });
      const receipt = await charge(order);
      span.setAttribute("payment.status", receipt.status);
      return receipt;
    } catch (err) {
      span.recordException(err as Error);
      span.setStatus({
        code: SpanStatusCode.ERROR,
        message: (err as Error).message,
      });
      throw err;
    } finally {
      span.end();
    }
  });
}

ネストされたスパン、非同期のファンアウト、キュー、手動のコンテキストなど、各パターンの完全なコードはカスタム計装をご覧ください。

命名

• スパン名には操作を記述します：GET /api/users、db.query SELECT、process-payment
• 属性名はドット区切りの名前空間にします：user.id、order.total、cache.hit
• 標準的なものにはOTel のセマンティック規約に従います：http.route、db.system、rpc.service
• 独自に追加する属性には名前空間を使用します：app.、checkout.、<company>.

スパン名のカーディナリティは低く抑える必要があります。ID をスパン名に埋め込んではいけません。ID は属性に設定します。

計装パッケージの選択

まずプロジェクトのパッケージマネージャーを確認します。package.json の packageManager フィールドがあればそれが優先されます。ない場合はロックファイルで判断します。pnpm-lock.yaml → pnpm、yarn.lock → yarn、bun.lock → bun、package-lock.json → npm です。インストールには必ずそのマネージャーを使用してください。別のマネージャーを使うと 2 つ目のロックファイルが作成され、気づかないうちに差異が生じます。npx @kopai/cli の検証コマンドはパッケージマネージャーに依存しません。npx は Node に付属しており、プロジェクトの依存関係ツリーには触れません。

非推奨かどうかはインストール時の出力ではなく、レジストリで確認してください。インストール時に完全な非推奨警告を表示するのは npm だけです。pnpm は警告を切り詰め、Yarn 4 はまったく表示しません。npm が警告を表示した場合は、内容を確認してください。インストール出力を tail、grep -v、--quiet でフィルタリングしてはいけません。

npm view @opentelemetry/instrumentation-<lib> deprecated   # empty output = not deprecated

npm view はレジストリの読み取り専用コマンドで、pnpm や yarn のプロジェクト内でも使用できます（npm は Node に付属しています）。ネイティブの同等コマンドは pnpm view <pkg> deprecated と yarn npm info <pkg> --fields deprecated --json（Yarn 4）です。

非推奨のメッセージには通常、置き換え先が記載されています。そのパッケージを使い、非推奨のパッケージは使わないでください。置き換え先が記載されていない場合は、推測せず、パッケージ独自の移行ガイドに従ってください。フレームワークのチームが独自のプラグイン（Fastify → @fastify/otel）を提供している場合は、contrib パッケージよりそちらを優先してください。フレームワークのプラグインシステムを通じて登録されるためです。一方、require／import をインターセプトする方式は、実験的なローダーフックを追加しない限り、ネイティブ ESM のインポートには適用されません。

ルール

タスクに応じたルールファイルです。ワークフローで指定された場合にのみ読み込みます。

セットアップ — setup-backend、setup-environment

言語 SDK — lang-nodejs、lang-fastify、 lang-nextjs、 lang-python、lang-go、 lang-java、lang-dotnet、 lang-ruby、lang-php、 lang-rust、lang-erlang、 lang-cpp

計装する対象 — instrument-spans（スパンとして記録する対象）、 instrument-attributes（属性、タイミング属性、非同期の概要）、 instrument-errors（error、スパンのステータス、slug）、 context-propagation（コンテキストの引き回し、フレームワークのアクセサーに関する注意点）、 layered-telemetry（トレース、メトリクス、ログの違い）、 sampling

動作を実証する — drive-traffic（トラフィックを自分で生成）、 validate-traces、validate-logs、 validate-metrics、validate-shutdown

問題を解決する — troubleshoot-no-data、 troubleshoot-missing-spans、 troubleshoot-missing-attrs、 troubleshoot-wrong-port

参考資料

詳細については、タスクで必要な場合にのみ読み込みます。

• attributes — カテゴリ別の標準属性カタログ
• custom-instrumentation — 言語ごとのすべてのパターンの完全なコード
• architectural-patterns — キュー、非同期ファンアウト、ETL、サーバーレス
• cli-reference — Kopai CLI コマンド
• nextjs-examples — Next.js の計装例
• otel-docs — OpenTelemetry のドキュメントへのリンク

関連スキル

• otel-genai-instrumentation — LLM、エージェント、ツール呼び出しの計装
• root-cause-analysis — テレメトリの流れが確認できた後の調査。このスキルが尋ねる質問に答えられるよう計装します：誰に影響があったか、何が変わったか、時間がどこにかかったか
• create-dashboard — ここで出力するシグナルの可視化