OpenTelemetry éles környezetben: A sötétben végzett hibakeresés leállítása

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

1~
2Nem akkor van először igazán szükséged a megfigyelhetőségre, ha nyugodtan nézel egy műszerfalat. Amikor a felhasználó azt írja ki, hogy "lassú a kijelentkezés", a hibadiagram normálisnak tűnik, és a naplókban csak egy sor megszakadt üzenet található.
3~
4A OpenTelemetry azért jött létre, hogy elkerüljük ezt a pillanatot: nem azért, hogy több grafika legyen, hanem hogy összekapcsoljuk a darabokat. Egy kérés belép a API-be, felhív egy adatbázist, átmegy egy külső szolgáltatón, felad egy sorban állást, és később három szolgáltatás is meghiúsul. Elosztott nyomkövetés nélkül kézzel rekonstruálhatja a történetet. A OpenTelemetry-vel legalább van térképed.
5~
6## A lényeg nem a trace, hanem a történet
7~
8A trace a span sorozata. Így fogalmazva hidegnek hangzik. A gyakorlatban minden span a történet egy darabja: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.
9~
10Az érték akkor jön létre, amikor elkezdesz válaszolni a valódi kérdésekre:
11~
12- melyik külső szolgáltatás lassul?
13- a hibák egy adott verzióból származnak?
14- mindenkit érint a probléma vagy csak egy bérlőt?
15- az újrapróbálkozás időtúllépést rejt?
16- az aszinkron munka elindul, de máshol meghal?
17~
18Ezeket a kérdéseket nem lehet megoldani egy sietve dobott `console.log`-vel. Valójában gyakran a vészhelyzetben hozzáadott napló ma segít, holnap pedig zaj lesz.
19~
20## Hogyan helyezném el ezt egy alkalmazásban Node.js
21~
22A legegészségesebb beállítás egyszerű: az alkalmazás telemetriát állít elő, a Collector dönti el, hova küldje.
23~
24```text
25Node.js app -> OpenTelemetry Collector -> backend di observability
26```
27~
28Miért nem exportálhatja közvetlenül az eladóhoz? Mivel eleinte gyorsabbnak tűnik, aztán rájössz, hogy minden szolgáltatás más-más konfigurációval, különböző újrapróbálkozásokkal, különböző szűrőkkel rendelkezik, és nincs központi pont az érzékeny adatok eltávolítására vagy a célhely megváltoztatására.
29~
30A Collector a megfelelő módon unalmas. OTLP fogad, kötegelést végez, tud szűrni, mintavételt végezni, általános attribútumokat adhat hozzá, és több rendszerbe is exportálhat.
31~
32## Önműszer: jó, de nem elég
33~
34A Node.js-ben az automatikus műszerezéssel kezdeném. Azonnali rálátást biztosít a HTTP-re, a támogatott keretrendszerekre, adatbázisokra és általános könyvtárakra.
35~
36```bash
37npm install @opentelemetry/sdk-node \
38  @opentelemetry/auto-instrumentations-node \
39  @opentelemetry/exporter-trace-otlp-http
40```
41~
42Ezután inicializálja a SDK-t az alkalmazás többi része előtt:
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~
59Ez azonban a keretet látja, nem a termékét. Tudja, hogy lekérdezést hajtott végre, de nem tudja, hogy a lekérdezés „megrendelés létrehozása” vagy „előfizetés megújítása” volt. Ehhez span kézikönyvre van szüksége azokon a pontokon, ahol a dominancia számít.
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~
77span kézikönyveket nem tennék sehova. Oda tenném őket, ahol hajnali háromkor szeretném megérteni, mi történt anélkül, hogy elolvasnám a fél kódbázist.
78~
79## Három szabály, amely elkerüli a sok káoszt
80~
81Első szabály: minden szolgáltatásnak rendelkeznie kell `service.name`-vel, környezettel és verzióval. Triviálisnak tűnik, de ezen attribútumok nélkül a trace sokkal kevésbé hasznos. Ha egy központi telepítés megszakít valamit, két másodpercen belül verzió szerint kell szűrni.
82~
83Második szabály: ne tegyen érzékeny adatokat az attribútumok közé. Az e-mailek, tokenek, egész számok és címek nem kerülhetnek véletlenül megfigyelhetőségi háttérrendszerbe. Ha azonosítania kell egy felhasználót, vegye figyelembe a belső azonosítókat, a hash-t vagy a kevésbé érzékeny mezőket.
84~
85Harmadik szabály: figyelj a kardinalitásra. A `user.id` mint az trace attribútuma értelmes lehet. Mérési címkeként tönkreteheti költségeit és teljesítményét.
86~
87## Mutatók: kevés, de jó
88~
89Nagyon praktikus mérőszámokkal kezdeném:
90~
91- a kérések aránya, hibái és időtartama;
92- külső függőségek késleltetése;
93- időtúllépések és újrapróbálkozások száma;
94- a farok mélysége;
95- a munkavégzés időtartama;
96- a hibák százalékos aránya verziónként.
97~
98A többit hozzáadjuk, ha szükséges. A grafikonokkal teli műszerfalak, amelyeket senki sem néz meg, bútorok, nem megfigyelhetőség.
99~
100## Naplók: Még mindig hasznos, de linkelve
101~
102A naplók nem tűnnek el. Egyszerűen sokkal hasznosabbá válnak, ha `trace_id` és `span_id` jelet hordoznak. Tehát elindíthatja egy hibanaplóból, és megnyithatja a trace-t, vagy kezdheti a lassú trace-t, és csak az ezen az útvonalon előállított naplókat olvashatja el.
103~
104Korreláció nélkül tűket keresel. A korrelációval legalább tudod, melyik fiókba nézz.
105~
106## Az ellenőrző lista, amelyet használnék, mielőtt azt mondanám, hogy "elég vagyunk"
107~
108- A trace valójában több szolgáltatást is keresztez.
109- A naplók közé tartozik a `trace_id` és a `span_id`.
110- A Collector kötegelési és memóriakorlátokkal van konfigurálva.
111- A hibákat a span tartalmazza.
112- Van mintavételi szabályzat.
113- A mérőszámok szabályozták a kardinalitást.
114- Az érzékeny adatok kiszűrésre kerülnek.
115- A riasztások a felhasználói tünetekből indulnak ki, nem véletlenszerű grafikonokból.
116~
117## Következtetés
118~
119A OpenTelemetry önmagában nem oldja meg a termelési problémákat. De megváltozik a velük való bánásmód. A naplók vakon történő hozzáadása helyett elkezdi követni a kérés tényleges elérési útját.
120~
121Számomra a jele annak, hogy működik, egyszerű: ha valami történik, a csapat abbahagyja a „hol keresünk?” kérdést. és elkezdi kérdezni "miért lassú az a darab?". Ekkor válik a megfigyelhetőség eszközzé, nem pedig műszerfalak gyűjteményévé.
122~
123## Források
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

