io.enterpriseai.resources.TelemetryClient
Source : sdks/java/enterprise-ai-java/src/main/java/io/enterpriseai/resources/TelemetryClient.java. Retour à l'index de la référence du SDK Java.
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.
Classe TelemetryClient
Télémétrie. Traces, journal des requêtes, flux en direct et objectifs de niveau de service (SLO) de la plateforme.
Constructeur TelemetryClient
TelemetryClient(Transport transport)
Crée le client sur le transport partagé ; EnterpriseAIClient le construit, on y accède par l'accesseur du même nom.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
transport | Transport | oui | Transport partagé par les sous-clients d'un même client. |
TelemetryClient.ingestSpans
JsonNode ingestSpans(Object body)
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 |
|---|---|---|---|---|
body | Object | oui | Requête d'export OTLP JSON (resourceSpans) ou {spans: [...]} où chaque span porte trace_id, span_id, parent_span_id facultatif, name, service, start_time, end_time (ISO 8601 ou startTimeUnixNano / endTimeUnixNano), status, attributes, et facultativement cost {amount, currency}, run_id et session_id. |
Retour : JsonNode. 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.ingestSpans
JsonNode ingestSpans(Object body, RequestOptions options)
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 |
|---|---|---|---|---|
body | Object | oui | Requête d'export OTLP JSON (resourceSpans) ou {spans: [...]} où chaque span porte trace_id, span_id, parent_span_id facultatif, name, service, start_time, end_time (ISO 8601 ou startTimeUnixNano / endTimeUnixNano), status, attributes, et facultativement cost {amount, currency}, run_id et session_id. | |
options | RequestOptions | oui | Options de l'appel (clé d'idempotence, traceparent, en-têtes, signal d'annulation). |
Retour : JsonNode. 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
JsonNode logs(Map<String, ?> query)
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 |
|---|---|---|---|---|
query | Map<String, ?> | oui | Paramètres de la chaîne de requête de la route. |
Retour : JsonNode. 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
JsonNode overview()
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).
Cet élément ne prend aucun paramètre.
Retour : JsonNode. 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.overview
JsonNode overview(Map<String, ?> query)
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 |
|---|---|---|---|---|
query | Map<String, ?> | oui | Paramètres de la chaîne de requête de la route. |
Retour : JsonNode. 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.setSloTarget
JsonNode setSloTarget(String service, Object body)
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 | String | oui | Service dont les objectifs sont définis : control_plane_api, model_gateway, tool_gateway ou realtime. | |
body | Object | oui | Nouveaux objectifs de disponibilité et de latence du service. |
Retour : JsonNode. 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
JsonNode slo()
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).
Cet élément ne prend aucun paramètre.
Retour : JsonNode. 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.slo
JsonNode slo(Map<String, ?> query)
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 |
|---|---|---|---|---|
query | Map<String, ?> | oui | Paramètres de la chaîne de requête de la route. |
Retour : JsonNode. 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.stream
io.enterpriseai.SseStream stream(String lastEventId)
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 |
|---|---|---|---|---|
lastEventId | String | oui | Dernier identifiant d'événement reçu, envoyé dans Last-Event-ID pour reprendre le flux ; null pour partir du début. |
Retour : io.enterpriseai.SseStream. 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
JsonNode trace(String traceId)
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 |
|---|---|---|---|---|
traceId | String | oui | Identifiant de trace : 32 caractères hexadécimaux (W3C trace context), insensible à la casse. |
Retour : JsonNode. Réponse JSON décodée de l'opération « Lire une trace ».
Erreurs levées : les erreurs typées du transport (Erreurs).
TelemetryClient.traces
JsonNode traces(Map<String, ?> query)
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 |
|---|---|---|---|---|
query | Map<String, ?> | oui | Paramètres de la chaîne de requête de la route. |
Retour : JsonNode. 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).