OpenTelemetry ve výrobě: Zastavte ladění ve tmě

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

1 
2Poprvé opravdu potřebujete pozorovatelnost, když se klidně díváte na palubní desku. Když uživatel napíše "pokladna je pomalá", graf chyb vypadá normálně a v protokolech najdete pouze řadu odpojených zpráv.
3 
4OpenTelemetry byl vytvořen, aby se tomuto okamžiku vyhnul: ne proto, aby měl více grafiky, ale aby spojoval kousky. Požadavek vstoupí do API, zavolá databázi, projde externím poskytovatelem, odešle úlohu ve frontě a možná selže o tři služby později. Bez distribuovaného sledování tento příběh rekonstruujete ručně. S OpenTelemetry máte alespoň mapu.
5 
6## Nejde o trace, ale o příběh
7 
8A trace je posloupnost span. Zní to tak chladně. V praxi je každé span částí příběhu: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.
9 
10Hodnota přichází, když začnete odpovídat na skutečné otázky:
11 
12- která externí služba se zpomaluje?
13- pocházejí chyby z konkrétní verze?
14- týká se problém všech nebo jen jednoho nájemce?
15- skrývá opakování časový limit?
16- asynchronní úloha se spustí, ale pak zemře někde jinde?
17 
18Tyto otázky nelze vyřešit `console.log` hozeným ve spěchu. Protokol přidaný v případě nouze vám často pomůže dnes a zítra se stane hlukem.
19 
20## Jak bych to vložil do aplikace Node.js
21 
22Nejzdravější nastavení je jednoduché: aplikace produkuje telemetrii, Collector rozhodne, kam ji poslat.
23 
24```text
25Node.js app -> OpenTelemetry Collector -> backend di observability
26```
27 
28Proč neexportovat přímo prodejci? Protože se to zpočátku zdá rychlejší, pak si uvědomíte, že každá služba má jiné konfigurace, jiné opakování, jiné filtry a žádný centrální bod pro odstranění citlivých dat nebo změnu cíle.
29 
30Collector je nuda ve všech správných směrech. Přijímá OTLP, provádí dávkování, umí filtrovat, umí vzorkování, může přidávat společné atributy a umí exportovat do více systémů.
31 
32## Sebeinstrumentace: dobrá, ale nedostatečná
33 
34V Node.js bych začal s autoinstrumentací. Poskytuje vám okamžitý přehled o HTTP, podporovaných rámcích, databázích a běžných knihovnách.
35 
36```bash
37npm install @opentelemetry/sdk-node \
38  @opentelemetry/auto-instrumentations-node \
39  @opentelemetry/exporter-trace-otlp-http
40```
41 
42Poté inicializujete SDK před zbytkem aplikace:
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 
59To však vidí rámec, nikoli váš produkt. Ví, že jste zadali dotaz, ale neví, že dotaz byl v „vytvořit objednávku“ nebo „obnovit předplatné“. K tomu potřebujete span manuálů v bodech, kde se počítá dominance.
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 
77span manuálů bych nikam nedával. Dal bych je tam, kde bych ve tři ráno rád pochopil, co se stalo, aniž bych přečetl polovinu základny kódu.
78 
79## Tři pravidla, která zabrání velkému chaosu
80 
81První pravidlo: každá služba musí mít `service.name`, prostředí a verzi. Zdá se to triviální, ale bez těchto atributů je trace mnohem méně užitečné. Když nasazení něco pokazí, chcete filtrovat podle verze do dvou sekund.
82 
83Druhé pravidlo: nevkládejte do atributů citlivá data. E-maily, tokeny, celá čísla a adresy by neměly skončit v backendu pozorovatelnosti náhodou. Pokud potřebujete identifikovat uživatele, zvažte interní ID, hash nebo méně citlivá pole.
84 
85Třetí pravidlo: věnujte pozornost mohutnosti. `user.id` jako atribut trace může dávat smysl. Jako metrický štítek může zničit vaše náklady a výkon.
86 
87## Metriky: málo, ale dobré
88 
89Začal bych velmi praktickými metrikami:
90 
91- sazby, chyby a trvání požadavků;
92- latence vnějších závislostí;
93- počet časových limitů a opakování;
94- hloubka ocasů;
95- délka práce;
96- procento chyb na verzi.
97 
98Zbytek se přidá v případě potřeby. Palubní desky plné grafů, na které se nikdo nedívá, jsou nábytek, nikoli pozorovatelnost.
99 
100## Protokoly: Stále užitečné, ale propojené
101 
102Protokoly nezmizí. Jednoduše se stanou mnohem užitečnějšími, když nosí `trace_id` a `span_id`. Můžete tedy začít z chybového protokolu a otevřít trace, nebo začít z pomalého trace a číst pouze protokoly vytvořené v této cestě.
103 
104Bez korelace hledáte jehly. S korelací alespoň víte, do které zásuvky se podívat.
105 
106## Kontrolní seznam, který bych použil, než řeknu „jsme pokryti“
107 
108- trace ve skutečnosti kříží více služeb.
109- Záznamy obsahují `trace_id` a `span_id`.
110- Collector je nakonfigurován s limity dávkování a paměti.
111- Chyby jsou zaznamenány v span.
112- Existuje zásada vzorkování.
113- Metriky mají řízenou mohutnost.
114- Citlivá data jsou filtrována.
115- Upozornění začínají od uživatelských příznaků, nikoli náhodných grafů.
116 
117## Závěr
118 
119OpenTelemetry sama o sobě neřeší výrobní problémy. Ale způsob, jakým s nimi zacházíte, se mění. Místo slepého přidávání protokolů začnete sledovat skutečnou cestu požadavku.
120 
121Znamení, že to funguje, je pro mě jednoduché: když se něco stane, tým se přestane ptát "kam to hledáme?" a začne se ptát "proč je ten kousek pomalý?". Zde se pozorovatelnost stává nástrojem, nikoli sbírkou řídicích panelů.
122 
123## Zdroje
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 ve výrobě: Zastavte ladění ve tmělines 1-129 (END) — press q to close

