Troubleshooting

Les cas typiques rencontrés en intégration.

Mon Flow Diagram ressemble à une cascade illisible

Cause probable : plusieurs top-level spans sans parent commun → fallback chronologique. Diagnostic : onglet Quality, check hierarchy_resolvable en CRITICAL. Fix : pattern context manager : un seul flow encapsulant tous vos top-level steps.

Mes spans n'apparaissent pas dans le cockpit

Vérifiez, dans l'ordre :

Clé API invalide ou révoquée → onglet Settings → API Keys du SIA.
base_url mal configuré → la variable est NIAONE_BASE_URL (et le paramètre base_url), pas endpoint. Elle doit pointer vers votre instance (pas localhost en prod).
Réseau → votre worker doit pouvoir joindre l'endpoint (firewall, proxy).
record_type manquant → en OTel manuel uniquement, assurez record_type: "run".

Diagnostic

Le SDK Python expose un logger niaone_sdk qui logue les erreurs d'envoi en WARNING. Activez safe_mode + un hook on_error pour les router vers votre observabilité.

Le badge Quality reste à 100 alors que mon SIA est cassé

< 20 spans sur la lookback → scoring désactivé. Émettez davantage puis revérifiez.
Cache (max 5 min) → cliquez « Re-analyser » en haut de l'onglet Quality.
api-server pas redéployé après une modif de config → redémarrez le service.

Mes step cards sont éclatées en plusieurs groupes

Cause : dérive (drift) de flow.name : plusieurs services émettent des noms légèrement différents pour le même flow_definition_id. Fix : centraliser le slug.

Mes annotations n'apparaissent pas comme colonne

L'annotation est émise, mais Explore ne l'affiche pas tant que vous n'avez pas ajouté la colonne custom pointant son chemin (annotations.<clé>). Voir Labels & annotations.

Mes juges ne déclenchent jamais

Le juge n'est pas activé (Settings → Judges).
Le sampling est trop agressif.
L'attach_level ne correspond pas (juge flow-level mais vous n'émettez que des steps).

J'ai corrigé l'instrumentation mais l'ancien rendu persiste

Le cockpit calcule sur une lookback de 7 jours : anciens spans cassés et nouveaux corrects cohabitent durant cette période. Patientez, ou demandez à l'équipe plateforme une purge ClickHouse.