Skip to content
Docs
Infrastructure & monitoring

Grafana

Let hires find dashboards, read and run their panels, query your data sources, see Grafana's alerts, and mark deploys and incidents with annotations.

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

With Grafana (open source; Grafana Cloud or your own), a hire can:

  • find dashboards by name or tag, and read one: its variables, its panels, and each panel's queries,
  • run a panel for a time range and get the numbers: each series' minimum, maximum, average and latest value with a few points across the range, or a table's rows,
  • write its own query for a data source: PromQL for Prometheus, LogQL for Loki, SQL for MySQL, PostgreSQL or SQL Server,
  • see which of Grafana's alerts are firing,
  • read annotations and add one, e.g. "deployed v42" or "incident started", so people see it on the graphs.

1. Make a service account token in Grafana

Straight there: https://<your-grafana>/org/serviceaccounts/create. Once you've typed your Grafana's address in Roster, the form links to it for you.

  1. In Grafana, open Administration → Users and access → Service accounts and click Add service account. Name it Roster.
  2. Role: Viewer for hires that only read. Editor if hires should add annotations.
  3. Click Add service account token, then copy the token (it starts with glsa_).

What hires do shows in Grafana as this service account.

2. Connect it in Roster

  1. Open Integrations → Tools → Add a tool, search for Grafana and choose it.
  2. Service account token: paste the token.
  3. Grafana address: your Grafana Cloud stack's address, like https://acme.grafana.net, or your own Grafana's.
  4. Click Connect.

Roster checks the key when you click Connect. If what you paste doesn't look like a key (service account tokens start with glsa_), the form says so straight away. Once it's accepted, the connection shows Connected as your Grafana organisation's name. If it's refused, Roster says what to fix (a mistyped key, a missing permission) and saves nothing.

3. Give hires access

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

  • Read only: everything above except adding annotations.
  • Read and write: it can also add annotations.
  • Folders: folder names or UIDs, one per line. Folders inside them are included; use General for dashboards that aren't in a folder. The hire only sees, runs and annotates dashboards in these folders, and only sees alerts whose rules live in them. Leave it empty for every folder the token can see.
  • Data sources: the data sources the hire may write its own queries for. Leave it empty for all. Panels on dashboards the hire can use always run, since you've allowed the dashboard.
  • Hold Prometheus queries to label and Allowed values (optional): e.g. namespace with shop. Every Prometheus query the hire runs, its own or a panel's, only sees series with one of those values. Queries to other kinds of data source are then refused, because Roster can't hold them to a label.

Dashboard variables

When a hire runs a panel, the dashboard's variables take their current values unless the hire gives others (namespace = checkout). "All" means everything.

Personal data in logs

Log lines from Loki come back with email addresses, IP addresses and anything that looks like a token replaced.

Watching for alerts

A hire's responsibility can watch Grafana: it's woken when one of Grafana's alerts starts firing in its folders (silenced ones left out), with the alert and its summary.

If something goes wrong

  • "Didn't accept the connection's credential": the token was deleted or has expired.
  • "Doesn't allow this": the service account's role is too low, often Viewer when a hire tried to add an annotation.
  • A panel shows "no data": try a longer time range, or give the panel's variables values.

Tools and permissions reference

This reference is built from the same definitions Roster uses to connect Grafana 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.

API key or access token

In Grafana: Administration → Users and access → Service accounts → Add, role Viewer (Editor to add annotations), then Add service account token.

When making a key, use these permissions from the connection guide:

  • Viewer (Editor to add annotations)

Connection fields

Grafana connection fields
FieldWhat to provide
Service account token
token
Required · sealed secret		In Grafana: Administration → Users and access → Service accounts → Add, role Viewer (Editor to add annotations), then Add service account token.
Grafana address
url
Required		Your Grafana Cloud stack's address, or your own Grafana's.

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.

Grafana per-hire limits
FieldWhat to provide
Folders
folders
Optional		Folder names or UIDs, one per line ("General" for dashboards outside any folder). Subfolders are included. Leave empty for every folder the token can see.
Data sources
datasources
Optional		Data sources the hire may write its own queries for, by name or UID. Leave empty for every one the token can see. Panels of allowed dashboards always run.
Hold Prometheus queries to label
scopeLabel
Optional		Optional: a label every Prometheus series the hire queries must have, with one of the values below. Queries to other kinds of data source are then refused.
Allowed values
scopeValues
Optional		Values of that label, one per line.

Actions

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

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

search_dashboardsRead only

Find dashboards by words in their title, or by tag.

Approval: Uses your workspace and hire approval settings.

Arguments for search_dashboards
ArgumentTypeDetails
queryOptionalstringSee input schema below.Default: ""
tagOptionalstringSee input schema below.
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "query": {
      "default": "",
      "type": "string",
      "maxLength": 200
    },
    "tag": {
      "type": "string",
      "maxLength": 100
    }
  }
}
get_dashboardRead only

A dashboard's variables and panels, with each panel's data source and queries.

Approval: Uses your workspace and hire approval settings.

Arguments for get_dashboard
ArgumentTypeDetails
dashboardRequiredstringthe dashboard's UID, from search_dashboards
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "dashboard": {
      "type": "string",
      "description": "the dashboard's UID, from search_dashboards"
    }
  },
  "required": [
    "dashboard"
  ]
}
run_panelRead only

