OpenTelemetry in produzione: smettere di debuggare al buio

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

1~
2La prima volta che l'osservabilità ti serve davvero non è quando stai guardando una dashboard con calma. È quando un utente scrive "il checkout è lento", il grafico degli errori sembra normale e nei log trovi solo una fila di messaggi scollegati.
3~
4OpenTelemetry nasce per evitare quel momento lì: non per avere più grafici, ma per collegare i pezzi. Una richiesta entra nell'API, chiama un database, passa da un provider esterno, pubblica un job in coda e magari fallisce tre servizi dopo. Senza tracing distribuito, quella storia la ricostruisci a mano. Con OpenTelemetry almeno hai una mappa.
5~
6## Il punto non sono le trace, è la storia
7~
8Una trace è una sequenza di span. Detto così suona freddo. In pratica, ogni span è un pezzo della storia: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.
9~
10Il valore arriva quando inizi a rispondere a domande vere:
11~
12- quale servizio esterno sta rallentando?
13- gli errori arrivano da una versione specifica?
14- il problema riguarda tutti o solo un tenant?
15- un retry sta nascondendo un timeout?
16- il job asincrono parte ma poi muore da un'altra parte?
17~
18Queste domande non le risolve un `console.log` messo di fretta. Anzi, spesso il log aggiunto in emergenza ti aiuta oggi e diventa rumore domani.
19~
20## Come lo metterei in una app Node.js
21~
22La configurazione più sana è semplice: l'app produce telemetry, il Collector decide dove mandarla.
23~
24```text
25Node.js app -> OpenTelemetry Collector -> backend di observability
26```
27~
28Perché non esportare direttamente al vendor? Perché all'inizio sembra più veloce, poi ti accorgi che ogni servizio ha configurazioni diverse, retry diversi, filtri diversi e nessun punto centrale dove togliere dati sensibili o cambiare destinazione.
29~
30Il Collector è noioso nel modo giusto. Riceve OTLP, fa batching, può filtrare, può fare sampling, può aggiungere attributi comuni e può esportare verso più sistemi.
31~
32## Auto-instrumentation: bene, ma non basta
33~
34In Node.js partirei con l'auto-instrumentation. Ti dà subito visibilità su HTTP, framework supportati, database e librerie comuni.
35~
36```bash
37npm install @opentelemetry/sdk-node \
38  @opentelemetry/auto-instrumentations-node \
39  @opentelemetry/exporter-trace-otlp-http
40```
41~
42Poi inizializzi l'SDK prima del resto dell'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~
59Questo però vede il framework, non il tuo prodotto. Sa che hai fatto una query, ma non sa che quella query era dentro "crea ordine" o "rinnova abbonamento". Per quello servono span manuali nei punti dove il dominio conta.
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~
77Non metterei span manuali ovunque. Li metterei dove, alle tre di notte, vorrei capire cosa è successo senza leggere mezzo codicebase.
78~
79## Tre regole che evitano molto caos
80~
81Prima regola: ogni servizio deve avere `service.name`, ambiente e versione. Sembra banale, ma senza questi attributi una trace è molto meno utile. Quando un deploy rompe qualcosa, vuoi filtrare per versione in due secondi.
82~
83Seconda regola: non mettere dati sensibili negli attributi. Email, token, payload interi e indirizzi non devono finire in un backend di observability per sbaglio. Se ti serve identificare un utente, valuta ID interni, hashing o campi meno delicati.
84~
85Terza regola: attenzione alla cardinalità. `user.id` come attributo di trace può avere senso. Come label di metrica può distruggerti costi e performance.
86~
87## Metriche: poche, ma buone
88~
89Io partirei da metriche molto pratiche:
90~
91- rate, errori e durata delle request;
92- latenza delle dipendenze esterne;
93- numero di timeout e retry;
94- profondità delle code;
95- durata dei job;
96- percentuale di errori per versione.
97~
98Il resto si aggiunge quando serve. Le dashboard piene di grafici che nessuno guarda sono arredamento, non observability.
99~
100## Log: ancora utili, ma collegati
101~
102I log non spariscono. Semplicemente diventano molto più utili quando portano `trace_id` e `span_id`. Così puoi partire da un log di errore e aprire la trace, oppure partire da una trace lenta e leggere solo i log prodotti in quel percorso.
103~
104Senza correlazione, stai cercando aghi. Con correlazione, almeno sai in quale cassetto guardare.
105~
106## La checklist che userei prima di dire "siamo coperti"
107~
108- Le trace attraversano davvero più servizi.
109- I log includono `trace_id` e `span_id`.
110- Il Collector è configurato con batching e limiti di memoria.
111- Gli errori vengono registrati negli span.
112- Esiste una policy di sampling.
113- Le metriche hanno cardinalità controllata.
114- I dati sensibili vengono filtrati.
115- Gli alert partono da sintomi utente, non da grafici casuali.
116~
117## Conclusione
118~
119OpenTelemetry non risolve da solo i problemi di produzione. Però cambia il modo in cui li affronti. Invece di aggiungere log alla cieca, inizi a seguire il percorso reale di una richiesta.
120~
121Per me il segnale che sta funzionando è semplice: quando succede qualcosa, il team smette di chiedere "dove guardiamo?" e inizia a chiedere "perché quel pezzo è lento?". È lì che l'osservabilità diventa uno strumento, non una collezione di dashboard.
122~
123## Fonti
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

