Logs

​

Stats

​

GET /v1/logs/stats

curl -sS --fail-with-body -G \
  -H "Authorization: Bearer $MIRADOR_SERVER_KEY" \
  --data-urlencode 'since=1h' \
  --data-urlencode 'interval=5m' \
  --data-urlencode 'group_by=severity' \
  --data-urlencode 'group_by=service.name' \
  https://api.mirador.org/v1/logs/stats

• interval=whole gives one exact-count bucket — the way to count logs, since log lists have no total.
• For every bucket, total_count == sum(groups[].count) + other_count. Empty expected buckets are returned explicitly.
• Bucket boundaries are aligned independently of the request boundary, so clipped first/last buckets can make the bucket count differ from naive duration / interval — trust expected_bucket_count and each bucket’s start/end.
• top_k applies per bucket; it doesn’t enumerate a whole population. Use the attribute catalogue’s service_names for a full service inventory.
• An attribute group with present: false is the never-set cohort; filter it with NOT attribute.<key>:*.
• event.name is the best structured classifier when emitters populate it. If they don’t, group by service or a discovered attribute, then inspect exemplars — body text can’t be grouped by stats.

​

Discovery

​

GET /v1/logs/attributes

{
  "project_id": "prj_...",
  "range_start": "...",
  "range_end": "...",
  "attributes": { "items": [ { "key": "...", "values": { "items": [...], "truncated": false } } ], "truncated": false },
  "service_names": { "items": ["checkout", "payments"], "truncated": false }
}

​

Records

​

GET /v1/logs

curl -sS --fail-with-body -G \
  -H "Authorization: Bearer $MIRADOR_SERVER_KEY" \
  --data-urlencode 'since=1h' \
  --data-urlencode 'filter=severity="error"' \
  --data-urlencode 'page_size=10' \
  https://api.mirador.org/v1/logs

• Optional fields (event_name, trace_id, span_id, scope_version, flags, dropped_attributes_count) may be omitted rather than null.
• A record carries no normalized severity field — only numeric severity_number and the emitter’s raw severity_text. Derive the band from severity_number: 1–4 trace, 5–8 debug, 9–12 info, 13–16 warn, 17–20 error, 21–24 fatal, 0 unspecified.
• Parse time as an instant before sorting — fractional seconds have variable width, so lexical comparison is unsafe. Don’t use time alone as a dedupe key.

​

Log filters

• body: splits on non-alphanumeric characters and matches tokens; repeated body terms are ANDed and share one 256-byte budget.
• Filter on the normalized severity, never raw severity_text. warning aliases warn. unspecified has no ordering, so ordered comparisons and severity!="error" omit unspecified records unless explicitly ORed in.
• Use service.name, not attribute.service.name; use trace_id/span_id, not attribute.trace_id — the normalized fields cover both promoted OTel context and same-named attributes.

​

Live SSE stream

​

GET /v1/logs/stream

# Bound exploratory tails; curl exit 28 is expected when --max-time expires.
curl -sS --fail-with-body -N --max-time 20 -G \
  -H "Authorization: Bearer $MIRADOR_SERVER_KEY" \
  --data-urlencode 'filter=severity>="error"' \
  --data-urlencode 'window=5m' \
  https://api.mirador.org/v1/logs/stream

• event: ready announces the resolved filter/window, snapshot count, and whether the connection resumed.
• event: log carries data: {"log": {...}, "replay": true|false}. The resume token is the SSE id: line, not a JSON field.
• event: heartbeat keeps idle connections alive.
• event: error announces termination — reconnect after the SSE retry: delay (milliseconds), with Last-Event-ID and the same filter (a different filter is rejected).

​

Correlating traces and logs

GET /v1/logs?filter=trace_id="4bf92f3577b34da6a3ce929d0e0e4736"
  &since=2026-06-18T17:01:11Z&until=2026-06-18T17:03:23Z

​

Next Steps