Monitor agent usage with OpenTelemetry

This article describes how to enable and configure OpenTelemetry monitoring for Copilot Chat agent interactions in VS Code.

Copilot Chat can export traces, metrics, and events via OpenTelemetry (OTel), giving you visibility into agent interactions, LLM calls, tool executions, and token usage. All signal names and attributes follow the OTel GenAI Semantic Conventions, so the data works with any OTel-compatible backend.

What gets collected

Copilot Chat emits three types of OTel signals: traces, metrics, and events.

Attribute namespaces

Copilot Chat emits OTel attributes under three namespaces:

Legacy copilot_chat.* keys continue to emit indefinitely so existing collectors, dashboards, and downstream consumers keep working without changes. There is no sunset date. The tables in this section mark dual-emitted rows as Legacy with a pointer to the preferred key.

Traces

Each agent interaction produces a hierarchical span tree that captures the full execution flow:

invoke_agent copilot                           [~15s]
  ├── chat gpt-4o                              [~3s]  (LLM requests tool calls)
  ├── execute_tool readFile                    [~50ms]
  ├── execute_tool runCommand                  [~2s]
  ├── chat gpt-4o                              [~4s]  (LLM generates final response)
  └── (span ends)

When an agent invokes a subagent (for example, through the runSubagent tool), the trace context is automatically propagated. The subagent's invoke_agent span appears as a child of the parent agent's execute_tool span, producing a connected trace tree across async boundaries.

invoke_agent span

Wraps the entire agent orchestration, including all LLM calls and tool executions.

chat span

One span per LLM API call.

execute_tool span

One span per tool invocation.

execute_hook span

One span per hook execution (for example, PreToolUse, Stop).

Metrics

GenAI semantic-convention metrics:

Extension-specific metrics:

Agent activity and outcome metrics track agentic code changes across all surfaces (inline chat, local agents, Copilot agents, Claude agents, and Copilot cloud agents):

Metrics include attributes for filtering, such as gen_ai.request.model, gen_ai.provider.name, gen_ai.tool.name, copilot_chat.edit.source, and error.type.

Events

Resource attributes

All signals carry these resource attributes:

Add custom resource attributes with OTEL_RESOURCE_ATTRIBUTES to filter by team, department, or other organizational boundaries:

export OTEL_RESOURCE_ATTRIBUTES="team.id=platform,department=engineering"

Identity capture

For Local harness sessions, identity capture can attribute agent activity to an individual developer and machine. When enabled, telemetry includes:

• user.name on agent invocation spans, including subagent and inline chat spans.
• process.user.name and host.name as resource attributes.

Enable identity capture with github.copilot.chat.otel.captureIdentity Open in VS Code Open in VS Code Insiders or COPILOT_OTEL_CAPTURE_IDENTITY=true. This control is independent of content capture.

Content capture

By default, no prompt content, responses, or tool arguments are captured. Only metadata like model names, token counts, and durations are included.

To capture full content, enable the github.copilot.chat.otel.captureContent Open in VS Code Open in VS Code Insiders setting or set COPILOT_OTEL_CAPTURE_CONTENT=true. This populates span attributes with full prompt messages, response messages, system prompts, tool schemas, tool arguments, and tool results.

Enable OTel monitoring

OTel activates when any of the following conditions is true:

• github.copilot.chat.otel.enabled Open in VS Code Open in VS Code Insiders is true
• github.copilot.chat.otel.dbSpanExporter.enabled Open in VS Code Open in VS Code Insiders is true
• COPILOT_OTEL_ENABLED=true
• OTEL_EXPORTER_OTLP_ENDPOINT is set

VS Code settings

Open Settings (⌘, (Windows, Linux Ctrl+,)) and search for copilot otel:

Environment variables

Environment variables always take precedence over VS Code settings. When your organization mandates OTel configuration through Copilot managed settings, those managed values override user settings. In the Copilot Chat extension, OTel environment variables can still override managed values.

Commands

When github.copilot.chat.otel.dbSpanExporter.enabled Open in VS Code Open in VS Code Insiders is true, Copilot Chat persists OTel spans to a local SQLite database. This is useful for offline inspection or sharing trace data without running an OTLP backend.

Manage OTel configuration for your organization

Enterprises can mandate OTel export configuration centrally through Copilot enterprise-managed settings, without each developer setting OTEL_* environment variables. Managed telemetry configuration applies to both the Copilot Chat extension and the Agent Host process. In addition to collector export, Copilot Agent Host sessions support a managed file destination.

For delivery methods, configuration fields, client support, and precedence, see telemetry in the enterprise-managed settings reference. For the behavior specific to VS Code, see Apply managed telemetry in VS Code.

For Local harness sessions, VS Code automatically tries once per editor session to restart the extension hosts when a managed OTel configuration that enables export arrives after Copilot Chat starts. The restart can interrupt other extensions. If the automatic restart can't complete, or for later policy changes, select Reload Window when prompted.

Export managed telemetry to a file

Starting with VS Code 1.143, administrators can set telemetry.filePath to save Copilot Agent Host telemetry as JSON Lines (JSONL), without running an OTLP collector or requiring developers to opt in through personal OTel settings. This managed destination is separate from the Copilot Chat extension's file exporter.

