OpenTelemetry w produkcji: Zatrzymaj debugowanie w ciemności

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

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

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~