Tout ce que fait SnagSpy, et comment y accéder

Vue d’ensemble

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.

Démarrage rapide

1. Créez un compte et un projet. POST /v1/auth/register, puis connectez-vous — l’inscription ne renvoie volontairement pas de session. Créez un projet depuis le tableau de bord ou avec POST /v1/projects.
2. Émettez un DSN. POST /v1/projects/{projectID}/dsns. Un DSN s’écrit scheme://publicKey@host/projectID et peut être livré sans risque dans un bundle navigateur — il peut écrire de la télémétrie et ne rien lire.
3. Envoyez quelque chose. L’un des SDK ci-dessous, ou de l’OTLP brut vers le point d’ingestion.
4. Regardez-le arriver. L’incident apparaît sous /v1/issues et dans le tableau de bord.

Go

import "github.com/rellinxe/snagspy/sdk/go/snagspy"

client, err := snagspy.New(snagspy.Options{
    DSN:         os.Getenv("SNAGSPY_DSN"),
    Environment: "production",
    Release:     buildSHA,
})
if err != nil {
    log.Fatal(err)
}
defer client.Close(context.Background())

if err := doWork(); err != nil {
    client.CaptureException(context.Background(), err)
}

JavaScript et le navigateur

import { init, captureException } from "@snagspy/browser"

init({
  dsn: globalThis._importMeta_.env.VITE_SNAGSPY_DSN,
  environment: "production",
  release: __BUILD_SHA__,
})

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.

Concepts

Organisation

La frontière de facturation et d’appartenance. Chaque donnée appartient à exactement une organisation, et l’isolation entre locataires est une condition de publication plutôt qu’une convention.

Projet

Une application. Possède ses DSN, son consentement à la relecture et sa limite d’ingestion.

DSN

Un identifiant d’écriture par projet, scheme://publicKey@host/projectID. Public par conception : il peut écrire de la télémétrie et ne rien lire.

Clé d’API

Un identifiant de lecture pour l’API du tableau de bord, limité à l’organisation. Affiché une seule fois à la création.

Événement / occurrence

Une erreur telle qu’elle s’est produite, avec sa pile, son contexte et les signaux corrélés.

Incident

Des occurrences regroupées par empreinte. Une pile minifiée est regroupée sur le message plus le nom de chunk de chaque frame, hash de contenu retiré, pour qu’un redéploiement ne scinde pas un incident en deux.

Trace et span

OTel standard. La liste des traces filtre sur les spans et agrège des traces entières, et indique lesquels de ses chiffres sont des estimations.

Unité de relecture

L’unité de facturation de la relecture de session : une unité par tranche de 64 Kio envoyée.

Investigation

Une analyse de cause racine par IA. Facturée par appel au modèle, avant d’en connaître le résultat — un appel en échec a quand même coûté un appel.

SDK

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.

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.

Envoyer de la télémétrie

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). Chaque route ici 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 sous Limites de débit.

Relecture de session

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é.

Envoyer un fragment

POST /v1/replay
Content-Type: application/octet-stream
X-Replay-Session:     <session id>
X-Replay-Seq:         <0, 1, 2, …>
X-Replay-Encoding:    json-zstd
X-Replay-Recorded-At: <RFC 3339, optional>

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é.

Trois choses qui vous seront refusées

• Le projet n’a pas donné son consentement. La capture de relecture est par projet et reste désactivée jusqu’à activation via PUT /v1/projects/{projectID}/session-replay.
• Votre offre ne vend pas la relecture. L’offre gratuite ne la comprend pas, et l’envoi est refusé avec plan_excludes_replay en nommant votre offre. Ce n’est pas un dépassement — rien ici ne compte d’unités face à un volume inclus.
• Le fragment est trop volumineux. Le plafond s’applique aux octets réellement lus, pas à ce que Content-Length annonçait.

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.

Source maps

Envoyez les artefacts à POST /v1/projects/{projectID}/artifacts. 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.

API du tableau de bord

Servie par le processus API sur :8080 par défaut. Tout se trouve sous /v1. Les réponses sont en JSON ; les erreurs portent un code stable, un message lisible et un request_id.

Authentification

Les requêtes authentifiées par cookie sont contrôlées sur l’en-tête Origin. Une requête sans Origin correspondant à DASHBOARD_ORIGIN est refusée avec origin_rejected (403). Scripter avec curl contre une pile locale demande donc -H "Origin: http://localhost:3000".

Limites de débit