2Poprvé opravdu potřebujete pozorovatelnost, když se klidně díváte na palubní desku. Když uživatel napíše "pokladna je pomalá", graf chyb vypadá normálně a v protokolech najdete pouze řadu odpojených zpráv.

4OpenTelemetry byl vytvořen, aby se tomuto okamžiku vyhnul: ne proto, aby měl více grafiky, ale aby spojoval kousky. Požadavek vstoupí do API, zavolá databázi, projde externím poskytovatelem, odešle úlohu ve frontě a možná selže o tři služby později. Bez distribuovaného sledování tento příběh rekonstruujete ručně. S OpenTelemetry máte alespoň mapu.

6## Nejde o trace, ale o příběh

8A trace je posloupnost span. Zní to tak chladně. V praxi je každé span částí příběhu: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.

10Hodnota přichází, když začnete odpovídat na skutečné otázky:

12- která externí služba se zpomaluje?

13- pocházejí chyby z konkrétní verze?

14- týká se problém všech nebo jen jednoho nájemce?

15- skrývá opakování časový limit?

16- asynchronní úloha se spustí, ale pak zemře někde jinde?

18Tyto otázky nelze vyřešit `console.log` hozeným ve spěchu. Protokol přidaný v případě nouze vám často pomůže dnes a zítra se stane hlukem.

20## Jak bych to vložil do aplikace Node.js

22Nejzdravější nastavení je jednoduché: aplikace produkuje telemetrii, Collector rozhodne, kam ji poslat.

24```text

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

26```

28Proč neexportovat přímo prodejci? Protože se to zpočátku zdá rychlejší, pak si uvědomíte, že každá služba má jiné konfigurace, jiné opakování, jiné filtry a žádný centrální bod pro odstranění citlivých dat nebo změnu cíle.

