Observability¶

Kla Digital provides deep observability into your agent executions through the Observability API. This allows you to debug issues, analyze performance, and audit agent behavior programmatically.

Traces API¶

The Traces API provides access to the OpenTelemetry spans generated during agent execution.

List Traces¶

GET /v1/traces

Returns a list of traces matching the specified filters.

Parameters:

• traceIds (optional): Filter by specific trace IDs.
• startTime (optional): ISO 8601 start timestamp.
• endTime (optional): ISO 8601 end timestamp.
• services (optional): Filter by service name.
• operations (optional): Filter by operation name.
• statusCode (optional): Filter by status code (0=Unset, 1=Ok, 2=Error).
• minDuration (optional): Minimum duration in milliseconds.
• limit (optional): Number of items to return (default: 100).
• offset (optional): Pagination offset.

Response:

{
  "traces": [
    {
      "trace_id": "1234567890abcdef1234567890abcdef",
      "span_id": "abcdef1234567890",
      "service_name": "agent-executor",
      "operation_name": "execute_tool",
      "start_time": "2023-10-27T10:00:00Z",
      "duration_ms": 150,
      "status_code": 1
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 1,
    "totalPages": 1
  }
}

Get Trace Details¶

GET /v1/traces/:traceId

Returns all spans associated with a specific trace ID, useful for reconstructing the full execution path.

Response:

{
  "traceId": "1234567890abcdef1234567890abcdef",
  "spans": [
    {
      "span_id": "root-span-id",
      "operation_name": "workflow_start",
      ...
    },
    {
      "span_id": "child-span-id",
      "parent_span_id": "root-span-id",
      "operation_name": "tool_call",
      ...
    }
  ],
  "duration": 500,
  "hasError": false
}