For a local Agent Host, add the following telemetry block to the device-wide managed-settings.json file, not your editor settings JSON:

{
  "telemetry": {
    "filePath": "~/copilot-telemetry/copilot-otel.jsonl",
    "captureContent": false,
    "capture": {
      "identity": false
    }
  }
}

Choose an absolute or home-relative output path that the Agent Host can write to. Paths refer to the machine that exports the telemetry. The ~/ prefix expands to that machine's user home directory. Environment-variable references such as $HOME or %USERPROFILE% in filePath are not expanded and are rejected.

Setting filePath enables Agent Host OTel export without enabled: true. An explicit managed telemetry.enabled: false takes precedence and turns off export.

After VS Code resolves a managed telemetry change, it restarts the local Agent Host automatically. Start a new Copilot Agent Host session and send a prompt, then check the destination file for spans such as invoke_agent and vscode.agent_host.session.

The exporter creates missing parent directories and appends one span per line. If it cannot resolve the path or write to the file, the Agent Host logs an error without blocking chat. It does not fall back to a collector. Apply your organization's access and retention controls to the exported files.

To remove the managed file destination, remove telemetry.filePath from the effective managed configuration. After the change is applied, another configured collector or personal Agent Host exporter can become effective again. Removing filePath stops all export only when no other exporter is configured. To turn off Agent Host OTel export through managed settings, set telemetry.enabled to false.

Configure dynamic headers

Starting with VS Code 1.143, administrators can configure telemetry.headersProvider for Copilot Agent Host sessions to generate and refresh HTTP headers for OTLP export. The Agent Host runs a helper executable to obtain header values, so developers don't need to update them manually. Use these headers to supply collector-specific metadata, route telemetry, or authenticate with the collector.

Configure the provider through Copilot enterprise-managed settings, not your editor settings JSON. For example, deploy the following telemetry block in managed-settings.json:

{
  "telemetry": {
    "enabled": true,
    "endpoint": "https://<collector-host>:4318",
    "protocol": "http/protobuf",
    "captureContent": false,
    "capture": {
      "identity": false
    },
    "headers": {
      "x-organization": "<organization-id>"
    },
    "headersProvider": {
      "path": "<absolute-path-to-header-helper>",
      "args": [],
      "refreshIntervalMs": 1740000
    }
  }
}

Replace the endpoint, organization ID, and helper path with your deployment values. Install the helper and its dependencies on the machine where the Agent Host runs. For remote sessions, the executable and paths must exist on the remote host.

The helper runs from the execution host's home directory, with the arguments in args passed without shell evaluation. It must finish within 30 seconds and write a JSON object with string values to standard output:

{
  "x-team": "platform",
  "x-environment": "production"
}

The helper can also return an Authorization header when the collector requires authentication.

The provider refreshes headers every 29 minutes by default. Set refreshIntervalMs to match how often your header values need to be refreshed. Returning {} clears dynamic headers. If a refresh fails, exports that require dynamic headers are blocked until the provider refreshes successfully.

Headers returned by the provider take precedence over managed static telemetry.headers values with the same name. Nonconflicting static headers remain in the request. Managed headers also take precedence over user-provided headers.

The provider requires an endpoint in the same telemetry block and supports HTTP OTLP export with http/protobuf or http/json, not gRPC. Managed export does not require developers to opt in through personal OTel settings.

Higher-precedence managed sources replace the entire telemetry block. Include all required fields in the winning source rather than splitting the endpoint and provider across delivery methods. See managed-settings delivery precedence and the header provider reference for more information.

Trace structure by harness

When OTel is enabled, the Copilot and Claude integrations described in this section are automatically instrumented. The same settings used for Local harness session traces also enable traces for these integrations.

Copilot harness

The shared runtime for Copilot harness sessions runs in the same VS Code process as the chat extension and produces a rich trace hierarchy that includes subagents, permissions, hooks, and tool calls. The extension wrapper span (invoke_agent copilotcli, service copilot-chat) parents the runtime's native spans (service github-copilot). Both appear in the same trace in your collector.

Copilot harness sessions also show the full runtime trace hierarchy in the Agent Debug Logs panel in VS Code, identical to what appears in your trace viewer. The debug panel works even when OTel export is disabled, because the runtime's internal tracing is always active for the panel.

When OTel export is disabled, the debug panel automatically captures full prompt and response content. When OTel export is enabled, the github.copilot.chat.otel.captureContent Open in VS Code Open in VS Code Insiders setting controls content capture for both the debug panel and OTLP export.

Copilot CLI (terminal session)

When you run a Copilot CLI session in the terminal (New Copilot CLI Session), it runs in a separate process. When OTel is enabled, the extension forwards COPILOT_OTEL_ENABLED and OTEL_EXPORTER_OTLP_ENDPOINT to the terminal process. Terminal traces appear as independent root traces under service github-copilot and are not linked to extension traces.

The CLI runtime only supports otlp-http. When otlp-grpc is configured, the terminal CLI still uses HTTP. Backends that serve both protocols on the same port (such as the Aspire Dashboard) work transparently.

