OpenTelemetry w produkcji: Zatrzymaj debugowanie w ciemności

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

1 
2Po raz pierwszy naprawdę potrzebujesz obserwowalności, nie wtedy, gdy spokojnie patrzysz na pulpit nawigacyjny. Dzieje się tak, gdy użytkownik napisze „zamawianie jest powolne”, wykres błędów wygląda normalnie, a w logach znajduje się tylko rząd niepołączonych wiadomości.
3 
4OpenTelemetry powstało, aby uniknąć tego momentu: nie po to, aby mieć więcej grafiki, ale aby połączyć elementy. Żądanie wchodzi do API, wywołuje bazę danych, przechodzi przez zewnętrznego dostawcę, umieszcza zadanie w kolejce i może zakończyć się niepowodzeniem trzech usług później. Bez rozproszonego śledzenia rekonstruujesz tę historię ręcznie. Przy OpenTelemetry przynajmniej masz mapę.
5 
6## Nie chodzi o trace, tylko o historię
7 
8A trace jest ciągiem span. Ujmując to, brzmi zimno. W praktyce każde span to fragment historii: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.
9 
10Wartość pojawia się, gdy zaczynasz odpowiadać na prawdziwe pytania:
11 
12- która usługa zewnętrzna zwalnia?
13- czy błędy pochodzą z konkretnej wersji?
14- czy problem dotyczy wszystkich, czy tylko jednego najemcy?
15- czy ponowna próba ukrywa przekroczenie limitu czasu?
16- zadanie asynchroniczne rozpoczyna się, ale potem kończy się gdzie indziej?
17 
18Tych pytań nie da się rozwiązać rzucając w pośpiechu `console.log`. Rzeczywiście, często dziennik dodany w sytuacji awaryjnej pomaga dzisiaj, a jutro staje się hałasem.
19 
20## Jak umieścić to w aplikacji Node.js
21 
22Najzdrowsza konfiguracja jest prosta: aplikacja generuje dane telemetryczne, a Collector decyduje, gdzie je wysłać.
23 
24```text
25Node.js app -> OpenTelemetry Collector -> backend di observability
26```
27 
28Dlaczego nie eksportować bezpośrednio do dostawcy? Ponieważ na początku wydaje się to szybsze, później zdajesz sobie sprawę, że każda usługa ma inną konfigurację, różne próby, różne filtry i brak centralnego punktu, w którym można usunąć wrażliwe dane lub zmienić miejsce docelowe.
29 
30Collector jest nudne pod każdym względem. Otrzymuje OTLP, wykonuje przetwarzanie wsadowe, może filtrować, może pobierać próbki, może dodawać wspólne atrybuty i może eksportować do wielu systemów.
31 
32## Samoinstrumentacja: dobra, ale niewystarczająca
33 
34W Node.js zacząłbym od autoinstrumentacji. Zapewnia natychmiastowy wgląd w protokół HTTP, obsługiwane platformy, bazy danych i popularne biblioteki.
35 
36```bash
37npm install @opentelemetry/sdk-node \
38  @opentelemetry/auto-instrumentations-node \
39  @opentelemetry/exporter-trace-otlp-http
40```
41 
42Następnie inicjujesz SDK przed resztą aplikacji:
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 
59Jednak to widzi ramy, a nie Twój produkt. Wie, że wykonałeś zapytanie, ale nie wie, że zapytanie było w „kolejności utworzenia” lub „odnowienia subskrypcji”. Do tego potrzebne są span podręczników w punktach, w których liczy się dominacja.
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 
77Nie umieściłbym nigdzie instrukcji span. Umieściłbym je tam, gdzie o trzeciej nad ranem chciałbym zrozumieć, co się stało, bez czytania połowy bazy kodu.
78 
79## Trzy zasady, które pozwalają uniknąć dużego chaosu
80 
81Pierwsza zasada: każda usługa musi mieć `service.name`, środowisko i wersję. Wydaje się to banalne, ale bez tych atrybutów trace jest znacznie mniej przydatne. Gdy wdrożenie coś zepsuje, w ciągu dwóch sekund chcesz filtrować według wersji.
82 
83Druga zasada: nie umieszczaj wrażliwych danych w atrybutach. E-maile, tokeny, ładunki w postaci liczb całkowitych i adresy nie powinny przypadkowo trafiać do backendu umożliwiającego obserwowanie. Jeśli chcesz zidentyfikować użytkownika, rozważ wewnętrzne identyfikatory, hashowanie lub mniej wrażliwe pola.
84 
85Trzecia zasada: zwracaj uwagę na kardynalność. `user.id` jako atrybut trace może mieć sens. Jako etykieta metryczna może zniszczyć Twoje koszty i wydajność.
86 
87## Wskaźniki: kilka, ale dobre
88 
89Zacząłbym od bardzo praktycznych wskaźników:
90 
91- stawki, błędy i czas trwania żądań;
92- opóźnienie zależności zewnętrznych;
93- liczba przekroczeń limitu czasu i ponownych prób;
94- głębokość ogonów;
95- czas trwania pracy;
96- procent błędów na wersję.
97 
98Resztę dodaje się w razie potrzeby. Dashboardy pełne wykresów, na które nikt nie patrzy, to meble, a nie obserwowalność.
99 
100## Dzienniki: nadal przydatne, ale połączone
101 
102Logi nie znikają. Po prostu stają się znacznie bardziej przydatne, gdy niosą `trace_id` i `span_id`. Możesz więc zacząć od dziennika błędów i otworzyć trace lub zacząć od wolnego trace i czytać tylko logi utworzone w tej ścieżce.
103 
104Bez korelacji szukasz igieł. Dzięki korelacji przynajmniej wiesz, w której szufladzie szukać.
105 
106## Lista kontrolna, której użyłbym przed stwierdzeniem „jesteśmy objęci”
107 
108- trace w rzeczywistości obejmuje wiele usług.
109- Dzienniki obejmują `trace_id` i `span_id`.
110- Collector jest skonfigurowany z limitami przetwarzania wsadowego i pamięci.
111- Błędy są rejestrowane w span.
112- Istnieje polityka pobierania próbek.
113- Metryki kontrolowały liczność.
114- Wrażliwe dane są filtrowane.
115- Alerty zaczynają się od objawów użytkownika, a nie losowych wykresów.
116 
117## Wniosek
118 
119OpenTelemetry samo w sobie nie rozwiązuje problemów produkcyjnych. Ale sposób, w jaki sobie z nimi radzisz, zmienia się. Zamiast na ślepo dodawać logi, zaczynasz podążać rzeczywistą ścieżką żądania.
120 
121Dla mnie znak, że to działa, jest prosty: kiedy coś się dzieje, zespół przestaje pytać „gdzie szukamy?” i zaczyna pytać „dlaczego ten utwór jest powolny?”. W tym miejscu obserwowalność staje się narzędziem, a nie zbiorem dashboardów.
122 
123## Źródła
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 w produkcji: Zatrzymaj debugowanie w ciemnościlines 1-129 (END) — press q to close

