Observability — Cheat Sheet

Tag: observability, telemetry, logs, metrics, traces, opentelemetry, monitoring

Livello: intermedio

TL;DR: L'osservabilità misura la capacità di comprendere lo stato interno di un sistema analizzando i suoi output esterni. Permette il debugging di sistemi distribuiti sconosciuti senza dover rilasciare nuovo codice.

Concetti chiave

Si basa sui tre pilastri classici: Logs (eventi), Metrics (aggregazioni temporali) e Traces (flussi di esecuzione).

Il monitoraggio segnala la presenza di un problema; l'osservabilità permette di scoprirne la causa.

La correlazione è fondamentale: log, metriche e tracce devono condividere gli stessi identificatori (trace ID, span ID).

OpenTelemetry è lo standard CNCF per strumentare, generare e collezionare dati telemetrici in modo agnostico.

Strumentazione automatica: le librerie iniettano hook nel runtime o nei framework senza toccare il codice di business.

Strumentazione manuale: lo sviluppatore aggiunge span custom o attributi di business direttamente nel codice.

Cardinalità: il numero di combinazioni uniche per i label di una metrica.

Alta cardinalità degrada le performance dei backend di telemetria (es. Prometheus) e aumenta i costi di storage.

Domande tipiche e risposte pronte

Q: Qual è la differenza tra monitoraggio e osservabilità?R: Il monitoraggio controlla cruscotti predefiniti per "known unknowns". L'osservabilità mi permette di interrogare il sistema per indagare "unknown unknowns".

Q: Come propaghi il contesto in un'architettura a microservizi?R: Sfrutto lo standard W3C Trace Context, iniettando l'header traceparent nelle chiamate HTTP e nei messaggi sui broker asincroni.

Q: Come gestisci il problema della high cardinality nelle metriche?R: Evito di inserire identificatori unici come email o user_id nelle label delle metriche. Sposto quei dati specifici nei log strutturati o come attributi negli span delle tracce.

Insidie e errori comuni

Produrre log testuali (testo libero) invece di log strutturati (es. JSON), rendendo complessa la ricerca e l'indicizzazione.

Interrompere la catena delle tracce non passando i context header attraverso code di messaggi (Kafka, RabbitMQ) o background job.

Collezionare troppi dati inutili (over-logging), aumentando i costi di retention senza fornire reale valore per il debugging.

Tenere log, metriche e tracce in sistemi separati e non integrati, costringendo l'operatore a correlare manualmente gli eventi.

Snippet e comandiTypeScript

```import { trace, context } from '@opentelemetry/api';

const tracer = trace.getTracer('my-business-service');

// Creazione di uno span custom manuale

tracer.startActiveSpan('process-payment', (span) => {

try {

const paymentId = "pay_98765";

// Aggiunta di contesto specifico di business

span.setAttribute('payment.id', paymentId);

span.setAttribute('payment.currency', 'EUR');

// Logica di business

span.setStatus({ code: 1 }); // OK

} catch (error) {

span.recordException(error);

span.setStatus({ code: 2, message: error.message }); // ERROR

throw error;

} finally {

span.end();

}

});

```