feat: add OpenTelemetry support across all SDKs

Add TelemetryConfig to all four SDKs (Node, Python, Go, .NET) to configure
OpenTelemetry instrumentation on the Copilot CLI process. This includes:

- TelemetryConfig type with OTLP endpoint, file exporter, source name, and
  capture-content options, mapped to CLI environment variables
- W3C Trace Context propagation (traceparent/tracestate) on session.create,
  session.resume, and session.send RPC calls
- Trace context restoration in tool call handlers (v2 RPC and v3 broadcast)
  so user tool code executes within the correct distributed trace
- Telemetry helper modules (telemetry.ts, telemetry.py, telemetry.go,
  Telemetry.cs) with unit tests
- Updated generated types from latest schema

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 2 people

docs/getting-started.md

@@ -1426,13 +1426,13 @@ Optional peer dependency: `@opentelemetry/api`
 
 <!-- docs-validate: skip -->
 ```python
-from copilot import CopilotClient
+from copilot import CopilotClient, SubprocessConfig
 
-client = CopilotClient(
+client = CopilotClient(SubprocessConfig(
     telemetry={
         "otlp_endpoint": "http://localhost:4318",
     },
-)
+))
 ```
 
 Install with telemetry extras: `pip install copilot-sdk[telemetry]` (provides `opentelemetry-api`)

docs/observability/opentelemetry.md

