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