Les annotations

Une courbe qui monte ou qui plonge se lit mieux avec ce qui s’est passé ce jour-là : l’envoi de la lettre d’information, la mise en production du nouveau tunnel de commande, une panne du paiement. Les annotations sont ces repères.

Une annotation

Champ	Contenu
Site	un site, ou tous les sites
Début et fin	une date, ou une période
Titre	« Lettre d’automne »
Description	facultative
Catégorie	campaign (campagne), release (mise en production), incident, other (autre)

Elles se saisissent dans l’onglet Annotations du site, qui montre aussi celles communes à tous les sites ; les annotations communes se gèrent dans Administration › Réglages.

Par l’API

Une chaîne de déploiement peut annoter ses mises en production, avec un jeton d’intégration eoa_… :

curl -X POST https://stats.exemple.fr/api/v1/sites/$SITE_ID/annotations \
  -H "Authorization: Bearer $EODIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "starts_at": "2026-10-04T09:30:00+02:00",
    "title": "Version 4.2 : nouveau tunnel de commande",
    "category": "release"
  }'

POST /api/v1/annotations crée une annotation commune à tous les sites (site_id vide).

La vue annotations

Une ligne par annotation et par site : les annotations communes sont recopiées sur chaque site, pour que la règle de ligne d’insights les laisse passer avec le reste.

Colonne	Contenu
site_id, annotation_id	le site, l’annotation
starts_at, ends_at	le début, la fin d’une période
day, end_day	les jours correspondants, dans le fuseau du site
title, description, category	le repère
all_sites	vrai pour une annotation commune

Dans insights, une annotation se superpose à une courbe par une jointure sur le jour :

SELECT s.day, count(DISTINCT s.session_id) AS visites, max(a.title) AS repère
FROM analytics.sessions s
LEFT JOIN analytics.annotations a
  ON a.site_id = s.site_id AND s.day BETWEEN a.day AND a.end_day
GROUP BY s.day
ORDER BY s.day