Logs

The LogsController and LokiQueryService provide tenant-scoped log querying against the Loki backend. Endpoints support filtering by service, log level, time range, and free-text search. Log queries use LogQL under the hood.

Query Logs (POST)

Endpoint: POST /api/v1/observability/logs

curl -X POST http://localhost:8088/api/v1/observability/logs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "X-Tenant-ID: 550e8400" \
  -d '{
    "start": "2026-02-12T09:00:00Z",
    "end": "2026-02-12T10:00:00Z",
    "services": ["ai-service", "query-engine"],
    "levels": ["ERROR", "WARN"],
    "query": "timeout",
    "limit": 500,
    "direction": "backward"
  }'

Query Logs (GET)

Endpoint: GET /api/v1/observability/logs

Parameter	Type	Default	Description
`start`	Instant	1 hour ago	Start time
`end`	Instant	now	End time
`services`	List	all	Filter by service names
`levels`	List	all	Filter by log levels
`query`	String	null	Free-text search
`limit`	int	1000	Maximum log entries
`direction`	String	`backward`	`forward` or `backward`

Recent Logs

Endpoint: GET /api/v1/observability/logs/recent

Returns the most recent logs for the tenant (last hour, default 100 entries).

Parameter	Type	Default	Description
`limit`	int	100	Maximum entries
`services`	List	all	Filter by services
`levels`	List	all	Filter by levels

Error Logs

Endpoint: GET /api/v1/observability/logs/errors

Returns recent ERROR and FATAL level logs.

Parameter	Type	Default	Description
`limit`	int	100	Maximum entries
`start`	Instant	24 hours ago	Start time
`end`	Instant	now	End time

Available Services

Endpoint: GET /api/v1/observability/logs/services

Returns the list of services that have emitted logs for the tenant within the specified time range.

Available Log Levels

Endpoint: GET /api/v1/observability/logs/levels

Returns the list of standard log levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL.

LogQueryRequest Structure

Field	Type	Description
`start`	Instant	Query start time
`end`	Instant	Query end time
`services`	List	Service name filters
`levels`	List	Log level filters
`query`	String	Free-text search term
`limit`	int	Maximum results
`direction`	String	Sort direction (`forward` or `backward`)

Tenant Scoping

Log queries are automatically scoped to the tenant via the X-Tenant-ID header. The LokiQueryService adds namespace labels to LogQL queries to ensure tenant isolation.

Metrics Tracing