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, err := 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.sdk.CopilotClient;
import com.github.copilot.sdk.json.*;

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 オプション

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

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

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

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 { propagation, context, trace } from "@opentelemetry/api";

session.registerTool(myTool, 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();
      }
    })
  );
});

言語ごとの依存関係

References

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