OpenTelemetry i produktion: Sluta felsöka i mörker

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

1 
2Första gången du verkligen behöver observerbarhet är inte när du lugnt tittar på en instrumentpanel. Det är när en användare skriver "utcheckningen är långsam", feldiagrammet ser normalt ut och i loggarna hittar du bara en rad med frånkopplade meddelanden.
3 
4OpenTelemetry skapades för att undvika det ögonblicket: inte för att ha mer grafik, utan för att koppla ihop bitarna. En begäran går in i API, anropar en databas, går via en extern leverantör, lägger upp ett köat jobb och misslyckas kanske tre tjänster senare. Utan distribuerad spårning rekonstruerar du den historien för hand. Med OpenTelemetry har du åtminstone en karta.
5 
6## Poängen är inte trace, det är historien
7 
8En trace är en sekvens av span. Satt så låter det kallt. I praktiken är varje span en del av berättelsen: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.
9 
10Värdet kommer när du börjar svara på riktiga frågor:
11 
12- vilken extern tjänst saktar ner?
13- kommer felen från en specifik version?
14– drabbar problemet alla eller bara en hyresgäst?
15- döljer ett nytt försök en timeout?
16- det asynkrona jobbet börjar men dör sedan någon annanstans?
17 
18Dessa frågor kan inte lösas genom att en `console.log` kastas i en hast. Faktum är att ofta loggen som läggs till i en nödsituation hjälper dig idag och blir till buller i morgon.
19 
20## Hur skulle jag lägga detta i en app Node.js
21 
22Den hälsosammaste installationen är enkel: appen producerar telemetri, Collector bestämmer vart den ska skickas.
23 
24```text
25Node.js app -> OpenTelemetry Collector -> backend di observability
26```
27 
28Varför inte exportera direkt till leverantören? För till en början verkar det snabbare, sedan inser du att varje tjänst har olika konfigurationer, olika försök, olika filter och ingen central punkt för att ta bort känslig data eller byta destination.
29 
30Collector är tråkigt på alla de rätta sätten. Den tar emot OTLP, gör batchning, kan filtrera, kan göra sampling, kan lägga till vanliga attribut och kan exportera till flera system.
31 
32## Självinstrumentering: bra, men inte tillräckligt
33 
34I Node.js skulle jag börja med autoinstrumentering. Det ger dig omedelbar insyn i HTTP, ramverk som stöds, databaser och vanliga bibliotek.
35 
36```bash
37npm install @opentelemetry/sdk-node \
38  @opentelemetry/auto-instrumentations-node \
39  @opentelemetry/exporter-trace-otlp-http
40```
41 
42Sedan initierar du SDK före resten av 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 
59Detta ser dock ramverket, inte din produkt. Den vet att du gjorde en fråga, men den vet inte att frågan var i "skapa ordning" eller "förnya prenumeration". För det behöver du span manualer på de punkter där dominans räknas.
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 
77Jag skulle inte lägga span manualer någonstans. Jag skulle lägga dem där jag klockan tre på morgonen skulle vilja förstå vad som hände utan att läsa halva kodbasen.
78 
79## Tre regler som undviker mycket kaos
80 
81Första regeln: varje tjänst måste ha `service.name`, miljö och version. Det verkar trivialt, men utan dessa attribut är en trace mycket mindre användbar. När en distribution bryter något vill du filtrera efter version på två sekunder.
82 
83Andra regeln: lägg inte känslig information i attributen. E-postmeddelanden, tokens, heltalsnyttolaster och adresser bör inte hamna i en observerbar backend av misstag. Om du behöver identifiera en användare, överväg interna ID:n, hashing eller mindre känsliga fält.
84 
85Tredje regeln: var uppmärksam på kardinalitet. `user.id` som ett attribut för trace kan vara vettigt. Som en metrisk etikett kan den förstöra dina kostnader och prestanda.
86 
87## Mätvärden: få, men bra
88 
89Jag skulle börja med mycket praktiska mått:
90 
91- antal, fel och varaktighet för förfrågningar.
92- latens för externa beroenden;
93- antal timeouts och omförsök;
94- djupet på svansarna;
95- jobbets varaktighet;
96- procentandel av fel per version.
97 
98Resten tillsätts vid behov. Instrumentpaneler fulla av grafer som ingen tittar på är möbler, inte observerbarhet.
99 
100## Loggar: Fortfarande användbara, men länkade
101 
102Loggar försvinner inte. De blir helt enkelt mycket mer användbara när de bär `trace_id` och `span_id`. Så du kan börja från en fellogg och öppna trace, eller börja från en långsam trace och bara läsa loggarna som skapas i den sökvägen.
103 
104Utan korrelation letar du efter nålar. Med korrelation vet du åtminstone vilken låda du ska titta i.
105 
106## Checklistan jag skulle använda innan jag sa "vi är täckta"
107 
108- trace korsar faktiskt flera tjänster.
109- Loggar inkluderar `trace_id` och `span_id`.
110- Collector är konfigurerad med batch- och minnesgränser.
111- Fel registreras i span.
112– Det finns en provtagningspolicy.
113– Mätvärden har kontrollerat kardinalitet.
114- Känsliga data filtreras.
115- Varningar utgår från användarsymptom, inte slumpmässiga grafer.
116 
117## Slutsats
118 
119OpenTelemetry löser inte produktionsproblem på egen hand. Men sättet du hanterar dem förändras. Istället för att blint lägga till loggar börjar du följa den faktiska sökvägen för en begäran.
120 
121För mig är tecknet på att det fungerar enkelt: när något händer slutar teamet att fråga "var letar vi?" och börjar fråga "varför är den biten långsam?". Det är där observerbarhet blir ett verktyg, inte en samling instrumentpaneler.
122 
123## Källor
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 i produktion: Sluta felsöka i mörkerlines 1-129 (END) — press q to close

