“Il sito è lento.”

Questo biglietto di quattro parole è la rovina di ogni team di ingegneri. Lento dove? La CPU del database è bloccata? La rete mobile è instabile? L’API di spedizione di terze parti è scaduta? Abbiamo distribuito codice errato ieri?

Se la tua strategia di debug si basa su console.log e sul controllo dei grafici della CPU del server, stai eseguendo il debug al buio. Il Monitoraggio indica che il sistema non funziona (Dashboard rosso). L’Osservabilità ti dice perché si è rotto.

Presso Maison Code Paris gestiamo piattaforme commerciali ad alto traffico in cui 1 minuto di inattività equivale a decine di migliaia di euro. Non indoviniamo. Utilizziamo la strumentazione del codice per ottenere la visione a raggi X nello stack distribuito.

Perché Maison Code ne parla

In Maison Code Paris, agiamo come la coscienza architettonica dei nostri clienti. Spesso ereditiamo stack “moderni” costruiti senza una comprensione fondamentale della scala.

Discutiamo di questo argomento perché rappresenta un punto di svolta critico nella maturità ingegneristica. Implementarlo correttamente differenzia un MVP fragile da una piattaforma resiliente di livello aziendale.

I tre pilastri dell’osservabilità

Per comprendere un sistema complesso, sono necessari tre tipi distinti di dati di telemetria:

Log: eventi discreti. “È successo qualcosa alle 10:00:01.”
Metriche: numeri aggregati. “La CPU era all’80% per 5 minuti.”
Tracce: il ciclo di vita di una richiesta. “Pulsante cliccato dall’utente -> API -> DB -> API -> UI.”

1. Registri: strutturati e ricercabili

Gli sviluppatori adorano console.log("Errore utente non trovato " + id). I DevOps lo odiano. In un sistema che produce 1.000 registri al secondo, la ricerca di “Utente errore” è lenta. Analizzarlo è impossibile. Non è possibile rappresentare graficamente il “Tasso di errore per ID utente”.

La regola d’oro: i log devono essere JSON strutturato.

{
  "livello": "errore",
  "message": "Timeout del gateway di pagamento",
  "timestamp": "2025-10-23T14:00:00Z",
  "servizio": "checkout-api",
  "contesto": {
    "userId": "u_123",
    "cartId": "c_456",
    "gateway": "striscia",
    "latenza": 5002
  },
  "traceId": "a1b2c3d4e5f6"
}

Ora, in strumenti come Datadog o ELK (Elasticsearch), puoi eseguire query:

service:checkout-api @context.gateway:stripe @level:error
“Mostrami un grafico degli errori di pagamento raggruppati per Gateway.”

2. Metriche: il polso

Le metriche sono economiche da archiviare. Sono solo numeri.

Contatori: “Richieste totali” (va verso l’alto).
Indicatori: “Utilizzo memoria” (va su e giù).
Istogrammi: “Distribuzione della latenza” (95% delle richieste < 200ms).

La trappola della cardinalità: Gli ingegneri junior spesso cercano di etichettare le metriche con dati ad alta cardinalità. http_request_duration_seconds{user_id="u_123"}. Se hai 1 milione di utenti, crei 1 milione di serie temporali. Ciò manderà in crash il tuo server Prometheus o manderà in bancarotta il tuo account Datadog. Regola: le metriche riguardano Integrità del sistema. I log/tracce sono per Specifiche dell’utente.

3. Tracciamento: il contesto

In un’architettura a microservizi o headless, il clic di un singolo utente raggiunge: CDN -> Funzione Edge -> API del nodo -> Database -> API di terze parti. Se la richiesta richiede 3 secondi, una metrica indica “Latenza elevata”. Una Traccia mostra:

API del nodo: 10 ms
Banca dati: 5 ms
API di spedizione: 2900 ms

Il tracciamento risolve il “gioco della colpa”.

OpenTelemetry: lo standard del settore

Storicamente, dovevi installare Datadog SDK o New Relic SDK. Se volevi cambiare fornitore, dovevi riscrivere il codice. OpenTelemetry (OTel) è lo standard aperto (CNCF) per la raccolta dei dati di telemetria. Strumenti il tuo codice una volta con OTel. Puoi quindi reindirizzare i dati a Datadog, Prometheus, Jaeger o semplicemente a “stdout”.

Strumentazione automatica Node.js

Il moderno OTel consente la “strumentazione automatica”. Non riscrivi i tuoi gestori Express. Applica le patch alle librerie standard (http, pg, redis) in fase di runtime.

// strumentazione.ts
importa { NodeSDK } da '@opentelemetry/sdk-node';
importa { HttpInstrumentation } da '@opentelemetry/instrumentation-http';
importa { PgInstrumentation } da '@opentelemetry/instrumentation-pg';
import { OTLPTraceExporter } da '@opentelemetry/exporter-trace-otlp-proto';

const sdk = nuovo NodeSDK({
  traceExporter: nuovo OTLPTraceExporter({
    url: 'https://api.honeycomb.io/v1/traces', // O il tuo raccoglitore
  }),
  strumentazioni: [
    new HttpInstrumentation(), // Traccia tutti gli HTTP in entrata/uscita
    new PgInstrumentation(), // Traccia tutte le query Postgres
  ],
  serviceName: 'maison-code-api',
});

sdk.start();

Con questo file da 20 righe, disponi immediatamente di grafici a cascata per ogni query del database e chiamata API nel tuo sistema di produzione.

Traccia la propagazione del contesto

