OpenTelemetry в производстве: прекратите отладку в темноте

spinny:~/writing $ vim 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~

NORMAL · opentelemetry-nodejs-observability-guide.md [readonly]129 lines · :q to close

2Впервые вам действительно нужна наблюдаемость, когда вы спокойно смотрите на приборную панель. Это когда пользователь пишет "оформление заказа медленно", график ошибок выглядит нормально, а в логах только ряд отключенных сообщений.

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

6## Дело не в trace, а в истории

8trace — это последовательность span. В таком случае это звучит холодно. На практике каждый span — это часть истории: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.

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~