Міграція з OpenTracing

Зворотна сумісність з OpenTracing була пріоритетом для проєкту OpenTelemetry з самого початку. Щоб полегшити міграцію, OpenTelemetry підтримує використання як API OpenTelemetry, так і OpenTracing в одному коді. Це дозволяє записувати інструментування OpenTracing за допомогою SDK OpenTelemetry.

Для цього кожен SDK OpenTelemetry надає OpenTracing shim, який діє як міст між API OpenTracing та SDK OpenTelemetry. Зверніть увагу, що OpenTracing shims стандартно вимкнені.

Підтримка версій мов

Перед використанням OpenTracing shim перевірте версії мови та компонентів середовища виконання вашого проєкту та оновіть їх за потреби. Мінімальні мовні версії API OpenTracing та OpenTelemetry наведені в таблиці нижче.

Зверніть увагу, що API та SDK OpenTelemetry зазвичай мають вищі вимоги до версій мов, ніж їхні аналоги OpenTracing.

Огляд міграції

Багато коду наразі інструментовано за допомогою OpenTracing. Цей код використовує API OpenTracing для інструментування коду своїх застосунків та/або встановлення втулків OpenTracing для інструментування своїх бібліотек та фреймворків.

Загальний підхід до міграції на OpenTelemetry можна описати наступним чином:

1. Встановіть SDK OpenTelemetry та видаліть поточну реалізацію OpenTracing — наприклад, клієнт Jaeger.
2. Встановіть бібліотеки інструментування OpenTelemetry та видаліть еквіваленти OpenTracing.
3. Оновіть свої панелі моніторингу, сповіщення тощо, щоб споживати нові дані OpenTelemetry.
4. Під час написання нового коду застосунку використовуйте API OpenTelemetry для всього нового інструментування.
5. Поступово реінструментуйте свій застосунок за допомогою API OpenTelemetry. Немає жорсткої вимоги видаляти наявні виклики API OpenTracing з вашого застосунку, вони продовжуватимуть працювати.

Хоча міграція великого застосунку може вимагати значних зусиль, як зазначено вище, ми рекомендуємо користувачам OpenTracing поступово мігрувати код своїх застосунків. Це полегшить навантаження на міграцію та допоможе уникнути перерв у спостережуваності.

Нижченаведені кроки представляють обережний, поступовий підхід до переходу на OpenTelemetry.

Крок 1: Встановіть SDK OpenTelemetry

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

1. Замініть реалізацію Tracer OpenTracing, яку ви наразі використовуєте, на SDK OpenTelemetry. Наприклад, якщо ви використовуєте Jaeger, видаліть клієнт Jaeger та встановіть еквівалентний клієнт OpenTelemetry.
2. Встановіть OpenTracing Shim. Цей shim дозволяє SDK OpenTelemetry споживати інструментування OpenTracing.
3. Налаштуйте SDK OpenTelemetry для експорту даних за допомогою того ж протоколу та формату, який використовував клієнт OpenTracing. Наприклад, якщо ви використовували клієнт OpenTracing, який експортував дані трасування у форматі Zipkin, налаштуйте клієнт OpenTelemetry для виконання того ж.
4. Альтернативно, налаштуйте SDK OpenTelemetry для генерування OTLP та надсилайте дані до Collector, де ви можете керувати експортом даних у кількох форматах.

Після встановлення SDK OpenTelemetry підтвердіть, що ви можете розгорнути свій застосунок і все ще отримувати ту ж телеметрію на основі OpenTracing. Іншими словами, підтвердіть, що ваші панелі моніторингу, сповіщення та інші інструменти аналізу трасування все ще працюють.

Крок 2: Поступово замінюйте інструментування

Після встановлення SDK OpenTelemetry все нове інструментування тепер можна писати за допомогою API OpenTelemetry. За кількома винятками, інструментування OpenTelemetry та OpenTracing працюватимуть разом без проблем (див. обмеження сумісності нижче).

Що до наявного інструментування? Немає жорсткої вимоги мігрувати наявний код застосунку на OpenTelemetry. Однак ми рекомендуємо мігрувати з будь-яких бібліотек інструментування OpenTracing, бібліотек, які використовуються для інструментування вебфреймворків, HTTP-клієнтів, клієнтів баз даних тощо, на їхні еквіваленти OpenTelemetry. Це покращить підтримку, оскільки багато бібліотек OpenTracing будуть виведені з експлуатації та можуть більше не оновлюватися.

