OpenTelemetry у виробництві: зупинити налагодження в темряві

spinny:~/writing $ less opentelemetry-nodejs-observability-guide.md

1 
2Перший раз, коли вам справді потрібна спостережливість, це не тоді, коли ви спокійно дивитеся на приладову панель. Коли користувач пише «оплата йде повільно», графік помилок виглядає нормально, а в журналах ви знайдете лише рядок відключених повідомлень.
3 
4OpenTelemetry було створено, щоб уникнути цього моменту: не для того, щоб мати більше графіки, а для того, щоб з’єднати частини. Запит надходить у API, викликає базу даних, проходить через зовнішнього постачальника, публікує завдання в черзі та, можливо, завершує роботу трьох служб пізніше. Без розподіленого трасування ви реконструюєте цю історію вручну. З OpenTelemetry у вас принаймні є карта.
5 
6## Справа не в trace, а в історії
7 
8trace є послідовністю span. У такому вигляді це звучить холодно. На практиці кожен span є частиною історії: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.
9 
10Цінність приходить, коли ви починаєте відповідати на реальні запитання:
11 
12- який зовнішній сервіс сповільнюється?
13- помилки походять від певної версії?
14- проблема стосується всіх чи лише одного орендаря?
15- повторна спроба приховує тайм-аут?
16- асинхронне завдання починається, але потім вмирає в іншому місці?
17 
18Ці питання неможливо вирішити `console.log`, кинутою поспішно. Дійсно, часто журнал, доданий в екстреній ситуації, допомагає вам сьогодні, а завтра стає шумом.
19 
20## Як розмістити це в додатку Node.js
21 
22Найкраще налаштування просте: додаток створює телеметрію, Collector вирішує, куди її надіслати.
23 
24```text
25Node.js app -> OpenTelemetry Collector -> backend di observability
26```
27 
28Чому б не експортувати безпосередньо до постачальника? Оскільки спочатку це здається швидшим, потім ви розумієте, що кожна служба має різні конфігурації, різні повторні спроби, різні фільтри та немає центральної точки для видалення конфіденційних даних або зміни призначення.
29 
30Collector нудний у всіх правильних аспектах. Він отримує OTLP, виконує пакетування, може фільтрувати, може робити вибірку, може додавати загальні атрибути та може експортувати до кількох систем.
31 
32## Власне інструментування: добре, але недостатньо
33 
34У Node.js я б почав з автоматичного інструментування. Це дає вам миттєве бачення HTTP, підтримуваних фреймворків, баз даних і загальних бібліотек.
35 
36```bash
37npm install @opentelemetry/sdk-node \
38  @opentelemetry/auto-instrumentations-node \
39  @opentelemetry/exporter-trace-otlp-http
40```
41 
42Потім ви ініціалізуєте SDK перед рештою програми:
43 
44```typescript
45import { NodeSDK } from '@opentelemetry/sdk-node';
46import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
47import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
48 
49const sdk = new NodeSDK({
50  traceExporter: new OTLPTraceExporter({
51    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
52  }),
53  instrumentations: [getNodeAutoInstrumentations()],
54});
55 
56sdk.start();
57```
58 
59Однак це бачить структуру, а не ваш продукт. Він знає, що ви зробили запит, але не знає, що запит був у «створити порядок» або «оновити підписку». Для цього вам знадобиться span посібників у точках, де враховується домінування.
60 
61```typescript
62const span = tracer.startSpan('checkout.create_order');
63 
64try {
65  span.setAttribute('cart.items_count', input.items.length);
66  const order = await createOrder(input);
67  span.setAttribute('order.id', order.id);
68  return order;
69} catch (error) {
70  span.recordException(error as Error);
71  throw error;
72} finally {
73  span.end();
74}
75```
76 
77Я б нікуди не клав посібники span. Я б поклав їх туди, де о третій ночі хотів би зрозуміти, що сталося, не читаючи половини кодової бази.
78 
79## Три правила, які допоможуть уникнути хаосу
80 
81Перше правило: кожна служба повинна мати `service.name`, середовище та версію. Це здається тривіальним, але без цих атрибутів trace набагато менш корисний. Коли розгортання щось порушує, ви хочете відфільтрувати за версією за дві секунди.
82 
83Друге правило: не розміщуйте конфіденційні дані в атрибутах. Електронні листи, токени, цілочисельні дані та адреси не повинні випадково опинитися в системі спостереження. Якщо вам потрібно ідентифікувати користувача, розгляньте внутрішні ідентифікатори, хешування або менш конфіденційні поля.
84 
85Правило третє: звертайте увагу на потужність. `user.id` як атрибут trace може мати сенс. Як ярлик показника він може знищити ваші витрати та продуктивність.
86 
87## Показники: мало, але добре
88 
89Я б почав із дуже практичних показників:
90 
91- частоти, похибки та тривалість запитів;
92- латентність зовнішніх залежностей;
93- кількість тайм-аутів і повторних спроб;
94- глибина хвостиків;
95- тривалість роботи;
96- відсоток помилок на версію.
97 
98Решта додається при необхідності. Інформаційні панелі, наповнені графіками, на які ніхто не дивиться, — це меблі, а не можливість спостереження.
99 
100## Журнали: все ще корисні, але пов’язані
101 
102Журнали не зникають. Вони просто стають набагато кориснішими, коли носять `trace_id` та `span_id`. Отже, ви можете почати з журналу помилок і відкрити trace або почати з повільного trace і прочитати лише журнали, створені на цьому шляху.
103 
104Без кореляції ви шукаєте голки. Завдяки кореляції ви принаймні знаєте, у яку шухляду шукати.
105 
106## Контрольний список, яким я б скористався, перш ніж сказати "ми охоплені"
107 
108- trace фактично перетинає кілька послуг.
109- Журнали включають `trace_id` та `span_id`.
110- Collector налаштовано з обмеженнями пакетування та пам’яті.
111- Помилки записуються в span.
112– Існує політика відбору проб.
113- Метрики мають керовану потужність.
114- Конфіденційні дані фільтруються.
115- Сповіщення починаються з симптомів користувача, а не з випадкових графіків.
116 
117## Висновок
118 
119OpenTelemetry самостійно не вирішує виробничі проблеми. Але те, як ви з ними справляєтеся, змінюється. Замість того, щоб сліпо додавати журнали, ви починаєте слідувати фактичному шляху запиту.
120 
121Для мене ознака того, що це працює, проста: коли щось стається, команда перестає запитувати «куди ми дивимося?» і починає запитувати "чому цей твір повільний?". Ось де спостережливість стає інструментом, а не набором інформаційних панелей.
122 
123## Джерела
124 
125- [OpenTelemetry: Overview](https://opentelemetry.io/docs/specs/otel/overview/)
126- [OpenTelemetry Collector: Configuration](https://opentelemetry.io/docs/collector/configuration/)
127- [OpenTelemetry JavaScript: Node.js getting started](https://opentelemetry.io/docs/languages/js/getting-started/nodejs/)
128- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/)
129

:OpenTelemetry у виробництві: зупинити налагодження в темрявіlines 1-129 (END) — press q to close

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

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

6## Справа не в trace, а в історії

8trace є послідовністю span. У такому вигляді це звучить холодно. На практиці кожен span є частиною історії: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.

10Цінність приходить, коли ви починаєте відповідати на реальні запитання:

12- який зовнішній сервіс сповільнюється?

13- помилки походять від певної версії?

14- проблема стосується всіх чи лише одного орендаря?

15- повторна спроба приховує тайм-аут?

16- асинхронне завдання починається, але потім вмирає в іншому місці?

18Ці питання неможливо вирішити `console.log`, кинутою поспішно. Дійсно, часто журнал, доданий в екстреній ситуації, допомагає вам сьогодні, а завтра стає шумом.

20## Як розмістити це в додатку Node.js

22Найкраще налаштування просте: додаток створює телеметрію, Collector вирішує, куди її надіслати.

24```text

25Node.js app -> OpenTelemetry Collector -> backend di observability

26```

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

30Collector нудний у всіх правильних аспектах. Він отримує OTLP, виконує пакетування, може фільтрувати, може робити вибірку, може додавати загальні атрибути та може експортувати до кількох систем.

32## Власне інструментування: добре, але недостатньо

34У Node.js я б почав з автоматичного інструментування. Це дає вам миттєве бачення HTTP, підтримуваних фреймворків, баз даних і загальних бібліотек.

36```bash

37npm install @opentelemetry/sdk-node \

38 @opentelemetry/auto-instrumentations-node \

39 @opentelemetry/exporter-trace-otlp-http

40```

42Потім ви ініціалізуєте SDK перед рештою програми:

44```typescript

45import { NodeSDK } from '@opentelemetry/sdk-node';

46import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

47import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';

49const sdk = new NodeSDK({

50 traceExporter: new OTLPTraceExporter({

51 url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,

52 }),

53 instrumentations: [getNodeAutoInstrumentations()],

54});

56sdk.start();

57```

59Однак це бачить структуру, а не ваш продукт. Він знає, що ви зробили запит, але не знає, що запит був у «створити порядок» або «оновити підписку». Для цього вам знадобиться span посібників у точках, де враховується домінування.

61```typescript

62const span = tracer.startSpan('checkout.create_order');

64try {

65 span.setAttribute('cart.items_count', input.items.length);

66 const order = await createOrder(input);

67 span.setAttribute('order.id', order.id);

68 return order;

69} catch (error) {

70 span.recordException(error as Error);

71 throw error;

72} finally {

73 span.end();

74}

75```

77Я б нікуди не клав посібники span. Я б поклав їх туди, де о третій ночі хотів би зрозуміти, що сталося, не читаючи половини кодової бази.

79## Три правила, які допоможуть уникнути хаосу

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

83Друге правило: не розміщуйте конфіденційні дані в атрибутах. Електронні листи, токени, цілочисельні дані та адреси не повинні випадково опинитися в системі спостереження. Якщо вам потрібно ідентифікувати користувача, розгляньте внутрішні ідентифікатори, хешування або менш конфіденційні поля.

85Правило третє: звертайте увагу на потужність. `user.id` як атрибут trace може мати сенс. Як ярлик показника він може знищити ваші витрати та продуктивність.

87## Показники: мало, але добре

89Я б почав із дуже практичних показників:

91- частоти, похибки та тривалість запитів;

92- латентність зовнішніх залежностей;

93- кількість тайм-аутів і повторних спроб;

94- глибина хвостиків;

95- тривалість роботи;

96- відсоток помилок на версію.

98Решта додається при необхідності. Інформаційні панелі, наповнені графіками, на які ніхто не дивиться, — це меблі, а не можливість спостереження.

100## Журнали: все ще корисні, але пов’язані

101

102Журнали не зникають. Вони просто стають набагато кориснішими, коли носять `trace_id` та `span_id`. Отже, ви можете почати з журналу помилок і відкрити trace або почати з повільного trace і прочитати лише журнали, створені на цьому шляху.

103

104Без кореляції ви шукаєте голки. Завдяки кореляції ви принаймні знаєте, у яку шухляду шукати.

105

106## Контрольний список, яким я б скористався, перш ніж сказати "ми охоплені"

107

108- trace фактично перетинає кілька послуг.

109- Журнали включають `trace_id` та `span_id`.

110- Collector налаштовано з обмеженнями пакетування та пам’яті.

111- Помилки записуються в span.

112– Існує політика відбору проб.

113- Метрики мають керовану потужність.

114- Конфіденційні дані фільтруються.

115- Сповіщення починаються з симптомів користувача, а не з випадкових графіків.

116

117## Висновок

118

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

120

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

122

123## Джерела

124

125- [OpenTelemetry: Overview](https://opentelemetry.io/docs/specs/otel/overview/)

126- [OpenTelemetry Collector: Configuration](https://opentelemetry.io/docs/collector/configuration/)

127- [OpenTelemetry JavaScript: Node.js getting started](https://opentelemetry.io/docs/languages/js/getting-started/nodejs/)

128- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/concepts/semantic-conventions/)

129