Elysia Tools
Навигация
Workflow Playbook
Соберите список старых атрибутов, перенесите семантические соглашения, проверьте передачу контекста и реальную трассу перед выпуском изменений.
Темы
Этот порядок действий рассчитан на владельца сервиса, который планово обновляет семантические соглашения OpenTelemetry, а не на расследование текущего инцидента. Сохраните лог до изменения, конфигурацию инструментации или Collector и запрос, проходящий хотя бы через два сервиса. Удалите персональные данные и секреты до передачи примеров. structured-log-analyzer показывает уже используемые атрибуты. Для logfmt примените logfmt-to-json-structured-log-bridge, чтобы увидеть значения в кавычках, приведение типов и повторяющиеся ключи. Готовый структурированный JSON преобразовывать незачем. Для отдельной проверки раскрытия чувствительных данных предназначен pii-log-redaction.
Запустите otel-semantic-convention-migration-tool на копии кода, конфигурации Collector или запросов панели мониторинга. Зафиксируйте исходную и целевую версии, предлагаемые переименования, удалённые и не сопоставленные поля. Результат инструмента является проектом, а не автоматическим развёртыванием. http.target, например, может потребовать осознанного разделения пути и строки запроса вместо буквальной замены имени. Согласуйте такие случаи с владельцами сервиса. После выпуска проверьте и запросы панелей: количество переименований не показывает, где осталось старое имя.
Передайте примеры traceparent, tracestate, baggage и OTLP-заголовков в opentelemetry-w3c-traceparent-tracestate-baggage-and-otlp-protobuf-headers-propagation-validator. На следующем сервисе идентификатор трассы должен сохраниться, а идентификатор спана измениться. Правильные заголовки не доказывают, что спаны были экспортированы. Разберите экспорт после обновления через distributed-trace-decoder-waterfall-visualizer, сравните порядок сервисов, родительские связи, ошибки и длительности с ожидаемым запросом. Отсутствующие спаны отмечайте явно, не восстанавливайте их по косвенным признакам.
Если установлена цель по задержке, сравните наблюдаемые времена этапов с согласованными лимитами в api-latency-budget-planner. Одна трасса помогает найти медленный этап, но не даёт статистически обоснованный P99. Для приёмки сохраните версии, сравнение атрибутов, проверку заголовков, экспорт и открытые отклонения. Если задача состоит в расследовании аварии или повторном воспроизведении API-запроса, переходите к observability-debugging или api-request-replay-and-debugging соответственно.
Руководство по рабочему процессу
Разберите очищенный лог до изменения. Преобразуйте logfmt в JSON только при необходимости увидеть значения в кавычках и повторные ключи.
Перепишите поддерживаемые атрибуты пути от v1.20, изучите различия и отдельно решите судьбу удалённых или не сопоставленных полей.
Проверьте traceparent, tracestate, baggage и OTLP-заголовки на переходе между сервисами, включая сохранение трассы и смену спана.
Разберите JSON-экспорт OTel, Jaeger или Zipkin после изменения и сравните сервисы, связи, ошибки и длительности с ожидаемым маршрутом.
Преобразуйте logfmt, если кавычки или повторяющиеся ключи скрывают поля; готовый типизированный JSON анализируйте напрямую.
Перед выпуском правил Collector вручную разберите удалённые и не сопоставленные атрибуты, например http.target.
Проверяйте заголовки для непрерывности контекста, экспорт для реально связанных спанов, а бюджет только при наличии цели.
Если цель установлена, сравните длительности спанов с согласованными лимитами этапов и запишите превышения.