Skip to content
PulsusDB

Logs with LogQL

import { Aside, Tabs, TabItem } from ‘@astrojs/starlight/components’;

PulsusDB parses LogQL and plans it against indexed log streams and entries in ClickHouse. The primary routes live under /api/logs/v1; optional Loki-compatible aliases use the same handlers.

Range query

Section titled “Range query”
Terminal window
curl --get 'http://localhost:3100/api/logs/v1/query_range' \
  --data-urlencode 'query={service_name="checkout"} |= "timeout"' \
  --data-urlencode 'start=1761901200000000000' \
  --data-urlencode 'end=1761904800000000000' \
  --data-urlencode 'limit=100'

Both GET and POST are supported for query endpoints. Use nanosecond timestamps or the documented accepted time formats for your client.

Instant query

Section titled “Instant query”
Terminal window
curl --get 'http://localhost:3100/api/logs/v1/query' \
  --data-urlencode 'query=sum by (service_name) (rate({environment="prod"}[5m]))' \
  --data-urlencode 'time=1761904800000000000'

Discover labels and streams

Section titled “Discover labels and streams”
Operation Route
Label names `GET
Label values `GET
Matching series `GET
Live tail GET /api/logs/v1/tail (WebSocket)
Index stats `GET

Query shapes

Section titled “Query shapes”
LogQL — line filtering
{service_name="api", environment=~"prod|staging"} |= "connection refused"
LogQL — parse and filter JSON
{service_name="checkout"} | json | status >= 500
LogQL — aggregate a range
sum by (service_name) (
  rate({environment="prod"} |= "error" [5m])
)

PulsusDB implements LogQL in milestones and maintains detailed compatibility tests against a pinned reference. Check the current feature matrix in the application repository before depending on a less common parser, stage, or operator.

Regular expressions

Section titled “Regular expressions”

LogQL regular expressions use the RE2 language. Backreferences and lookaround are not supported. PulsusDB applies validation so a pattern accepted by the query API has a linear-time matching model.

Compatibility routes

Section titled “Compatibility routes”

Set PULSUS_COMPAT_ENDPOINTS=true to mount aliases such as /loki/api/v1/query_range. Keep new integrations on /api/logs/v1 so they do not depend on a third-party compatibility surface.