АдминистрированиеOpenTelemetry

OpenTelemetry для Claude API

Copy page



Трассируйте запросы к Messages API, использования инструментов и сеансы Managed Agents с помощью спанов OpenTelemetry из Claude SDK и Claude API.

Claude API и SDK могут трассировать ваши запросы к Messages API, использование инструментов и сеансы Managed Agents с помощью OpenTelemetry. Вы можете просматривать эти трассировки в уже имеющейся у вас платформе наблюдаемости. Используйте их для отладки неудачных или медленных запросов, отслеживания расхода токенов и задержки, а также для создания оценок на основе реального трафика. Вы также можете видеть каждый запрос внутри собственных трассировок вашего приложения, связанный с пользователем или функцией, которые его отправили.

OpenTelemetry — это независимый от поставщиков стандарт, который поддерживают большинство платформ наблюдаемости. Trace (трассировка) — это полная запись одного запроса, проходящего через вашу систему. Span (спан) — это один шаг в трассировке, например запрос к модели или использование инструмента. API и SDK используют атрибуты из семантических соглашений GenAI, поэтому платформы, поддерживающие эти соглашения, могут распознавать спаны без дополнительной настройки.

Начало работы

Можно настроить трассировку SDK, трассировку API или обе. Настройте обе, чтобы видеть спаны SDK и API одного запроса в одной трассировке, как в примерах трассировок. Для запросов к Claude Platform on AWS спаны API вместо этого находятся в собственных трассировках.

Для Claude Code, Agent SDK или Cowork см. мониторинг Claude Code, наблюдаемость Agent SDK или мониторинг активности Cowork.

Отправка трассировок на партнерскую платформу

Отправляйте трассировки в любую платформу наблюдаемости, которая принимает OTLP, включая следующих партнеров:

Режимы содержимого

У каждого назначения и каждого клиента SDK есть «content mode» (режим содержимого), который определяет, включают ли спаны подсказки и ответы модели. Задайте его, когда добавляете назначение или настраиваете SDK.

• Metadata only (metadata_only в SDK): значение по умолчанию. Спаны включают идентификаторы, время, статус, количество токенов и выбранный вами текст, например имена и описания ваших агентов и инструментов, а также имена ваших серверов MCP.
• Full content (content в SDK): максимальная видимость. Спаны включают подсказки и ответы модели, а также всё, что входит в Metadata only.

С Full content вы также можете увидеть, почему выполнение завершилось сбоем или было медленным, читать полные диалоги и создавать оценки на основе реальных трассировок. В справочнике по спанам OpenTelemetry атрибуты, содержащие подсказки и ответы, помечены Content.

Если у вашей организации есть согласованное с Anthropic ограничение на обработку данных HIPAA, FERPA или K-12, назначения экспортируют только метаданные независимо от их режима содержимого. На спаны SDK это не влияет.

При нулевом хранении данных вы по-прежнему можете использовать Full content. Для запросов к Messages API экспортируемое содержимое API хранит только в памяти, пока не доставит его по назначению. Claude Managed Agents не поддерживает нулевое хранение данных, и его политика хранения данных не меняется при использовании OpenTelemetry.

Ограничения содержимого

В режиме Full content каждый спан по умолчанию содержит до 0,75 MB содержимого. Этого достаточно для контекстного окна в 200k токенов, заполненного текстом на английском языке, и при этом спан остаётся в пределах ограничения в 1 MB на размер запроса, распространённого во многих платформах наблюдаемости и прокси. Если в качестве Provider выбрана партнёрская платформа, Console устанавливает ограничение, которое принимает эта платформа.

Когда содержимое превышает ограничение, SDK или API сокращает его и устанавливает anthropic.content.truncated в значение true. В спанах запросов сначала удаляются системная подсказка и самые ранние сообщения, а в спанах инструментов блоки удаляются с конца результата. Изображения и документы представлены только своим типом.

Измените ограничение в следующих случаях:

• Ваша платформа наблюдаемости принимает полезные нагрузки большего размера: увеличьте или снимите ограничение, чтобы длинные подсказки и ответы сохранялись целиком. Для полностью заполненного контекстного окна в 1M токенов требуется около 4 MB.
• Ваша платформа наблюдаемости или прокси перед ней отклоняет большие запросы: уменьшите ограничение.

В SDK задайте traces.max_content_bytes. В Console при добавлении назначения установите для Content mode значение Full content, а затем задайте Maximum content size in MB в разделе Advanced settings.

Примеры трассировок и как их читать

Запрос к Messages API

Под спаном API запроса, который создаёт сообщение, API добавляет спан для каждого запроса к модели и спан инструмента для каждого использования серверного инструмента или инструмента MCP-коннектора, которое выполняет API.

В этом примере ваше приложение вызывает tool runner — вспомогательное средство SDK, которое запускает ваши инструменты и отправляет их результаты обратно Claude. Каждый запрос, который отправляет tool runner, имеет клиентский спан от SDK и серверный спан от API. Спаны появляются в следующем порядке:

1. Ваше приложение начинает спан answer_question и вызывает внутри него tool runner для Messages (показан как спан anthropic.messages.tool_runner).
2. Tool runner отправляет первый запрос (показан как первый клиентский спан anthropic.messages.create и спаны под ним). В этом запросе API запускает инструмент веб-поиска между двумя запросами к модели.
3. Во втором запросе к модели модель просит использовать пользовательский инструмент get_weather, поэтому первый запрос завершается.
4. Tool runner запускает get_weather (показан как спан anthropic.custom_tool_use get_weather).
5. Tool runner отправляет второй запрос с результатом инструмента (показан как второй клиентский спан anthropic.messages.create и спаны под ним).
6. Во втором запросе модель даёт окончательный ответ.

