Add OTLP protocol telemetry options

Expose OTLP HTTP protocol selection through each SDK telemetry config and map the values to the standard OpenTelemetry protocol environment variables when spawning the Copilot CLI.

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

Author: loganrosen

docs/getting-started.md

@@ -2227,11 +2227,16 @@ Dependency: `io.opentelemetry:opentelemetry-api`
 | Option | Node.js | Python | Go | Rust | Java | .NET | Description |
 |---|---|---|---|---|---|---|---|
 | OTLP endpoint | `otlpEndpoint` | `otlp_endpoint` | `OTLPEndpoint` | `otlp_endpoint` | `otlpEndpoint` | `OtlpEndpoint` | OTLP HTTP endpoint URL |
+| OTLP protocol | `otlpProtocol` | `otlp_protocol` | `OTLPProtocol` | `otlp_protocol` | `otlpProtocol` | `OtlpProtocol` | OTLP HTTP protocol for all signals: `"http/json"` or `"http/protobuf"` |
+| OTLP traces protocol | `otlpTracesProtocol` | `otlp_traces_protocol` | `OTLPTracesProtocol` | `otlp_traces_protocol` | `otlpTracesProtocol` | `OtlpTracesProtocol` | OTLP HTTP protocol override for traces |
+| OTLP metrics protocol | `otlpMetricsProtocol` | `otlp_metrics_protocol` | `OTLPMetricsProtocol` | `otlp_metrics_protocol` | `otlpMetricsProtocol` | `OtlpMetricsProtocol` | OTLP HTTP protocol override for metrics |
 | File path | `filePath` | `file_path` | `FilePath` | `file_path` | `filePath` | `FilePath` | File path for JSON-lines trace output |
 | Exporter type | `exporterType` | `exporter_type` | `ExporterType` | `exporter_type` | `exporterType` | `ExporterType` | `"otlp-http"` or `"file"` |
 | Source name | `sourceName` | `source_name` | `SourceName` | `source_name` | `sourceName` | `SourceName` | Instrumentation scope name |
 | Capture content | `captureContent` | `capture_content` | `CaptureContent` | `capture_content` | `captureContent` | `CaptureContent` | Whether to capture message content |
 
+The OTLP protocol fields configure the CLI's `"otlp-http"` exporter. Leave them unset to use the CLI default (`"http/json"`), set the general protocol for both traces and metrics, or use the traces/metrics fields to override one signal.
+
 ### File export
 
 To write traces to a local file instead of an OTLP endpoint:

docs/observability/opentelemetry.md

