Коротко
Автор создал Attrition — сканер, который находит устаревшие имена атрибутов, метрик, событий и значений enum в коде OpenTelemetry. Его ключевое отличие — решения основываются на структурированных данных спецификации и миграционных руководствах, поэтому инструмент учитывает контекст, единицы измерения и неоднозначные замены, а автоматические исправления остаются консервативными.
Контекст
Автор — участник проекта OpenTelemetry; ранее он создал демонстрацию на Go, трассирующую команды Redis в Sentry, и обнаружил в ней два уже выведенных из употребления имени. Проблема в том, что старые имена часто не вызывают явной ошибки, но со временем перестают совпадать с дашбордами и алертами. Attrition предназначен для проверки кода, локальной разработки и CI.
Главное
- Attrition сверяет ключи атрибутов, имена метрик и событий, а также значения enum по 1 563 именам из 26 выпусков OpenTelemetry.
- Импорт охватывает версии спецификации v1.21.0–v1.44.0 и создаёт 1 654 документа: 940 атрибутов, 571 метрику и 36 событий, а также пространства имён и статистику выпусков.
- История выпусков выявляет 50 имён, исчезнувших без явного deprecated; такие случаи помечаются как DROPPED и связываются с последним выпуском, где имя присутствовало.
- Замена может зависеть от типа span: например, net.peer.name превращается в server.address на клиентском span и client.address на серверном.
- Инструмент учитывает изменения единиц: http.server.duration заменяется на http.server.request.duration с переходом от миллисекунд к секундам; поэтому такие случаи не исправляются автоматически.
- Knowledge Base содержит 144 источника: 137 документов из набора данных, пять официальных руководств по миграции и две старые страницы спецификации.
- Четыре конфликта между реестром и руководствами разрешены в пользу руководств; например, http.resend_count сопоставлен с http.request.resend_count.
- Go CLI, Rust-сканер, веб-интерфейс, Python-агент и GitHub Action используют общий источник данных; Rust и Go дали одинаковые количества находок на пяти проверенных репозиториях.
- Наибольшее число находок в проверенной выборке было в jaeger: 67 имён в 13 файлах; go-gorm/opentelemetry оказался чистым.
- В go-redis обнаружены устаревшие метрики соединений и значения времени в миллисекундах; простое переименование без пересчёта единиц могло бы увеличить показания в тысячу раз.
Как сделано
Детерминированный импортёр прочитал YAML-спецификацию OpenTelemetry во всех тегированных выпусках с v1.21.0 по v1.44.0 и сформировал в Sanity структурированные документы. Для каждого имени код вычисляет категорию изменения по полям спецификации, хранит историю и варианты замены с условиями применения, включая тип span; отдельно записываются смены единиц и обнаруженные ошибки спецификации.
При сканировании извлечённые из кода имена одним GROQ-запросом сверяются с набором данных через Sanity Context. Для дополнительного контекста инструмент ищет и читает записи в Knowledge Base, построенной из официальных миграционных руководств и выбранных страниц спецификации. Вердикт и замена не генерируются моделью: модель используется в чате только после получения источников и отвечает в рамках найденных свидетельств.
Проект предоставляет веб-приложение на TypeScript/Next.js, CLI на Go, офлайн-сканер на Rust, Python-агента с официальным Python MCP SDK и GitHub Action. Автоматический патч ограничен безусловными переименованиями строковых ключей; случаи, требующие выбора по типу span, смены единиц или разрешения расхождений, оставляются человеку.
Результаты
В наборе данных учтено 1 563 имени из 26 выпусков спецификации; импорт создал 1 654 документа. Отдельно обнаружены 50 имён, исчезнувших из реестра без записи о deprecated. База знаний использует 144 источника, а четыре конфликта между данными реестра и миграционными руководствами разрешены в пользу руководств и опубликованы как постоянные решения.
На пяти репозиториях CLI нашёл: opentelemetry-demo — 6 устаревших имён в 4 файлах; jaeger — 67 в 13; go-redis — 16 в 4; go-gorm/opentelemetry — 0; uptrace/opentelemetry-go-extra — 18 в 7. Rust-сканер совпал с Go-версией по количеству находок на всех пяти репозиториях. Существенный пример — метрики пула соединений go-redis: переименование без преобразования миллисекунд в секунды могло бы исказить значения в тысячу раз.
Ограничения
Автор вручную проверил все вердикты, но сопоставление закреплённых версий SDK с точными версиями спецификации, которые они используют, ещё не реализовано. В Knowledge Base пока не включены все миграционные руководства: лимит составляет 150 документов. Найденное имя не обязательно является ошибкой — оно может использоваться в тестовых данных или намеренно передаваться параллельно со свежим именем во время миграции. Автоматическая правка умышленно не охватывает сложные и неоднозначные случаи. В статье не приведены измерения скорости, стоимости эксплуатации или независимая оценка точности.
Что взять себе
- При обновлении OpenTelemetry проверяйте не только имя атрибута, но и контекст его применения, единицы измерения, значения enum и дополнительные требования миграционного руководства.
- Не применяйте механически простую замену имени, если изменились единицы или одно старое поле разделилось на несколько новых.
- Для безопасного обновления используйте автоматизацию лишь для однозначных переименований, а контекстные и конфликтующие случаи проверяйте вручную.
- Проверка должна допускать отсутствие проблем: в репозитории go-gorm/opentelemetry сканер не сообщил устаревших имён.
Читать оригинал, если…
Откройте оригинал, если нужны исходный код и команды, GROQ-запросы, подробности по отдельным миграциям или таблица результатов с закреплёнными коммитами.