OpenTelemetry GenAI (любой инструментированный агент)

Claude Code — канонический кооперативный источник, но это не единственный кооперативный агент, который вы запускаете. Тот же коннектор, что принимает телеметрию Claude Code (kind: claude), несёт opt-in, вендор-нейтральный профиль OpenTelemetry GenAI: направьте любой инструментированный через OTel агент или фреймворк на тот же приёмник OTLP, и его телеметрия gen_ai.* наполнит карту доступа и конвейер затрат — LangChain, LangGraph, CrewAI, AutoGen, Google ADK и всё остальное, что эмитирует семантические соглашения GenAI в спанах или событиях журнала.

Почему это opt-in

Соглашения OpenTelemetry GenAI имеют статус Development (пред-стабильный) вверх по течению, а в парках 2026 года реально сосуществуют три диалекта. Поэтому профиль по умолчанию выключен и закрыт ровно так же, как его закрывают SDK OTel — через opt-in-токен:

{
  "sources": [{
    "name": "agents-otel",
    "kind": "claude",
    "tenant": "<tenant-id>",
    "config": {
      "semconv_opt_in": "gen_ai_latest_experimental"
    }
  }]
}

semconv_opt_in зеркалит OTEL_SEMCONV_STABILITY_OPT_IN: список через запятую, который должен содержать gen_ai_latest_experimental. При выключенном профиле запись gen_ai.* всё ещё питает сторожевой таймер живучести сессий, но не отображается на карте — честное отсутствие, а не молчаливый приём.

Что принимает нормализатор

Профиль привязан к semconv v1.41.1 и нормализует три диалекта GenAI, сосуществующие в реальных хозяйствах (estate), проставляя на каждое нормализованное событие привязку semconv его диалекта, чтобы происхождение сохранялось:

Диалект	Форма
Legacy OpenLLMetry	индексированные атрибуты gen_ai.prompt.{i}.*
v1.36 и ранее	устаревшие события на каждое сообщение
v1.37+	поколение messages

Поверх форм сообщений он отображает соглашения mcp.* (v1.39) и разделение client/internal для invoke_agent плюс invoke_workflow (v1.41) — так что оркестрованные фреймворком вызовы агентов и рабочих процессов попадают как структурированная топология, а не шум. Принимаются как эмиссия на основе спанов (так инструментируют LangGraph, LangChain, CrewAI, AutoGen и Google ADK), так и эмиссия на основе журналов.

Сэмплы затрат дедуплицируются по идентификатору спана W3C, поэтому агент, чья телеметрия приходит и по пути спанов, и по пути журналов, никогда не тарифицируется дважды.

Подключение агента к нему

Приёмник — собственная конечная точка OTLP коннектора (gRPC 127.0.0.1:4317, HTTP 127.0.0.1:4318 по умолчанию). На стороне агента применяется стандартная конфигурация SDK OTel — конечная точка экспортёра на приёмник на петлевом интерфейсе и opt-in GenAI, если ваша инструментация его требует:

OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental

То же правило петлевого интерфейса, что и у Claude Code

Кооперативный приём не аутентифицирован и по умолчанию привязан к петлевому интерфейсу. Всё, что может достичь сокета, способно подделать телеметрию — держите его на петлевом интерфейсе (allow_public_bind существует и намеренно помечен как DANGEROUS). Агенты за пределами хоста — задача страховочного слоя на уровне ядра, а не публичного порта OTLP.

Что вы увидите в консоли

Инструментированные сессии появляются в Sessions как живая активность, атрибутированная эмитирующему агенту; их вызовы моделей питают Cost & FinOps; спаны MCP и инструментов добавляют рёбра в Access map как любой кооперативный источник:

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

• Пред-стабильные соглашения, привязанный приём. Профиль привязан к v1.41.1; когда вверх по течению что-то меняется, привязка сдвигается намеренным обновлением, а не молчаливым дрейфом. Инструментация, эмитирующая четвёртый диалект, не угадывается.
• Кооперативный значит кооперативный. Агент, который не эмитирует, невидим для этого пути — именно для этого существуют eBPF/Tetragon и нативный для хранилища аудит.
• Причуды span-kind у фреймворков реальны. Некоторые фреймворки эмитируют спаны, чей kind не совпадает с правилами client/internal v1.41; нормализатор отображает то, что может доказать, и оставляет остальное неотображённым, а не атрибутирует неверно.

Связанное

• Подключить Claude Code — тот же приёмник, специфичная для Claude поверхность.
• Корпоративный OTel для Claude Code — состояние телеметрии в масштабе парка.
• Справочник по событиям — нормализованные наблюдения, которые это производит.