D’un compte neuf à une question résolue

Avant de commencer

Il vous faut une application capable d’émettre des requêtes HTTPS sortantes, et un endroit où poser deux variables d’environnement. C’est réellement tout : aucun agent à installer, aucun sidecar à faire tourner, aucun démon à maintenir en vie.

Si vous émettez déjà de l’OpenTelemetry, vous changez un endpoint plutôt que d’ajouter de l’instrumentation. Sinon, le SDK navigateur et la ligne de commande viennent tous deux de npm et demandent Node 20.19 ou plus récent.

Étape 1 — Créer un projet

Un projet, c’est une application. La plupart des équipes en créent un puis en ajoutent un second quand un deuxième service se met à remonter des données : les problèmes, la conservation et les filtres à l’entrée sont tous rattachés à un projet.

Sa création vous donne un DSN. Cette chaîne est à la fois l’adresse vers laquelle votre application envoie et l’identifiant qui la désigne, d’où sa place dans l’environnement plutôt que dans votre dépôt. Ce n’est pas un secret au sens d’une clé d’API — il ne permet que d’écrire de la télémétrie, jamais d’en lire — mais il n’a pas sa place dans un commit public.

• Ouvrez Projects dans le menu latéral. C’est sous Management, vers le bas, et non sous Monitoring en haut.
• Saisissez un nom dans la carte New project. Nommez-le d’après l’application et non d’après l’environnement : staging et production tiennent dans un même projet, distingués par l’attribut d’environnement que votre SDK envoie déjà.
• Cliquez sur Create project.
• Sur le projet qui apparaît, cliquez sur Create DSN. Rien ne part tant qu’aucun DSN n’existe.
• Copiez la chaîne affichée. Elle n’apparaît en entier qu’une fois ; l’étape 2 dit où elle va.

Menu latéral → Projects (sous Management) → New project

La liste sur votre tableau de bord confirme cette étape en lisant vos projets. Si elle la montre encore comme à faire, c’est que le projet n’a pas été créé — et non qu’il est passé inaperçu.

Étape 2a — Copier le DSN

La création du DSN l’affiche en entier, une fois. Copiez-le avant de quitter la page : ensuite, le projet n’en montre qu’un préfixe raccourci, assez pour distinguer deux clés et pas assez pour émettre. Le perdre n’a rien de dramatique — vous pouvez en créer un autre et révoquer le premier — mais c’est un détour évitable.

Ce que vous en utiliserez ensuite dépend du côté où vous êtes, et ce détail mérite deux lectures avant de coller quoi que ce soit.

Menu latéral → Projects → Create DSN (affiché une seule fois, à la création)

Étape 2b — La coller là où votre application lit son environnement

C’est-à-dire là d’où viennent déjà vos variables : le bloc env d’un conteneur, un secret Kubernetes, les variables de configuration de votre plateforme, ou un fichier .env local si vous travaillez sur un poste. Ni votre dépôt, ni votre code — le DSN change d’un projet à l’autre, le code non.

L’en-tête doit s’appeler exactement `Authorization`, avec le schéma `Bearer`. L’ingestion ne lit que celui-là : un en-tête portant un autre nom est rejeté exactement comme s’il était absent, et la réponse ne distingue pas les deux cas. C’est, de loin, la première raison pour laquelle un premier événement n’arrive jamais.

OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.snagspy.com
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20<la clé de votre DSN, pas le DSN entier>
OTEL_SERVICE_NAME=checkout-api

Le %20 est une espace, encodée en pourcent. OTEL_EXPORTER_OTLP_HEADERS est lue comme une liste de paires encodées en URL : une espace littérale entre « Bearer » et la clé n’y est pas sûre. Dans le YAML d’un collector, où cet encodage ne s’applique pas, écrivez-la avec une vraie espace : Authorization: Bearer ${SNAGSPY_DSN_KEY}.

Étape 3 — Confirmer l’arrivée du premier événement

Ne prenez pas l’absence d’erreur pour une réussite. Déployez le changement, puis faites échouer quelque chose exprès : levez une exception sur une route que vous pouvez atteindre, ou lancez une requête dont vous savez qu’elle renvoie une 500.

L’événement doit apparaître en quelques secondes. Si rien n’arrive, les causes habituelles sont, dans l’ordre : l’en-tête ne s’appelle pas exactement `Authorization` (une configuration copiée depuis un autre backend le nomme souvent autrement), la clé a été copiée avec une espace en fin de chaîne, une sortie vers l’hôte d’ingestion bloquée par un pare-feu, ou un exporter qui tamponnait et un processus terminé avant d’avoir vidé sa file.

Menu latéral → Errors

C’est l’étape que la liste du tableau de bord prouve au lieu de la supposer : elle lit votre consommation de la période en cours et ne coche que lorsque le compteur d’événements a réellement dépassé zéro. Rien d’autre sur la page ne peut faire apparaître cette coche.

Étape 4 — Choisir où les alertes vous parviennent

Une télémétrie dont personne n’est averti est une archive, pas de la supervision. Une destination est soit une adresse e-mail, soit un webhook vers une URL qui vous appartient ; l’adresse du webhook est vérifiée avant enregistrement, elle ne peut donc pas viser une adresse de réseau privé.

Les alertes et les résumés arrivent dans la langue réglée sur le compte, ce qu’il vaut la peine de définir maintenant si votre astreinte ne lit pas l’anglais.

Menu latéral → Alerts → Where to send them

Étape 5 — Inviter les personnes qui partagent l’astreinte

Les sièges sont vérifiés à l’émission de l’invitation puis de nouveau à son acceptation, parce que le nombre de sièges libres est un fait sur maintenant et non sur mardi dernier. L’offre gratuite est mono-siège : une seconde personne suppose une offre payante.

Une invitation s’envoie d’elle-même par e-mail et expire ; personne n’a besoin qu’on lui transmette un lien par messagerie.

Menu latéral → Teams → Invite a colleague

Trois décisions à prendre délibérément

Aucune ne bloque quoi que ce soit, et les trois sont plus faciles à trancher maintenant qu’à découvrir plus tard. Elles se trouvent sur la page des paramètres.

À quoi ressemble une installation terminée

• Un projet existe, et son DSN est dans votre environnement de déploiement plutôt que dans votre dépôt.
• Votre compteur d’événements de la période est supérieur à zéro, et vous avez vu une vraie erreur dans la liste des problèmes.
• Au moins une destination d’alerte existe et a été éprouvée par une alerte réellement déclenchée.
• Toute personne susceptible d’être réveillée dispose d’un compte.
• Les réglages d’IA et de conservation disent ce que vous vouliez qu’ils disent, plutôt que ce qu’ils valaient par défaut.

Si quelque chose ne fonctionne pas

Les deux endpoints de santé de la page d’état répondent sans authentification : vous pouvez distinguer un problème de plateforme d’un problème de configuration avant même d’écrire à quiconque.

Si c’est un problème de configuration, [email protected] est lu par les personnes qui ont construit ceci. Indiquez le nom du projet et l’heure approximative de l’événement qui n’est pas arrivé.