@@ -27,13 +27,13 @@ const client = new CopilotClient({
 
 <!-- docs-validate: skip -->
 ```python
-from copilot import CopilotClient
+from copilot import CopilotClient, SubprocessConfig
 
-client = CopilotClient(
+client = CopilotClient(SubprocessConfig(
     telemetry={
         "otlp_endpoint": "http://localhost:4318",
     },
-)
+))
 ```
 
 </details>

dotnet/src/Client.cs

@@ -431,6 +431,8 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
 
         try
         {
+            var (traceparent, tracestate) = TelemetryHelpers.GetTraceContext();
+
             var request = new CreateSessionRequest(
                 config.Model,
                 sessionId,
@@ -453,7 +455,9 @@ public async Task<CopilotSession> CreateSessionAsync(SessionConfig config, Cance
                 config.ConfigDir,
                 config.SkillDirectories,
                 config.DisabledSkills,
-                config.InfiniteSessions);
+                config.InfiniteSessions,
+                traceparent,
+                tracestate);
 
             var response = await InvokeRpcAsync<CreateSessionResponse>(
                 connection.Rpc, "session.create", [request], cancellationToken);
@@ -535,6 +539,8 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
 
         try
         {
+            var (traceparent, tracestate) = TelemetryHelpers.GetTraceContext();
+
             var request = new ResumeSessionRequest(
                 sessionId,
                 config.ClientName,
@@ -558,7 +564,9 @@ public async Task<CopilotSession> ResumeSessionAsync(string sessionId, ResumeSes
                 config.Agent,
                 config.SkillDirectories,
                 config.DisabledSkills,
-                config.InfiniteSessions);
+                config.InfiniteSessions,
+                traceparent,
+                tracestate);
 
             var response = await InvokeRpcAsync<ResumeSessionResponse>(
                 connection.Rpc, "session.resume", [request], cancellationToken);
@@ -1070,6 +1078,17 @@ private async Task VerifyProtocolVersionAsync(Connection connection, Cancellatio
             startInfo.Environment["COPILOT_SDK_AUTH_TOKEN"] = options.GitHubToken;
         }
 
+        // Set telemetry environment variables if configured
+        if (options.Telemetry is { } telemetry)
+        {
+            startInfo.Environment["COPILOT_OTEL_ENABLED"] = "true";
+            if (telemetry.OtlpEndpoint is not null) startInfo.Environment["OTEL_EXPORTER_OTLP_ENDPOINT"] = telemetry.OtlpEndpoint;
+            if (telemetry.FilePath is not null) startInfo.Environment["COPILOT_OTEL_FILE_EXPORTER_PATH"] = telemetry.FilePath;
+            if (telemetry.ExporterType is not null) startInfo.Environment["COPILOT_OTEL_EXPORTER_TYPE"] = telemetry.ExporterType;
+            if (telemetry.SourceName is not null) startInfo.Environment["COPILOT_OTEL_SOURCE_NAME"] = telemetry.SourceName;
+            if (telemetry.CaptureContent is { } capture) startInfo.Environment["OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"] = capture ? "true" : "false";
+        }
+
         var cliProcess = new Process { StartInfo = startInfo };
         cliProcess.Start();
 
@@ -1329,8 +1348,12 @@ public async Task<HooksInvokeResponse> OnHooksInvoke(string sessionId, string ho
         public async Task<ToolCallResponseV2> OnToolCallV2(string sessionId,
             string toolCallId,
             string toolName,
-            object? arguments)
+            object? arguments,
+            string? traceparent = null,
+            string? tracestate = null)
         {
+            using var _ = TelemetryHelpers.RestoreTraceContext(traceparent, tracestate);
+
             var session = client.GetSession(sessionId) ?? throw new ArgumentException($"Unknown session {sessionId}");
             if (session.GetTool(toolName) is not { } tool)
             {
@@ -1470,7 +1493,9 @@ internal record CreateSessionRequest(
         string? ConfigDir,
         List<string>? SkillDirectories,
         List<string>? DisabledSkills,
-        InfiniteSessionConfig? InfiniteSessions);
+        InfiniteSessionConfig? InfiniteSessions,
+        string? Traceparent = null,
+        string? Tracestate = null);
 
     internal record ToolDefinition(
         string Name,
@@ -1516,7 +1541,9 @@ internal record ResumeSessionRequest(
         string? Agent,
         List<string>? SkillDirectories,
         List<string>? DisabledSkills,
-        InfiniteSessionConfig? InfiniteSessions);
+        InfiniteSessionConfig? InfiniteSessions,
+        string? Traceparent = null,
+        string? Tracestate = null);
 
     internal record ResumeSessionResponse(
         string SessionId,

dotnet/src/Session.cs

@@ -152,12 +152,16 @@ private Task<T> InvokeRpcAsync<T>(string method, object?[]? args, CancellationTo
     /// </example>
     public async Task<string> SendAsync(MessageOptions options, CancellationToken cancellationToken = default)
     {
+        var (traceparent, tracestate) = TelemetryHelpers.GetTraceContext();
+
         var request = new SendMessageRequest
         {
             SessionId = SessionId,
             Prompt = options.Prompt,
             Attachments = options.Attachments,
-            Mode = options.Mode
+            Mode = options.Mode,
+            Traceparent = traceparent,
+            Tracestate = tracestate
         };
 
         var response = await InvokeRpcAsync<SendMessageResponse>(
@@ -412,7 +416,8 @@ private async Task HandleBroadcastEventAsync(SessionEvent sessionEvent)
                         if (tool is null)
                             return; // This client doesn't handle this tool; another client will.
 
-                        await ExecuteToolAndRespondAsync(data.RequestId, data.ToolName, data.ToolCallId, data.Arguments, tool);
+                        using (TelemetryHelpers.RestoreTraceContext(data.Traceparent, data.Tracestate))
+                            await ExecuteToolAndRespondAsync(data.RequestId, data.ToolName, data.ToolCallId, data.Arguments, tool);
                         break;
                     }
 
@@ -822,6 +827,8 @@ internal record SendMessageRequest
         public string Prompt { get; init; } = string.Empty;
         public List<UserMessageDataAttachmentsItem>? Attachments { get; init; }
         public string? Mode { get; init; }
+        public string? Traceparent { get; init; }
+        public string? Tracestate { get; init; }
     }
 
     internal record SendMessageResponse

dotnet/src/Telemetry.cs

@@ -0,0 +1,51 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+using System.Diagnostics;
+
+namespace GitHub.Copilot.SDK;
+
+internal static class TelemetryHelpers
+{
+    internal static (string? Traceparent, string? Tracestate) GetTraceContext()
+    {
+        return Activity.Current is { } activity 
+            ? (activity.Id, activity.TraceStateString) 
+            : (null, null);
+    }
+
+    /// <summary>
+    /// Sets <see cref="Activity.Current"/> to reflect the trace context from the given
+    /// W3C <paramref name="traceparent"/> / <paramref name="tracestate"/> headers.
+    /// The runtime already owns the <c>execute_tool</c> span; this just ensures
+    /// user code runs under the correct parent so any child activities are properly parented.
+    /// Dispose the returned <see cref="Activity"/> to restore the previous <see cref="Activity.Current"/>.
+    /// </summary>
+    /// <remarks>
+    /// Because this Activity is not created via an <see cref="ActivitySource"/>, it will not
+    /// be sampled or exported by any standard OpenTelemetry exporter — it is invisible in
+    /// trace backends.  It exists only to carry the remote parent context through
+    /// <see cref="Activity.Current"/> so that child activities created by user tool
+    /// handlers are parented to the CLI's span.
+    /// </remarks>
+    internal static Activity? RestoreTraceContext(string? traceparent, string? tracestate)
+    {
+        if (traceparent is not null &&
+            ActivityContext.TryParse(traceparent, tracestate, out ActivityContext parent))
+        {
+            Activity activity = new("copilot.tool_handler");
+            activity.SetParentId(parent.TraceId, parent.SpanId, parent.TraceFlags);
+            if (tracestate is not null)
+            {
+                activity.TraceStateString = tracestate;
+            }
+
+            activity.Start();
+
+            return activity;
+        }
+
+        return null;
+    }
+}

dotnet/src/Types.cs

@@ -63,6 +63,7 @@ protected CopilotClientOptions(CopilotClientOptions? other)
         Logger = other.Logger;
         LogLevel = other.LogLevel;
         Port = other.Port;
+        Telemetry = other.Telemetry;
         UseLoggedInUser = other.UseLoggedInUser;
         UseStdio = other.UseStdio;
         OnListModels = other.OnListModels;
@@ -148,6 +149,12 @@ public string? GithubToken
     /// </summary>
     public Func<CancellationToken, Task<List<ModelInfo>>>? OnListModels { get; set; }
 
+    /// <summary>
+    /// OpenTelemetry configuration for the CLI server.
+    /// When set to a non-<see langword="null"/> instance, the CLI server is started with OpenTelemetry instrumentation enabled.
+    /// </summary>
+    public TelemetryConfig? Telemetry { get; set; }
+
     /// <summary>
     /// Creates a shallow clone of this <see cref="CopilotClientOptions"/> instance.
     /// </summary>
@@ -163,6 +170,52 @@ public virtual CopilotClientOptions Clone()
     }
 }
 
+/// <summary>
+/// OpenTelemetry configuration for the Copilot CLI server.
+/// </summary>
+public sealed class TelemetryConfig
+{
+    /// <summary>
+    /// OTLP exporter endpoint URL.
+    /// </summary>
+    /// <remarks>
+    /// Maps to the <c>OTEL_EXPORTER_OTLP_ENDPOINT</c> environment variable.
+    /// </remarks>
+    public string? OtlpEndpoint { get; set; }
+
+    /// <summary>
+    /// File path for the file exporter.
+    /// </summary>
+    /// <remarks>
+    /// Maps to the <c>COPILOT_OTEL_FILE_EXPORTER_PATH</c> environment variable.
+    /// </remarks>
+    public string? FilePath { get; set; }
+
+    /// <summary>
+    /// Exporter type (<c>"otlp-http"</c> or <c>"file"</c>).
+    /// </summary>
+    /// <remarks>
+    /// Maps to the <c>COPILOT_OTEL_EXPORTER_TYPE</c> environment variable.
+    /// </remarks>
+    public string? ExporterType { get; set; }
+
+    /// <summary>
+    /// Source name for telemetry spans.
+    /// </summary>
+    /// <remarks>
+    /// Maps to the <c>COPILOT_OTEL_SOURCE_NAME</c> environment variable.
+    /// </remarks>
+    public string? SourceName { get; set; }
+
+    /// <summary>
+    /// Whether to capture message content as part of telemetry.
+    /// </summary>
+    /// <remarks>
+    /// Maps to the <c>OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT</c> environment variable.
+    /// </remarks>
+    public bool? CaptureContent { get; set; }
+}
+
 /// <summary>
 /// Represents a binary result returned by a tool invocation.
 /// </summary>

dotnet/test/TelemetryTests.cs

@@ -0,0 +1,65 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+using System.Diagnostics;
+using Xunit;
+
+namespace GitHub.Copilot.SDK.Test;
+
+public class TelemetryTests
+{
+    [Fact]
+    public void TelemetryConfig_DefaultValues_AreNull()
+    {
+        var config = new TelemetryConfig();
+
+        Assert.Null(config.OtlpEndpoint);
+        Assert.Null(config.FilePath);
+        Assert.Null(config.ExporterType);
+        Assert.Null(config.SourceName);
+        Assert.Null(config.CaptureContent);
+    }
+
+    [Fact]
+    public void TelemetryConfig_CanSetAllProperties()
+    {
+        var config = new TelemetryConfig
+        {
+            OtlpEndpoint = "http://localhost:4318",
+            FilePath = "/tmp/traces.json",
+            ExporterType = "otlp-http",
+            SourceName = "my-app",
+            CaptureContent = true
+        };
+
+        Assert.Equal("http://localhost:4318", config.OtlpEndpoint);
+        Assert.Equal("/tmp/traces.json", config.FilePath);
+        Assert.Equal("otlp-http", config.ExporterType);
+        Assert.Equal("my-app", config.SourceName);
+        Assert.True(config.CaptureContent);
+    }
+
+    [Fact]
+    public void CopilotClientOptions_Telemetry_DefaultsToNull()
+    {
+        var options = new CopilotClientOptions();
+
+        Assert.Null(options.Telemetry);
+    }
+
+    [Fact]
+    public void CopilotClientOptions_Clone_CopiesTelemetry()
+    {
+        var telemetry = new TelemetryConfig
+        {
+            OtlpEndpoint = "http://localhost:4318",
+            ExporterType = "otlp-http"
+        };
+
+        var options = new CopilotClientOptions { Telemetry = telemetry };
+        var clone = options.Clone();
+
+        Assert.Same(telemetry, clone.Telemetry);
+    }
+}

go/README.md

@@ -495,6 +495,8 @@ client, err := copilot.NewClient(copilot.ClientOptions{
 
 Trace context (`traceparent`/`tracestate`) is automatically propagated between the SDK and CLI on `CreateSession`, `ResumeSession`, and `Send` calls, and inbound when the CLI invokes tool handlers.
 
+> **Note:** The current `ToolHandler` signature does not accept a `context.Context`, so the inbound trace context cannot be passed to handler code. Spans created inside a tool handler will not be automatically parented to the CLI's `execute_tool` span. A future version may add a context parameter.
+
 Dependency: `go.opentelemetry.io/otel`
 
 ## User Input Requests