Prometheus

Let hires query your metrics with PromQL, see which alerts are firing, add and end silences in Alertmanager, and be woken when an alert starts firing.

Explore 7 actions and their permissionsExact inputs, sign-in scopes, access limits and approval rules.

With Prometheus (open source, on your own servers), a hire can:

run PromQL queries at a moment or over a period, e.g. "error rate per service over the last 6 hours", and get each series' minimum, maximum, average and latest value with a few points across the period,
look up metric names to write queries with,
see which alerts are firing (and which are about to),
with Alertmanager: see which alerts are silenced, add a silence for a while with a reason, and end a silence early.

It works with anything that speaks Prometheus's API: Prometheus itself, Thanos, Grafana Mimir, VictoriaMetrics, or a hosted Prometheus endpoint.

Short answers on purpose

Queries come back trimmed: at most 50 series at a moment (200 if the hire asks), 10 over a period, summarised rather than every point. Hires are told to add things up (sum by (service)) rather than read thousands of series.

1. Find the addresses

Prometheus address: where Prometheus's API answers, without /api/v1, e.g. https://prometheus.internal:9090. For Thanos, Mimir or VictoriaMetrics, use the address their Prometheus API is under (Mimir's is usually https://<mimir>/prometheus).
Alertmanager address (optional): e.g. https://alertmanager.internal:9093. Without it, hires see alerts from Prometheus's rules and can't add silences.

Roster has to be able to reach both. If they're only on your own network, run Roster there or open a route to them.

2. Connect it in Roster

Open Integrations → Tools → Add a tool, search for Prometheus and choose it.
How Roster signs in:
- No sign-in, if Prometheus is only reachable inside your network;
- Username and password, for Prometheus's own basic_auth_users or a proxy that asks for them;
- Bearer token, for a proxy or hosted endpoint that wants a token.
Alertmanager gets the same sign-in.
Fill in the addresses.
Longest silence (hours): a hire can't silence anything for longer. 24 hours unless you change it.
Click Connect.

3. Give hires access

On the hire's Tools tab, click Give access on Prometheus:

Read only: queries, metric names, alerts and silences, and nothing else.
Read and write: it can also add silences and end them.
Hold to label and Allowed values (optional): e.g. namespace with shop and checkout. Every query the hire runs only sees series with one of those values (Roster adds the match to each part of the query itself), it only sees alerts and silences with them, and any silence it adds is limited to them.

Silences are kept narrow

A silence needs at least one exact match, like alertname="HighLatency", so a hire can't silence everything at once. It shows in Alertmanager as made by the hire, with its reason. A silence of up to an hour goes ahead; a longer one waits for a person's approval in the thread. To change this for a hire, use When it asks first on its Tools tab.

Watching for alerts

A hire's responsibility can watch Prometheus: it's woken when an alert starts firing (from Alertmanager, leaving out silenced ones, when it has an address; otherwise from Prometheus's rules), with the alert and its summary. An alert that keeps firing isn't reported again until it stops and fires again. Checking costs nothing when nothing changed.

If something goes wrong

"Couldn't reach it": Roster can't get to the address. Check it from where Roster runs.
"Didn't accept the connection's credential": the username, password or token is wrong.
"Parse error": the query isn't valid PromQL; the hire sees Prometheus's own message and can fix it.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Prometheus and give hires access. It updates with each release.

Authentication and requested permissions

The account or app you connect sets the outer limit. Each hire's access can narrow it further. Connecting a tool gives it to no hire until you give access on that hire's Tools tab.

User name and password or key pair

A user from Prometheus's web config (basic_auth_users) or your proxy.

For: How Roster signs in: Username and password (Basic).

API key or access token

Sent as Authorization: Bearer, for a proxy or a hosted Prometheus API that wants one.

For: How Roster signs in: Bearer token.

No sign-in

Connecting without a sign-in credential is supported when the service allows it.

No fixed permission list is declared for this connection. Review the sign-in consent screen, the account's roles, and the service's own documentation before connecting.

Connection fields

Prometheus connection fields
Field	What to provide
How Roster signs in `signIn` Optional	Nothing, if Prometheus is only reachable on your own network. Otherwise the username and password, or the token, your proxy or Prometheus asks for. Choices: No sign-in (none); Username and password (Basic) (basic); Bearer token (token). Starts with: `none`.
Username `username` Required	A user from Prometheus's web config (basic_auth_users) or your proxy. Shown when `signIn: basic`.
Password `password` Required · sealed secret	Use the value for your account or connection. Shown when `signIn: basic`.
Bearer token `token` Required · sealed secret	Sent as Authorization: Bearer, for a proxy or a hosted Prometheus API that wants one. Shown when `signIn: token`.
Prometheus address `url` Required	Where Prometheus's API is, without /api/v1. Thanos, Mimir and VictoriaMetrics work too, at their Prometheus API's address.
Alertmanager address `alertmanagerUrl` Optional	Optional. With it, hires see alerts as Alertmanager has them (silenced or not) and can add and expire silences.
Longest silence (hours) `maxSilenceHours` Optional	A hire can't silence an alert for longer than this. Starts with: `24`.

Per-hire limits

Read-only hires receive only actions that read. Read-and-write access also allows actions that change things, where the connection itself permits them. An empty resource allowlist usually means everything the connected account can reach; each field below explains its meaning.

Prometheus per-hire limits
Field	What to provide
Hold to label `scopeLabel` Optional	Optional: a label every series, alert and silence the hire touches must have, with one of the values below.
Allowed values `scopeValues` Optional	Values of that label, one per line, e.g. shop and checkout. Leave empty for everything.

Actions

7 actions: 5 only read and 2 change something. A read action may still need approval when your workspace or hire is set to ask. A locked approval requirement always applies.

Find an actionAccess

7 of 7 actions. Open an action for its arguments and full input schema.

queryRead only

Run a PromQL query at one moment (now unless told), e.g. sum by (job) (rate(http_requests_total{code=~"5.."}[5m])). Prefer aggregations: at most 200 series come back.

Approval: Uses your workspace and hire approval settings.

Arguments for query
Argument	Type	Details
`query`Required	string	a PromQL expression.
`time`Optional	string	"now", how long ago ("1h"), or an ISO timeDefault: `"now"`
`limit`Optional	integer	most series to showDefault: `50`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "a PromQL expression."
    },
    "time": {
      "default": "now",
      "description": "\"now\", how long ago (\"1h\"), or an ISO time",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "description": "most series to show",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    }
  },
  "required": [
    "query"
  ]
}

