Claude code exports telemetry natively using OpenTelemetry (source: official documentation). Span is prepared to receive these metrics and process them to generate Claude Code related usage data. This means that each Claude Code user must configure our backend as their exporting endpoint in order for us to be able to receive the data.

Luckily, Claude Code has a flexible system to configure the settings in which we can setup managed settings: just by creating a managed-settings.json file:

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json

• Linux and WSL: /etc/claude-code/managed-settings.json

• Windows: C:\\ProgramData\\ClaudeCode\\managed-settings.json

Note: The legacy Windows path C:\ProgramData\ClaudeCode\managed-settings.json is no longer supported as of v2.1.75. Administrators who deployed settings to that location must migrate files to C:\Program Files\ClaudeCode\managed-settings.json.

Enable the integration

Head to the AI tool settings dashboard (https://span.app/_/settings/integrations) and enable the tool using the corresponding switch to the right:

Once you enable a tool, you’ll be able to access the token that you have to use to authenticate against our Otel backend:

OpenTelemetry Settings

The configurations of the managed-settings.json file should contain the following environment variables:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otel.span.app:443",
    "OTEL_EXPORTER_OTLP_HEADERS": "X-Span-Token=<PROVIDED_TOKEN>",
    "OTEL_RESOURCE_ATTRIBUTES": "work_email=<USER_EMAIL>"
  }
}

You can get the X-Span-Token from https://span.app/_/settings/integrations which you’ll have to include in all clients (see previous steps). This is important because without it, the metrics will be rejected by our servers.

OTEL_RESOURCE_ATTRIBUTES is optional but recommended: Claude Code generated telemetry will include the user’s email. The email is configured when the user starts Claude Code for the first time and is prompted to login. Because it is what we use to attribute the metrics to each developer, it MUST match the email address that they have registered in Span. If the developers are logging in with a different email address then you can still override it by setting the appropriate one in the work_email, which will take precedence in our internal attribution pipeline over the native one.

Distributing Settings

Any method that allows you to create the JSON file in the developer’s workstation will suffice, but we recommend doing it via MDM. Each MDM provider works differently, so there’s no way to enumerate all the options. The most common case, however, is for MDM services to distribute and execute a script. You can use the following script to create the file (replacing the placeholder values):

#!/usr/bin/env bash

set -e

# remember the location depends on the OS Claude Code will be running
mkdir -p '/Library/Application Support/ClaudeCode'

echo '{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otel.span.app:443",
    "OTEL_EXPORTER_OTLP_HEADERS": "X-Span-Token=<PROVIDED_TOKEN>",
    "OTEL_RESOURCE_ATTRIBUTES": "work_email=<USER_EMAIL>"
  }
}' > '/Library/Application Support/ClaudeCode/managed-settings.json'

PROVIDED_TOKEN will be the same for all your developers, but USER_EMAIL must be replaced by the email address of the corresponding developer that will use the workstation. For example, when using Mosyle we replaced it by the variable %Email%

Claude Code won’t refresh the settings of running sessions. In order for them to be applied, every Claude Code instance must be restarted.

Monitoring the integration status

In the AI settings dashboard you’ll see an entry for each support tool that sends telemetry via Otel. If the tool is enabled, you’ll see a health indicator showing the status. You can hover over it to see the date of the last message received:

You can use this to test your setup after deploying the configuration. Note that it might take a couple of minutes for the data to be reflected there, but if you see that it shows up as green it means that at least 1 setup is working.