OpenTelemetry in der Produktion: Hören Sie auf, im Dunkeln zu debuggen

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

1 
2Das erste Mal, dass Sie Beobachtbarkeit wirklich brauchen, ist nicht, wenn Sie ruhig auf ein Dashboard schauen. Wenn ein Benutzer schreibt: „Der Checkout ist langsam“, sieht das Fehlerdiagramm normal aus und in den Protokollen finden Sie nur eine Reihe nicht verbundener Nachrichten.
3 
4OpenTelemetry wurde geschaffen, um diesen Moment zu vermeiden: nicht um mehr Grafiken zu haben, sondern um die Teile zu verbinden. Eine Anfrage gelangt in den API, ruft eine Datenbank auf, durchläuft einen externen Anbieter, stellt einen Job in die Warteschlange und schlägt möglicherweise drei Dienste später fehl. Ohne verteilte Ablaufverfolgung rekonstruieren Sie diese Geschichte von Hand. Mit OpenTelemetry haben Sie zumindest eine Karte.
5 
6## Es geht nicht um die trace, sondern um die Geschichte
7 
8Ein trace ist eine Folge von span. So ausgedrückt klingt es kalt. In der Praxis ist jedes span ein Teil der Geschichte: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.
9 
10Der Wert entsteht, wenn Sie anfangen, echte Fragen zu beantworten:
11 
12- Welcher externe Dienst wird langsamer?
13- Stammen die Fehler von einer bestimmten Version?
14- Betrifft das Problem alle oder nur einen Mieter?
15- Versteckt ein Wiederholungsversuch eine Zeitüberschreitung?
16- Der asynchrone Job startet, stirbt dann aber woanders?
17 
18Diese Fragen können nicht durch eine überstürzte `console.log` gelöst werden. Tatsächlich hilft Ihnen das im Notfall hinzugefügte Protokoll oft heute und wird morgen zum Lärm.
19 
20## Wie würde ich das in eine App integrieren Node.js
21 
22Die gesündeste Einrichtung ist einfach: Die App erstellt Telemetriedaten, der Collector entscheidet, wohin sie gesendet werden.
23 
24```text
25Node.js app -> OpenTelemetry Collector -> backend di observability
26```
27 
28Warum nicht direkt zum Anbieter exportieren? Denn zunächst scheint es schneller zu sein, aber dann stellt man fest, dass jeder Dienst unterschiedliche Konfigurationen, unterschiedliche Wiederholungsversuche, unterschiedliche Filter und keinen zentralen Punkt hat, um vertrauliche Daten zu entfernen oder das Ziel zu ändern.
29 
30Der Collector ist in jeder Hinsicht langweilig. Es empfängt OTLP, führt Stapelverarbeitung durch, kann filtern, Stichproben durchführen, allgemeine Attribute hinzufügen und in mehrere Systeme exportieren.
31 
32## Selbstinstrumentierung: gut, aber nicht ausreichend
33 
34In Node.js würde ich mit der automatischen Instrumentierung beginnen. Sie erhalten sofortigen Einblick in HTTP, unterstützte Frameworks, Datenbanken und gängige Bibliotheken.
35 
36```bash
37npm install @opentelemetry/sdk-node \
38  @opentelemetry/auto-instrumentations-node \
39  @opentelemetry/exporter-trace-otlp-http
40```
41 
42Dann initialisieren Sie das SDK vor dem Rest der App:
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 
59Dabei wird jedoch das Framework gesehen, nicht Ihr Produkt. Es weiß, dass Sie eine Anfrage gestellt haben, aber es weiß nicht, dass sich die Anfrage auf „Bestellung erstellen“ oder „Abonnement erneuern“ bezog. Dafür braucht es span Handbücher an den Stellen, an denen es auf Dominanz ankommt.
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 
77Ich würde span Handbücher nirgendwo ablegen. Ich würde sie um drei Uhr morgens dort platzieren, wo ich gerne verstehen würde, was passiert ist, ohne die Hälfte der Codebasis zu lesen.
78 
79## Drei Regeln, die viel Chaos vermeiden
80 
81Erste Regel: Jeder Dienst muss `service.name`, Umgebung und Version haben. Es scheint trivial, aber ohne diese Attribute ist ein trace viel weniger nützlich. Wenn eine Bereitstellung etwas kaputt macht, möchten Sie in zwei Sekunden nach Version filtern.
82 
83Zweite Regel: Geben Sie keine sensiblen Daten in die Attribute ein. E-Mails, Token, Integer-Payloads und Adressen sollten nicht versehentlich in einem Observability-Backend landen. Wenn Sie einen Benutzer identifizieren müssen, ziehen Sie interne IDs, Hashing oder weniger vertrauliche Felder in Betracht.
84 
85Dritte Regel: Achten Sie auf die Kardinalität. `user.id` als Attribut von trace kann Sinn machen. Als metrisches Etikett kann es Ihre Kosten und Leistung zerstören.
86 
87## Kennzahlen: wenige, aber gut
88 
89Ich würde mit sehr praktischen Kennzahlen beginnen:
90 
91- Tarife, Fehler und Dauer der Anfragen;
92- Latenz externer Abhängigkeiten;
93- Anzahl der Zeitüberschreitungen und Wiederholungsversuche;
94- Tiefe der Schwänze;
95- Beschäftigungsdauer;
96- Prozentsatz der Fehler pro Version.
97 
98Der Rest wird bei Bedarf hinzugefügt. Dashboards voller Grafiken, die niemand anschaut, sind Möbel und keine Beobachtbarkeit.
99 
100## Protokolle: Immer noch nützlich, aber verlinkt
101 
102Protokolle verschwinden nicht. Sie werden einfach viel nützlicher, wenn sie `trace_id` und `span_id` tragen. Sie können also mit einem Fehlerprotokoll beginnen und trace öffnen oder mit einem langsamen trace beginnen und nur die in diesem Pfad erstellten Protokolle lesen.
103 
104Ohne Korrelation suchen Sie nach Nadeln. Mit der Korrelation wissen Sie zumindest, in welche Schublade Sie schauen müssen.
105 
106## Die Checkliste, die ich verwenden würde, bevor ich sage „Wir sind abgesichert“
107 
108- Die trace umfassen tatsächlich mehrere Dienste.
109- Zu den Protokollen gehören `trace_id` und `span_id`.
110- Der Collector ist mit Batch- und Speicherbegrenzungen konfiguriert.
111- Fehler werden in span erfasst.
112- Es gibt eine Probenahmerichtlinie.
113- Metriken haben eine kontrollierte Kardinalität.
114- Sensible Daten werden gefiltert.
115- Warnungen beginnen mit Benutzersymptomen, nicht mit zufälligen Diagrammen.
116 
117## Fazit
118 
119OpenTelemetry allein löst Produktionsprobleme nicht. Aber die Art und Weise, wie man mit ihnen umgeht, ändert sich. Anstatt blind Protokolle hinzuzufügen, beginnen Sie, dem tatsächlichen Pfad einer Anfrage zu folgen.
120 
121Für mich ist das Zeichen dafür, dass es funktioniert, einfach: Wenn etwas passiert, fragt das Team nicht mehr: „Wo suchen wir?“ und beginnt zu fragen: „Warum ist das Stück langsam?“. Hier wird Beobachtbarkeit zu einem Werkzeug und nicht zu einer Sammlung von Dashboards.
122 
123## Quellen
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 in der Produktion: Hören Sie auf, im Dunkeln zu debuggenlines 1-129 (END) — press q to close

