Tracing

The TracingController provides distributed trace querying through the Jaeger backend. Traces show the full request path across microservices, helping identify latency bottlenecks, error sources, and service dependencies.

Search Traces

Endpoint: POST /api/v1/observability/traces/search

curl -X POST http://localhost:8088/api/v1/observability/traces/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Tenant-ID: 550e8400" \
  -d '{
    "service": "ai-service",
    "operation": "POST /api/v1/conversations",
    "minDuration": "500ms",
    "maxDuration": "5s",
    "start": "2026-02-12T09:00:00Z",
    "end": "2026-02-12T10:00:00Z",
    "limit": 50,
    "tags": {
      "http.status_code": "500"
    }
  }'

Get Trace by ID

Endpoint: GET /api/v1/observability/traces/:traceId

Returns the full trace with all spans for a specific trace ID.

TraceSearchRequest Parameters

Field	Type	Description
`service`	String	Filter by originating service
`operation`	String	Filter by operation name
`minDuration`	String	Minimum trace duration (e.g., `100ms`, `1s`)
`maxDuration`	String	Maximum trace duration
`start`	Instant	Search start time
`end`	Instant	Search end time
`limit`	int	Maximum traces to return
`tags`	Map	Filter by span tags

Trace Response Structure

The TraceQueryResponse contains a list of JaegerTrace objects, each with:

Field	Description
`traceID`	Unique trace identifier
`spans`	List of spans in the trace
`processes`	Map of process IDs to service names

Each span contains:

spanID, operationName, serviceName
startTime, duration
tags (key-value pairs like HTTP method, status code)
logs (span-level log entries)
references (parent span references)

Service Dependencies

Endpoint: GET /api/v1/observability/traces/dependencies

Analyzes traces to build a service dependency graph showing which services communicate with each other and the characteristics of those connections.

ServiceDependency Structure

Field	Type	Description
`parent`	String	Calling service
`child`	String	Called service
`callCount`	long	Number of calls observed
`avgDuration`	double	Average call duration
`errorRate`	double	Percentage of calls that failed

Trace Correlation

Endpoint: GET /api/v1/observability/traces/correlate/:traceId

The TraceCorrelationController correlates a trace with associated logs and metrics, providing a unified view of what happened during a request. The CorrelatedObservability response includes:

Trace spans
Log entries from the same time window and services
Metrics data points from the same period

Logs Dashboards