# Java-агент OpenTelemetry 3.0 уже майже тут — спробуйте попередній перегляд сьогодні Site [llms.txt](/uk/llms.txt) --- **[Випуск 2.32.0][release-2.32.0]** [Java-агента OpenTelemetry][java-agent] уже доступний і слугує кандидатом на випуск **3.0**, запланований на **жовтень 2026 року**. Деяка поведінка все ще може змінитися до 3.0, але ви можете переглянути нову поведінку вже зараз, перш ніж вона стане типовою. Версія 3.0 змінює типові налаштування телеметрії, конфігурації та інструменталізації. Домовленості для баз даних і коду стають стабільними, обмін повідомленнями переходить на новіші домовленості, які все ще експериментальні, а деякі налаштування збору та типові налаштування інструменталізації змінюються. Розділ [Що перевірити](#what-to-check) охоплює кожну з цих ділянок. Спробуйте його на своїх інформаційних панелях, сповіщеннях і низхідних конвеєрах та [повідомте нам про будь-які проблеми][issues], перш ніж 3.0 буде завершено. ## Спробуйте попередній перегляд {#try-the-preview} Наведені нижче приклади показують змінні середовища та [декларативну конфігурацію][decl-config]. Підтримка декларативної конфігурації в Java-агенті є експериментальною. Якщо ви вирішите її спробувати, [конвертер конфігурації][dc-converter] та [конструктор конфігурації][explorer-builder] в Ecosystem Explorer допоможуть вам почати. Передайте файл YAML за допомогою `-Dotel.config.file=/path/to/otel-config.yaml`. Змінні середовища показано першими, а декларативна конфігурація — у другій вкладці. Фрагменти YAML призначені для обʼєднання з вашим наявним файлом конфігурації; збережіть свої налаштування ресурсу, експортера та інші. ### Крок 1: Порівняйте стару та нову телеметрію {#step-1-compare-old-and-new-telemetry} Почніть із тестового розгортання та зберіть базову телеметрію, перш ніж вмикати будь-які налаштування попереднього перегляду. Потім виберіть ділянки, що стосуються вашого застосунку. Коли загальний прапорець попереднього перегляду вимкнено, додайте `/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.system: "postgresql"` | `db.system.name: "postgresql"` | | `db.name: "orders"` | `db.namespace: "orders\|public"` | | `db.statement: "SELECT * FROM orders"` | `db.query.text: "SELECT * FROM orders"` | Тут `db.namespace` поєднує базу даних і схему як `orders|public`, тоді як `db.name` містить лише `orders`. Оновлюючи свої запити, перевіряйте як значення, так і ключі. Пробуючи попередній перегляд, збережіть свої наявні налаштування бази даних і схеми; `public` — це просто схема, обрана для цього прикладу. > [!NOTE] > > **Подвійна емісія не зберігає кожну застарілу метрику чи обидві форми трейсу.** Метрики пулу зʼєднань з базою даних переходять на нові назви та одиниці навіть із `database/dup`. Відрізок усе ще має лише одну назву та вид, а `/dup` використовує новішу домовленість для них. Використовуйте свій базовий збір для порівняння метрик і структури трейсу, а також атрибутів, випромінюваних разом. ### Крок 2: Перевірте комбінований попередній перегляд {#step-2-test-the-combined-preview} Далі увімкніть загальний прапорець, щоб перевірити домовленості та типові налаштування разом:

OTEL_INSTRUMENTATION_COMMON_V3_PREVIEW=true

instrumentation/development:
  java:
    common:
      v3_preview: true

