В этом материале
GenAI conventions развиваются. Версия и определения instrumentation должны храниться вместе с данными, иначе переименование можно принять за изменение работы сервиса.
Обновление instrumentation может изменить имена метрик и атрибутов без изменения модели или API-процесса. Dashboard перестаёт показывать ряд, alert молчит, а старые запросы всё ещё используют прежние labels. Для провайдера это миграция измерительного контракта. Она требует фиксации версии conventions, проверки фактического экспортируемого payload и явного перехода аналитики, а не только обновления зависимости в package manifest.
Укажите актуальный источник
На дату проверки GenAI conventions OpenTelemetry находятся в отдельном официальном репозитории. Client inference document описывает spans и метрики вызывающей стороны, сохраняя статус Development. Ссылку на текущий main нельзя считать неизменной спецификацией: для воспроизводимого решения нужна определённая ревизия либо сохранённая запись версии.
Запишите, какие документы использованы и какие элементы действительно реализованы библиотекой. Документация может уже описывать новую форму, пока установленный SDK ещё экспортирует старую. Имена из примера не должны автоматически появляться в утверждении о работающей телеметрии без проверки фактического вывода.
Разделите scope измерения
Документ о GenAI spans связывает span с логической операцией вызывающей стороны и её завершением. Серверная обработка и клиентский вызов наблюдаются в разных местах. Не подменяйте duration одного другим только потому, что оба относятся к одной модели и имеют похожие названия.
Если операция включает retries, определение её span должно отражать выбранную семантику. Внутренние attempts можно наблюдать отдельно, но их число не должно незаметно менять смысл логического outcome. Сохраните эту связь до построения dashboard, чтобы последующее сравнение периодов оставалось объяснимым.
Проверьте имена и единицы
GenAI metrics document отдельно описывает серверные duration, TTFT и TPOT. Проверяйте статус конкретного элемента, единицу и допустимые атрибуты. Development не означает бесполезность, но означает необходимость контролировать изменения вместо предположения о вечной стабильности каждого имени.
Создайте маленький fixture с короткой операцией, завершением и ошибкой. Сохраните экспортируемые instrument names, units, scope и набор attributes. Он проверяет instrumentation, а не производительность inference. Реальный prompt и секретные headers не нужны для подтверждения структуры наблюдений.
Сделайте migration diff
Сравните старый и новый payload по заранее заданной таблице: поле удалено, переименовано, изменило единицу либо появилось дополнительно. Отдельно отметьте изменения, которые требуют переписать запросы, recording rules или alerts. Простой факт успешного экспорта не подтверждает пригодность прежнего dashboard.
Не держите две одинаково названные серии с разным смыслом ради видимости непрерывности. Если временно экспортируются обе версии, политика должна предотвращать двойной счёт. Сохраните срок перехода и критерий удаления старой формы, иначе migration layer станет постоянным источником неоднозначности.
Ограничьте вывод версией
Прошедший fixture подтверждает выбранный SDK и конфигурацию, а не поддержку всех conventions каждым engine. После следующего обновления проверка повторяется. Сравнение latency или token usage возможно только после подтверждения, что наблюдаемая величина сохранила смысл и состав событий.
Связанные материалы — воспроизводимый стек и карта мониторинга. Итог — версионированный измерительный контракт без выдуманного стандарта на все времена и без утверждений о готовой observability-системе конкретного проекта.