OpenTelemetry Node.js: Observability English for Backend Engineers (англійською)

Introduction

OpenTelemetry став промисловим стандартом для інструментів в розподілених системах, і Node.js є одним з найбільш широко підтримуваних середовищ виконання. Незалежно від того, чи ви налаштовуєте відстеження для нової мікросервісу, зневаджуєте пік затримки у виробничій системі або переглядаєте код інструментації колеги, словник у цій статті допоможе вам точно повідомляти про спостережливість у середовищах Node. js. Ці дев’ять термінів охоплюють основні концепції OpenTelemetry Node.js SDK.

OpenTelemetry Node.js Словник

** TracerProvider ** — кореневий об’ єкт у API трасування OpenTelemetry, який керує налаштуванням і циклом життя трасувальників. TracerProvider налаштовується за допомогою експортерів, атрибутів ресурсів і параметрів вибірки, і він слугує як фабрика для створення екземплярів Tracer, які використовуються у всій програмі.

• “Ми ініціюємо TracerProvider під час запуску програми з нашим експортером OTLP і атрибутами ресурсів, а потім реєструємо його як глобального постачальника, щоб всі бібліотеки і середовища, що використовують API OpenTelemetry, могли отримати доступ до нього без потреби прямого посилання.” *

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

“Кожен вхідний запит HTTP створює кореневу область, названу за маршрутом, і кожен виклик служби або запит бази даних створює дочірню область під нею — отриманий слід показує, де саме в шляху запиту вводиться затримка.”

** Атрибути ** — метадані ключ- значення, які прив’ язано до діапазону, запису журналу або точки даних метрики, які нададуть додаткові відомості про дію, що записується. OpenTelemetry визначає семантичні конвенції для спільних назв атрибутів, таких як http.method, db.system і user.id.

“Ми додаємо атрибути до кожного розширення бази даних, включаючи db.statement, db.name, і нетиповий атрибут для ідентифікатора рентера — це дозволяє нам фільтрувати сліди в Grafana Tempo за рентером, щоб ізольувати проблеми з продуктивністю для конкретних клієнтів.”

** SpanKind ** — перелік, який категорізує роль, яку відіграє діапазон у розподільному трасуванні. Типовими значеннями є SERVER для вхідних запитів, CLIENT для вихідних запитів до зовнішніх служб, INTERNAL для операцій у межах одного процесу, PRODUCER для публікації повідомлень і CONSUMER для споживання повідомлень.

“Ми встановили SpanKind.CLIENT на всіх обхватах, що обгортають вихідні HTTP-виклики до сторонніх API — це говорить баку відстеження, що ці обхвати представляють зовнішні залежності і дозволяє йому побудувати правильний графік залежності від сервісу.”

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

“Контекстне розповсюдження автоматично обробляється нашою бібліотекою інструментів HTTP OpenTelemetry — вона вставляє заголовки W3C TraceContext у кожен вихідний запит і витягує їх з вхідних запитів, щоб підтримувати неперервність трасування через межі сервісу.”

** W3C TraceContext ** — стандарт W3C для розповсюдження контексту трасування у заголовках HTTP за допомогою заголовків traceparent і tracestate. Це типовий формат розповсюдження для OpenTelemetry і підтримується всіма основними платформами спостереження.

“Ми стандартизували на W3C TraceContext у всіх сервісах після того, як виявили, що наші застарілі заголовки поширення B3 не були перенаправлені нашим API-шлюзом - перехід на traceparent вилучив прогалини в наших розподілених слідах.”

** Експортатор OTLP ** — експортатор, який надсилає дані телеметрики — сліди, метрики і журнали — за допомогою протоколу OpenTelemetry, рідного формату дротів екосистеми OpenTelemetry. Експортери OTLP можуть бути спрямовані на OpenTelemetry Collector або сервер, який підтримує протокол безпосередньо, наприклад, Grafana Cloud або Honeycomb.

• “Ми налаштували експорт OTLP для відсилання до нашого OpenTelemetry Collector через gRPC — потім збірник розгортає дані до Grafana Tempo для слідів і Prometheus для метрики, надаючи нам одну точку інструментування для всієї телеметрики.” *

** Бібліотека інструментів ** — пакунок, який автоматично додає відстеження або метрику OpenTelemetry до певної платформи або бібліотеки, не вимагаючи від розробника програми додавати інструменти вручну. Поширені бібліотеки інструментації Node.js включають Express, Fastify, HTTP, gRPC, PostgreSQL, MongoDB і Redis.

• “Ми реєструємо бібліотеки інструментів OpenTelemetry для Express, pg і ioredis під час запуску — ці бібліотеки латкуть цільові модулі, щоб автоматично створювати діапазони для всіх маршрутів HTTP, запитів на базу даних і операцій з кешування без будь- яких змін у коді програми.” *

** Авто- інструментація ** — Практика використання інструментальних бібліотек і SDK bootstrap для автоматичного додавання можливості спостереження до програми з мінімальними або жодними змінами коду програми. У Node.js, автоматичне інструментування зазвичай досягається за допомогою вимоги модуля налаштування перед завантаженням коду програми.