2Das erste Mal, dass Sie Beobachtbarkeit wirklich brauchen, ist nicht, wenn Sie ruhig auf ein Dashboard schauen. Wenn ein Benutzer schreibt: „Der Checkout ist langsam“, sieht das Fehlerdiagramm normal aus und in den Protokollen finden Sie nur eine Reihe nicht verbundener Nachrichten.

4OpenTelemetry wurde geschaffen, um diesen Moment zu vermeiden: nicht um mehr Grafiken zu haben, sondern um die Teile zu verbinden. Eine Anfrage gelangt in den API, ruft eine Datenbank auf, durchläuft einen externen Anbieter, stellt einen Job in die Warteschlange und schlägt möglicherweise drei Dienste später fehl. Ohne verteilte Ablaufverfolgung rekonstruieren Sie diese Geschichte von Hand. Mit OpenTelemetry haben Sie zumindest eine Karte.

6## Es geht nicht um die trace, sondern um die Geschichte

8Ein trace ist eine Folge von span. So ausgedrückt klingt es kalt. In der Praxis ist jedes span ein Teil der Geschichte: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.

10Der Wert entsteht, wenn Sie anfangen, echte Fragen zu beantworten:

12- Welcher externe Dienst wird langsamer?

13- Stammen die Fehler von einer bestimmten Version?

14- Betrifft das Problem alle oder nur einen Mieter?

15- Versteckt ein Wiederholungsversuch eine Zeitüberschreitung?

16- Der asynchrone Job startet, stirbt dann aber woanders?

18Diese Fragen können nicht durch eine überstürzte `console.log` gelöst werden. Tatsächlich hilft Ihnen das im Notfall hinzugefügte Protokoll oft heute und wird morgen zum Lärm.

20## Wie würde ich das in eine App integrieren Node.js

22Die gesündeste Einrichtung ist einfach: Die App erstellt Telemetriedaten, der Collector entscheidet, wohin sie gesendet werden.

24```text

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

26```

28Warum nicht direkt zum Anbieter exportieren? Denn zunächst scheint es schneller zu sein, aber dann stellt man fest, dass jeder Dienst unterschiedliche Konfigurationen, unterschiedliche Wiederholungsversuche, unterschiedliche Filter und keinen zentralen Punkt hat, um vertrauliche Daten zu entfernen oder das Ziel zu ändern.

