SarutobiDocumentation
Retour

Comment ça fonctionne

Sarutobi relie quatre choses : une librairie qui envoie des événements, une ingestion qui les vérifie et les enrichit, des agrégats calculés en tâche de fond, et des écrans qui posent des questions. Cette page suit ce trajet dans l'ordre.

Le trajet d'un événement

  1. Librairieenvoie les événements du site par lots
  2. POST /api/collectvalide le lot, vérifie l’origine et le quota, répond 202 : lot accepté
  3. Événements brutsécrits à l’ingestion, rattachés à leur session et à leur personneTemps réellit directement les visites brutes : visiteurs actifs, pages consultées maintenant
  4. Agrégatscalculés par une tâche planifiée
  5. Écrans du dashboardlisent les agrégats pour chaque période

Chaque flèche compte. Un 202 à l'ingestion veut dire « lot accepté », pas « visible dans le dashboard » : les agrégats sont calculés par une tâche planifiée, avec quelques minutes de retard. C'est la source de confusion la plus fréquente, et elle a une conséquence pratique — un chiffre récent qui paraît bas est souvent un chiffre incomplet.

Les écrans se mettent à jour tout seuls

Un flux SSE par site pousse toutes les cinq secondes deux choses : les chiffres réellement instantanés — visiteurs actifs, pages consultées maintenant — et un repère de fraîcheur qui dit si les données ont bougé.

Quand ce repère avance, la page se redemande d'elle-même. Ce qui est diffusé, ce n'est donc pas le contenu de chaque écran mais le fait qu'il a changé — sans quoi il aurait fallu réimplémenter chaque lecture une seconde fois, côté flux, et les deux auraient divergé au premier correctif de définition.

  • Une seule connexion par flux, partagée par tous les composants de la page.
  • Un repère de fraîcheur dans la barre latérale dit quand les chiffres ont bougé — sans lui, un écran figé et un écran à jour se ressemblent exactement.
  • La liste des sites porte un compteur vivant par site, alimenté par une requête groupée et une connexion pour toute la page.
  • Vingt secondes minimum entre deux rafraîchissements : un onglet ouvert ne doit pas devenir un générateur de charge.
  • Rien ne se rafraîchit quand l'onglet est en arrière-plan ; le retard est rattrapé au retour.
  • Un filtre en cours de saisie ou un menu ouvert survivent au rafraîchissement : seuls les composants serveur sont rejoués.

1. Déclarer un site

Un site est l'unité de mesure : un domaine, un fuseau horaire, une clé publique. Il appartient à une organisation, qui porte les membres et leurs rôles. Rien ne traverse jamais la frontière d'une organisation.

Liste des sites accessibles, avec leur domaine et leur trafic récent.
La liste des sites. C'est le point de départ de toute navigation : chaque écran du dashboard vit sous un site.

2. Installer la librairie

L'écran d'installation donne la clé publique du site — appelée siteId — et l'extrait à coller. Il affiche aussi les rejets des dernières 24 h, ce qui répond à la question qu'on se pose vraiment quand rien n'arrive : est-ce que les événements sont refusés, et pourquoi.

Écran d'installation : extrait à copier, clé publique du site et rejets récents.
La clé est publique par construction : elle transite en clair dans le JavaScript. Ce qui protège les chiffres, c'est la liste des domaines autorisés et le quota, pas le secret de la clé.

3. Lire la vue d'ensemble

La vue d'ensemble répond à « combien, et par rapport à quand ». Chaque chiffre est comparé à la période précédente de même longueur — sans comparaison, un nombre ne dit rien.

Vue d'ensemble : visiteurs, visites, pages vues, rebond, durée, courbe comparée, pages, sources, pays et appareils.
Le panneau « Consulté maintenant » se met à jour tout seul, sans rechargement : il lit les visites brutes. Les tableaux au-dessous suivent le rythme du cron. Les visiteurs uniques, eux, ne s'additionnent pas d'un jour à l'autre — une personne revenue trois jours compte une fois sur la période et trois fois dans les buckets.

4. Poser une question précise

Trends est le constructeur de questions : un événement, une mesure, un découpage. La question vit dans l'URL, donc elle se partage et se rejoue — et elle peut être enregistrée comme insight, ce qui sauvegarde la définition, pas le résultat.

Trends : événement cta_clicked, mesure en occurrences, découpage par source, comparaison à la période précédente.
Un événement, une mesure, un découpage. Les mesures non additives — personnes uniques, sessions — affichent un avertissement : le total est recalculé sur la période, il n'est pas la somme des points.

5. Suivre les personnes

Une visite, une session et une personne sont trois choses distinctes. Une visite se clôt après trente minutes d'inactivité ; une personne peut couvrir plusieurs appareils dès qu'elle a été identifiée par identify().

De la première visite à la personne
Avant connexionanon_7f2…stable entre les visites
À la connexionidentify()user_42 · plan pro
Dans Sarutobiperson_idun historique continu
Sessionsess_b81…
Événementproject_created
Version[email protected]
reset() coupe proprement la chaîne à la déconnexion. Le navigateur suivant repart avec une nouvelle identité anonyme et une nouvelle session.
Liste des personnes avec leur nombre de sessions et d'événements, et leur dernière activité.
Quatre identifiants cohabitent et ne se confondent pas : anonymous_id (le navigateur), distinct_id (l'identité métier), person_id (la personne après fusion) et session_id.

6. Voir ce qui casse

Les erreurs JavaScript non gérées remontent groupées par signature, avec leur volume et leur dernière occurrence. Les messages sont expurgés avant stockage : un jeton ou une adresse qui traînerait dans une stack n'y arrive pas.

Groupes d'erreurs avec leur volume, leur première et leur dernière occurrence.
Groupées par signature plutôt que listées une par une : mille fois la même erreur est un problème, pas mille problèmes.

7. Brancher un agent

Un jeton d'agent permet à un programme — Claude Code, un job de CI — de lire ces mêmes chiffres par le serveur MCP, sans ouvrir le dashboard. Le jeton porte une identité et une seule organisation, et son rôle est relu à chaque appel.

Création d'un jeton d'agent : nom, organisation et scopes cochés, lecture seule par défaut.
Deux barrières indépendantes : le scope dit ce que le jeton a le droit de demander, le rôle dit ce que la personne a le droit de faire. Un appel doit passer les deux.

Le détail de la connexion vit sur la page du serveur MCP.

Ce qu'il faut retenir

  • Un 202 signifie « accepté », pas « visible ».
  • Le temps réel lit les visites brutes ; les vues agrégées lisent les rollups.
  • Les mesures non additives ne s'additionnent pas d'un bucket à l'autre.
  • Visite, session et personne sont trois notions différentes.
  • Les données mesurées sont écrites par des tiers : ce sont des données, pas des ordres.