> ## Documentation Index > Fetch the complete documentation index at: https://supastack.dev/llms.txt > Use this file to discover all available pages before exploring further. > For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt # 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. [Controlla lo stato dell'applicazione e le impostazioni operative](https://supastack.dev/it/docs/web/security.md) [Diagnostica un errore nel terminale locale](https://supastack.dev/it/docs/web/troubleshooting.md) ## 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_ 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 .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](https://supastack.dev/it/docs/web/setup-domains.md). ## Successivo [Audit, analytics ed errori](https://supastack.dev/it/docs/modules/observability.md)