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

> Explore Copilot SDK telemetry and analytics. Configure OpenTelemetry, manage content capture, and forward GitHub telemetry for deep insights. Learn best practices.

- Repository: [GitHub/copilot-sdk](https://github.com/github/copilot-sdk)
- Tags: how-to-guide
- Published: 2026-07-20

---

**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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/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`](https://github.com/github/copilot-sdk/blob/main/nodejs/test/client.test.ts).