Вы можете маршрутизировать полную телеметрию аудита от агентов Office на собственный сборщик OpenTelemetry (OTEL). Это дает вашей организации полный контроль над хранением, шифрованием и интеграцией с вашей платформой SIEM или наблюдаемости.
В этом руководстве описано, как включить пользовательский сборщик, какие данные вы получите и полная справка по схеме span.
Пользовательские сборщики OTEL доступны для организаций Claude Enterprise и для развертываний прямого поставщика (Amazon Bedrock, Google Vertex AI или шлюз).
Что вы получите
При настройке пользовательского сборщика агенты Office отправляют данные трассировки, охватывающие каждый ход пользователя. Каждый ход создает дерево span, захватывающее подсказку, вызовы модели, выполнение инструментов, загрузку файлов и события сжатия контекста.
Ваш сборщик получает все атрибуты span, включая те, которые содержат пользовательский контент (текст подсказки, входные и выходные данные инструментов, URL-адреса документов и имена файлов). Никакие атрибуты не редактируются и не фильтруются. Текст ответа помощника не включается в отправляемые данные span. Ваша организация владеет этими данными.
Важно: Метрики не отправляются на пользовательские сборщики. Пространство имен счетчика office_agent.* маршрутизируется только в Anthropic. Однако каждое увеличение счетчика также появляется как событие span на активном span, поэтому те же сигналы доступны в ваших трассировках.
Телеметрия отправляется через OTLP/HTTP на вашу конечную точку по адресу {your_url}/v1/traces. gRPC не поддерживается, так как надстройка работает в Office WebView.
Включение пользовательского сборщика
Процесс установки отличается в зависимости от того, как ваша организация проходит аутентификацию в Claude.
Важно: Когда настроена пользовательская конечная точка, телеметрия отправляется исключительно на ваш сборщик. Span не отправляются дважды в Anthropic.
Организации Claude Enterprise (OAuth)
Администратор организации устанавливает конечную точку сборщика в консоли администратора Claude.ai в разделе Параметры организации > Агенты Office. Параметр применяется ко всей организации.
Параметр | Описание |
| Базовый URL вашего сборщика OTLP. Надстройка добавляет /v1/traces. Настоятельно рекомендуется HTTPS. |
| Необязательные заголовки аутентификации, отформатированные в соответствии со спецификацией OpenTelemetry: key1=value1,key2=value2 |
Протокол должен быть основан на HTTP OTLP. gRPC отклоняется во время конфигурации.
Развертывания прямого поставщика (Amazon Bedrock, Google Vertex AI, шлюз)
Для развертываний, которые проходят аутентификацию у вашего собственного поставщика модели, а не у Claude.ai, конечная точка сборщика предоставляется через один из трех каналов конфигурации. Все три используют одни и те же два ключа.
Рекомендуется: Используйте плагин claude-in-office для Claude Code. Он проведет вас через создание манифеста, регистрацию атрибутов расширения Entra и установку конечной точки начальной загрузки с предварительно подключенными otlp_endpoint и otlp_headers. Три канала ниже задокументированы для справки и ручной установки.
Ключ | Формат | Описание |
| URL HTTPS | Базовый URL вашего сборщика OTLP. Надстройка удаляет любой завершающий слэш и добавляет /v1/traces. |
| key1=value1,key2=value2 | Необязательные заголовки аутентификации. Тот же формат, что и переменная окружения OTEL_EXPORTER_OTLP_HEADERS в OpenTelemetry. |
Если otlp_endpoint не установлен или пуст, пользовательский сборщик не настроен и надстройка возвращается к поведению по умолчанию.
Примечание: Эти каналы конфигурации применяются только к развертываниям Microsoft Office. Надстройки Google Workspace настраиваются отдельно.
Канал 1: Параметр URL манифеста
Добавьте ключи в качестве параметров строки запроса к URL-адресу области задач в пользовательском манифесте надстройки:
URL-кодируйте значения. Это применяет конфигурацию к каждому пользователю, который устанавливает манифест.
Канал 2: Расширение каталога Azure Entra ID
Для конфигурации для каждого пользователя зарегистрируйте ключи как атрибуты расширения каталога Entra ID и назначьте их через Microsoft Graph. Надстройка читает их из токена ID пользователя, используя вложенную аутентификацию приложения (NAA).
Имена утверждений в выданном токене ID следуют формату расширения каталога Azure:
Утверждение | Соответствует |
| otlp_endpoint |
| otlp_headers |
Установите их для каждого пользователя с помощью Graph PATCH для объекта пользователя. Azure кодирует значения расширения каталога как массивы с одним элементом в токене ID; надстройка автоматически их распаковывает. Этот канал требует entra_sso=1 в параметрах URL манифеста для включения получения токена NAA.
Канал 3: ответ конечной точки начальной загрузки
Если ваше развертывание использует конечную точку начальной загрузки (конечную точку JSON, которую размещает ваша организация и которую надстройка вызывает при запуске), включите ключи в тело ответа:
{
"otlp_endpoint": "https://otel-collector.your-domain.com",
"otlp_headers": "Authorization=Bearer <token>"
}URL конечной точки начальной загрузки сам по себе настраивается через bootstrap_url в параметрах URL манифеста или в утверждении Entra extn.bootstrap_url. Если был получен токен Entra ID, он передается конечной точке начальной загрузки как заголовок авторизации Bearer, чтобы ваша конечная точка могла аутентифицировать пользователя перед возвратом конфигурации для каждого пользователя.
Приоритет
Когда несколько каналов предоставляют значение, более поздние каналы переопределяют более ранние: параметры манифеста читаются первыми, затем утверждения Entra, затем ответ начальной загрузки. Ответ начальной загрузки имеет приоритет.
Если вы еще этого не сделали, самый быстрый способ — это плагин claude-in-office.
Режимы развертывания
Экспорт пользовательского сборщика доступен в обоих режимах развертывания:
Claude.ai Enterprise (OAuth): полный журнал аудита, включая идентификацию пользователя (
user.email,user.account_uuid,organization.id), метаданные сервера MCP и записи загрузки файлов.Прямой поставщик (Bedrock, Vertex AI, шлюз): основной журнал аудита (подсказки, входные и выходные данные инструментов, URL-адреса документов), но без идентификации пользователя, без метаданных MCP и без диапазонов загрузки файлов. Атрибуция пользователя требует сопоставления
session.idс журналами вашего собственного поставщика удостоверений.
Основной журнал аудита идентичен в обоих режимах. Развертывания прямого поставщика не имеют контекста учетной записи Claude.ai, поэтому атрибуты, полученные из профиля пользователя или организации Claude.ai, отсутствуют. Полный список см. в тегах [claude.ai-only] в схеме диапазона ниже.
Метки поверхности и поставщика
Каждый диапазон включает две метки, определяющие, какое приложение Office и платформа его создали. Используйте их в качестве основных измерений для фильтрации и панелей мониторинга.
Метка | Значения |
| sheet (Excel/Google Sheets), doc (Word), slide (PowerPoint) |
| m (Microsoft) |
Справочник диапазона
Каждый ход пользователя создает дерево родитель/потомок до пяти типов диапазонов. Атрибуты, отмеченные [content], содержат данные, созданные пользователем; они составляют ваш журнал аудита. Атрибуты, отмеченные [claude.ai-only], заполняются только при входе пользователя с учетной записью Claude; они отсутствуют при развертывании Bedrock, Vertex AI и шлюза. Отсутствующие атрибуты полностью опускаются из диапазона (нет ключа с нулевым значением).
Диапазон file.upload и все атрибуты mcp.* также являются [claude.ai-only], поскольку загрузка файлов и подключения сервера MCP — это функции платформы Claude.
Для развертываний прямого поставщика идентификация пользователя должна быть скоррелирована через session.id и document.url, объединенные с журналами сеансов вашего поставщика удостоверений.
Атрибуты ресурса
Эти атрибуты появляются на каждом диапазоне:
Атрибут | Описание |
| Фиксированное значение: office-agent |
| Фиксированное значение: 1.0.0 |
| Идентификатор коммита сборки |
agent.query (корневой диапазон)
Один диапазон на ход пользователя. Это корень дерева диапазонов и содержит идентификацию сеанса, контекст документа и статус сервера MCP. SpanKind: INTERNAL.
Атрибут | Описание |
| sheet | doc | slide |
| m |
| Подсказка пользователя (первые 4000 символов) |
| Непрозрачный идентификатор сеанса |
| Адрес электронной почты пользователя |
| Детерминированный хеш-бакет (SHA-256 электронной почты, mod 30) |
| UUID учетной записи Claude |
| URL открытого документа Office |
| UUID организации Claude |
| Уровень подписки Claude |
| Тип организации Claude |
| Модель, выбранная пользователем для этого сеанса |
| PC | Mac | OfficeOnline | iOS | Android | Universal |
| Номер сборки Office |
| Количество настроенных серверов MCP |
| Количество успешно подключенных серверов MCP |
| Количество серверов MCP, не подключившихся |
| success | error | timeout | no_auth | not_attempted |
| Время получения реестра MCP |
| Код статуса HTTP при получении реестра MCP |
| Сериализованные сведения о серверах MCP (имена, количество инструментов, сообщения об ошибках) |
| Количество файлов, прикрепленных к этому ходу |
| Всего загруженных байтов |
| Количество прикрепленных изображений |
| Количество прикрепленных документов |
| Количество других прикреплений |
| Имя класса исключения (присутствует при ошибке) |
| Этап, на котором произошла ошибка запроса (присутствует при ошибке) |
agent.stream
Один span на каждый вызов API к Claude, как дочерний элемент span запроса. SpanKind: CLIENT.
Атрибут | Описание |
| ID модели, используемой для этого вызова |
| Запрошено максимальное количество выходных токенов |
| Количество сообщений в беседе в момент начала потока |
| Входные токены, выставленные в счёт (из ответа API) |
| Выходные токены, выставленные в счёт (из ответа API) |
| Токены, полученные из кэша подсказок |
| Токены, записанные в кэш подсказок |
| end_turn | tool_use | max_tokens | и т. д. |
| Заголовок request-id API Anthropic, используемый для корреляции при обращении в поддержку |
Примечание о кэшировании подсказок: надстройка безусловно запрашивает кэширование подсказок. Атрибуты cache_read_tokens и cache_creation_tokens устанавливаются из ответа API поставщика и опускаются, если ответ их не содержит. Кэширование подсказок доступно на платформе Claude Developer Platform; на момент написания Amazon Bedrock и Google Vertex AI ещё не возвращают эти поля через клиент, используемый надстройкой. Когда поддержка появится у вашего поставщика, эти атрибуты начнут отображаться автоматически.
agent.tool_execution
Один спан на вызов инструмента как дочерний элемент спана потока. SpanKind: INTERNAL. Это основная запись о действиях, которые модель выполнила над документом.
Атрибут | Описание |
| Идентификатор инструмента (например, get_cell_ranges, execute_office_js, edit_slide_xml) |
| Уникальный ID этого вызова инструмента |
| server | client |
| first_party | mcp | server |
| read | write | read_write |
| manual | auto_accept | deferred |
| Сериализованный ввод инструмента (первые 4000 символов) |
| Логическое значение |
| Сериализованный вывод инструмента (первые 4000 символов) |
| Полная длина вывода в символах (используется для обнаружения усечения) |
| Классификация ошибки (присутствует при сбое) |
| Прочитанные ячейки (только поверхность листа) |
| Записанные ячейки (только поверхность листа) |
| Скопированные ячейки (только поверхность листа) |
Примечание: Атрибут tool.accept_decision записывает, как было принято решение о разрешении: manual (пользователь одобрил это конкретное действие), auto_accept (пользователь ранее предоставил постоянное одобрение) или deferred (действие было поставлено в очередь для последующего рассмотрения). Используйте это для аудита моделей одобрения в вашей организации.
agent.compaction
Одна пролог на разговор автоматического резюмирования, срабатывает при приближении контекста к лимиту окна. SpanKind: CLIENT.
Атрибут | Описание |
| Количество токенов до резюмирования |
| Количество токенов после резюмирования |
| Разница |
| Логическое значение |
| В настоящее время всегда реактивный |
Эта пролог также содержит agent.surface, agent.vendor, session.id, user.email [claude.ai-only], user.bucket [claude.ai-only], office.platform и office.version, дублированные из корневой пролога, чтобы вы могли независимо запрашивать события сжатия.
file.upload [claude.ai-only]
Одна пролог на отдельную загрузку файла как дочерняя пролога запроса. SpanKind: CLIENT. Этот тип пролога появляется только когда пользователи входят с учетной записью Claude.ai. Загрузка файлов недоступна при прямых развертываниях поставщика.
Атрибут | Описание |
| Исходное имя файла |
| Размер файла |
| Тип MIME |
| Идентификатор Anthropic Files API |
| Логическое значение |
События пролога
События пролога — это отмеченные временем маркеры, прикрепленные к приведенным выше прологам. Они фиксируют переходы жизненного цикла и сигналы, эквивалентные счетчикам.
agent.query: exception {exception.type}; file_upload {file_id, mime_type, content_category}agent.stream: first_token; stream_complete; stream_error {exception.type}agent.tool_execution: tool_init; tool_run; tool_result; tool_error {error_type}agent.compaction: compaction_start; compaction_complete; compaction_error {exception.type}file.upload: exception {exception.type}
Каждый внутренний счетчик продукта также записывает событие пролога с тем же именем на текущей активной пролог, обеспечивая эквивалент потока метрик в ваших данных трассировки. Событие office_agent.token.usage выдается на каждой пролог agent.stream, один раз для каждого ненулевого типа токена, с атрибутами {token_usage.type: input | output | cacheRead | cacheCreation, token_usage.model, token_usage.token_count}. Это отражает форму счетчика *.token.usage, выдаваемую другими продуктами Anthropic, поэтому один сборщик может агрегировать стоимость токена по продуктам путем группировки по service.name.
Поведение, специфичное для поверхности
Схема телеметрии согласована на всех поверхностях. Вот различия:
Sheets (Excel): пролог
agent.tool_executionвключают атрибутыsheet.cells_read,sheet.cells_writtenиsheet.cells_copied. События прологаoffice_agent.cell_edit_collision_totalпоявляются, когда пользователь находится в процессе редактирования ячейки, а инструмент пытается выполнить запись.Documents (Word): события воронки редактирования документов отслеживают жизненный цикл редактирования:
office_agent.doc_edit_received_total,office_agent.doc_edit_parsed_total,office_agent.doc_edit_applied_total,office_agent.doc_proposed_edit_reviewed_total. Нет атрибутовsheet.cells_*.Slides (PowerPoint): нет атрибутов или событий, специфичных для поверхности, помимо общей схемы.
Восстановление сеанса пользователя
Развертывания Claude.ai
Фильтруйте пролог по
user.email(илиuser.account_uuid) иsession.id.Упорядочьте пролог
agent.queryпо временной метке начала; каждая — это один ход пользователя.Для каждого хода
user.message— это подсказка, аdocument.url— это файл, над которым выполняется работа.Дочерние пролог
agent.tool_execution, упорядоченные по временной метке, — это выполненные действия:tool.input— это то, что было попытано,tool.output— это результат,tool.accept_decisionзаписывает, явно ли пользователь одобрил.
Развертывания прямого поставщика
Надстройка не имеет идентификации пользователя Claude.ai в этом режиме, поэтому пролог не содержат user.email или user.account_uuid. Чтобы отнести деятельность к пользователю:
Фильтруйте пролог по
session.id, чтобы выделить один непрерывный сеанс надстройки.Используйте
document.urlдля определения обрабатываемого файла.Сопоставьте сеанс с журналами вашего поставщика удостоверений: события входа Entra, журналы доступа шлюза или журнал запросов вашей конечной точки начальной загрузки (которая получает токен Entra ID пользователя в качестве заголовка Bearer).
После того как сеанс приписан пользователю, реконструкция за каждый ход идентична: agent.query упорядочены по временной метке, с
user.message,tool.input,tool.outputиtool.accept_decision, предоставляющими журнал аудита.
Это создает полный упорядоченный стенограмму взаимодействия в обоих режимах развертывания.