2Po raz pierwszy naprawdę potrzebujesz obserwowalności, nie wtedy, gdy spokojnie patrzysz na pulpit nawigacyjny. Dzieje się tak, gdy użytkownik napisze „zamawianie jest powolne”, wykres błędów wygląda normalnie, a w logach znajduje się tylko rząd niepołączonych wiadomości.

4OpenTelemetry powstało, aby uniknąć tego momentu: nie po to, aby mieć więcej grafiki, ale aby połączyć elementy. Żądanie wchodzi do API, wywołuje bazę danych, przechodzi przez zewnętrznego dostawcę, umieszcza zadanie w kolejce i może zakończyć się niepowodzeniem trzech usług później. Bez rozproszonego śledzenia rekonstruujesz tę historię ręcznie. Przy OpenTelemetry przynajmniej masz mapę.

6## Nie chodzi o trace, tylko o historię

8A trace jest ciągiem span. Ujmując to, brzmi zimno. W praktyce każde span to fragment historii: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.

10Wartość pojawia się, gdy zaczynasz odpowiadać na prawdziwe pytania:

12- która usługa zewnętrzna zwalnia?

13- czy błędy pochodzą z konkretnej wersji?

14- czy problem dotyczy wszystkich, czy tylko jednego najemcy?

15- czy ponowna próba ukrywa przekroczenie limitu czasu?

16- zadanie asynchroniczne rozpoczyna się, ale potem kończy się gdzie indziej?

18Tych pytań nie da się rozwiązać rzucając w pośpiechu `console.log`. Rzeczywiście, często dziennik dodany w sytuacji awaryjnej pomaga dzisiaj, a jutro staje się hałasem.

20## Jak umieścić to w aplikacji Node.js

22Najzdrowsza konfiguracja jest prosta: aplikacja generuje dane telemetryczne, a Collector decyduje, gdzie je wysłać.

24```text

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

26```

