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 /fr/docs/web/setup-observability.md (or send Accept: text/markdown).
Configurer l'observabilité
Suivi d'erreurs, analytics produit et alertes d'échec — tout est optionnel.
Trouver des informations utiles lorsqu'une action échoue
L'observabilité signifie voir ce que votre application a fait. Commencez par le terminal exécutant votre serveur Web : répétez une action qui a échoué et lisez la première erreur et tout ID de corrélation, une étiquette reliant les messages de la même requête. Partagez la commande, l'heure et l'erreur nettoyée lorsque vous demandez de l'aide ; ne partagez pas de fichiers ou de jetons .env.
Pour les rapports d'erreurs hébergés, suivez Santé et opérations pour configurer les paramètres de surveillance pris en charge dans apps/web/.env.local ou dans le tableau de bord de l'environnement de l'hôte. Enregistrez et redémarrez le serveur. Déclenchez un échec de test contrôlé dans un environnement de test et confirmez qu'il apparaît avec le contexte d'espace de travail correct. La surveillance en cours de configuration ne prouve pas qu'elle a reçu un événement.
ALERT_WEBHOOK_URL est une destination HTTPS facultative pour les alertes d’échec de livraison de webhooks de tâches et de terminaux. Si vous en avez besoin, créez un point de terminaison entrant compatible et enregistrez son côté serveur URL ; sinon laissez-le vide. Demandez à un agent de simuler une panne et de confirmer exactement une alerte, sans aucun secret dans son texte. Ne déclenchez pas de travail rémunéré ou d'échecs dans les comptes clients pour ce test.
Conserver une piste d’audit de l’espace de travail
Les enregistrements d’audit capturent des changements tels que les mises à jour de configuration d’un fournisseur dans un espace de travail. Résolvez l’espace authentifié avant de lire ou d’écrire ces enregistrements et conservez cette portée dans les événements propres au produit.
Enregistrez l’action et les identifiants nécessaires pour la comprendre. Les identifiants fournisseurs et autres valeurs sensibles doivent rester hors des charges utiles d’audit et des journaux.
Enregistrer les événements produit
Le package d’observabilité expose un adaptateur AnalyticsClient et des valeurs AnalyticsEvent limitées à l’espace de travail. Chaque événement contient un nom, une identité distincte, workspaceId et des propriétés facultatives.
Utilisez createObservability pour router les événements vers le client d’analyse configuré. Les propriétés structurées sont expurgées avant envoi ; évitez aussi les textes libres sensibles dans les noms et valeurs de propriétés.
Signaler les erreurs avec un contexte sûr
ErrorClient capture les exceptions avec des balises workspaceId et un contexte structuré supplémentaire. La couche d’observabilité partagée nettoie les exceptions et expurge le contexte sensible avant de le transmettre au client configuré.
Utilisez les adaptateurs locaux pour vérifier les événements et exceptions capturés sans contacter un fournisseur de surveillance. Avant d’activer une destination externe, vérifiez que les balises d’espace de travail sont présentes et que les identifiants sont supprimés.
Suivre une requête dans les tâches, jobs et webhooks
Les frontières d’entrée génèrent un identifiant de corrélation corr_<uuid> qui relie la requête initiale au travail déclenché. La soumission d’une tâche d’IA ajoute cet identifiant au payload de la tâche et à l’événement ai_task_submitted, chaque récepteur de webhook de facturation en génère un par requête et le planificateur en génère un par job distribué.
Le même identifiant accompagne les propriétés des événements job.completed et ai_task_completed, les données supplémentaires de captureException, la charge utile du registre webhook_event et les métadonnées payload de chaque webhook_delivery ; il figure ainsi dans le corps signé reçu par un abonné. Les identifiants absents ou mal formés sont tolérés : le consommateur en génère un nouveau au lieu de rejeter les anciennes lignes.
Déclencher des alertes pour les vrais échecs
Définissez ALERT_WEBHOOK_URL sur un endpoint HTTPS acceptant un POST JSON de forme {text, name, severity, context} ; un webhook entrant de style Slack fonctionne tel quel. Les alertes partent sans bloquer, avec un délai de cinq secondes ; un échec de livraison ajoute un avertissement console, et l’alerteur ne fait rien si la variable est absente.
Les alertes fournies sont job.failed (avertissement : un gestionnaire de job a levé une erreur ou le type est inconnu) et webhook.delivery_failed (critique : uniquement après l’échec terminal d’une livraison sortante à sa dernière tentative ; les nouvelles tentatives ordinaires restent silencieuses et chaque ligne de livraison déclenche au plus une alerte).
Mesurer les durées et diffuser des journaux structurés
serverObservability.measure chronomètre une opération asynchrone et émet un événement d’analyse <name>.duration avec durationMs, en cas de succès comme d’échec, sans masquer l’erreur originale. L’exécution du job ai.task.execute est déjà instrumentée ; sa durée arrive donc dans le client d’analyse configuré.
serverObservability.logger écrit une ligne JSON par entrée sur stdout avec les champs de base environment et service ; la couche d’expurgation partagée retire les secrets avant toute émission.
Configuration et paramètres
1. Définissez SENTRY_DSN pour le rapport d'erreurs — les exceptions sont capturées avec des IDs de corrélation et des tags de workspace.
2. Définissez NEXT_PUBLIC_POSTHOG_KEY et NEXT_PUBLIC_POSTHOG_HOST pour l'analytics produit — ce sont des valeurs publiques côté navigateur par design.
3. Définissez ALERT_WEBHOOK_URL vers un endpoint compatible Slack pour les alertes d'échec — l'app POSTe du 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/…Processus d’implémentation
La couche d'observabilité assainit les exceptions et masque les clés secrètes connues avant de transmettre — mais le texte libre des événements relève de l'auteur, donc gardez les identifiants hors des noms d'événement et des valeurs de propriété.
Les adaptateurs locaux laissent les tests assertionner sur les événements et exceptions capturés sans appeler Sentry ni PostHog ; aucune de ces variables n'est requise pour tourner en local.
Les signaux circulent ? Continuez vers Configurer les domaines personnalisés.
Vérification et dépannage
Déclenchez une exception de test et confirmez qu'elle atterrit dans Sentry avec les secrets retirés du payload, puis vérifiez qu'un échec câblé POSTe vers ALERT_WEBHOOK_URL. Si les événements n'arrivent jamais, vérifiez la paire DSN/clé et que l'hôte est joignable depuis le serveur.
Pour poursuivre la configuration, consultez Configurer les domaines personnalisés.