30Collector je nuda ve všech správných směrech. Přijímá OTLP, provádí dávkování, umí filtrovat, umí vzorkování, může přidávat společné atributy a umí exportovat do více systémů.

32## Sebeinstrumentace: dobrá, ale nedostatečná

34V Node.js bych začal s autoinstrumentací. Poskytuje vám okamžitý přehled o HTTP, podporovaných rámcích, databázích a běžných knihovnách.

36```bash

37npm install @opentelemetry/sdk-node \

38 @opentelemetry/auto-instrumentations-node \

39 @opentelemetry/exporter-trace-otlp-http

40```

42Poté inicializujete SDK před zbytkem aplikace:

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```

59To však vidí rámec, nikoli váš produkt. Ví, že jste zadali dotaz, ale neví, že dotaz byl v „vytvořit objednávku“ nebo „obnovit předplatné“. K tomu potřebujete span manuálů v bodech, kde se počítá dominance.

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```

77span manuálů bych nikam nedával. Dal bych je tam, kde bych ve tři ráno rád pochopil, co se stalo, aniž bych přečetl polovinu základny kódu.

79## Tři pravidla, která zabrání velkému chaosu

81První pravidlo: každá služba musí mít `service.name`, prostředí a verzi. Zdá se to triviální, ale bez těchto atributů je trace mnohem méně užitečné. Když nasazení něco pokazí, chcete filtrovat podle verze do dvou sekund.

83Druhé pravidlo: nevkládejte do atributů citlivá data. E-maily, tokeny, celá čísla a adresy by neměly skončit v backendu pozorovatelnosti náhodou. Pokud potřebujete identifikovat uživatele, zvažte interní ID, hash nebo méně citlivá pole.

85Třetí pravidlo: věnujte pozornost mohutnosti. `user.id` jako atribut trace může dávat smysl. Jako metrický štítek může zničit vaše náklady a výkon.

87## Metriky: málo, ale dobré

89Začal bych velmi praktickými metrikami:

91- sazby, chyby a trvání požadavků;

92- latence vnějších závislostí;

93- počet časových limitů a opakování;

94- hloubka ocasů;

95- délka práce;

96- procento chyb na verzi.

98Zbytek se přidá v případě potřeby. Palubní desky plné grafů, na které se nikdo nedívá, jsou nábytek, nikoli pozorovatelnost.

100## Protokoly: Stále užitečné, ale propojené

101

102Protokoly nezmizí. Jednoduše se stanou mnohem užitečnějšími, když nosí `trace_id` a `span_id`. Můžete tedy začít z chybového protokolu a otevřít trace, nebo začít z pomalého trace a číst pouze protokoly vytvořené v této cestě.

103

104Bez korelace hledáte jehly. S korelací alespoň víte, do které zásuvky se podívat.

105

106## Kontrolní seznam, který bych použil, než řeknu „jsme pokryti“

107

108- trace ve skutečnosti kříží více služeb.

109- Záznamy obsahují `trace_id` a `span_id`.

110- Collector je nakonfigurován s limity dávkování a paměti.

111- Chyby jsou zaznamenány v span.

112- Existuje zásada vzorkování.

113- Metriky mají řízenou mohutnost.

114- Citlivá data jsou filtrována.

115- Upozornění začínají od uživatelských příznaků, nikoli náhodných grafů.

116

117## Závěr

118

119OpenTelemetry sama o sobě neřeší výrobní problémy. Ale způsob, jakým s nimi zacházíte, se mění. Místo slepého přidávání protokolů začnete sledovat skutečnou cestu požadavku.

120

121Znamení, že to funguje, je pro mě jednoduché: když se něco stane, tým se přestane ptát "kam to hledáme?" a začne se ptát "proč je ten kousek pomalý?". Zde se pozorovatelnost stává nástrojem, nikoli sbírkou řídicích panelů.

122

123## Zdroje

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