query_rangeRead only

Run a PromQL query over a period and get each series' min, max, average and last value with a few points across it, e.g. to see when errors started.

Approval: Uses your workspace and hire approval settings.

Arguments for query_range
Argument	Type	Details
`query`Required	string	a PromQL expression.
`since`Optional	string	how long ago to start ("6h", "2d") or an ISO timeDefault: `"1h"`
`until`Optional	string	"now", how long ago, or an ISO timeDefault: `"now"`
`step`Optional	string	time between points; leave out for about 120 points
`limit`Optional	integer	most series to showDefault: `10`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "a PromQL expression."
    },
    "since": {
      "default": "1h",
      "description": "how long ago to start (\"6h\", \"2d\") or an ISO time",
      "type": "string"
    },
    "until": {
      "default": "now",
      "description": "\"now\", how long ago, or an ISO time",
      "type": "string"
    },
    "step": {
      "description": "time between points; leave out for about 120 points",
      "type": "string",
      "pattern": "^\\d{1,5}[smhd]$"
    },
    "limit": {
      "default": 10,
      "description": "most series to show",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "query"
  ]
}

list_metricsRead only

Metric names Prometheus has, to write queries with. Give part of a name to narrow it.

Approval: Uses your workspace and hire approval settings.

Arguments for list_metrics
Argument	Type	Details
`contains`Optional	string	part of a metric name, e.g. http_ or latency

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "contains": {
      "description": "part of a metric name, e.g. http_ or latency",
      "type": "string",
      "maxLength": 200
    }
  }
}

list_alertsRead only

Alerts firing now, as Alertmanager has them: firing, silenced or inhibited, with their labels and summary.

Approval: Uses your workspace and hire approval settings.

Arguments for list_alerts
Argument	Type	Details
`include_silenced`Optional	boolean	also show silenced and inhibited alertsDefault: `false`
`alertname`Optional	string	See input schema below.

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "include_silenced": {
      "default": false,
      "description": "also show silenced and inhibited alerts",
      "type": "boolean"
    },
    "alertname": {
      "type": "string",
      "maxLength": 200
    }
  }
}

list_silencesRead only

Silences in Alertmanager: active and pending ones, or expired too.

Approval: Uses your workspace and hire approval settings.

Arguments for list_silences
Argument	Type	Details
`include_expired`Optional	boolean	See input schema below.Default: `false`

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "include_expired": {
      "default": false,
      "type": "boolean"
    }
  }
}

create_silenceRead and write

Silence alerts matching some labels for a while (at most 24 hours), with a reason people will read. Needs at least one exact label match (e.g. alertname="HighLatency"), so nothing is silenced by accident. Check list_alerts first for the exact labels.

Approval: when it silences alerts for more than an hour.

Arguments for create_silence
Argument	Type	Details
`matchers`Required	object[]	See input schema below.
`minutes`Required	integer	how long, at most 1440 minutes
`comment`Required	string	why, for the people who'll see it

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "matchers": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
          },
          "value": {
            "type": "string",
            "maxLength": 500
          },
          "regex": {
            "default": false,
            "description": "value is a regular expression",
            "type": "boolean"
          },
          "negate": {
            "default": false,
            "description": "match labels NOT equal to the value",
            "type": "boolean"
          }
        },
        "required": [
          "name",
          "value"
        ]
      }
    },
    "minutes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1440,
      "description": "how long, at most 1440 minutes"
    },
    "comment": {
      "type": "string",
      "minLength": 3,
      "maxLength": 500,
      "description": "why, for the people who'll see it"
    }
  },
  "required": [
    "matchers",
    "minutes",
    "comment"
  ]
}

expire_silenceRead and write

End a silence now, so its alerts notify again.

Approval: Uses your workspace and hire approval settings.

Arguments for expire_silence
Argument	Type	Details
`id`Required	string	the silence's id, from list_silences

Full input schema (JSON)

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "the silence's id, from list_silences"
    }
  },
  "required": [
    "id"
  ]
}

Watches and incoming events

This integration supports a responsibility that watches for changes. The guide above explains what it checks and how to limit it.
No incoming webhook handler is declared for this integration.

Limits and troubleshooting

Permission errors: check both the connected account's rights and the hire's resource and read/write limits.
Expired or revoked access: reconnect or replace the key on the connection.
Rate limits and unavailable services can interrupt work. The hire's timecard records the outcome.
The action schema describes accepted inputs. It does not grant additional access or bypass approvals.

Service documentation · Integration source reference

1. Find the addressesCopy Anchor Link

2. Connect it in RosterCopy Anchor Link

3. Give hires accessCopy Anchor Link

If something goes wrongCopy Anchor Link

Tools and permissions reference

Authentication and requested permissions

User name and password or key pair

API key or access token

No sign-in

Connection fields

Per-hire limits

Actions

Watches and incoming events

Limits and troubleshooting

On this page

1. Find the addresses

2. Connect it in Roster

3. Give hires access

If something goes wrong