Come fa il database a sapere quale “clic dell’utente” ha causato la query? Propagazione del contesto. Quando il servizio A chiama il servizio B, inserisce un’intestazione HTTP generica: “traceparent”. tracciante: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

Il servizio B legge questa intestazione. Inizia il proprio intervallo, utilizzando l’ID di A come “ID genitore”. Ciò collega le operazioni distribuite in un singolo DAG (grafico aciclico diretto).

RUM (Monitoraggio utente reale)

L’osservabilità lato server funziona perfettamente, ma gli utenti continuano a lamentarsi. “Ho cliccato sul pulsante e non è successo niente.” Registri del server: “Nessuna richiesta ricevuta.” Conclusione: JavaScript si è bloccato nel browser prima di inviare la richiesta.

Per l’osservabilità del frontend, utilizziamo RUM (Sentry, LogRocket). Cattura automaticamente:

Core Web Vitals: Largest Contentful Paint (LCP), Interazione con Next Paint (INP).
Errori della console: undefinito non è una funzione.
Session Replay: una registrazione simile a un video dei movimenti del mouse dell’utente.

Case Study: abbiamo riscontrato un bug di checkout con 0 log. Guardando Session Replay, abbiamo visto che gli utenti su iPhone SE (schermo piccolo) non riuscivano a scorrere fino al pulsante “Paga” perché un “Cookie Banner” lo copriva con .zIndex: 9999. Nessun registro avrebbe potuto dircelo. L’osservabilità visiva lo ha fatto.

Filosofia degli avvisi: principi SRE

Non chiamare il tecnico alle 3 del mattino perché “La CPU è al 90%”. Forse il 90% va bene. Forse la coda si sta elaborando velocemente. Avviso sui sintomi, non sulle cause.

SLI (indicatore del livello di servizio): una metrica importante per l’utente.

Esempio: “Disponibilità della home page”.
Esempio: “Latenza di pagamento”.

SLO (obiettivo del livello di servizio): l’obiettivo.

“La home page dovrebbe essere 200 OK il 99,9% delle volte.”
“Il checkout dovrebbe essere inferiore a 2 secondi nel 95% dei casi.”

Condizione di avviso:

“Se tasso di errore > 0,1% per 5 minuti -> PagerDuty.”
“Se tasso di errore > 5% -> Sveglia il CEO.”

Il costo dell’osservabilità

Osservare tutto è costoso. Se monitori il 100% delle richieste, la fattura del monitoraggio potrebbe superare la fattura dell’hosting. Il campionamento è la soluzione.

Campionamento basato sulla testa: decidi all’inizio di una richiesta. “Traccia il 10% degli utenti.”
Campionamento basato sulla coda (Avanzato): mantiene tutte le tracce in memoria. Se si verifica un errore, inviare la traccia completa. Se ha successo, scartalo.
- Ciò ti garantisce di acquisire il 100% degli errori ma lo 0% dei noiosi registri dei successi.

10. Monitoraggio della logica aziendale (i segnali d’oro)

I grafici della CPU non pagano le bollette. Gli Ordini pagano le bollette. I registri di accesso non ti dicono se il pulsante “Aggiungi al carrello” è rotto (se è rotto, non ci sono registri). Definiamo le metriche aziendali:

ordini_al_minuto
aggiungi_al_carrello_valore_totale
tasso_di_rifiuto_gateway_pagamento Impostiamo avvisi di “Rilevamento anomalie”. “Se Ordini/Min scende del 50% rispetto a martedì scorso -> PagerDuty.” Ciò rileva “Errori silenziosi” (ad esempio, un ascoltatore di eventi Javascript non funzionante) che i registri del server non vedranno mai.

11. Strategie di controllo dei costi

Datadog è costoso. Memorizzare ogni console.log è uno spreco. Implementiamo Livelli di registro per ambiente:

“Sviluppo”: Debug (Tutto).
Produzione: Informazioni (Eventi chiave) + Errore. Utilizziamo anche i Filtri di esclusione a livello di agente: “Elimina tutti i registri contenenti Controllo integrità OK”. Ciò riduce il volume del 40% senza perdere il segnale.

12. L’esplosione della cardinalità (come mandare in bancarotta l’osservabilità)

Inizia innocente. metrics.increment('request_duration', { url: req.url }) Quindi un bot preme “/login?random=123”. Quindi /login?random=456. All’improvviso, hai 1 milione di valori di tag univoci. Datadog ti addebita le “metriche personalizzate”. Fattura: € 15.000 al mese. Correzione: normalizza le tue dimensioni. Sostituisci /login?random=123 con /login?random=* nel middleware prima di emettere la metrica.

13. ROI del registro: questo registro vale € 0,001?

Trattiamo i tronchi come beni immobili. “Utente loggato” -> Valore alto. Conservare per 30 giorni. “Controllo dello stato superato” -> Valore basso. Lascia perdere immediatamente. “Dump dell’array di debug” -> Valore negativo. Confonde la ricerca. Implementiamo il Campionamento dinamico: Durante un incidente, attiva DEBUG per l’1% degli utenti. In tempo di pace, tienilo spento.

14. Conclusione

L’osservabilità è la differenza tra “penso che funzioni” e “so che funziona”. Sposta la cultura da “Colpa” (“Il team di rete non è riuscito”) a “Dati” (“La traccia mostra un timeout di 500 ms sullo switch”).

In un ambiente moderno, distribuito e ad alto rischio, il codice senza strumentazione è a malapena un codice. È una scatola nera che aspetta di confonderti.

**[Assumi i nostri architetti](/contact)**.