@@ -104,11 +104,16 @@ let client = Client::start(ClientOptions::new()
 | Option | Node.js | Python | Go | .NET | Java | Rust | Description |
 |---|---|---|---|---|---|---|---|
 | OTLP endpoint | `otlpEndpoint` | `otlp_endpoint` | `OTLPEndpoint` | `OtlpEndpoint` | `otlpEndpoint` | `otlp_endpoint` | OTLP HTTP endpoint URL |
+| OTLP protocol | `otlpProtocol` | `otlp_protocol` | `OTLPProtocol` | `OtlpProtocol` | `otlpProtocol` | `otlp_protocol` | OTLP HTTP protocol for all signals: `"http/json"` or `"http/protobuf"` |
+| OTLP traces protocol | `otlpTracesProtocol` | `otlp_traces_protocol` | `OTLPTracesProtocol` | `OtlpTracesProtocol` | `otlpTracesProtocol` | `otlp_traces_protocol` | OTLP HTTP protocol override for traces |
+| OTLP metrics protocol | `otlpMetricsProtocol` | `otlp_metrics_protocol` | `OTLPMetricsProtocol` | `OtlpMetricsProtocol` | `otlpMetricsProtocol` | `otlp_metrics_protocol` | OTLP HTTP protocol override for metrics |
 | File path | `filePath` | `file_path` | `FilePath` | `FilePath` | `filePath` | `file_path` | File path for JSON-lines trace output |
 | Exporter type | `exporterType` | `exporter_type` | `ExporterType` | `ExporterType` | `exporterType` | `exporter_type` | `"otlp-http"` or `"file"` |
 | Source name | `sourceName` | `source_name` | `SourceName` | `SourceName` | `sourceName` | `source_name` | Instrumentation scope name |
 | Capture content | `captureContent` | `capture_content` | `CaptureContent` | `CaptureContent` | `captureContent` | `capture_content` | Whether to capture message content |
 
+The OTLP protocol fields configure the CLI's `"otlp-http"` exporter. Leave them unset to use the CLI default (`"http/json"`), set the general protocol for both traces and metrics, or use the traces/metrics fields to override one signal.
+
 ### Trace context propagation
 
 > **Most users don't need this.** The `TelemetryConfig` above is all you need to collect traces from the CLI. The trace context propagation described in this section is an **advanced feature** for applications that create their own OpenTelemetry spans and want them to appear in the **same distributed trace** as the CLI's spans.

dotnet/README.md

@@ -738,6 +738,9 @@ var client = new CopilotClient(new CopilotClientOptions
 **TelemetryConfig properties:**
 
 - `OtlpEndpoint` - OTLP HTTP endpoint URL
+- `OtlpProtocol` - OTLP HTTP protocol for all signals (`"http/json"` or `"http/protobuf"`)
+- `OtlpTracesProtocol` - OTLP HTTP protocol override for traces
+- `OtlpMetricsProtocol` - OTLP HTTP protocol override for metrics
 - `FilePath` - File path for JSON-lines trace output
 - `ExporterType` - `"otlp-http"` or `"file"`
 - `SourceName` - Instrumentation scope name

dotnet/src/Client.cs

@@ -1805,6 +1805,9 @@ private static bool IsUnsupportedConnectMethod(RemoteRpcException ex)
         {
             startInfo.Environment["COPILOT_OTEL_ENABLED"] = "true";
             if (telemetry.OtlpEndpoint is not null) startInfo.Environment["OTEL_EXPORTER_OTLP_ENDPOINT"] = telemetry.OtlpEndpoint;
+            if (telemetry.OtlpProtocol is not null) startInfo.Environment["OTEL_EXPORTER_OTLP_PROTOCOL"] = telemetry.OtlpProtocol;
+            if (telemetry.OtlpTracesProtocol is not null) startInfo.Environment["OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"] = telemetry.OtlpTracesProtocol;
+            if (telemetry.OtlpMetricsProtocol is not null) startInfo.Environment["OTEL_EXPORTER_OTLP_METRICS_PROTOCOL"] = telemetry.OtlpMetricsProtocol;
             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;

dotnet/src/Types.cs

@@ -413,6 +413,30 @@ public sealed class TelemetryConfig
     /// </remarks>
     public string? OtlpEndpoint { get; set; }
 
+    /// <summary>
+    /// OTLP HTTP protocol for all signals (<c>"http/json"</c> or <c>"http/protobuf"</c>).
+    /// </summary>
+    /// <remarks>
+    /// Maps to the <c>OTEL_EXPORTER_OTLP_PROTOCOL</c> environment variable.
+    /// </remarks>
+    public string? OtlpProtocol { get; set; }
+
+    /// <summary>
+    /// OTLP HTTP protocol for traces (<c>"http/json"</c> or <c>"http/protobuf"</c>).
+    /// </summary>
+    /// <remarks>
+    /// Maps to the <c>OTEL_EXPORTER_OTLP_TRACES_PROTOCOL</c> environment variable.
+    /// </remarks>
+    public string? OtlpTracesProtocol { get; set; }
+
+    /// <summary>
+    /// OTLP HTTP protocol for metrics (<c>"http/json"</c> or <c>"http/protobuf"</c>).
+    /// </summary>
+    /// <remarks>
+    /// Maps to the <c>OTEL_EXPORTER_OTLP_METRICS_PROTOCOL</c> environment variable.
+    /// </remarks>
+    public string? OtlpMetricsProtocol { get; set; }
+
     /// <summary>
     /// File path for the file exporter.
     /// </summary>

dotnet/test/E2E/ClientOptionsE2ETests.cs

@@ -78,6 +78,9 @@ public async Task Should_Propagate_Process_Options_To_Spawned_Cli()
             Telemetry = new TelemetryConfig
             {
                 OtlpEndpoint = "http://127.0.0.1:4318",
+                OtlpProtocol = "http/protobuf",
+                OtlpTracesProtocol = "http/json",
+                OtlpMetricsProtocol = "http/protobuf",
                 FilePath = telemetryPath,
                 ExporterType = "file",
                 SourceName = "dotnet-sdk-e2e",
@@ -104,6 +107,9 @@ public async Task Should_Propagate_Process_Options_To_Spawned_Cli()
         Assert.Equal("process-option-token", capturedEnv.GetProperty("COPILOT_SDK_AUTH_TOKEN").GetString());
         Assert.Equal("true", capturedEnv.GetProperty("COPILOT_OTEL_ENABLED").GetString());
         Assert.Equal("http://127.0.0.1:4318", capturedEnv.GetProperty("OTEL_EXPORTER_OTLP_ENDPOINT").GetString());
+        Assert.Equal("http/protobuf", capturedEnv.GetProperty("OTEL_EXPORTER_OTLP_PROTOCOL").GetString());
+        Assert.Equal("http/json", capturedEnv.GetProperty("OTEL_EXPORTER_OTLP_TRACES_PROTOCOL").GetString());
+        Assert.Equal("http/protobuf", capturedEnv.GetProperty("OTEL_EXPORTER_OTLP_METRICS_PROTOCOL").GetString());
         Assert.Equal(telemetryPath, capturedEnv.GetProperty("COPILOT_OTEL_FILE_EXPORTER_PATH").GetString());
         Assert.Equal("file", capturedEnv.GetProperty("COPILOT_OTEL_EXPORTER_TYPE").GetString());
         Assert.Equal("dotnet-sdk-e2e", capturedEnv.GetProperty("COPILOT_OTEL_SOURCE_NAME").GetString());
@@ -124,6 +130,32 @@ public async Task Should_Propagate_Process_Options_To_Spawned_Cli()
         await session.DisposeAsync();
     }
 
+    [Fact]
+    public async Task Should_Only_Set_Configured_Otlp_Protocol_Env_Vars()
+    {
+        var (cliPath, capturePath) = await CreateFakeCliCaptureAsync();
+
+        await using var client = Ctx.CreateClient(options: new CopilotClientOptions
+        {
+            Connection = RuntimeConnection.ForStdio(path: cliPath, args: ["--capture-file", capturePath]),
+            GitHubToken = "process-option-token",
+            Telemetry = new TelemetryConfig
+            {
+                OtlpTracesProtocol = "http/protobuf",
+            },
+            UseLoggedInUser = false,
+        });
+
+        await client.StartAsync();
+
+        using var capture = JsonDocument.Parse(await File.ReadAllTextAsync(capturePath));
+        var capturedEnv = capture.RootElement.GetProperty("env");
+        Assert.Equal("true", capturedEnv.GetProperty("COPILOT_OTEL_ENABLED").GetString());
+        Assert.Equal("http/protobuf", capturedEnv.GetProperty("OTEL_EXPORTER_OTLP_TRACES_PROTOCOL").GetString());
+        Assert.False(capturedEnv.TryGetProperty("OTEL_EXPORTER_OTLP_PROTOCOL", out _));
+        Assert.False(capturedEnv.TryGetProperty("OTEL_EXPORTER_OTLP_METRICS_PROTOCOL", out _));
+    }
+
     [Fact]
     public async Task Should_Forward_EnableSessionTelemetry_In_Wire_Request()
     {
@@ -642,6 +674,9 @@ function saveCapture() {
               COPILOT_SDK_AUTH_TOKEN: process.env.COPILOT_SDK_AUTH_TOKEN,
               COPILOT_OTEL_ENABLED: process.env.COPILOT_OTEL_ENABLED,
               OTEL_EXPORTER_OTLP_ENDPOINT: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+              OTEL_EXPORTER_OTLP_PROTOCOL: process.env.OTEL_EXPORTER_OTLP_PROTOCOL,
+              OTEL_EXPORTER_OTLP_TRACES_PROTOCOL: process.env.OTEL_EXPORTER_OTLP_TRACES_PROTOCOL,
+              OTEL_EXPORTER_OTLP_METRICS_PROTOCOL: process.env.OTEL_EXPORTER_OTLP_METRICS_PROTOCOL,
               COPILOT_OTEL_FILE_EXPORTER_PATH: process.env.COPILOT_OTEL_FILE_EXPORTER_PATH,
               COPILOT_OTEL_EXPORTER_TYPE: process.env.COPILOT_OTEL_EXPORTER_TYPE,
               COPILOT_OTEL_SOURCE_NAME: process.env.COPILOT_OTEL_SOURCE_NAME,

dotnet/test/Unit/TelemetryTests.cs

@@ -16,6 +16,9 @@ public void TelemetryConfig_DefaultValues_AreNull()
         var config = new TelemetryConfig();
 
         Assert.Null(config.OtlpEndpoint);
+        Assert.Null(config.OtlpProtocol);
+        Assert.Null(config.OtlpTracesProtocol);
+        Assert.Null(config.OtlpMetricsProtocol);
         Assert.Null(config.FilePath);
         Assert.Null(config.ExporterType);
         Assert.Null(config.SourceName);
@@ -28,13 +31,19 @@ public void TelemetryConfig_CanSetAllProperties()
         var config = new TelemetryConfig
         {
             OtlpEndpoint = "http://localhost:4318",
+            OtlpProtocol = "http/protobuf",
+            OtlpTracesProtocol = "http/json",
+            OtlpMetricsProtocol = "http/protobuf",
             FilePath = "/tmp/traces.json",
             ExporterType = "otlp-http",
             SourceName = "my-app",
             CaptureContent = true
         };
 
         Assert.Equal("http://localhost:4318", config.OtlpEndpoint);
+        Assert.Equal("http/protobuf", config.OtlpProtocol);
+        Assert.Equal("http/json", config.OtlpTracesProtocol);
+        Assert.Equal("http/protobuf", config.OtlpMetricsProtocol);
         Assert.Equal("/tmp/traces.json", config.FilePath);
         Assert.Equal("otlp-http", config.ExporterType);
         Assert.Equal("my-app", config.SourceName);

go/README.md

@@ -573,6 +573,9 @@ client, err := copilot.NewClient(copilot.ClientOptions{
 **TelemetryConfig fields:**
 
 - `OTLPEndpoint` (string): OTLP HTTP endpoint URL
+- `OTLPProtocol` (string): OTLP HTTP protocol for all signals (`"http/json"` or `"http/protobuf"`)
+- `OTLPTracesProtocol` (string): OTLP HTTP protocol override for traces
+- `OTLPMetricsProtocol` (string): OTLP HTTP protocol override for metrics
 - `FilePath` (string): File path for JSON-lines trace output
 - `ExporterType` (string): `"otlp-http"` or `"file"`
 - `SourceName` (string): Instrumentation scope name

go/client.go

@@ -1695,6 +1695,15 @@ func (c *Client) startCLIServer(ctx context.Context) error {
 		if t.OTLPEndpoint != "" {
 			c.process.Env = setEnvValue(c.process.Env, "OTEL_EXPORTER_OTLP_ENDPOINT", t.OTLPEndpoint)
 		}
+		if t.OTLPProtocol != "" {
+			c.process.Env = setEnvValue(c.process.Env, "OTEL_EXPORTER_OTLP_PROTOCOL", t.OTLPProtocol)
+		}
+		if t.OTLPTracesProtocol != "" {
+			c.process.Env = setEnvValue(c.process.Env, "OTEL_EXPORTER_OTLP_TRACES_PROTOCOL", t.OTLPTracesProtocol)
+		}
+		if t.OTLPMetricsProtocol != "" {
+			c.process.Env = setEnvValue(c.process.Env, "OTEL_EXPORTER_OTLP_METRICS_PROTOCOL", t.OTLPMetricsProtocol)
+		}
 		if t.FilePath != "" {
 			c.process.Env = setEnvValue(c.process.Env, "COPILOT_OTEL_FILE_EXPORTER_PATH", t.FilePath)
 		}

go/internal/e2e/client_options_e2e_test.go

@@ -109,11 +109,14 @@ func TestClientOptionsE2E(t *testing.T) {
 			opts.LogLevel = "debug"
 			opts.SessionIdleTimeoutSeconds = 17
 			opts.Telemetry = &copilot.TelemetryConfig{
-				OTLPEndpoint:   "http://127.0.0.1:4318",
-				FilePath:       telemetryPath,
-				ExporterType:   "file",
-				SourceName:     "go-sdk-e2e",
-				CaptureContent: copilot.Bool(true),
+				OTLPEndpoint:        "http://127.0.0.1:4318",
+				OTLPProtocol:        "http/protobuf",
+				OTLPTracesProtocol:  "http/json",
+				OTLPMetricsProtocol: "http/protobuf",
+				FilePath:            telemetryPath,
+				ExporterType:        "file",
+				SourceName:          "go-sdk-e2e",
+				CaptureContent:      copilot.Bool(true),
 			}
 			opts.UseLoggedInUser = copilot.Bool(false)
 		})
@@ -147,6 +150,9 @@ func TestClientOptionsE2E(t *testing.T) {
 			"COPILOT_SDK_AUTH_TOKEN":                             "process-option-token",
 			"COPILOT_OTEL_ENABLED":                               "true",
 			"OTEL_EXPORTER_OTLP_ENDPOINT":                        "http://127.0.0.1:4318",
+			"OTEL_EXPORTER_OTLP_PROTOCOL":                        "http/protobuf",
+			"OTEL_EXPORTER_OTLP_TRACES_PROTOCOL":                 "http/json",
+			"OTEL_EXPORTER_OTLP_METRICS_PROTOCOL":                "http/protobuf",
 			"COPILOT_OTEL_FILE_EXPORTER_PATH":                    telemetryPath,
 			"COPILOT_OTEL_EXPORTER_TYPE":                         "file",
 			"COPILOT_OTEL_SOURCE_NAME":                           "go-sdk-e2e",
@@ -195,6 +201,46 @@ func TestClientOptionsE2E(t *testing.T) {
 			t.Errorf("Expected session.create.params.includeSubAgentStreamingEvents=false, got %v", params["includeSubAgentStreamingEvents"])
 		}
 	})
+
+	t.Run("should only set configured OTLP protocol env vars", func(t *testing.T) {
+		ctx := testharness.NewTestContext(t)
+
+		cliPath := filepath.Join(ctx.WorkDir, "fake-cli-"+randomHex(t)+".js")
+		capturePath := filepath.Join(ctx.WorkDir, "fake-cli-capture-"+randomHex(t)+".json")
+		if err := os.WriteFile(cliPath, []byte(fakeStdioCliScript), 0644); err != nil {
+			t.Fatalf("Failed to write fake CLI script: %v", err)
+		}
+
+		client := ctx.NewClient(func(opts *copilot.ClientOptions) {
+			opts.Connection = copilot.StdioConnection{
+				Path: cliPath,
+				Args: []string{"--capture-file", capturePath},
+			}
+			opts.GitHubToken = "process-option-token"
+			opts.Telemetry = &copilot.TelemetryConfig{
+				OTLPTracesProtocol: "http/protobuf",
+			}
+			opts.UseLoggedInUser = copilot.Bool(false)
+		})
+		t.Cleanup(func() { client.ForceStop() })
+
+		if err := client.Start(t.Context()); err != nil {
+			t.Fatalf("Start failed: %v", err)
+		}
+
+		capture := readCapture(t, capturePath)
+		if got := capture.Env["COPILOT_OTEL_ENABLED"]; got != "true" {
+			t.Errorf("Expected COPILOT_OTEL_ENABLED=true, got %q", got)
+		}
+		if got := capture.Env["OTEL_EXPORTER_OTLP_TRACES_PROTOCOL"]; got != "http/protobuf" {
+			t.Errorf("Expected OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf, got %q", got)
+		}
+		for _, key := range []string{"OTEL_EXPORTER_OTLP_PROTOCOL", "OTEL_EXPORTER_OTLP_METRICS_PROTOCOL"} {
+			if got, ok := capture.Env[key]; ok {
+				t.Errorf("Expected %s to be unset, got %q", key, got)
+			}
+		}
+	})
 }
 
 // ---------------------------------------------------------------------------
@@ -372,6 +418,9 @@ function saveCapture() {
       COPILOT_SDK_AUTH_TOKEN: process.env.COPILOT_SDK_AUTH_TOKEN,
       COPILOT_OTEL_ENABLED: process.env.COPILOT_OTEL_ENABLED,
       OTEL_EXPORTER_OTLP_ENDPOINT: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+      OTEL_EXPORTER_OTLP_PROTOCOL: process.env.OTEL_EXPORTER_OTLP_PROTOCOL,
+      OTEL_EXPORTER_OTLP_TRACES_PROTOCOL: process.env.OTEL_EXPORTER_OTLP_TRACES_PROTOCOL,
+      OTEL_EXPORTER_OTLP_METRICS_PROTOCOL: process.env.OTEL_EXPORTER_OTLP_METRICS_PROTOCOL,
       COPILOT_OTEL_FILE_EXPORTER_PATH: process.env.COPILOT_OTEL_FILE_EXPORTER_PATH,
       COPILOT_OTEL_EXPORTER_TYPE: process.env.COPILOT_OTEL_EXPORTER_TYPE,
       COPILOT_OTEL_SOURCE_NAME: process.env.COPILOT_OTEL_SOURCE_NAME,