OpenTelemetry i produktion: Stop fejlsøgning i mørke

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

1~
2Den første gang, du virkelig har brug for observerbarhed, er ikke, når du roligt kigger på et dashboard. Det er, når en bruger skriver "checkout is slow", fejlgrafen ser normal ud, og i loggene finder man kun en række afbrudte beskeder.
3~
4OpenTelemetry blev skabt for at undgå det øjeblik: ikke for at have mere grafik, men for at forbinde brikkerne. En anmodning kommer ind i API, kalder en database, går gennem en ekstern udbyder, sender et job i kø og mislykkes måske tre tjenester senere. Uden distribueret sporing rekonstruerer du den historie i hånden. Med OpenTelemetry har du i det mindste et kort.
5~
6## Pointen er ikke trace, det er historien
7~
8En trace er en sekvens af span. Sådan lyder det koldt. I praksis er hver span en del af historien: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.
9~
10Værdien kommer, når du begynder at besvare rigtige spørgsmål:
11~
12- hvilken ekstern service bremser?
13- kommer fejlene fra en bestemt version?
14- rammer problemet alle eller kun én lejer?
15- skjuler et genforsøg en timeout?
16- det asynkrone job starter, men dør så et andet sted?
17~
18Disse spørgsmål kan ikke løses med en `console.log` kastet i en fart. Faktisk hjælper loggen, der tilføjes i en nødsituation, dig i dag og bliver til støj i morgen.
19~
20## Hvordan ville jeg placere dette i en app Node.js
21~
22Den sundeste opsætning er enkel: appen producerer telemetri, Collector bestemmer, hvor den skal sendes.
23~
24```text
25Node.js app -> OpenTelemetry Collector -> backend di observability
26```
27~
28Hvorfor ikke eksportere direkte til leverandøren? For i første omgang virker det hurtigere, så indser du, at hver tjeneste har forskellige konfigurationer, forskellige genforsøg, forskellige filtre og intet centralt punkt til at fjerne følsomme data eller ændre destination.
29~
30Collector er kedelig på alle de rigtige måder. Den modtager OTLP, udfører batching, kan filtrere, kan udføre sampling, kan tilføje fælles attributter og kan eksportere til flere systemer.
31~
32## Selvinstrumentering: god, men ikke nok
33~
34I Node.js ville jeg starte med auto-instrumentering. Det giver dig øjeblikkelig synlighed i HTTP, understøttede rammer, databaser og almindelige biblioteker.
35~
36```bash
37npm install @opentelemetry/sdk-node \
38  @opentelemetry/auto-instrumentations-node \
39  @opentelemetry/exporter-trace-otlp-http
40```
41~
42Så initialiserer du SDK før resten af appen:
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~
59Dette ser dog rammerne, ikke dit produkt. Den ved, at du har lavet en forespørgsel, men den ved ikke, at forespørgslen var i "opret rækkefølge" eller "forny abonnement". Til det har du brug for span manualer på de punkter, hvor dominans tæller.
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~
77Jeg ville ikke placere span manualer nogen steder. Jeg ville placere dem, hvor jeg klokken tre om morgenen gerne ville forstå, hvad der skete uden at læse halvdelen af kodebasen.
78~
79## Tre regler, der undgår en masse kaos
80~
81Første regel: hver tjeneste skal have `service.name`, miljø og version. Det virker trivielt, men uden disse attributter er en trace meget mindre nyttig. Når en implementering bryder noget, vil du filtrere efter version på to sekunder.
82~
83Anden regel: Indsæt ikke følsomme data i attributterne. E-mails, tokens, heltals nyttelaster og adresser bør ikke ende i en observerbar backend ved et uheld. Hvis du har brug for at identificere en bruger, skal du overveje interne id'er, hashing eller mindre følsomme felter.
84~
85Tredje regel: vær opmærksom på kardinalitet. `user.id` som en egenskab af trace kan give mening. Som en metrisk etiket kan den ødelægge dine omkostninger og ydeevne.
86~
87## Metrics: få, men gode
88~
89Jeg vil starte med meget praktiske målinger:
90~
91- rater, fejl og varighed af anmodninger;
92- latenstid af eksterne afhængigheder;
93- antal timeouts og genforsøg;
94- dybden af halerne;
95- jobbets varighed;
96- procentdel af fejl pr. version.
97~
98Resten tilsættes efter behov. Dashboards fulde af grafer, som ingen ser på, er møbler, ikke observerbarhed.
99~
100## Logs: Stadig nyttige, men linkede
101~
102Logs forsvinder ikke. De bliver simpelthen meget mere nyttige, når de bærer `trace_id` og `span_id`. Så du kan starte fra en fejllog og åbne trace, eller starte fra en langsom trace og kun læse de logfiler, der er produceret i den sti.
103~
104Uden korrelation leder du efter nåle. Med korrelation ved du i det mindste, hvilken skuffe du skal kigge i.
105~
106## Tjeklisten, jeg ville bruge, før jeg sagde "vi er dækket"
107~
108- trace krydser faktisk flere tjenester.
109- Logs inkluderer `trace_id` og `span_id`.
110- Collector er konfigureret med batch- og hukommelsesgrænser.
111- Fejl er registreret i span.
112- Der er en prøveudtagningspolitik.
113- Metrikker har kontrolleret kardinalitet.
114- Følsomme data filtreres.
115- Advarsler starter fra brugersymptomer, ikke tilfældige grafer.
116~
117## Konklusion
118~
119OpenTelemetry løser ikke produktionsproblemer alene. Men måden, du håndterer dem på, ændrer sig. I stedet for blindt at tilføje logfiler, begynder du at følge den faktiske sti til en anmodning.
120~
121For mig er tegnet på, at det virker, enkelt: når der sker noget, holder teamet op med at spørge "hvor leder vi?" og begynder at spørge "hvorfor er det stykke langsomt?". Det er her observerbarhed bliver et værktøj, ikke en samling af dashboards.
122~
123## Kilder
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

