Copilot SDK 用の OpenTelemetry インストルメンテーション

組み込みのテレメトリのサポート

SDK には、CLI プロセスで OpenTelemetry を構成し、SDK と CLI の間で W3C トレース コンテキストを伝達するためのサポートが組み込まれています。 オプトインするクライアントを作成するときに TelemetryConfig を指定します。

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient({
  telemetry: {
    otlpEndpoint: "http://localhost:4318",
  },
});

from copilot import CopilotClient

client = CopilotClient(
    telemetry={
        "otlp_endpoint": "http://localhost:4318",
    },
)

client := copilot.NewClient(&copilot.ClientOptions{
    Telemetry: &copilot.TelemetryConfig{
        OTLPEndpoint: "http://localhost:4318",
    },
})

var client = new CopilotClient(new CopilotClientOptions
{
    Telemetry = new TelemetryConfig
    {
        OtlpEndpoint = "http://localhost:4318",
    },
});

import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;

var client = new CopilotClient(new CopilotClientOptions()
    .setTelemetry(new TelemetryConfig()
        .setOtlpEndpoint("http://localhost:4318"))
);

use github_copilot_sdk::{Client, ClientOptions, TelemetryConfig};

let client = Client::start(ClientOptions::new()
    .with_telemetry(TelemetryConfig::new()
        .with_otlp_endpoint("http://localhost:4318"))
).await?;

TelemetryConfig オプション

OTLP プロトコル フィールドは、すべての信号に対して CLI の "otlp-http" エクスポーターを構成します。 CLI の既定値を使用するように設定したままにするか、http 経由で protobuf をエクスポートする "http/protobuf" に設定します。

スキルとコマンドのテレメトリ

ランタイムは、別のスキル操作を追加せず、既存のスパンを絞り込むことで、execute_toolに従います。 ローダーには、 execute_tool skill {skill}という名前が付けられています。 明確に識別されたリソースまたはスクリプトは、execute_tool {tool} {skill} {resource} という名前で、その名前はスキル相対リソース名です。 他のコマンド部分では、実際に判明しているランチャー名が追加されます。

• gen_ai.skill.name と gen_ai.skill.resource.name: コンテンツ キャプチャとは別に使用できます
• gen_ai.skill.description と gen_ai.skill.source.uri: TelemetryConfig を通じたコンテンツ キャプチャが必要
• process.executable.name: シェルランチャーなどの、直接起動された実行可能ファイル。推測されたコマンド トークンではありません
• process.executable.path: 絶対既知のパス。コンテンツ キャプチャが必要
• process.exit.code: コマンド実行ツールが終了を報告する場合、0 を含む整数。利用不可の終了コードと spawn 前の失敗は省略されます

ポーリング ツールは、読み取ったコマンドからプロセス属性を継承しません。 サンドボックス バックエンドがそれらを公開しない場合、サンドボックス実行可能 ID は省略されます。 ゼロ以外の終了コードは、ツール自体が失敗したことを意味しません。 スキル定義とディレクトリ一覧は、スキル リソースと呼ばれるリソースではありません。 事前に読み込まれたスキルは、人工的なツール スパンなしで呼び出しイベントを生成します。 同じ選択されたエージェント スキル コンテキストを繰り返し準備すると、1 つのレシートが生成されます。変更されたコンテンツまたは来歴では、別のレシートが生成されます。 子セッションは、自身のプリロードを個別に報告します。 デタッチされたコマンド スパンは、直接生成された Unix shスーパーバイザー、または選択された Windows PowerShell 実行可能ファイルを識別します。

組み込みの名前をオーバーライドするカスタム ツールは、ネイティブ スキルやプロセス属性を継承しません。 モデルの呼び出しが無効になっている場合でも、表示可能で有効なスキルはリソースを所有します。 スクリプト属性では、ポストフック コマンドと選択したシェルのパスが使用されます。スタートアップ スクリプトまたはプロファイルによって実行コンテキストが不明な場合は省略されます。

マネージド テレメトリの設定が未解決の間は、保留中の追跡バッファーでは、キャプチャに依存しないツールファクトのみが記録されます。 ポリシーの解決が完了する前に観察された説明、ソース URI、実行可能パスは、キャプチャが後で有効になっている場合でも省略されます。 最終的なポリシーはリプレイを管理します。無効またはキャンセルされたトラッキングでは、バッファーが破棄されます。

