Skip to main content

QUERY PROMETHEUS METRICS AND LOKI LOGS THROUGH GRAFANA

This guide shows you how to query Prometheus metrics and Loki logs through Grafana's datasource proxy for a time range, and keep the results as data in your repository.

Prerequisites

  • A behavior named grafana of type @keeb/grafana/instance, with grafanaUrl set to your Grafana server (see Create and Run a Behavior)
  • A Prometheus datasource and, for logs, a Loki datasource configured in that Grafana
  • If your Grafana server needs an API key, the apiKey global argument referenced from a vault with ${{ vault.get('<vault-name>', '<key>') }} (see Vaults)

If the @keeb/grafana extension is not in the repository yet, pull it:

swamp extension pull @keeb/grafana

The output looks like:

INF extension·pull: Pulling "@keeb/grafana"@"2026.07.18.1"
INF extension·pull: Identity verified: "@keeb/grafana"@"2026.07.18.1"
INF extension·pull: Pulled "@keeb/grafana"@"2026.07.18.1"
INF extension·pull: Extracted 7 files:

Query Prometheus metrics

Run queryMetrics with a PromQL query, a start and end time, and a step:

swamp behavior run grafana queryMetrics \
  --input 'query=up{job="node"}' \
  --input start=2026-10-15T00:00:00Z \
  --input end=2026-10-15T01:00:00Z \
  --input step=60s

This command needs a reachable Grafana server. It sends the PromQL query through Grafana's Prometheus datasource proxy and writes the result to the queryResult resource.

Wrap the query in single quotes so the shell passes braces and double quotes through unchanged. For a wider time range, raise the step to keep the number of returned points manageable.

Query Loki logs

Run queryLogs with a LogQL query and the same time range. Set direction to backward to get the newest lines first:

swamp behavior run grafana queryLogs \
  --input 'query={app="api"}' \
  --input start=2026-10-15T00:00:00Z \
  --input end=2026-10-15T01:00:00Z \
  --input direction=backward

This command needs a reachable Grafana server. It runs the LogQL query as a query_range through Grafana's Loki datasource proxy and writes the streams and lines to the logResult resource.

If you want the oldest lines first, set direction to forward. If Grafana has more than one Loki datasource, pass datasourceName to choose one. To cap the number of lines returned, pass limit.

Read the results

Each run stores its result as a new version of queryResult or logResult on the grafana behavior. To find and read those records, see Query and Manage Data.

To check a service after a change as part of a workflow, see Verify Infrastructure with Assert Steps. Refer to the Grafana extensions reference for every method and argument.