2Den første gang, du virkelig har brug for observerbarhed, er ikke, når du roligt kigger på et dashboard. Det er, når en bruger skriver "checkout is slow", fejlgrafen ser normal ud, og i loggene finder man kun en række afbrudte beskeder.

4OpenTelemetry blev skabt for at undgå det øjeblik: ikke for at have mere grafik, men for at forbinde brikkerne. En anmodning kommer ind i API, kalder en database, går gennem en ekstern udbyder, sender et job i kø og mislykkes måske tre tjenester senere. Uden distribueret sporing rekonstruerer du den historie i hånden. Med OpenTelemetry har du i det mindste et kort.

6## Pointen er ikke trace, det er historien

8En trace er en sekvens af span. Sådan lyder det koldt. I praksis er hver span en del af historien: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.

10Værdien kommer, når du begynder at besvare rigtige spørgsmål:

11~

12- hvilken ekstern service bremser?

13- kommer fejlene fra en bestemt version?

14- rammer problemet alle eller kun én lejer?

15- skjuler et genforsøg en timeout?

16- det asynkrone job starter, men dør så et andet sted?

17~

18Disse spørgsmål kan ikke løses med en `console.log` kastet i en fart. Faktisk hjælper loggen, der tilføjes i en nødsituation, dig i dag og bliver til støj i morgen.

19~

20## Hvordan ville jeg placere dette i en app Node.js

21~

22Den sundeste opsætning er enkel: appen producerer telemetri, Collector bestemmer, hvor den skal sendes.

23~

24```text

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

26```

27~

28Hvorfor ikke eksportere direkte til leverandøren? For i første omgang virker det hurtigere, så indser du, at hver tjeneste har forskellige konfigurationer, forskellige genforsøg, forskellige filtre og intet centralt punkt til at fjerne følsomme data eller ændre destination.

29~

