Files

T

Auto Tag Develop / tag (push) Successful in 9s

Details

feat : error tracking backend vers GlitchTip (via Tailscale) (#37 )

## Objectif
Remonter les erreurs **backend** Symfony vers **GlitchTip** (SDK Sentry), **prod uniquement**, **inerte sans `SENTRY_DSN`**. Transport réseau via **Tailscale** sur le host de prod (infra, hors repo). Frontend hors périmètre.

## Contenu
- `sentry/sentry-symfony:^5.10` (+ `symfony.lock` recipe)
- `config/bundles.php` → `SentryBundle ['prod' => true]`
- `config/packages/sentry.yaml` (nouveau) : DSN runtime, release `%app.version%`, 4xx ignorés, pas de tracing, handler Monolog ERROR+
- `config/packages/monolog.yaml` : handler `sentry` en `when@prod`
- `.env` : bloc `SENTRY_DSN` documenté (vide → inerte)
- `doc/error-tracking.md` (runbook Tailscale) + section `CLAUDE.md`
- Spec + plan sous `docs/superpowers/`

## Vérifications
- Prod `cache:clear` OK, service `Sentry\Monolog\Handler` chargé
- **267/267 tests verts**, dev/test inchangés (bundle non chargé hors prod)
- Aucun changement `frontend/` / `.gitea/` / `deploy/docker/`
- Revue multi-agents : **READY TO MERGE** (aucun Critical/Important)

## Activation prod (hors code, cf. `doc/error-tracking.md`)
1. Tailscale sur l'hôte GlitchTip **et** sur le VPS OVH (prod)
2. Créer le projet `sirh-api` dans GlitchTip → récupérer le DSN
3. `SENTRY_DSN=http://<clé>@<IP-tailnet>:<port>/<id>` dans l'env_file serveur + redéploiement

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: #37
Co-authored-by: matthieu <matthieu@yuno.malio.fr>
Co-committed-by: matthieu <matthieu@yuno.malio.fr>

2026-06-28 11:46:35 +00:00

11 KiB

Raw Blame History

GlitchTip Backend Error Tracking Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Remonter les erreurs backend Symfony de SIRH vers GlitchTip (SDK Sentry), en prod uniquement, inerte sans DSN, le transport réseau étant assuré par Tailscale (infra, hors repo).

Architecture: On installe sentry/sentry-symfony, enregistré prod-only dans bundles.php. Un fichier config/packages/sentry.yaml (bloc when@prod) configure le SDK (DSN runtime %env(SENTRY_DSN)%, release = %app.version%, 4xx ignorés, pas de tracing) et déclare un handler Monolog qui remonte les logs ERROR+ comme Issues. Sans SENTRY_DSN, le SDK est un no-op. Aucun changement frontend ni CI.

Tech Stack: PHP 8.4, Symfony 8, API Platform, sentry/sentry-symfony ^5.10, Monolog, Docker (prod), Tailscale (transport infra).

Global Constraints

Prod only : SentryBundle enregistré ['prod' => true], config sous when@prod. Dev/test : zéro impact.
Inerte sans DSN : env(SENTRY_DSN) défaut '' → SDK no-op si vide.
DSN runtime : lu depuis l'env_file serveur, jamais baké dans l'image, jamais committé.
Version dépendance : sentry/sentry-symfony:^5.10 (identique au projet Lesstime, même stack).
Release : %app.version% (déjà fourni par config/version.yaml, ex. 0.1.127).
Pas de tracing/APM : traces_sample_rate: 0.0.
Format commit (hook SIRH) : Conventional Commits FR, ex. feat : …, docs : …. Terminer par la ligne Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>.
Pas de modif frontend (frontend/**), pas de modif CI (.gitea/workflows/**), pas de modif Dockerfile (DSN runtime ; CA HTTPS hors périmètre).
Branche : feat/glitchtip-backend-error-tracking (déjà créée).

Task 1: Câblage backend Sentry/GlitchTip (inerte sans DSN)

Files:

Modify: composer.json, composer.lock (via composer require)
Modify: config/bundles.php
Create: config/packages/sentry.yaml
Modify: config/packages/monolog.yaml
Modify: .env

Interfaces:

Consumes: paramètre %app.version% (config/version.yaml), variable d'env SENTRY_DSN, %env(APP_ENV)%.
Produces: service Sentry\Monolog\Handler (handler Monolog niveau Error), variable d'env attendue SENTRY_DSN (runtime). Aucune API PHP consommée par d'autres tâches.
Step 1: Installer la dépendance

Depuis le container PHP (make shell ou docker compose exec php sh) :

composer require sentry/sentry-symfony:^5.10

Expected : composer.json + composer.lock modifiés, paquet sentry/sentry-symfony 5.x installé.

Step 2: Forcer l'enregistrement prod-only du bundle

Le recipe Flex peut écrire ['all' => true] dans config/bundles.php. Corriger en prod-only. Contenu attendu de la ligne ajoutée :

use Sentry\SentryBundle\SentryBundle;
// ... dans le tableau de retour :
    SentryBundle::class                 => ['prod' => true],

Si Flex a aussi généré un config/packages/sentry.yaml, il sera remplacé à l'étape suivante.

Step 3: Écrire config/packages/sentry.yaml

Remplacer intégralement le contenu du fichier par :

# Error tracking → GlitchTip (compatible SDK Sentry).
# Actif uniquement en prod (bundle enregistré prod-only dans bundles.php).
# Si SENTRY_DSN est vide/non défini, le SDK est inerte (rien n'est envoyé).
when@prod:
    parameters:
        env(SENTRY_DSN): ''

    sentry:
        dsn: '%env(SENTRY_DSN)%'
        # Capture des erreurs fatales PHP via le handler. On DÉSACTIVE le listener
        # kernel pour éviter les doublons avec le handler Monolog (les exceptions du
        # kernel sont déjà logguées par Symfony → remontées via Monolog).
        register_error_listener: false
        register_error_handler: true
        options:
            environment: '%env(APP_ENV)%'
            release: '%app.version%'
            traces_sample_rate: 0.0
            ignore_exceptions:
                - Symfony\Component\HttpKernel\Exception\NotFoundHttpException
                - Symfony\Component\HttpKernel\Exception\MethodNotAllowedHttpException
                - Symfony\Component\Security\Core\Exception\AccessDeniedException

    # Handler Monolog → Sentry : remonte les logs niveau ERROR+ comme Issues GlitchTip.
    services:
        Sentry\Monolog\Handler:
            arguments:
                $hub: '@Sentry\State\HubInterface'
                $level: !php/const Monolog\Level::Error
                $bubble: true

Step 4: Brancher le handler Monolog en prod

Dans config/packages/monolog.yaml, sous when@prod: → monolog: → handlers:, ajouter le handler sentry (à côté des handlers cron, main, deprecation existants, sans les modifier) :

            # Remonte les logs ERROR+ vers GlitchTip en tant qu'Issues (service défini
            # dans sentry.yaml). Envoi immédiat, indépendamment des handlers fichier.
            sentry:
                type: service
                id: Sentry\Monolog\Handler
                channels: ["!event", "!doctrine", "!deprecation", "!cron"]

Step 5: Documenter la variable dans .env

Ajouter à la fin de .env le bloc commenté (valeur réelle injectée côté serveur uniquement) :

###> sentry/sentry-symfony ###
# Error tracking backend → GlitchTip (projet "sirh-api"). Prod only, vide => inerte.
# À définir dans l'env_file du serveur, PAS ici. Format :
#   SENTRY_DSN=http://<clé>@<host-ou-IP-tailnet>:<port>/<id-projet>
# SENTRY_DSN=
###< sentry/sentry-symfony ###

Si Flex a déjà inséré un bloc ###> sentry/sentry-symfony ###, le remplacer par celui-ci (ne pas dupliquer).

Step 6: Vérifier que la conf prod compile (DSN vide → inerte)

Depuis le container :

APP_ENV=prod php bin/console cache:clear --no-warmup
APP_ENV=prod php bin/console debug:container --env=prod 2>/dev/null | grep -i sentry | head

Expected :

cache:clear : [OK] Cleared the cache. (aucune erreur de config/DI).
debug:container : au moins une ligne Sentry\... (services chargés). DSN vide → SDK inerte, aucun envoi.
Step 7: Vérifier que le dev n'est pas impacté

php bin/console cache:clear           # APP_ENV=dev par défaut
make test

Expected : cache dev OK ; suite de tests verte (le bundle n'est pas chargé hors prod).

Step 8: Commit

git add composer.json composer.lock config/bundles.php config/packages/sentry.yaml config/packages/monolog.yaml .env
git commit -m "$(cat <<'EOF'
feat : error tracking backend vers GlitchTip (prod-only, inerte sans DSN)

Ajout du SDK sentry/sentry-symfony enregistré prod-only, config sentry.yaml
(DSN runtime, release app.version, 4xx ignorés, pas de tracing) et handler
Monolog ERROR+. Sans SENTRY_DSN le SDK est no-op. Transport réseau via
Tailscale (infra, hors repo).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
EOF
)"

Task 2: Documentation (doc/ + CLAUDE.md)