Настройка корпоративного OpenTelemetry для Claude Code

Экспорт OpenTelemetry в Claude Code — это санкционированный путь наблюдения для управляемого флота: он не ограничен тарифом, переносит телеметрию, привязанную к сессии, и уровень managed settings может включить его для каждого разработчика — без проксирования чего-либо. Эта страница — корпоративная конфигурация поверх Подключение Claude Code: что задать на уровне всего флота, что даёт каждая настройка и какую обязанность она создаёт. Имена ключей и семантика ниже были проверены по собственной документации Claude Code от 2026-06-10 (клиент 2.1.17x); перепроверяйте их там перед тем, как кодировать новые — они меняются быстро.

Что вы получаете

Настройка	Что она даёт	Обязанность, которую она создаёт
Managed-телеметрия `env`	Каждая сессия экспортирует OTLP в ваш коллектор — наблюдение, переживающее собственную конфигурацию разработчика	Никакой — структурная телеметрия по умолчанию
`OTEL_RESOURCE_ATTRIBUTES`	Заданные организацией метки (команда, проект, центр затрат) на каждой точке данных метрики и каждой записи события; control plane направляет их в измерения расходов FinOps	Держите значения меток нечувствительными; коннектор фильтрует их по allowlist и очищает
Бета-трассировка	Спаны `claude_code.llm_request` / `claude_code.tool` несут `agent_id` / `parent_agent_id` — иерархию субагентов на уровне экземпляров в графе доступа	Бета-поверхность: проверяйте при обновлении
`OTEL_LOG_TOOL_DETAILS=1`	`tool_parameters` в событиях инструментов — включая то, какая команда была отклонена при запрещённом решении по инструменту	Входные данные инструмента покидают хост: обязанность по резидентности/маскированию чувствительных данных, которую вы должны взять на себя
`OTEL_METRICS_INCLUDE_ENTRYPOINT=true`	`app.entrypoint` (cli / sdk-ts / claude-vscode …) — какая поверхность запустила каждую сессию	Никакой (метка низкой кардинальности)

Шаг 1 — включите экспорт на уровне managed

Опишите телеметрический env в вашей политике managed settings (хелпер TelemetryEnv коннектора managed-settings рендерит именно эту конфигурацию): включите телеметрию, направьте экспортёр OTLP на коллектор control plane и экспортируйте и метрики, и логи. За полным справочником переменных обращайтесь к собственной документации Claude Code по мониторингу — не копируйте значения отсюда вручную.

Захват содержимого (промпты, тела инструментов) остаётся выключенным, пока вы его не включите явно — и коннектор control plane независимо сохраняет только структурные данные, что бы ни эмитил клиент.

Шаг 2 — разметьте флот для FinOps

Задайте OTEL_RESOURCE_ATTRIBUTES в том же managed env, используя строгое форматирование W3C Baggage (значения с percent-кодированием; без пробелов и кавычек):

OTEL_RESOURCE_ATTRIBUTES=team=payments,project=atlas,cost_center=cc-42

С клиента 2.1.161 эти значения едут на каждой точке данных метрики и каждой записи события, а не только в блоке ресурсов OTLP — и пользовательские ключи никогда не переопределяют стандартные атрибуты. На control plane перечислите ключи, которые вы признаёте, в allowlist resource_labels коннектора claude; коннектор очищает значения и прикрепляет их как метки к рёбрам идентичности сессии и к каждому образцу затрат. FinOps повышает team и project до первоклассных измерений расходов, так что «разбить расходы Claude Code по команде» работает от начала до конца. Ключи, не входящие в allowlist, отбрасываются — минимум данных по умолчанию.

Шаг 3 — иерархия субагентов (бета-трассировка)

Включите бета-режим расширенной телеметрии плюс экспортёр трейсов в managed env, чтобы получить спаны. Атрибуты идентичности субагентов (agent_id, parent_agent_id) — только в спанах — они не появляются ни в одной метрике и ни в одном событии лога — и живут на спанах claude_code.llm_request (с 2.1.139) и claude_code.tool (с 2.1.145). Коннектор отображает их в граф доступа как:

session → identity.subagent — экземпляр субагента, который действовал, и
parent agent → identity.subagent — кто его породил (отсутствует для агентов, которых главная сессия породила напрямую).

Именно это позволяет различать два одновременных субагента одного типа — сам по себе subagent_type инструмента Agent — это метка типа, а не экземпляра.

Шаг 4 — опциональные настройки точности

OTEL_LOG_TOOL_DETAILS=1 добавляет tool_parameters к событиям инструментов — в том числе при запрещённых решениях по инструментам (с 2.1.157), так что finding об отклонении может назвать санитизированную команду, которая была заблокирована. Коннектор сводит входные данные к маскированным ссылкам на ресурсы при приёме и никогда не хранит их в сыром виде; но значения ДЕЙСТВИТЕЛЬНО покидают хост разработчика, поэтому включение этого — осознанное решение по резидентности.
OTEL_METRICS_INCLUDE_ENTRYPOINT=true добавляет app.entrypoint ко всем метрикам и событиям (по умолчанию выключено). Коннектор записывает его как топологию сессии — флот со встроенным SDK имеет иную картину рисков, чем интерактивное использование CLI.

Честные ограничения этого пути

Неаутентифицированный приём по loopback. Кооперативный приёмник по умолчанию привязывается к loopback и должен там оставаться; всё, до чего можно достучаться, может подделать телеметрию (см. Подключение Claude Code).
Подпроцессы не покрыты. OTEL_* не доходит до подпроцессов Bash/хуков/MCP; только TRACEPARENT наследуется при трассировке.
Канал admin plane не видит сторонних провайдеров. Claude Code Analytics API отслеживает использование только на Claude API — Claude Platform на AWS, Microsoft Foundry, Amazon Bedrock и Gemini Enterprise Agent Platform (formerly Vertex AI) в него не входят. Для флота на этих поверхностях этот путь OTel — единственное наблюдение, которое у вас есть, и детектор теневой аутентификации на admin-канале не может их очистить.
Цифры затрат здесь — оценки. Телеметрия затрат по запросам сверяется с авторитетными отчётами о затратах; один источник затрат на сессию, никогда не оба.

Дальнейшие шаги

Подключение Claude Code — базовая обвязка, на которой строится эта страница.
Управление и согласование — половина с обеспечением (managed settings, хуки, PEP).
Пересылка аудита в Splunk — отправьте findings, которые производит эта телеметрия, в ваш SIEM.