Загальний прапорець вмикає новіші домовленості для баз даних, коду та обміну повідомленнями й **вимикає `/dup` для цих ділянок**. Перевірте запуск застосунку, зібрані поля, а також відсутні відрізки й метрики. Переконайтеся, що інформаційні панелі та сповіщення працюють без застарілих полів, перевіряючи значення й одиниці, а також назви: порогове значення, виражене в мілісекундах, потребує перерахунку, коли його метрика переходить у секунди. Якщо щось зламається і ви не можете визначити, чи спричинила це зміна домовленості, чи зміна типового налаштування, вимкніть загальний прапорець і приберіть `/dup` із налаштувань кроку 1, щоб перевірити лише нові домовленості. ## Що перевірити {#what-to-check} ### Назви, значення, типи та одиниці {#names-values-types-and-units} Наведений вище приклад 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`. ### Ідентичність точки доступу бази даних {#database-endpoint-identity} Щоб дізнатися деталі міграції баз даних, почніть із [настанови з міграції стабільності семантичних домовленостей для баз даних][db-migration]. Для підтримуваних клієнтів баз даних `server.address` описує налаштовану ціль, тоді як `network.peer.address` ідентифікує точку доступу, з якою фактично встановлено звʼязок, де це доступно. Для кластера налаштована ціль може бути списком точок доступу, а не одним хостом. Перегляньте графіки сервісів та інформаційні панелі, згруповані за `server.address`: їхнє групування може змінитися, навіть якщо назва атрибута не змінилася. ### Структура трейсу обміну повідомленнями {#messaging-trace-structure} Обмін повідомленнями переходить із семантичних домовленостей [v1.24][messaging-1.24] на [v1.43][messaging-1.43]. Це впливає як на запити, так і на те, як робота продюсера зʼєднується з роботою споживача в трейсі. Для Kafka зміни в найменуванні виглядають так: | Операція | Застаріла назва відрізка | Назва відрізка в попередньому перегляді | | ---------- | ------------------------ | --------------------------------------- | | Надсилання | `orders publish` | `send orders` | | Отримання | `orders receive` | `poll orders` | | Обробка | `orders process` | `process orders` | Тепер операція стоїть першою, а її назва відображає клієнтський API. Старий атрибут `messaging.operation` також розділяється на `messaging.operation.name` і `messaging.operation.type`: для опитування Kafka назва — `poll`, а тип — `receive`. **У деяких конфігураціях змінюються батьківські звʼязки.** Коли Kafka обробляє по одному повідомленню за раз, а контекст продюсера поширюється в повідомленні, батько залежить від того, як працює ваш споживач: | Ваша конфігурація | Застаріла поведінка | Попередній перегляд | | --------------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | | Відрізки отримання вимкнено (типово), немає активного відрізка | Відрізок обробки є дочірнім відрізком надсилання | Без змін, плюс посилання на відрізок надсилання | | Відрізки отримання вимкнено, повідомлення обробляються в іншому | Відрізок обробки є дочірнім відрізком надсилання | Відрізок обробки є дочірнім відрізком активного відрізка і лише посилається на відрізок надсилання | | Відрізки отримання увімкнено, немає активного відрізка | Відрізок обробки є дочірнім відрізком отримання, в окремому трейсі | Відрізок обробки є дочірнім відрізком надсилання, в тому самому трейсі | Коли обробка повідомлень відбувається всередині активного відрізка застосунку, наприклад відрізка запланованого завдання чи відрізка методу, створеного `@WithSpan`, попередній перегляд робить цей відрізок батьком відрізка обробки. Відрізок обробки посилається на відрізок продюсера замість того, щоб використовувати його як свого батька. Це також застосовується, коли відрізки отримання увімкнено. Пакетні відрізки обробки можуть посилатися на кілька повідомлень і не дотримуються цієї моделі батьківства для одного повідомлення. Коли відрізки отримання увімкнено і немає активного відрізка на боці споживача, приклад з одним повідомленням виглядає так: ```text 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, зміни домовленостей такі: | Застаріла метрика | Метрика в попередньому перегляді | | ---------------------------- | ------------------------------------- | | `messaging.publish.duration` | `messaging.client.operation.duration` | | `messaging.receive.duration` | `messaging.client.operation.duration` | | `messaging.receive.messages` | `messaging.client.consumed.messages` | | _(немає)_ | `messaging.client.sent.messages` | | _(немає)_ | `messaging.process.duration` | Kafka отримує інструменти попереднього перегляду з цієї таблиці; вона не видавала застарілі інструменти, перелічені тут. Не очікуйте, що `messaging/dup` створюватиме обидва набори для Kafka. ### Налаштування збору та типові налаштування інструменталізації {#capture-settings-and-instrumentation-defaults} Попередній перегляд може додавати або прибирати телеметрію, а також перейменовувати її. Припустімо, ваш застосунок уже додає `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` може розширити збір. Інші зміни типових налаштувань можуть бути помітні у вашій телеметрії або під час запуску: | Що ви можете помітити після ввімкнення попереднього перегляду | Що перевірити | | ------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Додаткові структуровані атрибути журналу | Перегляньте загальні селектори `.included` / `.excluded` | | Відсутні відрізки Hibernate, Hystrix або Twilio | Ці інструменталізації типово вимкнені; явно повторно ввімкніть ті, які вам потрібні | | Ініціалізація агента/SDK не вдається з експортером Zipkin | Підтримку експортера Zipkin вилучено в режимі попереднього перегляду; перейдіть на OTLP | ### Збір ідентичності {#identity-capture} Якщо ви збираєте атрибути ідентичності користувача, оновіть налаштування збору, а також запити. Загальний попередній перегляд ігнорує старі налаштування `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` не має заміни й більше не збирається. ### Для супровідників розширень і дистрибутивів {#for-extension-and-distribution-maintainers} Супровідники розширень і дистрибутивів також мають перевірити попередній перегляд: інструменталізація invokedynamic стає типовою, змінюючи спосіб завантаження класів інструменталізації та допоміжних класів. ## Використання ШІ для допомоги в міграції {#using-ai-to-help-with-the-migration} [OpenTelemetry Ecosystem Explorer][explorer] надає метадані інструменталізації для конкретної версії, які можуть допомогти ШІ-агенту визначити зміни в назвах, типах і одиницях. Поєднайте їх зі своєю зібраною телеметрією `/dup`, щоб підтвердити зміни значень, а потім попросіть агента підготувати оновлення для ваших інформаційних панелей та сповіщень.

Приклад запиту, який можна адаптувати до свого стеку

```text Help migrate my dashboards and alerts to the Java agent 3.0 preview. Agent version, libraries, and preview settings:

Queries and backend naming conventions: Baseline and preview telemetry: 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. ```

Перегляньте запропоновані зміни на реальних даних, перш ніж застосовувати їх. ## Розкажіть нам, що ви знайшли {#tell-us-what-you-find} [Відкрийте issue][issues] із версією вашого агента, конфігурацією, версіями уражених бібліотек і невеликим прикладом неочікуваної поведінки. Тестування вже зараз дає нам час вирішити проблеми, перш ніж 3.0 стане типовою. [release-2.32.0]: https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/tag/v2.32.0 [java-agent]: https://github.com/open-telemetry/opentelemetry-java-instrumentation [issues]: https://github.com/open-telemetry/opentelemetry-java-instrumentation/issues [decl-config]: /docs/zero-code/java/agent/declarative-configuration/ [explorer]: https://explorer.opentelemetry.io/ [dc-converter]: /docs/zero-code/java/agent/declarative-configuration/#convert-your-existing-configuration [explorer-builder]: https://explorer.opentelemetry.io/java-agent/configuration/builder [messaging-1.24]: https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/messaging/messaging-spans.md [messaging-1.43]: https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/messaging/messaging-spans.md [db-migration]: /docs/specs/semconv/non-normative/db-migration/