2Nem akkor van először igazán szükséged a megfigyelhetőségre, ha nyugodtan nézel egy műszerfalat. Amikor a felhasználó azt írja ki, hogy "lassú a kijelentkezés", a hibadiagram normálisnak tűnik, és a naplókban csak egy sor megszakadt üzenet található.

4A OpenTelemetry azért jött létre, hogy elkerüljük ezt a pillanatot: nem azért, hogy több grafika legyen, hanem hogy összekapcsoljuk a darabokat. Egy kérés belép a API-be, felhív egy adatbázist, átmegy egy külső szolgáltatón, felad egy sorban állást, és később három szolgáltatás is meghiúsul. Elosztott nyomkövetés nélkül kézzel rekonstruálhatja a történetet. A OpenTelemetry-vel legalább van térképed.

6## A lényeg nem a trace, hanem a történet

8A trace a span sorozata. Így fogalmazva hidegnek hangzik. A gyakorlatban minden span a történet egy darabja: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.

10Az érték akkor jön létre, amikor elkezdesz válaszolni a valódi kérdésekre:

11~

12- melyik külső szolgáltatás lassul?

13- a hibák egy adott verzióból származnak?

14- mindenkit érint a probléma vagy csak egy bérlőt?

15- az újrapróbálkozás időtúllépést rejt?

16- az aszinkron munka elindul, de máshol meghal?

17~

18Ezeket a kérdéseket nem lehet megoldani egy sietve dobott `console.log`-vel. Valójában gyakran a vészhelyzetben hozzáadott napló ma segít, holnap pedig zaj lesz.

19~

20## Hogyan helyezném el ezt egy alkalmazásban Node.js

21~

22A legegészségesebb beállítás egyszerű: az alkalmazás telemetriát állít elő, a Collector dönti el, hova küldje.

23~

24```text

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

26```

27~

28Miért nem exportálhatja közvetlenül az eladóhoz? Mivel eleinte gyorsabbnak tűnik, aztán rájössz, hogy minden szolgáltatás más-más konfigurációval, különböző újrapróbálkozásokkal, különböző szűrőkkel rendelkezik, és nincs központi pont az érzékeny adatok eltávolítására vagy a célhely megváltoztatására.

