enterprise_ai.telemetry
Source : sdks/python/src/enterprise_ai/telemetry/__init__.py. Retour à l'index de la référence du SDK Python.
Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.
Modèle SpanRecord
Un span terminé, au format de l'exportateur de repli.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
name | str | oui | Nom du span. |
trace_id | str | oui | Identifiant de trace W3C, 32 caractères hexadécimaux en minuscules, pour relier l'événement à une trace. |
span_id | str | oui | Identifiant du span, 16 caractères hexadécimaux aléatoires. |
parent_span_id | str | None | oui | Identifiant du span parent (16 caractères hexadécimaux), ou None pour un span racine. |
start_time_unix_nano | int | oui | Heure de début en nanosecondes depuis l'epoch Unix. |
end_time_unix_nano | int | non | Heure de fin en nanosecondes depuis l'epoch Unix ; 0 tant que le span est ouvert. |
attributes | dict[str, Any] | non | Attributs libres du composant, comme le fournisseur d'un modèle. |
status | str | non | Statut du span : ok (par défaut) ou error. |
events | list[dict[str, Any]] | non | Événements horodatés du span : name, time_unix_nano, attributes. |
SpanRecord.add_event
add_event(name: str, attributes: dict[str, Any] | None = None) -> None
Ajoute un événement horodaté au span.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
name | str | oui | Nom de l'événement. | |
attributes | dict[str, Any] | None | None | non | Attributs de l'événement ; vides par défaut. |
Retour : None.
SpanRecord.set_attribute
set_attribute(key: str, value: Any) -> None
Définit un attribut du span.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
key | str | oui | Nom de l'attribut, par exemple un nom de convention sémantique gen_ai.*. | |
value | Any | oui | Valeur de l'attribut ; remplace la précédente. |
Retour : None.
SpanRecord.to_dict
to_dict() -> dict[str, Any]
Span sous forme du dict envoyé à /v1/telemetry/spans.
Cet élément ne prend aucun paramètre.
Retour : dict[str, Any]. Dict de tous les champs du span.
Classe TelemetryClient
Télémétrie. Traces, journal des requêtes, flux en direct et objectifs de niveau de service (SLO) de la plateforme.
Resource
TelemetryClient.end_span
end_span(span: SpanRecord, status: str = 'ok') -> Any
Ingérer des spans de télémétrie. Accepte jusqu'à 5000 spans et répond 202 avec le nombre accepté, le nombre enregistré (un span déjà connu pour les mêmes identifiants de trace et de span est ignoré) et le résultat de chaque exportateur (ok ou error). Demande un principal de tenant avec tenant_admin, developer ou agent (403 forbidden).
Route : /v1/telemetry/spans (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
span | SpanRecord | oui | Span ouvert renvoyé par start_span ; un span déjà terminé lève ValueError. | |
status | str | 'ok' | non | Statut final du span : ok (par défaut) ou error. |
Retour : Any. Réponse JSON décodée de l'opération « Ingérer des spans de télémétrie ».
Erreurs levées : ValueError, les erreurs typées du transport (Erreurs).
TelemetryClient.ingest
ingest(spans: list[dict[str, Any]]) -> Any
Ingérer des spans de télémétrie. Accepte jusqu'à 5000 spans et répond 202 avec le nombre accepté, le nombre enregistré (un span déjà connu pour les mêmes identifiants de trace et de span est ignoré) et le résultat de chaque exportateur (ok ou error). Demande un principal de tenant avec tenant_admin, developer ou agent (403 forbidden).
Route : /v1/telemetry/spans (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
spans | list[dict[str, Any]] | oui | Spans à envoyer, sous forme de dicts au format de SpanRecord.to_dict(). |
Retour : Any. Réponse JSON décodée de l'opération « Ingérer des spans de télémétrie ».
Erreurs levées : les erreurs typées du transport (Erreurs).
TelemetryClient.logs
logs(**filters: Any) -> Any
Lister le journal des requêtes. Journal des requêtes du tenant tiré des résumés de spans, du plus récent au plus ancien : une ligne par span avec son heure, son niveau (error si le span a échoué, sinon info), son service, son nom, son message (type d'erreur, ou méthode, route et code de statut), sa durée, sa trace, son span, son exécution et ses attributs conservés. Jamais de prompt ni de sortie de modèle. Demande un principal de tenant avec platform_admin, tenant_admin, auditor, viewer ou support_engineer (403 forbidden). Un niveau inconnu ou un from postérieur à to répond 400 invalid_request.
Route : /v1/telemetry/logs (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
**filters | Any | non | Filtres de requête : level (error, info), service, trace_id, q, from, to, limit. |
Retour : Any. Réponse JSON décodée de l'opération « Lister le journal des requêtes ».
Erreurs levées : les erreurs typées du transport (Erreurs).
TelemetryClient.overview
overview(**filters: Any) -> Any
Lire la vue d'ensemble de la télémétrie. Tableau de bord du tenant sur les days derniers jours : nombre de requêtes (spans racines), erreurs, taux d'erreur, latences p50 et p95 en millisecondes, coût total, et par jour les requêtes, les erreurs et le coût (coût des spans plus le coût mesuré ou estimé des événements d'usage LLM). Indique aussi quels exportateurs (Opik, OpenTelemetry, ClickHouse) sont configurés. Le coût total est libellé en USD. Demande un principal de tenant (403 tenant_required).
Route : /v1/telemetry/overview (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
**filters | Any | non | Paramètres de requête envoyés tels quels à /v1/telemetry/overview. |
Retour : Any. Réponse JSON décodée de l'opération « Lire la vue d'ensemble de la télémétrie ».
Erreurs levées : les erreurs typées du transport (Erreurs).
TelemetryClient.record_event
record_event(span: SpanRecord, name: str, attributes: dict[str, Any] | None = None) -> SpanRecord
Ajoute un événement horodaté à un span ouvert (sans requête).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
span | SpanRecord | oui | Span ouvert ; un span déjà terminé lève ValueError. | |
name | str | oui | Nom de l'événement. | |
attributes | dict[str, Any] | None | None | non | Attributs de l'événement ; vides par défaut. |
Retour : SpanRecord. Un SpanRecord : un span terminé, au format de l'exportateur de repli.
Erreurs levées : ValueError.
TelemetryClient.set_slo_target
set_slo_target(service: str, availability: float, latency_seconds: float, latency_objective: float, reason: str = '') -> Any
Définir les objectifs d'un service. Objectifs d'un service de la plateforme, écrits en base de données où ils remplacent les valeurs par défaut EAI_SLO_* pour chaque réplique sous 30 secondes. Réservé à l'administrateur de la plateforme (403 forbidden). Un service inconnu répond 404 slo_service_unknown. La modification, avec les valeurs avant et après et la raison, est auditée (telemetry.slo.target.update) ; la réponse donne les objectifs enregistrés avec leur version.
Route : /v1/telemetry/slo/targets/{service} (PUT).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
service | str | oui | Service dont les objectifs sont définis : control_plane_api, model_gateway, tool_gateway ou realtime. | |
availability | float | oui | Cible de disponibilité : part des requêtes qui ne doivent pas échouer en 5xx, de 0,5 inclus à 1 exclu (par exemple 0,999). | |
latency_seconds | float | oui | Cible de latence en secondes : une requête plus lente compte contre l'objectif de latence. Supérieure à 0, au plus 300. | |
latency_objective | float | oui | Part des requêtes qui doivent être plus rapides que latency_seconds, de 0,5 inclus à 1 exclu. | |
reason | str | '' | non | Raison du changement d'objectifs, 500 caractères au plus, vide par défaut. Inscrite dans le journal d'audit. |
Retour : Any. Réponse JSON décodée de l'opération « Définir les objectifs d'un service ».
Erreurs levées : les erreurs typées du transport (Erreurs).
TelemetryClient.slo
slo(window_minutes: int | None = None, tenant_id: str | None = None) -> Any
Lire les budgets d'erreur des SLO. Pour chaque service, sur les window_minutes dernières minutes : requêtes, erreurs (5xx), requêtes au-delà de la cible de latence, cible de latence et son origine (database ou settings), et pour la disponibilité et la latence la cible, le taux de mauvaises requêtes, le budget restant et le rythme de consommation. Les comptes sont ceux de la réplique qui répond. Demande platform_admin, tenant_admin, auditor, viewer ou support_engineer (403 forbidden). Un administrateur de la plateforme lit toute la plateforme ou un tenant ; les autres ne lisent que leur propre tenant (403 slo_scope_forbidden pour un autre). Une fenêtre hors de 1 à EAI_SLO_RETENTION_MINUTES répond 422 slo_window_invalid. Chaque lecture est auditée (telemetry.slo.read).
Route : /v1/telemetry/slo (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
window_minutes | int | None | None | non | Longueur de la fenêtre en minutes, 60 par défaut, de 1 à la rétention EAI_SLO_RETENTION_MINUTES. |
tenant_id | str | None | None | non | Tenant à lire. Un administrateur de la plateforme peut l'omettre pour toute la plateforme ; tout autre appelant ne peut donner que son propre tenant. |
Retour : Any. Réponse JSON décodée de l'opération « Lire les budgets d'erreur des SLO ».
Erreurs levées : les erreurs typées du transport (Erreurs).
TelemetryClient.start_span
start_span(name: str, attributes: dict[str, Any] | None = None, traceparent: str | None = None) -> SpanRecord
Ouvre un span explicite (sans requête) : enfant de traceparent ou du contexte courant.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
name | str | oui | Nom du span. | |
attributes | dict[str, Any] | None | None | non | Attributs initiaux du span. |
traceparent | str | None | None | non | traceparent W3C du parent (00-<trace_id>-<span_id>-<flags>) ; le contexte courant s'il est omis, une nouvelle trace s'il n'y en a pas. |
Retour : SpanRecord. Un SpanRecord : un span terminé, au format de l'exportateur de repli.
Erreurs levées : ValueError.
TelemetryClient.stream
stream(last_event_id: str | None = None, **params: Any) -> Any
Suivre la télémétrie en direct. Server-Sent Events (text/event-stream) du tenant : un événement metrics à chaque intervalle (requêtes, erreurs, taux d'erreur et latence p95 de la dernière minute), un événement trace pour chaque nouveau span racine et un événement incident pour chaque incident créé ou modifié. Chaque événement porte un id: (un horodatage) que le client renvoie dans Last-Event-ID ou since pour reprendre. Le flux se ferme après timeout secondes (l'EventSource se reconnecte après 3 secondes) ou après max_events événements. Demande un principal de tenant avec platform_admin, tenant_admin, auditor, viewer ou support_engineer.
Route : /v1/telemetry/stream (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
last_event_id | str | None | None | non | Identifiant du dernier événement déjà reçu, envoyé comme Last-Event-ID pour reprendre le flux. |
**params | Any | non | Champs supplémentaires fusionnés dans la requête. |
Retour : Any. Réponse JSON décodée de l'opération « Suivre la télémétrie en direct ».
Erreurs levées : les erreurs typées du transport (Erreurs).
TelemetryClient.trace
trace(trace_id: str) -> Any
Lire une trace. Tous les spans de la trace dans l'ordre de début (avec leur coût s'il est connu), le nombre de spans, la durée totale en millisecondes, le nombre d'erreurs, les événements d'audit qui portent cet identifiant de trace, et un lien vers la trace dans Opik quand Opik est configuré. Demande un principal de tenant (403 tenant_required). Un identifiant mal formé répond 400 invalid_request ; une trace sans span ni événement d'audit répond 404 not_found.
Route : /v1/telemetry/traces/{trace_id} (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
trace_id | str | oui | Identifiant de trace : 32 caractères hexadécimaux (W3C trace context), insensible à la casse. |
Retour : Any. Réponse JSON décodée de l'opération « Lire une trace ».
Erreurs levées : les erreurs typées du transport (Erreurs).
TelemetryClient.tracer
tracer(service: str = 'enterprise-ai-agent', batch_size: int = 50, use_otel: bool | None = None) -> Tracer
Un :class:Tracer qui exporte via OpenTelemetry ou via ce client.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
service | str | 'enterprise-ai-agent' | non | Nom du service inscrit dans service.name sur chaque span (enterprise-ai-agent par défaut). |
batch_size | int | 50 | non | Nombre de spans terminés mis en mémoire avant leur envoi (50 par défaut). |
use_otel | bool | None | None | non | Utilise OpenTelemetry : None s'il est installé, True toujours (erreur d'import sinon), False jamais. |
Retour : Tracer. Un Tracer : Télémétrie. Traces, journal des requêtes, flux en direct et objectifs de niveau de service (SLO) de la plateforme.
TelemetryClient.traces
traces(**filters: Any) -> Any
Lister les traces récentes. Traces récentes du tenant, de la plus récente à la plus ancienne : une ligne par span racine avec son nom, son service, son début, sa durée, son statut, son exécution, sa session et ses nombres de spans et d'erreurs. Demande un principal de tenant avec platform_admin, tenant_admin, auditor, viewer ou support_engineer (403 forbidden). Un statut inconnu ou un from postérieur à to répond 400 invalid_request.
Route : /v1/telemetry/traces (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
**filters | Any | non | Filtres de requête : status (ok, error, unset), service, run_id, from, to, limit. |
Retour : Any. Réponse JSON décodée de l'opération « Lister les traces récentes ».
Erreurs levées : les erreurs typées du transport (Erreurs).
Classe Tracer
Télémétrie. Traces, journal des requêtes, flux en direct et objectifs de niveau de service (SLO) de la plateforme.
Attributs :
| Nom | Type | Requis | Description |
|---|---|---|---|
batch_size | oui | Nombre de spans terminés mis en mémoire avant leur envoi. | |
service | oui | Nom du service inscrit dans service.name sur chaque span. | |
telemetry | oui | Client de télémétrie qui reçoit les spans de repli, ou None. |
Constructeur Tracer
Tracer(telemetry: TelemetryClient | None, service: str, batch_size: int = 50, use_otel: bool | None = None) -> None
Crée un traceur ; il utilise OpenTelemetry s'il est disponible, sinon il met les spans en mémoire et les envoie via telemetry.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
telemetry | TelemetryClient | None | oui | Client de télémétrie qui reçoit les spans de repli, ou None pour seulement les garder en mémoire. | |
service | str | oui | Nom du service inscrit dans service.name sur chaque span. | |
batch_size | int | 50 | non | Nombre de spans terminés mis en mémoire avant leur envoi (50 par défaut). |
use_otel | bool | None | None | non | Utilise OpenTelemetry : None s'il est installé, True toujours (erreur d'import sinon), False jamais. |
Tracer.flush
flush() -> list[dict[str, Any]]
Ingérer des spans de télémétrie. Accepte jusqu'à 5000 spans et répond 202 avec le nombre accepté, le nombre enregistré (un span déjà connu pour les mêmes identifiants de trace et de span est ignoré) et le résultat de chaque exportateur (ok ou error). Demande un principal de tenant avec tenant_admin, developer ou agent (403 forbidden).
Route : /v1/telemetry/spans (POST).
Cet élément ne prend aucun paramètre.
Retour : list[dict[str, Any]]. Réponse JSON décodée de l'opération « Ingérer des spans de télémétrie ».
Erreurs levées : les erreurs typées du transport (Erreurs).
Tracer.span
span(name: str, attributes: dict[str, Any] | None = None) -> Iterator[Any]
Ouvre un span ; les requêtes du SDK faites à l'intérieur portent son traceparent.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
name | str | oui | Nom du span. | |
attributes | dict[str, Any] | None | None | non | Attributs du span, ajoutés à service.name. |
Retour : Iterator[Any]. Gestionnaire de contexte qui fournit le span OpenTelemetry ou un SpanRecord ; une exception marque l'enregistrement en error avec error.type.
Fonctions
usage_attributes
usage_attributes(response: dict[str, Any]) -> dict[str, Any]
Attributs GenAI tirés d'une complétion au format OpenAI.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
response | dict[str, Any] | oui | Dict de complétion de chat avec model, id, usage et choices. |
Retour : dict[str, Any]. Dict de gen_ai.response.model, gen_ai.response.id, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens et gen_ai.response.finish_reasons, sans les valeurs absentes.