Перейти к основному содержимому

Логирование и наблюдаемость

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

Журналы выполнения​

Журналы выполнения — это журналы процесса, которые пишет запущенный сервис gpt2giga. Сейчас их обрабатывает существующий логгер на базе Loguru; они пишутся в stdout и настроенный файл журнала.

Журналы выполнения используются для:

  • статуса запуска и остановки;
  • операционных предупреждений и ошибок;
  • диагностики в рамках запроса с внутренним идентификатором запроса;
  • логирования отладочной полезной нагрузки только для разработки, если это разрешено конфигурацией.

Журналы выполнения не должны содержать необработанных API-ключей, учётных данных, cookie, токенов или других секретов. Маскирование чувствительных полей остаётся включённым по умолчанию.

Журналы трафика​

Журналы трафика — это структурированные записи трафика запросов и ответов LLM. Они отделены от журналов выполнения и предназначены для контролируемых приёмников хранилища: JSONL, Postgres или OpenSearch.

Журналы трафика могут содержать:

  • идентификатор запроса, идентификатор трейса, protocol, route, method и метаданные тайминга;
  • хешированные идентификаторы клиента или API-ключа;
  • запрошенное и фактическое имена модели;
  • статус и использование токенов;
  • промпты и ответы, если это явно разрешено включаемыми настройками.

Захват содержимого должен оставаться выключенным по умолчанию. Маскирование должно оставаться включённым по умолчанию. Необработанные заголовки авторизации, x-api-key, cookie, учётные данные и локальный материал сертификатов никогда не должны сохраняться.

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

Наблюдаемость включает трейсы, спаны и метрики, которые отправляются через интеграции, совместимые с OpenTelemetry/OpenInference. Arize Phoenix — необязательное место назначения, а не замена журналов выполнения или журналов трафика.

События наблюдаемости должны использовать поля контекста запроса для корреляции:

  • request_id;
  • trace_id;
  • необязательный span_id;
  • метаданные protocol и route;
  • метаданные model, если доступны.

Захват промптов и ответов для наблюдаемости должен быть включаемым и следовать тем же правилам маскирования, что и журналы трафика.

Наблюдаемость, специфичная для LLM, строится вокруг нормализованных моделей запроса/ответа, где это возможно: Chat Completions использует NormalizedChatRequest и NormalizedResponse, помощники Responses и Anthropic приводят публичные полезные нагрузки к нормализованному чат-подобному представлению для спанов, а вехи потока могут строиться из NormalizedStreamEvent. Это позволяет добавлять новый протокол/провайдер без копирования всей логики сопоставления OpenInference/Phoenix. Подробности: Нормализованные сообщения.

Метрики​

Метрики — это агрегированные счётчики и гистограммы для контроля работоспособности. Они выключены по умолчанию и могут публиковаться через эндпоинт /metrics, совместимый с Prometheus, при GPT2GIGA_METRICS_ENABLED=True.

Метрики должны описывать агрегированное поведение, например:

  • число запросов по protocol, route, status и model;
  • гистограммы задержки;
  • число ошибок вышестоящего сервиса;
  • число отключений потока;
  • сбои приёмников журналов трафика и наблюдаемости.

Метрики не должны включать содержимое промптов или ответов. Метки должны избегать необработанных идентификаторов с высокой кардинальностью; по возможности используйте ограниченные значения protocol, route, status и model.

Эндпоинт метрик следует той же политике API-ключа, что и публичные API-маршруты. В PROD он требует GPT2GIGA_API_KEY; в DEV он открыт только при выключенной глобальной аутентификации по API-ключу. Он экспортирует базовые серии сервиса для числа запросов, задержки запроса/вышестоящего сервиса, ошибок вышестоящего сервиса, суммарных токенов, отключений потока и отбрасываний из очереди журналов трафика.