Query logs, metrics, and traces

This guide runs one query against each of the three signals: a log query, a metric query, and a trace search, all scoped to a single workspace.

Before you begin

• Authentication. Export an API token as $QIBDO_API_TOKEN. Every path is relative to https://api.qibdo.example.com. See Authenticate a user and manage the session.
• Permissions. Your identity needs permission to read telemetry in the workspace. See the authorization model.
• Prerequisites. A workspace UUID and an engine. Throughout, {workspace} is your workspace UUID and {engine} is the telemetry provider: qibdo, aws, gcp, or azure. The examples use qibdo, whose log queries are LogQL and whose metric queries are PromQL.

Your deployment’s API domain

api.qibdo.example.com is an example host. qibdo runs on your own infrastructure, so the API lives at your deployment’s own domain. Replace it with yours before running these examples.

Query across a whole organisation

Pass - as the workspace to run a read-only query across every workspace under your organisation that you are allowed to read (AIP-159).

Console

Coming soon

A step-by-step walkthrough in the qibdo console is on the way. For now, use the REST tab.

CLI

Coming soon

A qibdo CLI walkthrough is on the way. For now, use the REST tab.

REST

1. Query logs

Log queries are a POST: the query is a LogQL expression on the qibdo engine, bounded by a start/end window and a limit. The call returns one page of lines.

POST /observability/v1/workspaces/{workspace}/engines/qibdo/logs:query HTTP/1.1
Host: api.qibdo.example.com
Authorization: Bearer $QIBDO_API_TOKEN
Content-Type: application/json

{
  "query": "{service=\"checkout\"} |= \"error\"",
  "start": "2026-07-03T00:00:00Z",
  "end": "2026-07-03T01:00:00Z",
  "limit": 100,
  "order_by": "timestamp desc"
}

To follow new lines instead of querying a fixed window, POST just the query (and an optional filter) to logs:tail. To see which streams exist first, GET logs/streams.

2. Query metrics

Metric queries are a POST with a PromQL query. Omit time to evaluate at now, or set it to evaluate at a past instant:

POST /observability/v1/workspaces/{workspace}/engines/qibdo/metrics:query HTTP/1.1
Host: api.qibdo.example.com
Authorization: Bearer $QIBDO_API_TOKEN
Content-Type: application/json

{ "query": "rate(http_requests_total{service=\"checkout\"}[5m])" }

For a time series over a window rather than a single instant, POST to metrics:queryRange instead. To discover what is queryable, GET metrics/descriptors and metrics/labels.

3. Search traces

Trace search is a POST with a TraceQL query. Each result carries a trace id you can fetch in full:

POST /observability/v1/workspaces/{workspace}/engines/qibdo/traces:search HTTP/1.1
Host: api.qibdo.example.com
Authorization: Bearer $QIBDO_API_TOKEN
Content-Type: application/json

{ "query": "{ .service.name = \"checkout\" && duration > 500ms }" }

Fetch the full span tree with a GET on traces/{id}, or read the service-graph to see how requests flowed between services over a window.

Listings the telemetry backend enumerates

Three observability listings are answered directly by the telemetry backend rather than by the platform’s query layer:

• log streams
• metric descriptors
• metric labels

They accept filter and order_by for interface consistency, but they carry no curated field set, so neither behaves the way Filtering describes. Narrow these with the query languages shown above (LogQL, PromQL, TraceQL) rather than with an AIP-160 expression.

This is a stated exclusion, not an oversight. What these three return is not a set of records with attributes; it is the label vocabulary of a time-series store, which is precisely what LogQL and PromQL selectors exist to navigate. A field predicate over it would be a second, weaker query language layered on top of the one built for the job.

Every other observability listing, such as alert rules, silences and retention policies, uses the standard filter language and publishes its filterable fields in the observability reference.

Next steps

• Read the three signals for when to reach for logs, metrics, or traces.
• Turn a query into an alert with alerting and silences.