テレメトリ名の変更は破壊的変更です。github.copilot.skill.nameやgen_ai.skill.nameではなくgithub.copilot.tool.parameters.skill_nameを使用し、gen_ai.skill.source.uriではなくgithub.copilot.skill.pathを使用します。 ローカル ソース値はファイル URI であり、ベア パスではありません。

github.copilot.skill.invoked イベントとそのコンテンツ、ソース カテゴリ、トリガー、プラグインの各フィールドは、Copilot固有のままです。 スキル コンテンツは、既存のキャプチャ ゲートを保持します。

スキル属性とスパンの絞り込みには、開発の安定性があります。プロセス属性には、リリース候補の安定性があります。

トレース コンテキストの伝達

ほとんどのユーザーはこれを必要としません。 上記の TelemetryConfig は、CLI からトレースを収集するために必要なすべてです。 このセクションで説明するトレース コンテキスト伝達は、独自の OpenTelemetry スパンを作成し、CLI のスパンと同じ分散トレースに表示するアプリケーションの高度な機能です。

SDK は、JSON-RPC ペイロードに W3C トレース コンテキスト (traceparent/tracestate) を伝達できるため、アプリケーションのスパンと CLI のスパンが 1 つの分散トレースにリンクされます。 これは、たとえば、アプリ内の「ツール呼び出しを処理」スパンが CLI の「ツールを実行」スパンの内側に入れ子になった状態で表示したい場合や、SDK 呼び出しをリクエスト処理スパンの子として表示したい場合に便利です。

トレースとあわせてコストの帰属を確認するには、assistant.usage イベントを購読し、apiEndpoint（AssistantUsageApiEndpoint）を確認して、そのターンで Chat Completions、Responses、または Anthropic Messages のいずれが使用されたかを確認します。ストリーミング セッション イベント を参照してください。

SDK → CLI (送信)

Node.jsの場合は、クライアント オプションにonGetTraceContextコールバックを指定します。 これは、アプリケーションで既に @opentelemetry/api を使用しており、スパンを CLI のスパンにリンクする場合にのみ必要です。 SDK は、RPC を session.create、 session.resume、および session.send する前に、このコールバックを呼び出します。

import { CopilotClient } from "@github/copilot-sdk";
import { propagation, context } from "@opentelemetry/api";

const client = new CopilotClient({
  telemetry: { otlpEndpoint: "http://localhost:4318" },
  onGetTraceContext: () => {
    const carrier: Record<string, string> = {};
    propagation.inject(context.active(), carrier);
    return carrier; // { traceparent: "00-...", tracestate: "..." }
  },
});

Python、Go、および .NET では、それぞれの OpenTelemetry/Activity API が構成されている場合、トレース コンテキストの挿入は自動的に行われます。コールバックは必要ありません。

CLI → SDK（インバウンド）

CLI がツール ハンドラーを呼び出すと、CLI のスパンからの traceparent と tracestate は、すべての言語で使用できます。

• Go: ToolInvocation.TraceContext フィールドは、すでに復元されたトレースを含む context.Context です。これをスパンの親としてそのまま使用してください。
• Python: トレース コンテキストは、trace_context() を介してハンドラーの周囲に自動的に復元されます。子スパンは CLI のスパンに自動的に親されます。
• .NET: トレース コンテキストは自動的に復元され、RestoreTraceContext()子Activityインスタンスは自動的に CLI のスパンに紐付けられます。
• Node.js: SDK には OpenTelemetry 依存関係がないため、 traceparent と tracestate は、 ToolInvocation オブジェクトに生の文字列として渡されます。 必要に応じて、コンテキストを手動で復元します。

import { defineTool } from "@github/copilot-sdk";
import { propagation, context, trace } from "@opentelemetry/api";

const myTool = defineTool("my-tool", {
  description: "Do work",
  handler: async (args, invocation) => {
    // Restore the CLI's trace context as the active context
    const carrier = {
      traceparent: invocation.traceparent,
      tracestate: invocation.tracestate,
    };
    const parentCtx = propagation.extract(context.active(), carrier);

    // Create a child span under the CLI's span
    const tracer = trace.getTracer("my-app");
    return context.with(parentCtx, () =>
      tracer.startActiveSpan("my-tool", async (span) => {
        try {
          const result = await doWork(args);
          return result;
        } finally {
          span.end();
        }
      })
    );
  },
});

// Tool handlers are registered when the session is created.
const session = await client.createSession({ tools: [myTool] });

言語ごとの依存関係

References

• OpenTelemetry GenAI セマンティック規則
• OpenTelemetry MCP セマンティック規則
• OpenTelemetry Python SDK
• Copilot SDK ドキュメント