30Collector er kedelig på alle de rigtige måder. Den modtager OTLP, udfører batching, kan filtrere, kan udføre sampling, kan tilføje fælles attributter og kan eksportere til flere systemer.

31~

32## Selvinstrumentering: god, men ikke nok

33~

34I Node.js ville jeg starte med auto-instrumentering. Det giver dig øjeblikkelig synlighed i HTTP, understøttede rammer, databaser og almindelige biblioteker.

35~

36```bash

37npm install @opentelemetry/sdk-node \

38 @opentelemetry/auto-instrumentations-node \

39 @opentelemetry/exporter-trace-otlp-http

40```

41~

42Så initialiserer du SDK før resten af appen:

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~

59Dette ser dog rammerne, ikke dit produkt. Den ved, at du har lavet en forespørgsel, men den ved ikke, at forespørgslen var i "opret rækkefølge" eller "forny abonnement". Til det har du brug for span manualer på de punkter, hvor dominans tæller.

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~

77Jeg ville ikke placere span manualer nogen steder. Jeg ville placere dem, hvor jeg klokken tre om morgenen gerne ville forstå, hvad der skete uden at læse halvdelen af kodebasen.

78~

79## Tre regler, der undgår en masse kaos

80~

81Første regel: hver tjeneste skal have `service.name`, miljø og version. Det virker trivielt, men uden disse attributter er en trace meget mindre nyttig. Når en implementering bryder noget, vil du filtrere efter version på to sekunder.

82~

83Anden regel: Indsæt ikke følsomme data i attributterne. E-mails, tokens, heltals nyttelaster og adresser bør ikke ende i en observerbar backend ved et uheld. Hvis du har brug for at identificere en bruger, skal du overveje interne id'er, hashing eller mindre følsomme felter.

84~

85Tredje regel: vær opmærksom på kardinalitet. `user.id` som en egenskab af trace kan give mening. Som en metrisk etiket kan den ødelægge dine omkostninger og ydeevne.

86~

87## Metrics: få, men gode

88~

89Jeg vil starte med meget praktiske målinger:

90~

91- rater, fejl og varighed af anmodninger;

92- latenstid af eksterne afhængigheder;

93- antal timeouts og genforsøg;

94- dybden af halerne;

95- jobbets varighed;

96- procentdel af fejl pr. version.

97~

98Resten tilsættes efter behov. Dashboards fulde af grafer, som ingen ser på, er møbler, ikke observerbarhed.

99~

100## Logs: Stadig nyttige, men linkede

101~

102Logs forsvinder ikke. De bliver simpelthen meget mere nyttige, når de bærer `trace_id` og `span_id`. Så du kan starte fra en fejllog og åbne trace, eller starte fra en langsom trace og kun læse de logfiler, der er produceret i den sti.

103~

104Uden korrelation leder du efter nåle. Med korrelation ved du i det mindste, hvilken skuffe du skal kigge i.

105~

106## Tjeklisten, jeg ville bruge, før jeg sagde "vi er dækket"

107~

108- trace krydser faktisk flere tjenester.

109- Logs inkluderer `trace_id` og `span_id`.

110- Collector er konfigureret med batch- og hukommelsesgrænser.

111- Fejl er registreret i span.

112- Der er en prøveudtagningspolitik.

113- Metrikker har kontrolleret kardinalitet.

114- Følsomme data filtreres.

115- Advarsler starter fra brugersymptomer, ikke tilfældige grafer.

116~

117## Konklusion

118~

119OpenTelemetry løser ikke produktionsproblemer alene. Men måden, du håndterer dem på, ændrer sig. I stedet for blindt at tilføje logfiler, begynder du at følge den faktiske sti til en anmodning.

120~

121For mig er tegnet på, at det virker, enkelt: når der sker noget, holder teamet op med at spørge "hvor leder vi?" og begynder at spørge "hvorfor er det stykke langsomt?". Det er her observerbarhed bliver et værktøj, ikke en samling af dashboards.

122~

123## Kilder

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~