Skip to content
Osuite Osuite Docs

Write PromQL Agent

The Write PromQL Agent turns a plain-language request into a PromQL query built against your real Osuite metrics. Describe what you want to measure and it finds the right metric, inspects its labels, applies the correct function for the metric type, and returns a ready-to-use query. Like the other Osuite agents, it runs inside your AI IDE.

Writing PromQL by hand means knowing which metric carries your signal, remembering its exact name and labels, and picking the right function for its type — rate() for a counter, histogram_quantile() for a histogram, an aggregation for a gauge. The Write PromQL Agent does that lookup for you against the metrics you actually have, so it does not invent a metric name or a label that isn’t there.

Setup

Section titled “Setup”

The Write PromQL Agent installs with the rest of the Osuite agents. Follow the one-time agent setup — create an API key, install the CLI, and run osuite init-ai — then the agent is available as /osuite-write-promql.

Using the agent

Section titled “Using the agent”

In your AI IDE, describe the query you want:

Terminal window
/osuite-write-promql HTTP error rate by service

The agent works against your live metric catalog:

  1. Searches for the metric with semantic search over your metrics (osuite metrics search-embedding), which returns matching metrics with their types, descriptions, and labels.
  2. Inspects the labels of the best-matching metric (osuite metrics get-labels) and, when you filter by a dimension, its label values (osuite metrics get-label-values).
  3. Composes the query — applying the right function for the metric type and mapping the labels you described to real label names.
  4. Returns the PromQL, without running it unless you ask.

For the request above, the agent might return:

sum by (service) (rate(http_requests_total{status=~"5.."}[$__rate_interval]))

More example invocations:

Terminal window
/osuite-write-promql average memory usage per instance in production
/osuite-write-promql p99 request latency for the payments service
/osuite-write-promql pod restarts per namespace over the last hour

The agent adapts the query to context: for a dashboard widget it uses $__rate_interval; for an ad-hoc query it uses a concrete window such as [5m].

When to use it vs the Visualizer Agent

Section titled “When to use it vs the Visualizer Agent”

Both agents write PromQL, but they produce different things:

Use the Write PromQL Agent whenUse the Visualizer Agent when
You want the query text itself — to paste into a panel, an alert rule, or an ad-hoc query.You want a finished dashboard or widget — the query plus a chart type, unit, and time range.
You are refining or debugging an existing query.You are describing what you want to see and letting the agent assemble and apply the panel.

The Visualizer Agent uses the same metric-discovery and query-composition steps internally, then goes further and builds the visualization. Reach for the Write PromQL Agent when the query is the deliverable.

Next steps

Section titled “Next steps”