Java-агент OpenTelemetry 3.0 уже майже тут — спробуйте попередній перегляд сьогодні

Випуск 2.32.0 Java-агента OpenTelemetry уже доступний і слугує кандидатом на випуск 3.0, запланований на жовтень 2026 року. Деяка поведінка все ще може змінитися до 3.0, але ви можете переглянути нову поведінку вже зараз, перш ніж вона стане типовою.

Версія 3.0 змінює типові налаштування телеметрії, конфігурації та інструменталізації. Домовленості для баз даних і коду стають стабільними, обмін повідомленнями переходить на новіші домовленості, які все ще експериментальні, а деякі налаштування збору та типові налаштування інструменталізації змінюються. Розділ Що перевірити охоплює кожну з цих ділянок.

Спробуйте його на своїх інформаційних панелях, сповіщеннях і низхідних конвеєрах та повідомте нам про будь-які проблеми, перш ніж 3.0 буде завершено.

Спробуйте попередній перегляд

Наведені нижче приклади показують змінні середовища та декларативну конфігурацію. Підтримка декларативної конфігурації в Java-агенті є експериментальною. Якщо ви вирішите її спробувати, конвертер конфігурації та конструктор конфігурації в Ecosystem Explorer допоможуть вам почати. Передайте файл YAML за допомогою -Dotel.config.file=/path/to/otel-config.yaml.

Змінні середовища показано першими, а декларативна конфігурація — у другій вкладці. Фрагменти YAML призначені для обʼєднання з вашим наявним файлом конфігурації; збережіть свої налаштування ресурсу, експортера та інші.

Крок 1: Порівняйте стару та нову телеметрію

Почніть із тестового розгортання та зберіть базову телеметрію, перш ніж вмикати будь-які налаштування попереднього перегляду. Потім виберіть ділянки, що стосуються вашого застосунку. Коли загальний прапорець попереднього перегляду вимкнено, додайте /dup, щоб видавати старі та нові атрибути, а також метрики, де підтримується подвійне випромінювання, разом:

• Змінні середовища
• Декларативна конфігурація

OTEL_INSTRUMENTATION_COMMON_V3_PREVIEW=false
OTEL_SEMCONV_STABILITY_OPT_IN=database/dup,code/dup
OTEL_SEMCONV_STABILITY_PREVIEW=messaging/dup

instrumentation/development:
  general:
    stability_opt_in_list: 'database/dup,code/dup'
  java:
    common:
      v3_preview: false
      semconv_stability:
        preview: [messaging/dup]

Наприклад, розгляньте зʼєднання PostgreSQL JDBC з базою даних orders, налаштоване на використання схеми public. У разі подвійної емісії один відрізок може містити обидві схеми найменування:

Тут db.namespace поєднує базу даних і схему як orders|public, тоді як db.name містить лише orders. Оновлюючи свої запити, перевіряйте як значення, так і ключі. Пробуючи попередній перегляд, збережіть свої наявні налаштування бази даних і схеми; public — це просто схема, обрана для цього прикладу.

Крок 2: Перевірте комбінований попередній перегляд

Далі увімкніть загальний прапорець, щоб перевірити домовленості та типові налаштування разом:

• Змінні середовища
• Декларативна конфігурація

OTEL_INSTRUMENTATION_COMMON_V3_PREVIEW=true

instrumentation/development:
  java:
    common:
      v3_preview: true

Загальний прапорець вмикає новіші домовленості для баз даних, коду та обміну повідомленнями й вимикає /dup для цих ділянок.

Перевірте запуск застосунку, зібрані поля, а також відсутні відрізки й метрики. Переконайтеся, що інформаційні панелі та сповіщення працюють без застарілих полів, перевіряючи значення й одиниці, а також назви: порогове значення, виражене в мілісекундах, потребує перерахунку, коли його метрика переходить у секунди.

Якщо щось зламається і ви не можете визначити, чи спричинила це зміна домовленості, чи зміна типового налаштування, вимкніть загальний прапорець і приберіть /dup із налаштувань кроку 1, щоб перевірити лише нові домовленості.

Що перевірити

Назви, значення, типи та одиниці

Наведений вище приклад JDBC показує перейменування атрибутів, але саме лише перейменування ключа не виправить кожен запит:

• Назви: db.client.connections.max стає db.client.connection.limit; замінити connections на connection недостатньо.
• Значення: db.system: "mssql" стає db.system.name: "microsoft.sql_server".
• Одиниці: метрики тривалості пулу зʼєднань з базою даних переходять із мілісекунд у секунди.
• Консолідація: code.namespace і code.function обʼєднуються в code.function.name.

Ідентичність точки доступу бази даних

Щоб дізнатися деталі міграції баз даних, почніть із настанови з міграції стабільності семантичних домовленостей для баз даних.

Для підтримуваних клієнтів баз даних server.address описує налаштовану ціль, тоді як network.peer.address ідентифікує точку доступу, з якою фактично встановлено звʼязок, де це доступно. Для кластера налаштована ціль може бути списком точок доступу, а не одним хостом. Перегляньте графіки сервісів та інформаційні панелі, згруповані за server.address: їхнє групування може змінитися, навіть якщо назва атрибута не змінилася.

Структура трейсу обміну повідомленнями

Обмін повідомленнями переходить із семантичних домовленостей v1.24 на v1.43. Це впливає як на запити, так і на те, як робота продюсера зʼєднується з роботою споживача в трейсі. Для Kafka зміни в найменуванні виглядають так:

Тепер операція стоїть першою, а її назва відображає клієнтський API. Старий атрибут messaging.operation також розділяється на messaging.operation.name і messaging.operation.type: для опитування Kafka назва — poll, а тип — receive.