Важливо зазначити, що при переході на бібліотеку інструментування OpenTelemetry дані, які генеруються, зміняться. OpenTelemetry має покращену модель для інструментування програмного забезпечення (те, що ми називаємо нашими “семантичними домовленостями”). У багатьох випадках OpenTelemetry генерує кращі, більш комплексні дані трасування. Однак “краще” також означає “інше”. Це означає, що наявні панелі моніторингу, сповіщення тощо, засновані на старих бібліотеках інструментування OpenTracing, можуть більше не працювати, коли ці бібліотеки замінюються.

Для наявного інструментування рекомендується:

1. Замініть один елемент інструментування OpenTracing на його еквівалент OpenTelemetry.
2. Спостерігайте, як це змінює телеметрію, яку генерує ваш застосунок.
3. Створіть нові панелі моніторингу, сповіщення тощо, які споживають цю нову телеметрію. Налаштуйте ці панелі перед розгортанням нової бібліотеки OpenTelemetry у промислову експлуатацію.
4. За бажанням, додайте правила обробки до Collector, які перетворюють нову телеметрію назад у стару телеметрію. Collector можна налаштувати для генерування обох версій тієї ж телеметрії, створюючи перекриття даних. Це дозволяє новим панелям заповнюватися, поки ви продовжуєте використовувати старі панелі.

Обмеження сумісності

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

Семантичні домовленості

Як зазначено вище, OpenTelemetry має покращену модель для інструментування програмного забезпечення. Це означає, що “теґи”, які встановлюються інструментуванням OpenTracing, можуть відрізнятися від “атрибутів”, які встановлюються OpenTelemetry. Іншими словами, при заміні наявного інструментування дані, які генерує OpenTelemetry, можуть відрізнятися від даних, які генерує OpenTracing.

Знову ж таки, для ясності: при зміні інструментування обовʼязково оновіть будь-які панелі моніторингу, сповіщення тощо, які покладалися на старі дані.

Baggage

У OpenTracing baggage переноситься з обʼєктом SpanContext, повʼязаним зі Span. У OpenTelemetry контекст і поширення є нижчими концепціями — spans, baggage, інструменти метрик та інші елементи переносяться в обʼєкті контексту.

В результаті цієї зміни baggage, встановлене за допомогою API OpenTracing, недоступне для OpenTelemetry Propagators. В результаті змішування API OpenTelemetry та OpenTracing не рекомендується при використанні baggage.

Зокрема, коли baggage встановлюється за допомогою API OpenTracing:

• Baggage недоступне через API OpenTelemetry.
• Інʼєкція Baggage не виконується OpenTelemetry propagators.

Якщо ви використовуєте baggage, рекомендується, щоб усі виклики API, повʼязані з baggage, були переключені на OpenTelemetry одночасно. Переконайтеся, що будь-які критичні елементи baggage все ще поширюються перед впровадженням цих змін у промислову експлуатацію.

Управління контекстом у JavaScript

У JavaScript API OpenTelemetry використовує загальнодоступні менеджери контексту, такі як async_hooks для Node.js та Zones.js для оглядача. Ці менеджери контексту роблять інструментування трасування набагато менш інвазивним та обтяжливим завданням порівняно з додаванням span як параметра до кожного методу, який потрібно трасувати.

Однак API OpenTracing передує загальному використанню цих менеджерів контексту. Код OpenTracing, який передає поточний активний span як параметр, може створювати проблеми при змішуванні з кодом OpenTelemetry, який зберігає активний span у менеджері контексту. Використання обох методів в одному трасуванні може створити зламані або невідповідні spanʼи, і не рекомендується.

Замість змішування двох API в одному трасуванні, ми рекомендуємо мігрувати повні шляхи коду з OpenTracing на OpenTelemetry як єдиний блок, щоб використовувався лише один API одночасно.

Специфікація та деталі реалізації

Для отримання деталей про те, як працює кожен OpenTracing shim, дивіться відповідну документацію для конкретної мови. Для деталей про дизайн OpenTracing shim, дивіться OpenTracing Compatibility.