Les limites de débit servent à contrer les abus, et ce sont les seules ici qui refusent réellement une requête. Elles n’ont rien à voir avec ce que comprend votre offre : dépasser un volume inclus ne vous ralentit jamais et ne rejette jamais de télémétrie. Redis fait autorité pour que toutes les instances partagent le même compteur, avec un repli par processus qui maintient la limitation si Redis est indisponible.

Une requête refusée répond 429 avec Retry-After.

Offres, usage et rétention

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.

Ce tableau est généré à partir de la même constante que celle sur laquelle la plateforme facture : il ne peut donc pas annoncer un chiffre que le produit n’utilise pas.

Rétention

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 via PATCH /v1/settings. 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.

Alertes et intégrations

Les destinations se configurent par organisation à /v1/alert-destinations. Le type d’une destination choisit le notificateur, et un type sans notificateur derrière lui échoue bruyamment plutôt que d’être ignoré.

Déploiements

Enregistrez les déploiements avec POST /v1/deployments, ou connectez GitHub ou GitLab à /v1/projects/{projectID}/integrations. 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.

Synthèses

Un résumé planifié à /v1/reports/schedule. Prévisualisez le prochain sans l’envoyer à /v1/reports/preview.

Surveillance des tâches planifiées et disponibilité

Créez un contrôle, puis faites appeler par votre tâche son URL de pointage. Le jeton dans l’URL est l’identifiant, donc le point d’entrée 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 https://ingest.example.com/v1/checkins/<token>

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 le résultat à /v1/uptime/monitors/{monitorID}/checks.

Investigations IA

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.

• Entièrement désactivées sauf si ANTHROPIC_API_KEY est défini — désactivées, et non en échec à chaque requête.
• Facturées par appel au modèle, avant d’en connaître le résultat. Un appel en échec a quand même coûté un appel : ne facturer qu’en cas de succès masquerait une boucle emballée à l’endroit précis où vous la chercheriez.
• Refusables par organisation. Les données envoyées sont un sous-ensemble volontairement minimal d’un seul incident : type d’exception, message, pile, coupable, décomptes et la version corrélée. Jamais d’identifiants d’utilisateurs finaux, jamais de sacs d’attributs bruts, jamais d’événements entiers.

Auto-hébergement

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.

Commandes

Les 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.

Sécurité et confidentialité

• Le masquage a lieu deux fois. Les SDK masquent les valeurs qui ressemblent à des secrets avant l’envoi, et le chemin d’ingestion masque à nouveau à l’arrivée — clés, jetons, en-têtes d’autorisation, JWT, identifiants cloud, et affectations clé=valeur dans le texte libre.
• La relecture est masquée avant la capture, dans le navigateur, avec les réglages par défaut de rrweb inversés.
• Les locataires sont isolés comme condition de publication, pas par convention. La suite inter-locataires fait partie des contrôles qui doivent passer.
• Les requêtes sortantes sont contrôlées. Les destinations d’alertes passent par un composeur qui refuse les adresses privées et lien-local : un webhook ne peut donc pas être pointé vers l’intérieur du réseau.
• Les changements d’offre sont audités. Qui a accordé quoi est le seul historique que garde cette attribution.
• Le site vitrine ne stocke rien et n’appelle personne — pas d’analytique, pas de CDN, pas de polices chargées à l’exécution — c’est pourquoi il ne porte aucune bannière de cookies. Un test l’impose.

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é.

Ce que cette plateforme ne fait pas

É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.

• Elle n’agit pas sur ce que comprend une offre. Dépasser un volume inclus ne vous ralentit jamais, ne rejette jamais de télémétrie et ne déclenche aucun prélèvement — il n’y a aucune facturation au dépassement.
• Elle ne prédit pas les pannes. Elle signale une métrique qui monte vers une ligne qu’elle trace déjà, avec la pente et le trafic derrière, et dit ce qui invaliderait la projection. Il n’y a ni probabilité ni heure de décès.
• Elle ne suggère pas de mises à jour de dépendances. Une frame de pile nomme un paquet et jamais une version : une suggestion serait une instruction assurée à propos d’un logiciel qu’elle n’a jamais vu.
• Elle n’exécute aucune remédiation. Une suggestion est une phrase.
• Il n’y a pas de facturation annuelle. Le catalogue ne porte qu’un prix mensuel et le paiement vend des mois à ce prix.
• Il n’y a pas encore de factures. Rien n’est émis à personne.
• L’ingestion de points de métrique n’est pas conditionnée à l’offre, contrairement à la relecture. Une offre sans volume de points de métrique peut quand même en envoyer et les voir mesurés.
• Le tableau de bord est uniquement en anglais. Les pages vitrine, légales et de documentation sont en anglais et en français ; le produit, non.