30Der Collector ist in jeder Hinsicht langweilig. Es empfängt OTLP, führt Stapelverarbeitung durch, kann filtern, Stichproben durchführen, allgemeine Attribute hinzufügen und in mehrere Systeme exportieren.

32## Selbstinstrumentierung: gut, aber nicht ausreichend

34In Node.js würde ich mit der automatischen Instrumentierung beginnen. Sie erhalten sofortigen Einblick in HTTP, unterstützte Frameworks, Datenbanken und gängige Bibliotheken.

36```bash

37npm install @opentelemetry/sdk-node \

38 @opentelemetry/auto-instrumentations-node \

39 @opentelemetry/exporter-trace-otlp-http

40```

42Dann initialisieren Sie das SDK vor dem Rest der App:

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

59Dabei wird jedoch das Framework gesehen, nicht Ihr Produkt. Es weiß, dass Sie eine Anfrage gestellt haben, aber es weiß nicht, dass sich die Anfrage auf „Bestellung erstellen“ oder „Abonnement erneuern“ bezog. Dafür braucht es span Handbücher an den Stellen, an denen es auf Dominanz ankommt.

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

77Ich würde span Handbücher nirgendwo ablegen. Ich würde sie um drei Uhr morgens dort platzieren, wo ich gerne verstehen würde, was passiert ist, ohne die Hälfte der Codebasis zu lesen.

79## Drei Regeln, die viel Chaos vermeiden

81Erste Regel: Jeder Dienst muss `service.name`, Umgebung und Version haben. Es scheint trivial, aber ohne diese Attribute ist ein trace viel weniger nützlich. Wenn eine Bereitstellung etwas kaputt macht, möchten Sie in zwei Sekunden nach Version filtern.

83Zweite Regel: Geben Sie keine sensiblen Daten in die Attribute ein. E-Mails, Token, Integer-Payloads und Adressen sollten nicht versehentlich in einem Observability-Backend landen. Wenn Sie einen Benutzer identifizieren müssen, ziehen Sie interne IDs, Hashing oder weniger vertrauliche Felder in Betracht.

85Dritte Regel: Achten Sie auf die Kardinalität. `user.id` als Attribut von trace kann Sinn machen. Als metrisches Etikett kann es Ihre Kosten und Leistung zerstören.

87## Kennzahlen: wenige, aber gut

89Ich würde mit sehr praktischen Kennzahlen beginnen:

91- Tarife, Fehler und Dauer der Anfragen;

92- Latenz externer Abhängigkeiten;

93- Anzahl der Zeitüberschreitungen und Wiederholungsversuche;

94- Tiefe der Schwänze;

95- Beschäftigungsdauer;

96- Prozentsatz der Fehler pro Version.

98Der Rest wird bei Bedarf hinzugefügt. Dashboards voller Grafiken, die niemand anschaut, sind Möbel und keine Beobachtbarkeit.

100## Protokolle: Immer noch nützlich, aber verlinkt

101

102Protokolle verschwinden nicht. Sie werden einfach viel nützlicher, wenn sie `trace_id` und `span_id` tragen. Sie können also mit einem Fehlerprotokoll beginnen und trace öffnen oder mit einem langsamen trace beginnen und nur die in diesem Pfad erstellten Protokolle lesen.

103

104Ohne Korrelation suchen Sie nach Nadeln. Mit der Korrelation wissen Sie zumindest, in welche Schublade Sie schauen müssen.

105

106## Die Checkliste, die ich verwenden würde, bevor ich sage „Wir sind abgesichert“

107

108- Die trace umfassen tatsächlich mehrere Dienste.

109- Zu den Protokollen gehören `trace_id` und `span_id`.

110- Der Collector ist mit Batch- und Speicherbegrenzungen konfiguriert.

111- Fehler werden in span erfasst.

112- Es gibt eine Probenahmerichtlinie.

113- Metriken haben eine kontrollierte Kardinalität.

114- Sensible Daten werden gefiltert.

115- Warnungen beginnen mit Benutzersymptomen, nicht mit zufälligen Diagrammen.

116

117## Fazit

118

119OpenTelemetry allein löst Produktionsprobleme nicht. Aber die Art und Weise, wie man mit ihnen umgeht, ändert sich. Anstatt blind Protokolle hinzuzufügen, beginnen Sie, dem tatsächlichen Pfad einer Anfrage zu folgen.

120

121Für mich ist das Zeichen dafür, dass es funktioniert, einfach: Wenn etwas passiert, fragt das Team nicht mehr: „Wo suchen wir?“ und beginnt zu fragen: „Warum ist das Stück langsam?“. Hier wird Beobachtbarkeit zu einem Werkzeug und nicht zu einer Sammlung von Dashboards.

122

123## Quellen

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