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

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

NORMAL · opentelemetry-nodejs-observability-guide.md [readonly]129 lines · :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:

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~