Наблюдаемость API

OpenTelemetry для LLM API: как собирать метрики без содержимого запросов

OpenTelemetry для LLM API полезен, когда команда хочет видеть задержку, ошибки, очередь и стоимость сценария, не превращая систему наблюдаемости в копию пользовательских запросов. Хорошая телеметрия измеряет технические события: маршрут, разрешённую модель, код статуса, длительность, количество токенов при наличии, внутренний request ID и результат валидации. Она намеренно исключает API-ключи, заголовки Authorization, prompts, необработанные ответы и персональные данные.

Опубликовано 26 августа 2026 · 11 минут чтения · Ключевой запрос: OpenTelemetry мониторинг LLM API

Сформулируйте вопрос, на который отвечает телеметрия

Начните не с набора атрибутов, а с операционных вопросов. Какова p95 задержка по сценарию? Где возникает 429? Сколько попыток приходится на одну успешную операцию? Какая версия приложения повысила долю timeout? Какие запросы не проходят серверную schema? Ответы нужны для решения: включить очередь, уменьшить параллельность, остановить rollout, исправить конфигурацию или проверить доступ модели.

Не используйте trace как универсальный журнал. Содержимое диалога редко нужно для графика задержки и почти всегда повышает риск утечки. Для предметного анализа заведите отдельный безопасный процесс с явным основанием доступа, минимизацией данных и сроком хранения. Базовые диагностические поля и redaction описаны в статье о безопасных логах AI API.

Выберите минимальный набор атрибутов

Обычно достаточно назвать операцию, сервис, окружение, маршрут, безопасный model ID, HTTP-класс статуса, длительность, число попыток, признак успешной бизнес-валидации и внутренний request ID. Токены и оценку стоимости добавляйте только если endpoint возвращает их в usage и ваша политика разрешает агрегирование. Атрибуты должны иметь ограниченную кардинальность: не вставляйте user ID, сырой URL, prompt, текст ошибки или случайный внешний идентификатор в label метрики.

Секреты исключают до экспорта, а не после: collector или сторонняя система наблюдаемости не должны получать их «на минуту». Проверьте, что SDK не автоматически захватывает заголовки, query string, тело HTTP-запроса и environment variables. Имена моделей, каталоги и функции RussiaAPI способны меняться; подтверждайте их текущей консолью, а не стройте правило вокруг постоянного списка.

Границы trace, metric и log

Trace связывает шаги одной операции: ваш HTTP-handler, очередь, вызов модели и серверную валидацию. Metric показывает распределение задержки, счётчики статусов и бюджетные агрегаты. Log помогает расследовать конкретный сбой по request ID, но тоже проходит redaction. Смешивание этих ролей создаёт либо слишком мало контекста, либо хранилище чувствительных данных. Дайте каждой записи TTL, владельца и понятный доступ.

Внутренний operation ID можно передавать через trace context, если он случайный, не содержит данных пользователя и не попадает в пользовательский интерфейс. Внешний request ID RussiaAPI полезен как безопасная корреляция с поддержкой, но его формат и наличие зависят от фактического ответа. Не придумывайте идентификатор и не обещайте, что любой endpoint вернёт одинаковые поля.

Пример обёртки без ключа и prompt

Следующая функция показывает минимальный span вокруг server-side вызова. Её аргументы уже очищены: она принимает route, model, status и usage, а не HTTP headers, API key или текст запроса. Конкретная настройка exporter и семантических соглашений зависит от вашей версии OpenTelemetry; сверяйте её с актуальной официальной документацией OpenTelemetry. RussiaAPI не является сервисом OpenTelemetry и не заявляет совместимость с чужими observability-платформами.

import { metrics, trace } from '@opentelemetry/api';

const meter = metrics.getMeter('ai-gateway');
const latencyMs = meter.createHistogram('ai.request.duration.ms');
const requests = meter.createCounter('ai.requests');
const tracer = trace.getTracer('ai-gateway');

export async function observeAiCall({ route, model, call }) {
  const started = performance.now();
  return tracer.startActiveSpan('ai.request', async (span) => {
    try {
      const result = await call(); // call() must keep key, headers and prompt private.
      const attrs = { route, model, status_class: String(result.status).slice(0, 1) + 'xx' };
      requests.add(1, attrs);
      latencyMs.record(performance.now() - started, attrs);
      span.setAttributes(attrs);
      return result;
    } finally {
      span.end();
    }
  });
}

Проверьте пример тестом, который искусственно передаёт строку, похожую на ключ, в ошибку и подтверждает, что она не уходит в telemetry. Также убедитесь, что метрика не содержит high-cardinality label: иначе рост трафика увеличит стоимость и сделает дашборд бесполезным. Экспортёр запускают сначала в staging на обезличенном сценарии.

Метрики для задержек, ошибок и очереди

Смотрите на распределения, а не только на среднее: p50 показывает обычный опыт, p95 и p99 — хвост, который часто замечает пользователь. Разделите client timeout, upstream-like временную ошибку, 4xx конфигурации, 429 и ошибку собственной валидации. У 401/403 сначала проверяют собственный server-side ключ, base URL, модель и права; не передавайте секрет в поддержку. Чек-лист для этой диагностики есть в разборе ошибок 401/403.

Для очереди измеряйте время ожидания, число повторов, отмены и terminal status. Не считайте задержку модели без ожидания, если продуктовая задача включает очередь: пользователь видит весь путь. При росте 429 ограничьте параллельность и используйте конечный backoff, а не бесконечный генератор повторов. Связанные правила описаны в материале о лимите параллельных запросов.

Свяжите наблюдаемость с контролем стоимости

Если usage доступен, агрегируйте токены и оценочную стоимость по сценарию, модели и окружению — без содержимого prompt. Объясняйте отчёт как оценку на основе зафиксированной методики и текущей конфигурации, а не как неизменный публичный тариф. Сравнивайте число токенов с успешными операциями: скачок входа может означать разрастание истории, а скачок выхода — новый шаблон или неограниченный формат ответа.

Задайте алерты на аномалию, а не на каждую единичную ошибку: например, рост p95, доли 429, доли неуспешной валидации или стоимости успешной задачи. У алерта должны быть владелец и runbook с безопасными действиями. Материал о мониторинге стоимости помогает совместить финансы и надёжность без подмены наблюдаемости биллингом.

Проверка перед production

1. У каждой метрики есть операционный вопрос, владелец и ограниченный набор label.
2. Headers, ключи, cookie, prompt, ответы и персональные данные исключены до экспорта.
3. Trace связывает только безопасный operation ID, а request ID используется как корреляция при наличии.
4. p95, статусы, очередь, retry и бизнес-валидация измеряются отдельно.
5. Exporter и retention сначала проверены в staging на обезличенных данных.

Наблюдаемость не обещает доступность моделей или SLA. Она даёт команде доказательства для безопасного изменения клиента и сверки фактического поведения с текущим каталогом RussiaAPI.

FAQ

Читайте также

• Мониторинг стоимости AI API
• Логи AI API без утечек
• Лимит параллельных запросов
• Документы RussiaAPI