“Ми ввімкнули автоматичне інструментування, додавши —require @opentelemetry/auto-instrumentations-node/register до нашої команди запуску Node.js — за кілька хвилин ми мали сліди для всіх HTTP-запитів і викликів бази даних без змін до коду програми.”

Архітектурні шаблони для OpenTelemetry в Node.js

Найефективніші налаштування OpenTelemetry в Node.js дотримуються чіткого розділення між інструментами і експортом. Автоматичне інструментування обробляє більшу частину створення діапазонів; вручну інструментування додає атрибути бізнес- контексту і нетипові діапазони для операцій, специфічних для домену. Централізовані налаштування TracerProvider забезпечують, що всі прилади використовують ті ж правила вибірки і параметри експортера.

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

Мова для обговорення спостережуваності

При обговоренні спостережливості в англійській мові важлива точність. Трассування не є тим самим, що журнал, а діапазон не є тим самим, що метрика. Атрибути не є тим самим, що і мітки, хоча вони виконують подібні функції у різних системах. Використання правильного словника OpenTelemetry свідчить про те, що ви розумієте архітектуру системи, а не лише інструменти поверхневого рівня. У перегляді коду і обговореннях архітектури, можливість сказати “це має бути SpanKind.CLIENT span, а не SpanKind.INTERNAL, тому що це представляє вихідний RPC виклик” заробить вам довіру досвідчених інженерів спостережливості.

Наприклад: навігаційний пошук (навигація) — пошук інформації

Будьмо чесними; навіть з чітким розумінням того, * що * робить OpenTelemetry — збираючи метрики, сліди і журнали, щоб дати вам доступ до ваших систем backend — іноді конкретна англійська, використовувана навколо нього, може відчуватися … щільною. Це не просто про те, щоб знати, що «span» відноситься до сегмента трасування; це про розуміння тонких наслідків того, як цей термін застосовується в командній розмові або офіційному документі. Це особливо стосується розробників, чия рідна мова не є англійською, і які вивчають професійний словник, пов’язаний з розробкою програмного забезпечення.

Уявіть такий сценарій: ви надіслали запит на витягування, додаючи інструмент OpenTelemetry до вашої служби Node.js. Під час перегляду коду Сара з відділу контролю якості залишає коментар щодо одного з ваших діапазонів: « Цей діапазон здається трохи широким; чи не могли б ми вдосконалити його, щоб зосередитись на потоці автентифікації користувача? » Зараз він захоплює все, що відбувається в службі. ” Початкове відчуття може бути розчаруванням - чи є «широкий» критикою? Чи означає “вдосконалити” щось фундаментально неправильне у вашому підході? Знання лексики допоможе вам відповісти спокійно і конструктивно. « Широкий » у цьому випадку не означає поганий; це просто означає, що обсяг збирання даних виходить за межі запланованого. « Вдосконалення » пропонує зменшити обсяг зібраних даних, саме про це і просила Сара. Це стандартний спосіб сказати: « Давайте поліпшимо точність цього трасування ». Після цього ви можете пояснити, чому ви спочатку включили всі події — можливо, ви збирали дані для майбутнього зневаджування. Ключовим моментом є визнання того, що технічна англійська часто використовує слова з трохи іншими конотаціями, ніж у повсякденній розмові.

Іншим прикладом може бути повідомлення Slack, яке обговорює проблеми з продуктивністю, виявлені за допомогою OpenTelemetry. Старший інженер пише: «Ми бачимо високі піки затримки в order-processing сервісі, і сліди вказують на потенційне вузьке місце в базі даних. Давайте подальше дослідимо це питання за допомогою експортера OTLP, щоб надіслати ці дані до Datadog. » Фраза « вузьке місце » має тут вирішальне значення — вона не просто говорить про те, що щось повільно; вона описує певне обмеження, що обмежує продуктивність. Використання «OTLP-експортера» негайно сигналізує про заплановане призначення для цих діагностичних даних, підкреслюючи інтегровану природу рішення спостережливості. Це розуміння того, як різні терміни поєднуються, щоб описати складні технічні проблеми і рішення.

Нарешті, розглянемо опис PR: «Додає інструменти OpenTelemetry для обробки реєстрації користувачів. Включає поширення контексту розширення за допомогою W3C Trace Context v1. Додано експортер для надсилання даних до New Relic.» У цьому короткому описі використано ключові слова — * розповсюдження контексту *, * контекст слідування W3C * — щоб ясно описати призначення і налаштування доданих інструментів. Такий рівень деталізації очікується в професійній документації, що демонструє чітке розуміння можливостей інструменту.

# Example using OpenTelemetry Node.js SDK to create a span:
import { v1 } from 'otel-node';
const trace = v1.start('user_registration');
try {
  // ... user registration logic ...
} finally {
  trace.end(); // Ensure the span is always closed.
}

---

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