У деяких конфігураціях змінюються батьківські звʼязки. Коли Kafka обробляє по одному повідомленню за раз, а контекст продюсера поширюється в повідомленні, батько залежить від того, як працює ваш споживач:

Коли обробка повідомлень відбувається всередині активного відрізка застосунку, наприклад відрізка запланованого завдання чи відрізка методу, створеного @WithSpan, попередній перегляд робить цей відрізок батьком відрізка обробки. Відрізок обробки посилається на відрізок продюсера замість того, щоб використовувати його як свого батька. Це також застосовується, коли відрізки отримання увімкнено. Пакетні відрізки обробки можуть посилатися на кілька повідомлень і не дотримуються цієї моделі батьківства для одного повідомлення.

Коли відрізки отримання увімкнено і немає активного відрізка на боці споживача, приклад з одним повідомленням виглядає так:

Legacy                                   Preview
trace A                                  trace A
  orders publish        PRODUCER           send orders            PRODUCER
                                             └─ process orders    CONSUMER
trace B                                  trace B
  orders receive        CONSUMER           poll orders            CLIENT
    └─ orders process   CONSUMER             (link → send orders)
         (link → orders publish)

У попередньому перегляді відрізок обробки також посилається на відрізок надсилання, навіть коли той відрізок є його батьком. Відрізок опитування тепер самостійно представляє клієнтську операцію, а його вид змінюється з CONSUMER на CLIENT.

Відрізки отримання залишаються опціональними. Для Kafka у версії 2.32.0 увімкнення телеметрії отримання також вмикає метрики тривалості опитування. Якщо їх вимкнено, попередній перегляд усе одно записує кількість спожитих повідомлень під час обробки разом із тривалістю обробки. Там, де видавалися застарілі метрики обміну повідомленнями, як-от у Pulsar, зміни домовленостей такі:

Kafka отримує інструменти попереднього перегляду з цієї таблиці; вона не видавала застарілі інструменти, перелічені тут. Не очікуйте, що messaging/dup створюватиме обидва набори для Kafka.

Налаштування збору та типові налаштування інструменталізації

Попередній перегляд може додавати або прибирати телеметрію, а також перейменовувати її. Припустімо, ваш застосунок уже додає order.id і customer.tier як структуровані поля до запису журналу, використовуючи пари ключ-значення SLF4J. Після ввімкнення загального попереднього перегляду ці поля можуть зʼявлятися в експортованих журналах без окремого ввімкнення збору. MDC залишається налаштовуваним окремо й опціональним.

Щоб збирати лише order.id із цих структурованих полів:

• Змінні середовища
• Декларативна конфігурація

OTEL_INSTRUMENTATION_COMMON_LOGGING_STRUCTURED_ATTRIBUTES_INCLUDED=order.id

instrumentation/development:
  java:
    common:
      logging:
        structured_attributes:
          included: [order.id]

Загальні селектори .included / .excluded замінюють старі специфічні для джерела налаштування збору структурованих полів, які ігноруються в режимі попереднього перегляду. Під час міграції перегляньте емітовані поля: нові селектори підтримують glob-шаблони, тож * означає «включити все». Під час міграції інших налаштувань збору, які використовували списки літеральних назв, як-от capture-headers для обміну повідомленнями, копіювання * у відповідний селектор .included може розширити збір.

Інші зміни типових налаштувань можуть бути помітні у вашій телеметрії або під час запуску:

Збір ідентичності

Якщо ви збираєте атрибути ідентичності користувача, оновіть налаштування збору, а також запити. Загальний попередній перегляд ігнорує старі налаштування otel.instrumentation.common.enduser.*.enabled. Збір залишається опціональним: використовуйте otel.instrumentation.common.user.name.enabled=true і otel.instrumentation.common.user.roles.enabled=true для потрібних вам полів.

• enduser.id стає user.name.
• enduser.role, рядок із розділеними комами значеннями, стає user.roles, масивом рядків.
• enduser.scope не має заміни й більше не збирається.

Для супровідників розширень і дистрибутивів

Супровідники розширень і дистрибутивів також мають перевірити попередній перегляд: інструменталізація invokedynamic стає типовою, змінюючи спосіб завантаження класів інструменталізації та допоміжних класів.

Використання ШІ для допомоги в міграції

OpenTelemetry Ecosystem Explorer надає метадані інструменталізації для конкретної версії, які можуть допомогти ШІ-агенту визначити зміни в назвах, типах і одиницях. Поєднайте їх зі своєю зібраною телеметрією /dup, щоб підтвердити зміни значень, а потім попросіть агента підготувати оновлення для ваших інформаційних панелей та сповіщень.

Help migrate my dashboards and alerts to the Java agent 3.0 preview.

Agent version, libraries, and preview settings: <details>
Queries and backend naming conventions: <files or examples>
Baseline and preview telemetry: <files or samples>

Use the OpenTelemetry Ecosystem Explorer (https://explorer.opentelemetry.io/)
metadata for my version and my telemetry. Check the emission conditions against
my settings; use upstream sources to verify mappings the metadata cannot prove.

Return a cited old-to-new mapping and draft query changes. Check names, types,
values, and units; flag trace-shape or capture changes separately. Mark missing
or conflicting evidence VERIFY, including unavailable version metadata. Do not
assume missing metadata means no change. Preserve query intent and flag any
backend naming assumptions. Do not apply changes.

Перегляньте запропоновані зміни на реальних даних, перш ніж застосовувати їх.

Розкажіть нам, що ви знайшли

Відкрийте issue із версією вашого агента, конфігурацією, версіями уражених бібліотек і невеликим прикладом неочікуваної поведінки. Тестування вже зараз дає нам час вирішити проблеми, перш ніж 3.0 стане типовою.

• ←Попередня
• Наступна→