Copilot SDK Telemetry and Analytics: Configuration, Implementation, and Best Practices

The Copilot SDK provides comprehensive telemetry and analytics capabilities including OpenTelemetry integration, content capture controls, GitHub telemetry forwarding, and per-session management through the TelemetryConfig interface.

The github/copilot-sdk repository embeds a production-ready telemetry system designed for enterprise observability requirements. Understanding Copilot SDK telemetry configuration options enables developers to capture runtime metrics, debug AI interactions, and maintain strict control over sensitive data exposure while maintaining compliance with organizational privacy policies.

Core Telemetry Configuration

The SDK exposes telemetry settings through the TelemetryConfig interface defined in nodejs/src/types.ts. These configurations apply globally to the CopilotClient instance and determine how telemetry data is collected, filtered, and transmitted.

OpenTelemetry Support

You can integrate with existing observability stacks by providing an otlpEndpoint in your configuration. When specified, the SDK automatically sets the related environment variables for the spawned runtime, enabling standard tracing and metrics collection compatible with OpenTelemetry collectors.

According to the source code in nodejs/src/types.ts (lines 332-338), the telemetry option accepts an OTLP endpoint string that routes telemetry to your specified collector. This allows the Copilot SDK telemetry to appear alongside your application's existing traces in tools like Jaeger, Zipkin, or vendor-specific observability platforms.

Content Capture Controls

Privacy-sensitive deployments can disable payload logging using the captureContent boolean flag. When set to false, the SDK excludes request and response contents—including prompts and completions—from telemetry streams while still capturing metadata and performance metrics.

The test suite in nodejs/test/telemetry.test.ts (lines 125-131) verifies this behavior, confirming that the captureContent setting properly gates whether message contents appear in exported telemetry events.

GitHub Telemetry Forwarding

For first-party hosts requiring raw telemetry streams, the SDK supports real-time event forwarding through the onGitHubTelemetry callback. This mechanism, defined in nodejs/src/types.ts (lines 97-104), transmits every internal telemetry event—including restricted-data events—over the JSON-RPC gitHubTelemetry.event notification protocol.

This forwarding mechanism gives host applications access to GitHub-shaped telemetry schemas, enabling seamless integration with existing GitHub analytics pipelines while respecting the restricted flag present on sensitive events.

Session-Level Telemetry Management

Individual sessions expose granular telemetry controls through the rpc.telemetry namespace, allowing runtime adjustments without recreating the client instance.

Engagement IDs and Correlation

Each session provides a unique engagement ID accessible via session.rpc.telemetry.getEngagementId(). As implemented in nodejs/test/e2e/rpc_session_state_extras.e2e.test.ts (lines 306-310), this identifier enables end-to-end correlation of telemetry events across distributed systems, linking specific user interactions with backend processing spans.

Dynamic Feature Overrides

Runtime configuration changes are supported through session.rpc.telemetry.setFeatureOverrides(), which programmatically enables or disables specific telemetry features for an active session. The implementation in nodejs/test/e2e/rpc_session_state.e2e.test.ts (lines 424-428) demonstrates how to toggle settings like captureContent mid-session without terminating the connection.

Distributed Tracing Integration

The SDK supports W3C trace context propagation through the TraceContextProvider mechanism. By supplying an onGetTraceContext callback, you can inject current trace context into every RPC call, allowing your existing spans to merge with the SDK's internal traces.

The nodejs/src/telemetry.ts file (lines 15-27) implements the getTraceContext helper, which extracts context from the active span and serializes it for RPC transmission. This ensures distributed traces flow through the Copilot SDK telemetry pipeline and connect with your application-level observability.

Local Development and Debugging

For offline analysis and debugging scenarios, the SDK supports file-based telemetry export through the filePath configuration option. When specified in TelemetryConfig, the SDK emits JSON-L (JSON Lines) formatted events to the specified filesystem path.

The test coverage in nodejs/test/client.test.ts (lines 322-324) validates this file exporter path, confirming that telemetry entries are written as newline-delimited JSON objects suitable for post-processing with standard log analysis tools.

Implementation Examples

Production Configuration with OpenTelemetry

Configure the Copilot SDK telemetry pipeline to forward traces to an OpenTelemetry collector while capturing content for debugging:

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

const telemetry: TelemetryConfig = {
  otlpEndpoint: "http://localhost:4318",
  captureContent: true,
};

function getTraceContext() {
  const carrier: Record<string, string> = {};
  // Example using @opentelemetry/api:
  // propagation.inject(context.active(), carrier);
  return carrier;
}

const client = new CopilotClient({
  telemetry,
  onGetTraceContext: getTraceContext,
  onGitHubTelemetry: async (note) => {
    console.log("GitHub telemetry event:", note);
  },
});

const session = await client.session.create();
await session.rpc.telemetry.setFeatureOverrides({ captureContent: false });
const engId = await session.rpc.telemetry.getEngagementId();
console.log("Engagement ID:", engId);

Local File Export for Analysis

Export telemetry to a JSON-L file for offline inspection:

import { join } from "path";
import { readFile } from "fs/promises";
import { CopilotClient } from "@github/copilot-sdk";

const telemetryPath = join(process.cwd(), "telemetry.jsonl");
const client = new CopilotClient({
  telemetry: { filePath: telemetryPath },
});

await client.session.create();
// Execute workflow...

const entries = (await readFile(telemetryPath, "utf8"))
  .trim()
  .split("\n")
  .map(line => JSON.parse(line));

entries.forEach(entry => console.log(entry));

Summary

• OpenTelemetry integration via otlpEndpoint in nodejs/src/types.ts enables standard observability pipeline integration.
• Content filtering through captureContent and per-session overrides protects sensitive prompt data while preserving metrics.
• GitHub forwarding via onGitHubTelemetry provides real-time access to internal telemetry events shaped for GitHub analytics.
• Trace correlation using getEngagementId() and TraceContextProvider connects SDK traces with application spans.
• File export to JSON-L format supports local debugging workflows without external dependencies.

Frequently Asked Questions

How do I disable content capture in Copilot SDK telemetry?

Set captureContent: false in your TelemetryConfig object when initializing CopilotClient, or call session.rpc.telemetry.setFeatureOverrides({ captureContent: false }) at runtime. The test suite in nodejs/test/telemetry.test.ts verifies that this prevents prompts and completions from appearing in telemetry streams while maintaining event metadata collection.

What is the difference between OTLP and GitHub telemetry forwarding?

OTLP forwarding sends OpenTelemetry-formatted traces and metrics to a standard collector endpoint specified by otlpEndpoint. GitHub telemetry forwarding via onGitHubTelemetry emits GitHub-specific event schemas through JSON-RPC notifications, including events marked as restricted that might be filtered from standard OTLP streams. Use OTLP for observability platforms and GitHub forwarding for analytics pipelines expecting GitHub's native telemetry shapes.

How can I correlate Copilot SDK telemetry with my existing traces?

Implement the onGetTraceContext callback to return your current W3C trace context, which the SDK injects into RPC calls as shown in nodejs/src/telemetry.ts. Additionally, retrieve the unique engagement ID from session.rpc.telemetry.getEngagementId() to tag your application's logs and spans, enabling correlation with SDK-internal telemetry events.

Where does the Copilot SDK store telemetry data by default?

By default, the SDK does not persist telemetry to local storage; it either streams to the specified otlpEndpoint, forwards via onGitHubTelemetry, or buffers temporarily in memory. To capture telemetry to disk, explicitly configure the filePath option in TelemetryConfig to write JSON-L formatted events to your specified filesystem path, as validated in nodejs/test/client.test.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}