Run a dashboard panel's queries for a time range and get the numbers (series summarised, tables as rows). Give variable values to override the dashboard's.

Approval: Uses your workspace and hire approval settings.

Arguments for run_panel
ArgumentTypeDetails
dashboardRequiredstringthe dashboard's UID, from search_dashboards
panelRequiredintegerthe panel's id, from get_dashboard
fromOptionalstringstart: "now-6h", "now-7d" or an ISO timeDefault: "now-1h"
toOptionalstringend: "now" or an ISO timeDefault: "now"
variablesOptionalobjectSee input schema below.Default: {}
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "dashboard": {
      "type": "string",
      "description": "the dashboard's UID, from search_dashboards"
    },
    "panel": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "the panel's id, from get_dashboard"
    },
    "from": {
      "default": "now-1h",
      "description": "start: \"now-6h\", \"now-7d\" or an ISO time",
      "type": "string"
    },
    "to": {
      "default": "now",
      "description": "end: \"now\" or an ISO time",
      "type": "string"
    },
    "variables": {
      "default": {},
      "type": "object",
      "propertyNames": {
        "type": "string",
        "pattern": "^\\w{1,100}$"
      },
      "additionalProperties": {
        "type": "string",
        "maxLength": 500
      }
    }
  },
  "required": [
    "dashboard",
    "panel"
  ]
}
query_datasourceRead only

Run your own query against a data source: PromQL for Prometheus, LogQL for Loki, SQL for MySQL, PostgreSQL or SQL Server. Series come back summarised, tables and log lines as rows.

Approval: Uses your workspace and hire approval settings.

Arguments for query_datasource
ArgumentTypeDetails
datasourceRequiredstringthe data source's name or UID, from list_datasources
queryRequiredstringSee input schema below.
fromOptionalstringstart: "now-6h", "now-7d" or an ISO timeDefault: "now-1h"
toOptionalstringend: "now" or an ISO timeDefault: "now"
instantOptionalbooleanPrometheus: one value per series at the end timeDefault: false
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "datasource": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "the data source's name or UID, from list_datasources"
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000
    },
    "from": {
      "default": "now-1h",
      "description": "start: \"now-6h\", \"now-7d\" or an ISO time",
      "type": "string"
    },
    "to": {
      "default": "now",
      "description": "end: \"now\" or an ISO time",
      "type": "string"
    },
    "instant": {
      "default": false,
      "description": "Prometheus: one value per series at the end time",
      "type": "boolean"
    }
  },
  "required": [
    "datasource",
    "query"
  ]
}
list_datasourcesRead only

The data sources this hire can query, with their kind.

Approval: Uses your workspace and hire approval settings.

This action takes no arguments.

Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {}
}
list_alertsRead only

Grafana's alerts firing now, with their labels and summary.

Approval: Uses your workspace and hire approval settings.

Arguments for list_alerts
ArgumentTypeDetails
include_silencedOptionalbooleanSee input schema below.Default: false
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "include_silenced": {
      "default": false,
      "type": "boolean"
    }
  }
}
list_annotationsRead only

Annotations (deploys, incidents, notes people left) on a dashboard, or across allowed dashboards, in a time range.

Approval: Uses your workspace and hire approval settings.

Arguments for list_annotations
ArgumentTypeDetails
dashboardOptionalstringthe dashboard's UID, from search_dashboards
fromOptionalstringstart: "now-7d" or an ISO timeDefault: "now-7d"
toOptionalstringend: "now" or an ISO timeDefault: "now"
tagsOptionalstring[]See input schema below.Default: []
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "dashboard": {
      "type": "string",
      "description": "the dashboard's UID, from search_dashboards"
    },
    "from": {
      "default": "now-7d",
      "description": "start: \"now-7d\" or an ISO time",
      "type": "string"
    },
    "to": {
      "default": "now",
      "description": "end: \"now\" or an ISO time",
      "type": "string"
    },
    "tags": {
      "default": [],
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100
      }
    }
  }
}
create_annotationRead and write

Mark a moment (or a period) on a dashboard with a note people will see on its graphs, e.g. a deploy or the start of an incident.

Approval: Uses your workspace and hire approval settings.

Arguments for create_annotation
ArgumentTypeDetails
dashboardOptionalstringthe dashboard's UID; leave out for a note on every dashboard
panelOptionalintegera panel's id, to mark only that panel
textRequiredstringSee input schema below.
tagsOptionalstring[]See input schema below.Default: []
timeOptionalstring"now" or an ISO timeDefault: "now"
endOptionalstringan ISO time, to mark a period
Full input schema (JSON)
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "dashboard": {
      "description": "the dashboard's UID; leave out for a note on every dashboard",
      "type": "string"
    },
    "panel": {
      "description": "a panel's id, to mark only that panel",
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "text": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "tags": {
      "default": [],
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 100
      }
    },
    "time": {
      "default": "now",
      "description": "\"now\" or an ISO time",
      "type": "string"
    },
    "end": {
      "description": "an ISO time, to mark a period",
      "type": "string"
    }
  },
  "required": [
    "text"
  ]
}

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

Gatus

Let hires see which of your endpoints are up or down in Gatus, with uptime, response times and why a check failed, and be woken when one goes down or comes back.

HCP Terraform

Workspaces, runs, plans and the Terraform registry.

On this page

1. Make a service account token in Grafana2. Connect it in Roster3. Give hires accessIf something goes wrongTools and permissions reference