28Dlaczego nie eksportować bezpośrednio do dostawcy? Ponieważ na początku wydaje się to szybsze, później zdajesz sobie sprawę, że każda usługa ma inną konfigurację, różne próby, różne filtry i brak centralnego punktu, w którym można usunąć wrażliwe dane lub zmienić miejsce docelowe.

30Collector jest nudne pod każdym względem. Otrzymuje OTLP, wykonuje przetwarzanie wsadowe, może filtrować, może pobierać próbki, może dodawać wspólne atrybuty i może eksportować do wielu systemów.

32## Samoinstrumentacja: dobra, ale niewystarczająca

34W Node.js zacząłbym od autoinstrumentacji. Zapewnia natychmiastowy wgląd w protokół HTTP, obsługiwane platformy, bazy danych i popularne biblioteki.

36```bash

37npm install @opentelemetry/sdk-node \

38 @opentelemetry/auto-instrumentations-node \

39 @opentelemetry/exporter-trace-otlp-http

40```

42Następnie inicjujesz SDK przed resztą aplikacji:

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

59Jednak to widzi ramy, a nie Twój produkt. Wie, że wykonałeś zapytanie, ale nie wie, że zapytanie było w „kolejności utworzenia” lub „odnowienia subskrypcji”. Do tego potrzebne są span podręczników w punktach, w których liczy się dominacja.

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

77Nie umieściłbym nigdzie instrukcji span. Umieściłbym je tam, gdzie o trzeciej nad ranem chciałbym zrozumieć, co się stało, bez czytania połowy bazy kodu.

79## Trzy zasady, które pozwalają uniknąć dużego chaosu

81Pierwsza zasada: każda usługa musi mieć `service.name`, środowisko i wersję. Wydaje się to banalne, ale bez tych atrybutów trace jest znacznie mniej przydatne. Gdy wdrożenie coś zepsuje, w ciągu dwóch sekund chcesz filtrować według wersji.

83Druga zasada: nie umieszczaj wrażliwych danych w atrybutach. E-maile, tokeny, ładunki w postaci liczb całkowitych i adresy nie powinny przypadkowo trafiać do backendu umożliwiającego obserwowanie. Jeśli chcesz zidentyfikować użytkownika, rozważ wewnętrzne identyfikatory, hashowanie lub mniej wrażliwe pola.

85Trzecia zasada: zwracaj uwagę na kardynalność. `user.id` jako atrybut trace może mieć sens. Jako etykieta metryczna może zniszczyć Twoje koszty i wydajność.

87## Wskaźniki: kilka, ale dobre

89Zacząłbym od bardzo praktycznych wskaźników:

91- stawki, błędy i czas trwania żądań;

92- opóźnienie zależności zewnętrznych;

93- liczba przekroczeń limitu czasu i ponownych prób;

94- głębokość ogonów;

95- czas trwania pracy;

96- procent błędów na wersję.

98Resztę dodaje się w razie potrzeby. Dashboardy pełne wykresów, na które nikt nie patrzy, to meble, a nie obserwowalność.

100## Dzienniki: nadal przydatne, ale połączone

101

102Logi nie znikają. Po prostu stają się znacznie bardziej przydatne, gdy niosą `trace_id` i `span_id`. Możesz więc zacząć od dziennika błędów i otworzyć trace lub zacząć od wolnego trace i czytać tylko logi utworzone w tej ścieżce.

103

104Bez korelacji szukasz igieł. Dzięki korelacji przynajmniej wiesz, w której szufladzie szukać.

105

106## Lista kontrolna, której użyłbym przed stwierdzeniem „jesteśmy objęci”

107

108- trace w rzeczywistości obejmuje wiele usług.

109- Dzienniki obejmują `trace_id` i `span_id`.

110- Collector jest skonfigurowany z limitami przetwarzania wsadowego i pamięci.

111- Błędy są rejestrowane w span.

112- Istnieje polityka pobierania próbek.

113- Metryki kontrolowały liczność.

114- Wrażliwe dane są filtrowane.

115- Alerty zaczynają się od objawów użytkownika, a nie losowych wykresów.

116

117## Wniosek

118

119OpenTelemetry samo w sobie nie rozwiązuje problemów produkcyjnych. Ale sposób, w jaki sobie z nimi radzisz, zmienia się. Zamiast na ślepo dodawać logi, zaczynasz podążać rzeczywistą ścieżką żądania.

120

121Dla mnie znak, że to działa, jest prosty: kiedy coś się dzieje, zespół przestaje pytać „gdzie szukamy?” i zaczyna pytać „dlaczego ten utwór jest powolny?”. W tym miejscu obserwowalność staje się narzędziem, a nie zbiorem dashboardów.

122

123## Źródła

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