For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /it/docs/web/setup-observability.md (or send Accept: text/markdown).
Configura l'osservabilità
Tracciamento degli errori, analytics di prodotto e avvisi di fallimento — tutto opzionale.
Trova informazioni utili quando un'azione fallisce
Osservabilità significa vedere cosa ha fatto la tua app. Inizia con il terminale che esegue il tuo server Web: ripeti un'azione non riuscita e leggi il primo errore e qualsiasi ID di correlazione, un'etichetta che collega i messaggi della stessa richiesta. Condividi il comando, l'ora e l'errore disinfettato quando chiedi aiuto; non condividere file o token .env.
Per i report sugli errori ospitati, segui Integrità e operazioni per configurare le impostazioni di monitoraggio supportate in apps/web/.env.local o nel dashboard dell'ambiente dell'host. Salva e riavvia il server. Attiva un errore di test controllato in un ambiente di test e verifica che venga visualizzato con il contesto dell'area di lavoro corretto. Il monitoraggio in fase di configurazione non dimostra di aver ricevuto un evento.
ALERT_WEBHOOK_URL è una destinazione HTTPS opzionale per gli avvisi di errore di consegna del webhook del terminale e del lavoro. Se ne hai bisogno, crea un endpoint in entrata compatibile e salva il suo lato server URL; altrimenti lascialo vuoto. Chiedi a un agente di simulare un guasto e di confermare esattamente un avviso, senza segreti nel testo. Non attivare lavori retribuiti o fallimenti negli account cliente per questo test.
Mantieni un audit trail per workspace
I record di audit catturano cambiamenti come gli aggiornamenti di configurazione dei provider dentro un workspace. Risolvi il workspace autenticato prima di leggere o scrivere quei record e preserva quel confine quando aggiungi eventi propri del prodotto.
Registra l'azione e gli identificatori necessari per comprenderla. Credenziali dei provider e altri valori sensibili devono restare fuori dai payload di audit e dai log.
Cattura eventi di prodotto
Il pacchetto di osservabilità espone un adattatore AnalyticsClient e valori AnalyticsEvent delimitati al workspace. Ogni evento porta un nome, un'identità distinct, un workspaceId e proprietà opzionali.
Usa createObservability per instradare gli eventi attraverso il tuo client di analytics configurato. Le proprietà strutturate vengono sanificate prima della consegna; tieni anche il testo libero sensibile fuori dai nomi degli eventi e dai valori delle proprietà.
Riporta gli errori con contesto sicuro
ErrorClient cattura eccezioni con tag workspaceId e contesto aggiuntivo strutturato. Il livello di osservabilità condiviso sanifica eccezioni e contesto sensibile prima di inoltrarli al client configurato.
Usa gli adattatori locali per verificare eventi ed eccezioni catturati senza chiamare un provider di monitoraggio. Testa che i tag di workspace restino presenti e che le credenziali vengano rimosse prima di attivare una destinazione esterna.
Segui una richiesta tra attività, lavori e webhook
I limiti della voce creano un ID di correlazione corr_<uuid> che collega la richiesta di origine al lavoro che attiva. L'invio dell'attività AI contrassegna l'ID sul payload dell'attività e sull'evento ai_task_submission, ogni destinatario del webhook di fatturazione ne conia uno per richiesta e lo scheduler ne conia uno per il lavoro inviato.
Lo stesso ID riguarda le proprietà dell'evento job.completed e ai_task_completed, gli extra captureException, il payload del ledger webhook_event e ogni meta del payload webhook_delivery, in modo che arrivi all'interno del corpo firmato che riceve un abbonato. Sono tollerati ID mancanti o non corretti: il consumatore conia un nuovo ID invece di rifiutare le righe più vecchie.
Avviso sui fallimenti reali
Imposta ALERT_WEBHOOK_URL su qualsiasi endpoint HTTPS che accetta un formato JSON POST {testo, nome, gravità, contesto}; un webhook in entrata in stile Slack funziona così com'è. Gli avvisi sono attivati e dimenticati con un timeout di cinque secondi, una consegna non riuscita registra un avviso sulla console e l'avvisatore emette un noop mentre la variabile non è impostata.
Gli avvisi inviati sono job.failed (avviso: un gestore lavoro ha lanciato o un tipo di lavoro è sconosciuto) e webhook.delivery_failed (critico: solo quando una consegna in uscita raggiunge un errore terminale dopo il suo ultimo tentativo; i tentativi ordinari rimangono silenziosi e ogni riga di consegna avvisa al massimo una volta).
Misura le durate e trasmetti in streaming log strutturati
serverObservability.measure cronometra un'operazione asincrona ed emette un evento analitico <name>.duration che trasporta lengthMs — in caso di successo e in caso di fallimento, senza mascherare l'errore originale. L'esecuzione del lavoro ai.task.execute è già terminata, quindi la durata dell'esecuzione dell'attività arriva nel client di analisi configurato.
serverObservability.logger scrive una riga JSON per record su stdout con i campi ambiente e base servizio; il livello di redazione condiviso rimuove i segreti prima che venga emessa qualsiasi riga.
Installazione e configurazione
1. Imposta SENTRY_DSN per il reporting degli errori — le eccezioni vengono catturate con correlation id e tag di workspace.
2. Imposta NEXT_PUBLIC_POSTHOG_KEY e NEXT_PUBLIC_POSTHOG_HOST per le analytics di prodotto — sono valori pubblici del browser per design.
3. Imposta ALERT_WEBHOOK_URL su un endpoint compatibile Slack per gli avvisi di fallimento — l'app fa POST di JSON {text, name, severity, context}.
SENTRY_DSN=https://…@….ingest.sentry.io/…
NEXT_PUBLIC_POSTHOG_KEY=phc_…
NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
ANALYTICS_PROVIDER=off # off | local | plausible | posthog
# ANALYTICS_SITE_ID=
# ANALYTICS_HOST=
ALERT_WEBHOOK_URL=https://hooks.slack.com/services/…Flusso di implementazione
Il livello di osservabilità sanifica le eccezioni e redige le chiavi segrete note prima dell'inoltro — ma il testo libero degli eventi è responsabilità dell'autore, quindi tieni le credenziali fuori dai nomi degli eventi e dai valori delle proprietà.
Gli adattatori locali permettono ai test di asserire su eventi ed eccezioni catturati senza chiamare Sentry o PostHog; nessuna di queste variabili è richiesta per girare in locale.
I segnali scorrono? Continua con Configura i domini personalizzati.
Verifica e risoluzione dei problemi
Scatena un'eccezione di test e conferma che arrivi in Sentry con i secret eliminati dal payload, poi controlla che un fallimento collegato faccia POST ad ALERT_WEBHOOK_URL. Se gli eventi non arrivano mai, verifica la coppia DSN/chiave e che l'host sia raggiungibile dal server.
Per continuare la configurazione, leggi Configura i domini personalizzati.