io.enterpriseai.resources.TelemetryClient
Source: sdks/java/enterprise-ai-java/src/main/java/io/enterpriseai/resources/TelemetryClient.java. Back to the Java SDK reference index.
This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.
Class TelemetryClient
Telemetry spans, overview and traces.
Constructor TelemetryClient
TelemetryClient(Transport transport)
Creates the client on the shared transport; EnterpriseAIClient builds it and exposes it through the accessor of the same name.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
transport | Transport | yes | Transport shared by the sub-clients of one client. |
TelemetryClient.ingestSpans
JsonNode ingestSpans(Object body)
Ingest telemetry spans. Accepts up to 5000 spans and answers 202 with the number accepted, the number stored (a span already known for the same trace and span id is skipped) and the result of each exporter (ok or error). Requires a tenant principal with tenant_admin, developer or agent (403 forbidden).
Route: /v1/telemetry/spans (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
body | Object | yes | OTLP JSON export request (resourceSpans) or {spans: [...]} where each span has trace_id, span_id, optional parent_span_id, name, service, start_time, end_time (ISO 8601 or startTimeUnixNano / endTimeUnixNano), status, attributes, optional cost {amount, currency}, run_id and session_id. |
Returns: JsonNode. Decoded JSON answer of the operation "Ingest telemetry spans".
Raises: the typed errors of the transport (Errors).
TelemetryClient.ingestSpans
JsonNode ingestSpans(Object body, RequestOptions options)
Ingest telemetry spans. Accepts up to 5000 spans and answers 202 with the number accepted, the number stored (a span already known for the same trace and span id is skipped) and the result of each exporter (ok or error). Requires a tenant principal with tenant_admin, developer or agent (403 forbidden).
Route: /v1/telemetry/spans (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
body | Object | yes | OTLP JSON export request (resourceSpans) or {spans: [...]} where each span has trace_id, span_id, optional parent_span_id, name, service, start_time, end_time (ISO 8601 or startTimeUnixNano / endTimeUnixNano), status, attributes, optional cost {amount, currency}, run_id and session_id. | |
options | RequestOptions | yes | Per call options (idempotency key, traceparent, headers, abort signal). |
Returns: JsonNode. Decoded JSON answer of the operation "Ingest telemetry spans".
Raises: the typed errors of the transport (Errors).
TelemetryClient.logs
JsonNode logs(Map<String, ?> query)
List the request journal. Request journal of the tenant from the span summaries, newest first: one line per span with its time, level (error when the span failed, else info), service, name, message (error type, or method, route and status code), duration, trace, span, run and kept attributes. Never a prompt or a model output. Requires a tenant principal with platform_admin, tenant_admin, auditor, viewer or support_engineer (403 forbidden). An unknown level or a from after to answers 400 invalid_request.
Route: /v1/telemetry/logs (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
query | Map<String, ?> | yes | Query string parameters of the route. |
Returns: JsonNode. Decoded JSON answer of the operation "List the request journal".
Raises: the typed errors of the transport (Errors).
TelemetryClient.overview
JsonNode overview()
Read the telemetry overview. Dashboard of the tenant over the last days days: number of requests (root spans), errors, error rate, p50 and p95 latency in milliseconds, total cost, and per day requests, errors and cost (span costs plus the measured or estimated cost of the LLM usage events). Also says which exporters (Opik, OpenTelemetry, ClickHouse) are configured. The total cost is labelled USD. Requires a tenant principal (403 tenant_required).
Route: /v1/telemetry/overview (GET).
This element takes no parameter.
Returns: JsonNode. Decoded JSON answer of the operation "Read the telemetry overview".
Raises: the typed errors of the transport (Errors).
TelemetryClient.overview
JsonNode overview(Map<String, ?> query)
Read the telemetry overview. Dashboard of the tenant over the last days days: number of requests (root spans), errors, error rate, p50 and p95 latency in milliseconds, total cost, and per day requests, errors and cost (span costs plus the measured or estimated cost of the LLM usage events). Also says which exporters (Opik, OpenTelemetry, ClickHouse) are configured. The total cost is labelled USD. Requires a tenant principal (403 tenant_required).
Route: /v1/telemetry/overview (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
query | Map<String, ?> | yes | Query string parameters of the route. |
Returns: JsonNode. Decoded JSON answer of the operation "Read the telemetry overview".
Raises: the typed errors of the transport (Errors).
TelemetryClient.setSloTarget
JsonNode setSloTarget(String service, Object body)
Set the objectives of a service. Objectives of one platform service, written in the database where they override the EAI_SLO_* defaults for every replica within 30 seconds. Platform administrator only (403 forbidden). An unknown service answers 404 slo_service_unknown. The change, with the values before and after and the reason, is audited (telemetry.slo.target.update); the answer gives the stored objectives with their version.
Route: /v1/telemetry/slo/targets/{service} (PUT).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
service | String | yes | Service whose objectives are set: control_plane_api, model_gateway, tool_gateway or realtime. | |
body | Object | yes | New availability and latency objectives of the service. |
Returns: JsonNode. Decoded JSON answer of the operation "Set the objectives of a service".
Raises: the typed errors of the transport (Errors).
TelemetryClient.slo
JsonNode slo()
Read the SLO error budgets. For each service, over the last window_minutes minutes: requests, errors (5xx), requests over the latency target, the latency target and where it comes from (database or settings), and for availability and latency the target, bad ratio, remaining budget and burn rate. Counts are those of the replica that answers. Requires platform_admin, tenant_admin, auditor, viewer or support_engineer (403 forbidden). A platform administrator reads the whole platform or one tenant; anyone else reads only its own tenant (403 slo_scope_forbidden for another one). A window outside 1 to EAI_SLO_RETENTION_MINUTES answers 422 slo_window_invalid. Each read is audited (telemetry.slo.read).
Route: /v1/telemetry/slo (GET).
This element takes no parameter.
Returns: JsonNode. Decoded JSON answer of the operation "Read the SLO error budgets".
Raises: the typed errors of the transport (Errors).
TelemetryClient.slo
JsonNode slo(Map<String, ?> query)
Read the SLO error budgets. For each service, over the last window_minutes minutes: requests, errors (5xx), requests over the latency target, the latency target and where it comes from (database or settings), and for availability and latency the target, bad ratio, remaining budget and burn rate. Counts are those of the replica that answers. Requires platform_admin, tenant_admin, auditor, viewer or support_engineer (403 forbidden). A platform administrator reads the whole platform or one tenant; anyone else reads only its own tenant (403 slo_scope_forbidden for another one). A window outside 1 to EAI_SLO_RETENTION_MINUTES answers 422 slo_window_invalid. Each read is audited (telemetry.slo.read).
Route: /v1/telemetry/slo (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
query | Map<String, ?> | yes | Query string parameters of the route. |
Returns: JsonNode. Decoded JSON answer of the operation "Read the SLO error budgets".
Raises: the typed errors of the transport (Errors).
TelemetryClient.stream
io.enterpriseai.SseStream stream(String lastEventId)
Stream live telemetry events. Server-Sent Events (text/event-stream) of the tenant: a metrics event at every tick (requests, errors, error rate and p95 latency over the last minute), a trace event for every new root span and an incident event for every incident created or changed. Each event carries an id: (a timestamp) the client sends back as Last-Event-ID or since to resume. The stream closes after timeout seconds (the EventSource reconnects after 3 seconds) or after max_events events. Requires a tenant principal with platform_admin, tenant_admin, auditor, viewer or support_engineer.
Route: /v1/telemetry/stream (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
lastEventId | String | yes | Last event id received, sent as Last-Event-ID to resume the stream; null to start fresh. |
Returns: io.enterpriseai.SseStream. A SseStream: Blocking Server-Sent Events reader. Use it with try-with-resources, as an Iterator, a Stream or a reactive Flow.Publisher. A data: [DONE] event ends the stream.
Raises: the typed errors of the transport (Errors).
TelemetryClient.trace
JsonNode trace(String traceId)
Get one trace. Every span of the trace in start order (with cost when known), the span count, total duration in milliseconds, error count, the audit events that carry this trace id, and a link to the trace in Opik when Opik is configured. Requires a tenant principal (403 tenant_required). A malformed id answers 400 invalid_request; a trace without span nor audit event answers 404 not_found.
Route: /v1/telemetry/traces/{trace_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
traceId | String | yes | Trace identifier: 32 hexadecimal characters (W3C trace context), case insensitive. |
Returns: JsonNode. Decoded JSON answer of the operation "Get one trace".
Raises: the typed errors of the transport (Errors).
TelemetryClient.traces
JsonNode traces(Map<String, ?> query)
List the recent traces. Recent traces of the tenant, newest first: one row per root span with its name, service, start, duration, status, run, session and its span and error counts. Requires a tenant principal with platform_admin, tenant_admin, auditor, viewer or support_engineer (403 forbidden). An unknown status or a from after to answers 400 invalid_request.
Route: /v1/telemetry/traces (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
query | Map<String, ?> | yes | Query string parameters of the route. |
Returns: JsonNode. Decoded JSON answer of the operation "List the recent traces".
Raises: the typed errors of the transport (Errors).