2La prima volta che l'osservabilità ti serve davvero non è quando stai guardando una dashboard con calma. È quando un utente scrive "il checkout è lento", il grafico degli errori sembra normale e nei log trovi solo una fila di messaggi scollegati.

4OpenTelemetry nasce per evitare quel momento lì: non per avere più grafici, ma per collegare i pezzi. Una richiesta entra nell'API, chiama un database, passa da un provider esterno, pubblica un job in coda e magari fallisce tre servizi dopo. Senza tracing distribuito, quella storia la ricostruisci a mano. Con OpenTelemetry almeno hai una mappa.

6## Il punto non sono le trace, è la storia

8Una trace è una sequenza di span. Detto così suona freddo. In pratica, ogni span è un pezzo della storia: `POST /checkout`, `SELECT inventory`, `call payment provider`, `publish order.created`.

10Il valore arriva quando inizi a rispondere a domande vere:

11~

12- quale servizio esterno sta rallentando?

13- gli errori arrivano da una versione specifica?

14- il problema riguarda tutti o solo un tenant?

15- un retry sta nascondendo un timeout?

16- il job asincrono parte ma poi muore da un'altra parte?

17~

18Queste domande non le risolve un `console.log` messo di fretta. Anzi, spesso il log aggiunto in emergenza ti aiuta oggi e diventa rumore domani.

19~

20## Come lo metterei in una app Node.js

21~

22La configurazione più sana è semplice: l'app produce telemetry, il Collector decide dove mandarla.

23~

24```text

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

26```

27~

28Perché non esportare direttamente al vendor? Perché all'inizio sembra più veloce, poi ti accorgi che ogni servizio ha configurazioni diverse, retry diversi, filtri diversi e nessun punto centrale dove togliere dati sensibili o cambiare destinazione.

29~

30Il Collector è noioso nel modo giusto. Riceve OTLP, fa batching, può filtrare, può fare sampling, può aggiungere attributi comuni e può esportare verso più sistemi.

31~

32## Auto-instrumentation: bene, ma non basta

33~

34In Node.js partirei con l'auto-instrumentation. Ti dà subito visibilità su HTTP, framework supportati, database e librerie comuni.

35~

36```bash

37npm install @opentelemetry/sdk-node \

38 @opentelemetry/auto-instrumentations-node \

39 @opentelemetry/exporter-trace-otlp-http

40```

41~

42Poi inizializzi l'SDK prima del resto dell'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~

59Questo però vede il framework, non il tuo prodotto. Sa che hai fatto una query, ma non sa che quella query era dentro "crea ordine" o "rinnova abbonamento". Per quello servono span manuali nei punti dove il dominio conta.

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~

77Non metterei span manuali ovunque. Li metterei dove, alle tre di notte, vorrei capire cosa è successo senza leggere mezzo codicebase.

78~

79## Tre regole che evitano molto caos

80~

81Prima regola: ogni servizio deve avere `service.name`, ambiente e versione. Sembra banale, ma senza questi attributi una trace è molto meno utile. Quando un deploy rompe qualcosa, vuoi filtrare per versione in due secondi.

82~

83Seconda regola: non mettere dati sensibili negli attributi. Email, token, payload interi e indirizzi non devono finire in un backend di observability per sbaglio. Se ti serve identificare un utente, valuta ID interni, hashing o campi meno delicati.

84~

85Terza regola: attenzione alla cardinalità. `user.id` come attributo di trace può avere senso. Come label di metrica può distruggerti costi e performance.

86~

87## Metriche: poche, ma buone

88~

89Io partirei da metriche molto pratiche:

90~

91- rate, errori e durata delle request;

92- latenza delle dipendenze esterne;

93- numero di timeout e retry;

94- profondità delle code;

95- durata dei job;

96- percentuale di errori per versione.

97~

98Il resto si aggiunge quando serve. Le dashboard piene di grafici che nessuno guarda sono arredamento, non observability.

99~

100## Log: ancora utili, ma collegati

101~

102I log non spariscono. Semplicemente diventano molto più utili quando portano `trace_id` e `span_id`. Così puoi partire da un log di errore e aprire la trace, oppure partire da una trace lenta e leggere solo i log prodotti in quel percorso.

103~

104Senza correlazione, stai cercando aghi. Con correlazione, almeno sai in quale cassetto guardare.

105~

106## La checklist che userei prima di dire "siamo coperti"

107~

108- Le trace attraversano davvero più servizi.

109- I log includono `trace_id` e `span_id`.

110- Il Collector è configurato con batching e limiti di memoria.

111- Gli errori vengono registrati negli span.

112- Esiste una policy di sampling.

113- Le metriche hanno cardinalità controllata.

114- I dati sensibili vengono filtrati.

115- Gli alert partono da sintomi utente, non da grafici casuali.

116~

117## Conclusione

118~

119OpenTelemetry non risolve da solo i problemi di produzione. Però cambia il modo in cui li affronti. Invece di aggiungere log alla cieca, inizi a seguire il percorso reale di una richiesta.

120~

121Per me il segnale che sta funzionando è semplice: quando succede qualcosa, il team smette di chiedere "dove guardiamo?" e inizia a chiedere "perché quel pezzo è lento?". È lì che l'osservabilità diventa uno strumento, non una collezione di dashboard.

122~

123## Fonti

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~