2Första gången du verkligen behöver observerbarhet är inte när du lugnt tittar på en instrumentpanel. Det är när en användare skriver "utcheckningen är långsam", feldiagrammet ser normalt ut och i loggarna hittar du bara en rad med frånkopplade meddelanden.

4OpenTelemetry skapades för att undvika det ögonblicket: inte för att ha mer grafik, utan för att koppla ihop bitarna. En begäran går in i API, anropar en databas, går via en extern leverantör, lägger upp ett köat jobb och misslyckas kanske tre tjänster senare. Utan distribuerad spårning rekonstruerar du den historien för hand. Med OpenTelemetry har du åtminstone en karta.

6## Poängen är inte trace, det är historien

8En trace är en sekvens av span. Satt så låter det kallt. I praktiken är varje span en del av berättelsen: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.

10Värdet kommer när du börjar svara på riktiga frågor:

12- vilken extern tjänst saktar ner?

13- kommer felen från en specifik version?

14– drabbar problemet alla eller bara en hyresgäst?

15- döljer ett nytt försök en timeout?

16- det asynkrona jobbet börjar men dör sedan någon annanstans?

18Dessa frågor kan inte lösas genom att en `console.log` kastas i en hast. Faktum är att ofta loggen som läggs till i en nödsituation hjälper dig idag och blir till buller i morgon.

20## Hur skulle jag lägga detta i en app Node.js

22Den hälsosammaste installationen är enkel: appen producerar telemetri, Collector bestämmer vart den ska skickas.

24```text

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

26```

28Varför inte exportera direkt till leverantören? För till en början verkar det snabbare, sedan inser du att varje tjänst har olika konfigurationer, olika försök, olika filter och ingen central punkt för att ta bort känslig data eller byta destination.

30Collector är tråkigt på alla de rätta sätten. Den tar emot OTLP, gör batchning, kan filtrera, kan göra sampling, kan lägga till vanliga attribut och kan exportera till flera system.

32## Självinstrumentering: bra, men inte tillräckligt

34I Node.js skulle jag börja med autoinstrumentering. Det ger dig omedelbar insyn i HTTP, ramverk som stöds, databaser och vanliga bibliotek.

36```bash

37npm install @opentelemetry/sdk-node \

38 @opentelemetry/auto-instrumentations-node \

39 @opentelemetry/exporter-trace-otlp-http

40```

42Sedan initierar du SDK före resten av appen:

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

59Detta ser dock ramverket, inte din produkt. Den vet att du gjorde en fråga, men den vet inte att frågan var i "skapa ordning" eller "förnya prenumeration". För det behöver du span manualer på de punkter där dominans räknas.

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

77Jag skulle inte lägga span manualer någonstans. Jag skulle lägga dem där jag klockan tre på morgonen skulle vilja förstå vad som hände utan att läsa halva kodbasen.

79## Tre regler som undviker mycket kaos

81Första regeln: varje tjänst måste ha `service.name`, miljö och version. Det verkar trivialt, men utan dessa attribut är en trace mycket mindre användbar. När en distribution bryter något vill du filtrera efter version på två sekunder.

83Andra regeln: lägg inte känslig information i attributen. E-postmeddelanden, tokens, heltalsnyttolaster och adresser bör inte hamna i en observerbar backend av misstag. Om du behöver identifiera en användare, överväg interna ID:n, hashing eller mindre känsliga fält.

85Tredje regeln: var uppmärksam på kardinalitet. `user.id` som ett attribut för trace kan vara vettigt. Som en metrisk etikett kan den förstöra dina kostnader och prestanda.

87## Mätvärden: få, men bra

89Jag skulle börja med mycket praktiska mått:

91- antal, fel och varaktighet för förfrågningar.

92- latens för externa beroenden;

93- antal timeouts och omförsök;

94- djupet på svansarna;

95- jobbets varaktighet;

96- procentandel av fel per version.

98Resten tillsätts vid behov. Instrumentpaneler fulla av grafer som ingen tittar på är möbler, inte observerbarhet.

100## Loggar: Fortfarande användbara, men länkade

101

102Loggar försvinner inte. De blir helt enkelt mycket mer användbara när de bär `trace_id` och `span_id`. Så du kan börja från en fellogg och öppna trace, eller börja från en långsam trace och bara läsa loggarna som skapas i den sökvägen.

103

104Utan korrelation letar du efter nålar. Med korrelation vet du åtminstone vilken låda du ska titta i.

105

106## Checklistan jag skulle använda innan jag sa "vi är täckta"

107

108- trace korsar faktiskt flera tjänster.

109- Loggar inkluderar `trace_id` och `span_id`.

110- Collector är konfigurerad med batch- och minnesgränser.

111- Fel registreras i span.

112– Det finns en provtagningspolicy.

113– Mätvärden har kontrollerat kardinalitet.

114- Känsliga data filtreras.

115- Varningar utgår från användarsymptom, inte slumpmässiga grafer.

116

117## Slutsats

118

119OpenTelemetry löser inte produktionsproblem på egen hand. Men sättet du hanterar dem förändras. Istället för att blint lägga till loggar börjar du följa den faktiska sökvägen för en begäran.

120

121För mig är tecknet på att det fungerar enkelt: när något händer slutar teamet att fråga "var letar vi?" och börjar fråga "varför är den biten långsam?". Det är där observerbarhet blir ett verktyg, inte en samling instrumentpaneler.

122

123## Källor

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