29~

30A Collector a megfelelő módon unalmas. OTLP fogad, kötegelést végez, tud szűrni, mintavételt végezni, általános attribútumokat adhat hozzá, és több rendszerbe is exportálhat.

31~

32## Önműszer: jó, de nem elég

33~

34A Node.js-ben az automatikus műszerezéssel kezdeném. Azonnali rálátást biztosít a HTTP-re, a támogatott keretrendszerekre, adatbázisokra és általános könyvtárakra.

35~

36```bash

37npm install @opentelemetry/sdk-node \

38 @opentelemetry/auto-instrumentations-node \

39 @opentelemetry/exporter-trace-otlp-http

40```

41~

42Ezután inicializálja a SDK-t az alkalmazás többi része előtt:

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~

59Ez azonban a keretet látja, nem a termékét. Tudja, hogy lekérdezést hajtott végre, de nem tudja, hogy a lekérdezés „megrendelés létrehozása” vagy „előfizetés megújítása” volt. Ehhez span kézikönyvre van szüksége azokon a pontokon, ahol a dominancia számít.

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~

77span kézikönyveket nem tennék sehova. Oda tenném őket, ahol hajnali háromkor szeretném megérteni, mi történt anélkül, hogy elolvasnám a fél kódbázist.

78~

79## Három szabály, amely elkerüli a sok káoszt

80~

81Első szabály: minden szolgáltatásnak rendelkeznie kell `service.name`-vel, környezettel és verzióval. Triviálisnak tűnik, de ezen attribútumok nélkül a trace sokkal kevésbé hasznos. Ha egy központi telepítés megszakít valamit, két másodpercen belül verzió szerint kell szűrni.

82~

83Második szabály: ne tegyen érzékeny adatokat az attribútumok közé. Az e-mailek, tokenek, egész számok és címek nem kerülhetnek véletlenül megfigyelhetőségi háttérrendszerbe. Ha azonosítania kell egy felhasználót, vegye figyelembe a belső azonosítókat, a hash-t vagy a kevésbé érzékeny mezőket.

84~

85Harmadik szabály: figyelj a kardinalitásra. A `user.id` mint az trace attribútuma értelmes lehet. Mérési címkeként tönkreteheti költségeit és teljesítményét.

86~

87## Mutatók: kevés, de jó

88~

89Nagyon praktikus mérőszámokkal kezdeném:

90~

91- a kérések aránya, hibái és időtartama;

92- külső függőségek késleltetése;

93- időtúllépések és újrapróbálkozások száma;

94- a farok mélysége;

95- a munkavégzés időtartama;

96- a hibák százalékos aránya verziónként.

97~

98A többit hozzáadjuk, ha szükséges. A grafikonokkal teli műszerfalak, amelyeket senki sem néz meg, bútorok, nem megfigyelhetőség.

99~

100## Naplók: Még mindig hasznos, de linkelve

101~

102A naplók nem tűnnek el. Egyszerűen sokkal hasznosabbá válnak, ha `trace_id` és `span_id` jelet hordoznak. Tehát elindíthatja egy hibanaplóból, és megnyithatja a trace-t, vagy kezdheti a lassú trace-t, és csak az ezen az útvonalon előállított naplókat olvashatja el.

103~

104Korreláció nélkül tűket keresel. A korrelációval legalább tudod, melyik fiókba nézz.

105~

106## Az ellenőrző lista, amelyet használnék, mielőtt azt mondanám, hogy "elég vagyunk"

107~

108- A trace valójában több szolgáltatást is keresztez.

109- A naplók közé tartozik a `trace_id` és a `span_id`.

110- A Collector kötegelési és memóriakorlátokkal van konfigurálva.

111- A hibákat a span tartalmazza.

112- Van mintavételi szabályzat.

113- A mérőszámok szabályozták a kardinalitást.

114- Az érzékeny adatok kiszűrésre kerülnek.

115- A riasztások a felhasználói tünetekből indulnak ki, nem véletlenszerű grafikonokból.

116~

117## Következtetés

118~

119A OpenTelemetry önmagában nem oldja meg a termelési problémákat. De megváltozik a velük való bánásmód. A naplók vakon történő hozzáadása helyett elkezdi követni a kérés tényleges elérési útját.

120~

121Számomra a jele annak, hogy működik, egyszerű: ha valami történik, a csapat abbahagyja a „hol keresünk?” kérdést. és elkezdi kérdezni "miért lassú az a darab?". Ekkor válik a megfigyelhetőség eszközzé, nem pedig műszerfalak gyűjteményévé.

122~

123## Források

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~