Documentation développeur
SnagSpy reçoit l’OpenTelemetry de votre application, regroupe les erreurs en incidents, les corrèle avec les déploiements, les requêtes en base, la topologie des services et les journaux, puis vous dit pourquoi quelque chose a cassé. Commencez par un guide ci-dessous ; la référence de l’API a sa propre page, et chaque réglage, chaque limite et la liste honnête de ce qu’elle ne fait pas se trouvent plus bas.
Cette page est une traduction. La version anglaise fait foi : en cas de divergence sur un détail technique, c’est elle qui décrit le comportement réel. La traduction n’a pas encore été relue par un locuteur natif.
Tout ce qui suit a été vérifié dans le code en cours d’exécution plutôt qu’écrit de mémoire. Si une fonctionnalité manque ici, considérez qu’elle manque à la plateforme et dites-le — la section finale énumère délibérément les manques.
La plateforme est un monolithe modulaire en Go avec un tableau de bord Nuxt. Deux processus vous concernent : ingest, qui accepte la télémétrie, et l’API, qui sert tout ce que vous lisez. Ils sont séparés pour qu’un afflux de télémétrie n’emporte pas le tableau de bord avec lui.
Traces, journaux et métriques arrivent en OpenTelemetry. Rien n’est propriétaire : une application qui fait déjà tourner un SDK OTel peut le pointer ici et se passer entièrement de nos SDK — et le pointer ailleurs plus tard.
Un incident porte le déploiement qui l’a précédé, les requêtes lentes autour de lui, les services en amont et les journaux à côté.
Les investigations IA sélectionnent et formulent ; la plateforme calcule. Chaque chiffre d’une réponse est vérifiable, et une réponse qui ne peut être étayée n’est pas donnée.
import { init, captureException } from "@snagspy/browser"
init({ dsn: globalThis._importMeta_.env.VITE_SNAGSPY_DSN, environment: "production" })
try { risky() } catch (error) { captureException(error) }Les deux SDK masquent les valeurs qui ressemblent à des secrets avant que quoi que ce soit ne quitte le processus. Ce n’est pas une politesse côté serveur : un mot de passe qui nous est envoyé puis masqué à l’arrivée a déjà traversé le réseau.
Les deux sont de fines couches d’ergonomie au-dessus d’OpenTelemetry plutôt que des bibliothèques d’instrumentation à part entière. Ce qu’elles ajoutent est la partie facile à rater : la gestion du DSN, l’enregistrement des exceptions dans la forme sur laquelle la plateforme regroupe, et le masquage avant envoi.
| SDK | Paquet | Apporte |
|---|---|---|
| Go | sdk/go/snagspy | Analyse du DSN, CaptureException, masquage, middleware HTTP. |
| Navigateur et Node | sdk/js | Analyse du DSN, capture des erreurs et des rejets non gérés, normalisation des piles vers la forme de V8, relecture de session, retours utilisateurs, masquage, un plugin Vite pour les source maps. |
Le SDK navigateur normalise la pile de chaque moteur vers la forme de V8 avant l’envoi, et transporte les identifiants de débogage dans un attribut de span. Un identifiant de débogage fait 32 caractères hexadécimaux sans séparateurs — le SDK retire pour vous les tirets d’un UUID canonique.
Le service d’ingestion est distinct de l’API et écoute sur son propre port (:8081 par défaut ; publiez-le via INGEST_PUBLIC_URL). Il accepte l’OTLP sur HTTP, et chaque route s’authentifie avec un DSN, pas avec une session.
Deux compteurs s’appliquent à chaque envoi : une limite de requêtes par projet et une limite d’événements par organisation. Les deux sont décrites sur la page de référence de l’API.
Les points d’entrée, les en-têtes et une configuration de collecteur se trouvent dans le guide OpenTelemetry. →La relecture est enregistrée avec rrweb, et le masquage est inversé par rapport aux réglages par défaut de rrweb : le texte est masqué sauf autorisation explicite, plutôt qu’exposé sauf masquage explicite. Le masquage a lieu dans le navigateur avant la capture, car rien côté serveur ne peut défaire un enregistrement non masqué déjà arrivé.
Content-Type: application/octet-stream
X-Replay-Session: <session id>
X-Replay-Seq: <0, 1, 2, …>
X-Replay-Encoding: json-zstdLe SDK navigateur les envoie pour vous. Le corps est constitué d’octets compressés opaques que cette plateforme s’engage à ne pas lire. Une horloge client absente ou illisible n’est pas une erreur — le serveur substitue la sienne, car un enregistrement horodaté à tort vaut toujours la peine d’être conservé.
Regarder un enregistrement exige la portée propriétaire, revérifie le consentement du projet au moment de la lecture, et est inscrit au journal d’audit avant que les octets ne soient lus.
Les artefacts s’envoient par projet depuis votre build — le SDK JavaScript fournit un plugin Vite qui s’en charge. La ligne vit dans PostgreSQL et les octets dans un magasin d’objets, adressés par contenu : envoyer deux fois la même source map ne coûte donc qu’une copie.
Les frames sont résolues à la lecture, pas à l’ingestion. Une frame qui ne peut pas être résolue dit pourquoi au lieu de faire échouer la page : un envoi manquant se dégrade en frame minifiée accompagnée d’une explication, plutôt qu’en erreur.
L’usage est mesuré et rapporté. Il n’entraîne jamais d’action sur le chemin d’écriture. Dépasser un volume inclus ne vous ralentit pas, ne rejette pas votre télémétrie et ne déclenche aucun prélèvement — il n’y a aucune facturation à l’usage ici. Vous êtes prévenu une fois par signal et par période, et le message dit clairement que rien n’a été ralenti. La seule chose que décide une offre, c’est si un signal est vendu : une offre qui ne comprend pas la relecture de session refuse les envois de relecture, ce qui est un acte différent de la destruction de télémétrie déjà payée.
Une offre restreint le plafond de la plateforme et ne l’élargit jamais. Les plafonds sont de 90 jours pour les erreurs et événements et de 30 jours pour les spans de trace ; les lignes de journal suivent le réglage des traces. Une organisation peut restreindre sa propre rétention dans ses réglages. Le journal d’audit n’est pas configurable par le client.
Une offre expirée conserve ses données quatorze jours de plus. Les limites, les sièges et les fonctionnalités reviennent à l’offre gratuite dès la fin de la période payée, parce qu’un paiement les rétablit ; la fenêtre de rétention, non, parce qu’un historique d’erreurs supprimé ne revient pas.
Les destinations se configurent par organisation. Le type d’une destination choisit le notificateur, et un type sans notificateur derrière lui échoue bruyamment plutôt que d’être ignoré.
| Type | Nécessite | Notes |
|---|---|---|
| Slack | Une URL de webhook entrant | Porte un champ text à côté de l’alerte structurée. |
| Discord | Une URL de webhook | Porte un champ content. |
| Webhook générique | Une URL | Les requêtes sortantes passent par un composeur qui refuse les adresses privées et lien-local. |
| Courriel | SMTP_* configuré | Une destination n’est pas confirmée tant que l’adresse ne s’est pas prouvée. |
Enregistrez les déploiements depuis votre pipeline, ou connectez GitHub ou GitLab projet par projet. Chaque fournisseur a son propre adaptateur de webhook, et un déploiement enregistre quel fournisseur l’a attesté, et pas seulement qu’un webhook l’a fait.
Un résumé planifié, réglé par organisation. Vous pouvez prévisualiser le prochain sans l’envoyer à qui que ce soit.
Créez un contrôle, puis faites appeler par votre tâche son URL de pointage — le tableau de bord en émet une par contrôle et vous fournit une ligne de crontab prête à l’emploi. Le jeton dans l’URL est l’identifiant, donc l’appel n’est volontairement pas authentifié : une tâche cron sur une machine sans secrets peut quand même signaler son passage.
# at the end of your job
curl -fsS "$SNAGSPY_CHECKIN_URL"Un pointage qui n’arrive pas dans son délai de grâce déclenche une alerte. Les moniteurs de disponibilité vont dans l’autre sens : la plateforme sonde une URL que vous indiquez et enregistre chaque résultat sur le moniteur.
Une investigation lit un incident, une alerte ou un projet et explique ce qui s’est passé. La répartition des rôles est délibérée et mérite d’être connue avant de faire confiance à une réponse : le modèle sélectionne et formule ; la plateforme calcule. Chaque chiffre d’une réponse provient d’une requête, pas du modèle, et une réponse qui ne peut être étayée par une requête n’est pas donnée.
La pile est en Docker Compose : PostgreSQL, Redis, ClickHouse, l’API, ingest, un worker et un service migrate à usage unique. Tout se configure par l’environnement.
DATABASE_URLREDIS_URLENVLOG_LEVELDASHBOARD_ORIGINAPI_PUBLIC_URLINGEST_PUBLIC_URLSESSION_COOKIE_NAMESESSION_TTLSECURE_COOKIESSHUTDOWN_TIMEOUTINGEST_REQUESTS_PER_MINUTEINGEST_EVENTS_PER_MINUTEAUTH_ATTEMPTS_PER_MINUTEINVESTIGATIONS_PER_HOURCLICKHOUSE_URLREAD_EVENTS_FROM_CLICKHOUSESECRET_ENCRYPTION_KEYARTIFACT_DIR / ARTIFACT_S3_*BACKUP_ENCRYPTION_KEYBACKUP_DIR / BACKUP_S3_* / BACKUP_WAL_SPOOLBACKUP_RETENTION_DAYS / BACKUP_MIN_ARTIFACTSANTHROPIC_API_KEY / ANTHROPIC_MODELGENIUSPAY_API_KEY / _API_SECRET / _WEBHOOK_SECRETGENIUSPAY_BASE_URLSMTP_HOST / _PORT / _USERNAME / _PASSWORD / _FROMOPERATOR_WEBHOOK_URLACCOUNT_ALERT_WEBHOOK_URLOTLP_ENDPOINTcmd/apicmd/ingestcmd/workercmd/alertscmd/migratecmd/seedcmd/plancmd/retentioncmd/purgecmd/erasecmd/refingerprintcmd/backfillcmd/backupLes migrations sont embarquées dans le binaire. Un nouveau fichier .sql ne fait rien tant que l’image migrate n’est pas reconstruite, et le conteneur journalise « migrations applied » dans les deux cas. Vérifiez la version du schéma plutôt que la ligne de journal.
Le registre des sous-traitants et les plafonds de rétention sont publiés séparément et relèvent du même engagement : voir les pages sécurité et confidentialité.
Énuméré plutôt qu’omis. Un développeur qui ne trouve pas une fonctionnalité suppose qu’il l’a manquée, et l’apprend de la manière coûteuse.