Intégration SDK
Concepts & objectifs
Avant le code : pourquoi instrumenter, et ce que vous obtenez en retour. Si vous comprenez ces trois schémas, tout le reste du guide coule de source.
Pourquoi instrumenter
Votre application IA exécute des LLM, des recherches vectorielles, des tools, des scripts. Le SDK émet, à chaque étape, des enregistrements structurés que la plateforme recompose en traces lisibles. Vous gagnez : observabilité bout-en-bout, débogage, évaluation par des juges, analytics de coût/latence, et auditabilité, sans proxy au milieu de vos appels.
Le modèle mental : flow → step → records
Flow — une exécution
Step 1
preprocessStep 2
analysisStep 3
finalizeRecords émis
runpayloadmetriclogscoreaudit
run = début/fin d'un step payload = I/O metric log
- Un flow = une exécution sémantique (une conversation, une requête, un job batch).
- Un step (span, mesure d'une opération) = une étape interne (un appel LLM, une recherche, un tool).
- Des records = ce qui est émis :
run(début/fin de step),payload(I/O),metric,log,score(verdict de juge),audit.
| record | rôle |
|---|---|
| run | Début et fin d'un step (statut, durée, métriques) |
| payload | Données : entrée, sortie, contexte |
| metric | Mesure quantitative (tokens, latence, coût…) |
| log | Log technique ou métier rattaché au span |
| score | Verdict d'un juge (note, pass/fail, raison) |
| audit | Trace d'audit |
Le modèle d'identité
session_idconversation multi-tours — relie plusieurs flowsactor_id
trace_id
flow_id
span_id
span_id
span_id
trace_id contient un ou plusieurs flow_id, chacun contenant des span_id (steps).
| identifiant | portée | génération |
|---|---|---|
| flow_definition_id | Configuration logique du SIA | fourni par vous |
| flow_id | Une exécution | auto (UUID7) |
| trace_id | Une trace distribuée | auto (UUID4 hex) |
| span_id | Un step | auto (16 hex) |
| session_id | Conversation multi-tours | optionnel (vous) |
| actor_id | Utilisateur final | optionnel (vous) |
Ce que la plateforme vous rend
C'est l'objectif final : les records émis alimentent toutes les vues du cockpit.
SDK
votre appIntake API
POST /v1/intake/batchClickHouse
par tenantintake_eventsintake_metricsintake_scores
Ce que la plateforme rend
Explore
traces & sessionsFlow Diagram
DAG des stepsQuality
qualité d'intégrationJudges
verdictsOverview
KPIs · coûtsAlerting
alertes- Explore : liste et détail des traces & sessions (recherche, filtres, colonnes custom).
- Flow Diagram : le DAG (graphe d'exécution) de vos steps, reconstruit à partir des
parent_span_id. - Integration Quality : un score mesurant si vos données sont exploitables.
- Judges : les verdicts d'évaluation (sécurité, qualité, grounding…).
- Overview / Alerting : KPIs, coûts, alertes.