SDK в вашем приложении создаёт спан anthropic.messages.tool_runner, спан anthropic.custom_tool_use и клиентский спан каждого запроса. Чтобы получить эти спаны, настройте трассировку SDK.

Использование токенов каждого запроса указано в нескольких его спанах. Чтобы учитывать каждый токен один раз, см. Подсчёт токенов.

С Full content серверный спан anthropic.messages.create содержит подсказку и ответ. Системная подсказка находится в gen_ai.system_instructions, сообщения запроса — в gen_ai.input.messages, а ответ — в gen_ai.output.messages.

Описание каждого спана и его атрибутов см. в справочнике по спанам OpenTelemetry.

Сеанс Managed Agents

Сеанс содержит "span" (спан) для каждого запроса к Sessions API и спан хода для каждого хода агента. Ход, который запускается запросом, является дочерним по отношению к спану этого запроса. Ход содержит спан для каждого запроса к модели и для каждого инструмента, который запускает API, за исключением случаев, перечисленных в справочнике по спанам инструментов. Он также содержит спан для каждой оценки результата.

В этом примере рассматривается один запрос чата, в котором ваше приложение отправляет сообщение в сеанс и запускает пользовательский инструмент. "Trace" (трассировка) содержит спаны как от вашего приложения, так и от API в следующем порядке:

1. Ваше приложение получает от пользователя запрос POST /chat.
2. Ваше приложение запускает средство запуска инструментов сеанса (session tool runner) из SDK, которое получает список событий сеанса и передаёт их в потоковом режиме (показано как спаны anthropic.sessions.events.stream и anthropic.sessions.events.list).
3. Ваше приложение отправляет сообщение пользователя в сеанс, вызывая sessions.events.send.
4. Начинается ход, который включает запросы к модели, использование инструмента bash и ход в другом потоке (показано как первый спан anthropic.session.turn и спаны под ним).
5. Модель запрашивает использование пользовательского инструмента list_issues, поэтому ход завершается с причиной остановки requires_action.
6. Средство запуска инструментов сеанса запускает list_issues (показано как спан anthropic.custom_tool_use list_issues) и отправляет его результат, вызывая sessions.events.send.
7. Второй ход начинается с результата инструмента (показано как последний спан anthropic.session.turn).

SDK в вашем приложении создаёт спан anthropic.custom_tool_use и клиентский спан каждого запроса. Чтобы получать эти спаны, настройте трассировку SDK.

Спаны сеанса могут находиться в нескольких трассировках, например когда вы отправляете последующий запрос из новой корневой трассировки. При включённом мультиагентном режиме сеанс также может иметь несколько потоков. Чтобы найти нужные спаны, группируйте их по идентификатору.

• Один поток: группируйте спаны по gen_ai.conversation.id, который содержит идентификатор потока сеанса. Отсортируйте их по времени начала, чтобы прочитать поток как стенограмму.
• Весь сеанс со всеми его потоками: группируйте спаны по anthropic.session.id во всех трассировках.

В режиме Full content вы можете прочитать содержимое сеанса по его спанам.

• Чтобы прочитать содержимое хода, используйте его спан хода. Системная подсказка находится в gen_ai.system_instructions первого спана хода потока, входные данные — в gen_ai.input.messages (ваши сообщения и результаты инструментов, события system.message и сообщения из других потоков), а выходные данные — в gen_ai.output.messages (сообщения агента, использования инструментов и результаты инструментов).
• Чтобы увидеть аргументы и результат использования инструмента, прочитайте его спан инструмента. Аргументы находятся в gen_ai.tool.call.arguments, а результат — в anthropic.tool_result.content.

Описание каждого спана и его атрибутов см. в справочнике по спанам OpenTelemetry.

Подсчёт токенов

Чтобы учесть каждый токен один раз, суммируйте спаны только одного источника для каждого запроса. Если у запроса к Messages API есть и спан SDK, и спан API, суммируйте его спаны API. Оба называются anthropic.messages.create, поэтому различайте их по типу: спан SDK имеет тип CLIENT, а его дочерний спан, спан API, — тип SERVER.

Для каждого источника суммируйте только следующие спаны, поскольку некоторые атрибуты использования повторяются на нескольких уровнях спанов API:

• Спаны SDK: суммируйте спаны anthropic.messages.create. Если у запроса есть сжатия, также добавьте атрибуты спана anthropic.usage.compaction.input_tokens и anthropic.usage.compaction.output_tokens, поскольку атрибуты gen_ai.usage.* не включают токены сжатия. Если запрос обслужила резервная модель, его спан содержит использование только той модели, которая сформировала ответ.
• Спаны API запроса к Messages API: суммируйте либо спаны anthropic.messages.create, либо их спаны anthropic.model_request, но не те и другие одновременно. Если у запроса есть сжатия, также добавьте его спаны anthropic.compaction. Не добавляйте при этом атрибуты anthropic.usage.compaction.* спана anthropic.messages.create, поскольку они содержат те же токены.
• Спаны API сеанса Managed Agents: суммируйте спаны anthropic.model_request и anthropic.session.outcome_evaluation.

Спаны могут поступать более одного раза, например если доставка повторяется. Если ваша платформа наблюдаемости не удаляет дубликаты, учитывайте каждый спан один раз по его идентификатору трассировки и идентификатору спана.

gen_ai.usage.input_tokens уже включает токены, прочитанные из кэша подсказок и записанные в него, поэтому не добавляйте к нему атрибуты кэша. Все атрибуты использования см. в разделе Использование токенов.