Claude agent

When OTel is enabled, Claude agent sessions produce extension-level spans under service copilot-chat that follow the GenAI semantic conventions. The extension creates spans by intercepting Claude SDK messages and proxying LLM calls through a local HTTP server.

The invoke_agent claude root span wraps each user request, with nested chat, execute_tool, and execute_hook spans. When the tool is Agent (a Claude subagent invocation), child chat and execute_tool spans are nested underneath, giving full subagent visibility.

Filter by agent type

In your trace viewer, filter by service.name to see traces from specific agent runtimes:

Within the copilot-chat service, distinguish agent types by gen_ai.agent.name:

Use with observability backends

Copilot Chat's OTel output works with any backend that supports the OTLP protocol. Point the github.copilot.chat.otel.otlpEndpoint Open in VS Code Open in VS Code Insiders setting or OTEL_EXPORTER_OTLP_ENDPOINT environment variable at the backend's OTLP ingestion URL, and configure the exporter type to match the backend's protocol (otlp-http or otlp-grpc).

Aspire Dashboard

The Aspire Dashboard is the simplest option for local development. It is a single app with a built-in OTLP endpoint and trace viewer, and requires no cloud account.

You can start the dashboard using the Aspire CLI:

aspire dashboard run

Or run the same standalone dashboard from its Docker container image:

docker run --rm -d -p 18888:18888 -p 4318:18890 --name aspire-dashboard \
  mcr.microsoft.com/dotnet/aspire-dashboard:latest

VS Code configuration:

{
  "github.copilot.chat.otel.enabled": true,
  "github.copilot.chat.otel.captureContent": true
}

Open http://localhost:18888 and go to Traces to view your agent interaction spans.

Jaeger

Jaeger is an open-source distributed tracing platform that accepts OTLP directly.

docker run -d --name jaeger -p 16686:16686 -p 4318:4318 jaegertracing/jaeger:latest

VS Code configuration:

{
  "github.copilot.chat.otel.enabled": true,
  "github.copilot.chat.otel.otlpEndpoint": "http://localhost:4318"
}

Open http://localhost:16686, select service copilot-chat, and select Find Traces.

Azure Application Insights

Use an OTel Collector with the Azure Monitor exporter to forward Copilot Chat telemetry to Application Insights. Point the VS Code github.copilot.chat.otel.otlpEndpoint Open in VS Code Open in VS Code Insiders setting at the collector's OTLP endpoint, and configure the collector to export to your Application Insights connection string.

For an end-to-end setup with a ready-made dashboard, see Monitor AI coding agents with Grafana. The guide walks through running the OTel Collector, pointing VS Code at it, and importing a prebuilt Azure Managed Grafana dashboard. The dashboard visualizes Copilot operations, input and output tokens, chat sessions, tool calls, and per-model response time and TTFT from Application Insights.

Langfuse

Langfuse is an open-source LLM observability platform with native OTLP ingestion and support for OTel GenAI Semantic Conventions.

VS Code configuration:

{
  "github.copilot.chat.otel.enabled": true,
  "github.copilot.chat.otel.otlpEndpoint": "http://localhost:3000/api/public/otel",
  "github.copilot.chat.otel.captureContent": true
}

Set the auth header with the OTEL_EXPORTER_OTLP_HEADERS environment variable. See the Langfuse OTel docs for details.

Other backends

Any OTLP-compatible backend works, including Grafana Tempo, Honeycomb, and Datadog. Refer to each backend's documentation for OTLP ingestion setup.

Other exporter examples

The default exporter is otlp-http. You can switch to otlp-grpc, console, or file to fit your backend or debugging workflow.

OTLP/gRPC:

{
  "github.copilot.chat.otel.enabled": true,
  "github.copilot.chat.otel.exporterType": "otlp-grpc",
  "github.copilot.chat.otel.otlpEndpoint": "http://localhost:4317"
}

Console output (quick debugging):

{
  "github.copilot.chat.otel.enabled": true,
  "github.copilot.chat.otel.exporterType": "console"
}

File-based output from the Copilot Chat extension (offline or CI):

{
  "github.copilot.chat.otel.enabled": true,
  "github.copilot.chat.otel.exporterType": "file",
  "github.copilot.chat.otel.outfile": "/tmp/copilot-otel.jsonl"
}

For organization-managed output from Copilot Agent Host sessions, see Export managed telemetry to a file.

For static HTTP headers, set OTEL_EXPORTER_OTLP_HEADERS. Administrators can also configure managed static headers and, for Copilot Agent Host sessions, dynamic headers.

Security and privacy

OTel monitoring is off by default. You or your organization must configure monitoring before data is exported. For managed deployments, your organization controls what is collected and where it goes.

Related content

• AI settings reference
• Manage AI settings in enterprise environments
• Troubleshoot AI in VS Code
• Diagnose prompt caching with the Cache Explorer
• OTel GenAI Semantic Conventions
• Inside the LLM Call: GenAI Observability with OpenTelemetry
• Aspire Dashboard standalone docs
• Video: Tracing agent sessions with OpenTelemetry and Aspire