Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 37 ยท Dashboards and Variables

Grafana Annotations, Data Links and Dashboard Drilldowns

Mark events on graphs with annotations, connect dashboards with dashboard, panel and data links, pass variables and time range in URLs, and use value mappings.

A graph tells you that something changed. An annotation tells you why: a deployment, an incident, a config change. A link takes you from the symptom to the detail. This lesson covers annotations, the three kinds of links, the URL parameters that carry context between dashboards, and value mappings that make raw numbers readable.

Grafana is not available on this site, so interface steps are in words. The runnable blocks are Python stand-ins for URL building and annotation filtering.

Annotations

An annotation is a marker (a vertical line, or a shaded region between two times) drawn on time series panels, with a text, tags and optional time end.

Built-in annotations. Every dashboard has a built-in query called Annotations & Alerts. It shows annotations stored in Grafana's own database, including alert state changes. To add one by hand, hold Ctrl (or Cmd on macOS) and click on a time series graph; to add a region, hold Ctrl and drag. Type a description and tags, then save. They appear for everyone with access to the dashboard.

Annotation queries. In Dashboard settings > Annotations you can add a query that reads events from a data source: a SQL table deployments(time, service, version), a Prometheus expression for restarts, an Elasticsearch query, or Loki lines. Settings include:

  • Data source and the query (use $__timeFilter for SQL).
  • The columns that give time, time end (for regions), title and text, tags and a color.
  • A toggle to show the annotations by default, and a filter to limit them to specific panels.

The API can also create annotations from scripts: your deploy pipeline can post one at each release, so graphs show a line labelled with the commit or version. That is a very cheap, very effective practice.

Python Stand-in: which annotations fall in the visible range?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

  1. Dashboard links (Dashboard settings > Links): appear at the top of the dashboard. Types: Dashboards (a dropdown of dashboards chosen by tags) or Link (any URL). Options let you Include current time range and Include current template variable values, so the target opens with the same context.
  2. Panel links (Panel options > Panel links): shown in a small icon in the panel's header.
  3. Data links (Standard options > Data links, or Field overrides): attached to the data points, table cells or series. Clicking a bar or a table cell goes to a URL built from that point's values.

Data links support these variables inside the URL:

  • ${__value.raw}, ${__value.text}, ${__value.numeric}: the clicked value.
  • ${__field.name}, ${__field.labels.instance}: the field's name and label values.
  • ${__data.fields.hostname}: the value of another column in the same row (table panels).
  • ${__series.name}.
  • ${__url_time_range}: expands to from=...&to=... for the current dashboard range.
  • ${__all_variables}: all current dashboard variables as var-name=value pairs.

A drilldown from an overview table to a per-host dashboard might use:

TEXT
/d/node-detail/node-detail?var-host=${__data.fields.hostname}&${__url_time_range}

URL parameters

You can build a link to any dashboard by hand. The parts are:

  • /d/<uid>/<slug>: the dashboard UID (stable) and a readable slug.
  • from and to: absolute epoch milliseconds, or relative values like now-6h and now.
  • var-<name>=<value>: set a variable. Repeat the key to pass several values for a multi-value variable.
  • viewPanel=<id>: open straight into one panel; kiosk hides the chrome; refresh=30s sets auto refresh; orgId=1 selects the organization; theme=light forces a theme.
Python Stand-in: build a drilldown URL

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Value mappings and display

Raw values are often not what a human wants to read. Value mappings (Standard options > Value mappings) change how values are displayed:

  • Value: 0 becomes Down in red, 1 becomes Up in green.
  • Range: from 0 to 50 becomes Low.
  • Regex: any text matching a pattern gets a label and color.
  • Special: null, NaN, true, false, empty.

Mappings combine well with the State timeline and Status history panels and with Stat panels for service health. Units (bytes, percent, seconds), decimals, and thresholds (color changes at values) live in the same Standard options section, and overrides let you change them for one series only.

Putting it together

A solid incident dashboard: a stat row at the top with value mappings and threshold colors, a time series with a deployments annotation query, a table with a data link per row to the host dashboard, and a dashboard link back to an "all services" overview. Every click carries the time range and the variable values, so the viewer never loses context.

flowchart LR
    O["Overview table"] -- "data link<br/>var-host=${__data.fields.host}" --> H["Host dashboard"]
    H -- "dashboard link<br/>include time range" --> L["Logs dashboard"]
    A["Deploy annotations"] -.-> H

Links pass context forward; annotations explain the graph you land on.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you add a manual annotation to a time series graph?

    Ctrl or Cmd plus click adds an annotation; Ctrl plus drag adds a region.
  2. 2. Which link type is attached to individual data points or table cells?

    Data links are configured in Standard options and can use values from the clicked point.
  3. 3. What does ${__url_time_range} expand to?

    It adds the from and to parameters so the target opens on the same range.
  4. 4. How do you pass two values of a multi-value variable in a URL?

    Repeating the var-name key sets several selected values.

Summary

  • Annotations mark events on graphs: manual (Ctrl+click), from queries, or posted by pipelines.
  • Dashboard, panel and data links connect views; data links can use the clicked value and other columns.
  • URLs carry context: from, to, var-<name>, viewPanel, kiosk, refresh.
  • Value mappings and thresholds turn raw numbers into readable states and colors.
  • Annotations plus drilldown links make dashboards answer "why" and "where next".

Next: Time Ranges and Refresh