Create your first watcher on Grafana Labs

Keep the scope narrow

Fri, 30 Oct 2026 12:59:38 -0400

Keep the scope narrow

Focus the watcher on one service or failure mode and the signals that need attention. For example, watch checkout on its own rather than checkout, payments, and inventory together.

A checkout watcher is one service and one question: does checkout recover after a rollout, or does it stay broken?

Pick something with live data

Assistant builds the watcher’s checks from the telemetry in the data sources you choose. If those data sources have no telemetry for what you describe, Assistant can’t build the checks. Pick one service or job that’s sending data now. If you’re not sure what has data, the hands-on learning path includes an optional step that lists the Prometheus jobs that are up.

Give the watcher context

Fri, 30 Oct 2026 12:59:38 -0400

Give the watcher context

Telemetry can show that checkout errors rose. It can’t show that a short spike during a rollout is expected, or how quickly the service should recover.

When you create a watcher, you describe what to monitor and the behavior you expect, such as brief error spikes during deployments. You can also mention relevant alert rules or dashboards.

For example:

Watch the checkout service in production. Short error spikes during deploys are expected, but errors should recover within a few minutes.

How calibration works

Fri, 30 Oct 2026 12:59:38 -0400

How calibration works

When you create a watcher, Assistant starts calibration. Calibration builds checks from your description and data sources, plus a baseline that each run compares your telemetry against. Calibration runs in the background.

Depending on your data sources, checks can include PromQL, LogQL, TraceQL metrics, BigQuery SQL, and Grafana-managed alert checks. Assistant might ask you questions during calibration, and only the person who started calibration can see and answer them. If calibration stops, it explains why, so you can correct the description or data sources and try again.

What happens when calibration succeeds

When calibration succeeds, the watcher starts monitoring automatically and runs on a schedule, every 10 minutes by default. You can also trigger an extra run at any time, or pause scheduled runs without deleting the watcher.

Each watcher keeps the following:

Its goal, baseline, and saved checks. Calibrated checks are read-only, so to change them, you recalibrate.
The issues it’s tracking, with the evidence behind each one.
A history of recent runs, each with its own report.

The hands-on learning path walks you through calibration, running the watcher, and reading a run’s report.

What a result means

Fri, 30 Oct 2026 12:59:38 -0400

What a result means

When you run the checkout watcher, each completed run gets an assessment. The Watchers list shows the latest one, so you can tell whether checkout needs attention before you open the report.

Label	Meaning
All clear	The latest completed run found no concerns.
Flagged	The latest completed run found a warning-level concern.
Escalated	The latest completed run found a critical concern.
No verdict yet	No reliable assessment is available yet.
Checks failing	The latest finished run failed.

The hands-on learning path has you trigger a run and read this assessment.

Create a watcher path

Fri, 30 Oct 2026 12:59:38 -0400

Create a watcher path

In this path, you create a watcher for a service that has live data, follow calibration as it saves checks, trigger Run now, and read the run’s report on the Run history tab. You end with a calibrated watcher scanning on its schedule, which you can pause or archive afterward.

Learning path

Get started with Assistant Watchers

Create a watcher, calibrate checks against your telemetry, run it, and review the first result.

13 min

Intermediate

Docs & blog posts

Open in Grafana Cloud

Complete this learning path directly in your Grafana Cloud stack with an interactive learning experience.

Open in Grafana Cloud

View on website

Keep your watcher current

Fri, 30 Oct 2026 12:59:38 -0400

Keep your watcher current

Your service keeps changing after you create a watcher, through new releases, new traffic, and new kinds of expected errors. Calibrated checks are read-only, so when they stop matching your service, you recalibrate the watcher.

Recalibrate after a change

After service changes or repeated noisy findings, click Recalibrate at the top of the watcher’s page, or Suggest a change on the Calibration tab. Optionally describe the change in What would you like to change?, for example to ignore brief latency spikes during deployments, and click Start recalibration.

Recalibration pauses scanning, keeps the issues the watcher is tracking, and starts monitoring again when it succeeds.

Let Assistant review the checks on a schedule

To have Assistant review and update the checks for you, open the Configuration tab, turn on Automatically update checks under Automatic actions, and choose a Review frequency.

Reviews run in the background without pausing scanning, and they keep your goal, data sources, schedule, and notifications. A review can finish without changing anything. Reviews run only while the watcher is Active.

Restore an earlier version

Calibration and automatic review changes are saved as versions on the Versions tab. If a change makes the watcher less useful, expand an earlier version to compare it, click Restore, and confirm with Restore watcher. Review the restored checks, then turn scheduled scanning back on with the switch at the top of the page.

Track token usage

Watcher runs, calibration, and automatic reviews use tokens from your Grafana Assistant plan’s monthly allowance. The Token usage card on the watcher’s Overview tab estimates its monthly usage at the current schedule. The usage meter on the Watchers list shows how much of the monthly limit your watchers have used and when it resets. If you reach the limit, runs and calibration stop until the reset, and scheduled watchers resume automatically.

Resources

Fri, 30 Oct 2026 12:59:38 -0400

Resources

Documentation

These pages cover the workflow you practiced and the actions the hands-on learning path left off.

Use Assistant Watchers: Create, calibrate, run, pause, review, and troubleshoot watchers.
Recalibrate a watcher automatically and Review versions and restore a definition: Keep a watcher’s checks current.
Understand Grafana Assistant pricing and usage: How watcher runs use tokens and what happens at the limit.
Manage watcher notifications: Slack, Microsoft Teams, webhooks, and launching an investigation.
Configure Slack: Connect Slack if you want Post to Slack.
Grafana Assistant Investigations: What Launch on a critical assessment starts.
Manage Assistant access with RBAC: Watchers permissions.

Create your first watcher on Grafana Labs

Keep the scope narrow

Keep the scope narrow

Pick something with live data

Give the watcher context

Give the watcher context

How calibration works

How calibration works

What happens when calibration succeeds

What a result means

What a result means

Create a watcher path

Create a watcher path

Get started with Assistant Watchers

Open in Grafana Cloud

Keep your watcher current

Keep your watcher current

Recalibrate after a change

Let Assistant review the checks on a schedule

Restore an earlier version

Track token usage

Resources

Resources

Documentation

Community