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

          Copilot SDK は現在 テクニカル プレビューです。 機能と可用性は変更される場合があります。

          GitHub Copilot SDK には、CLI プロセスで OpenTelemetry を構成し、SDK と CLI の間で W3C トレース コンテキストを伝達するためのサポートが組み込まれています。

Python、Go、.NET の例については、 github/copilot-sdkrepository を参照してください。

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

テレメトリをオプトインするには、クライアントの作成時に TelemetryConfig を指定します。

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

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

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

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

TelemetryConfig オプション

          `"otlp-http"` または `"file"` |

| ソース名 | sourceName | 計装範囲名 | | コンテンツをキャプチャする | captureContent | メッセージの内容をキャプチャするかどうか |

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

SDK は、JSON-RPC ペイロードに W3C トレース コンテキスト (traceparent/tracestate) を伝達できるため、アプリケーションのスパンと CLI のスパンが 1 つの分散トレースにリンクされます。 これは、たとえば、要求処理スパンの子として SDK 呼び出しを表示する場合に便利です。

セッション フローの詳細なシーケンス図については、 github/copilot-sdkrepository を参照してください。

SDK から CLI (送信)

クライアント オプションに 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: "..." }
  },
});

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: "..." }
  },
});

CLI から SDK へのインバウンド

CLI がツール ハンドラーを呼び出すと、CLI のスパンからの traceparent と tracestate を使用できます。 SDK には OpenTelemetry 依存関係がないため、これらは 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();
      }
    })
  );
});

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();
      }
    })
  );
});

詳細については、次を参照してください。

•         [OpenTelemetry ドキュメントの OpenTelemetry GenAI セマンティック規則](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
  

•         [OpenTelemetry ドキュメントの OpenTelemetry MCP セマンティック規則](https://opentelemetry.io/docs/specs/semconv/gen-ai/mcp/)
  

•         [OpenTelemetry ドキュメントの OpenTelemetry Python SDK](https://opentelemetry.io/docs/instrumentation/python/)