Definition JSON reference

A dashboard definition is one JSON document. This page is its syntax — which fields exist and what gets rejected.

The editor, the create API, import, and repository sync all go through the same validator, so the rules here hold whichever path you use. The import screen runs the same validation before saving, so a hand-written document can simply be pasted there to check it.

Minimal example

One panel plotting request count per service over time.

{
  "schemaVersion": 1,
  "panels": [
    {
      "id": "throughput",
      "title": "Throughput",
      "layout": { "x": 0, "y": 0, "w": 6, "h": 6 },
      "visualization": { "type": "TIME_SERIES" },
      "queries": [
        {
          "refId": "A",
          "signal": "traces",
          "aggregation": { "function": "COUNT" },
          "groupBy": ["service.name"],
          "output": { "type": "TIME_SERIES" }
        }
      ]
    }
  ]
}

variables, sections, and settings may be omitted — the server fills in empty arrays and defaults and stores the normalized document.

Top level

settings

The execute API takes absolute timestamps (from, to). defaultTimeRange is what the screen selects when the dashboard is first opened.

variables

Rules per type

How a selection reaches a filter

{
  "variables": [
    { "name": "service", "label": "Service",     "type": "SERVICE", "defaultValue": "ALL", "multi": true },
    { "name": "env",     "label": "Environment", "type": "ATTRIBUTE",
      "source": { "signal": "traces", "field": "environment" } },
    { "name": "keyword", "label": "Search",      "type": "TEXT" },
    { "name": "tier",    "label": "Tier",        "type": "CUSTOM", "options": ["free", "pro"] }
  ],
  "panels": [
    {
      "id": "errors", "layout": { "x": 0, "y": 0, "w": 6, "h": 6 },
      "visualization": { "type": "TIME_SERIES" },
      "queries": [
        {
          "refId": "A", "signal": "traces",
          "aggregation": { "function": "COUNT" },
          "filters": [
            { "field": "service.name", "operator": "IN", "value": "${service}" },
            { "field": "has_error",    "operator": "EQ", "value": true }
          ],
          "groupBy": ["service.name"],
          "output": { "type": "TIME_SERIES" }
        }
      ]
    }
  ]
}

sections

panels

layout

visualization

The visualization does not decide the shape of the result. The query's output.type does, and validation only checks that the two are compatible.

A mismatch is INCOMPATIBLE_OUTPUT. visualization.options is free-form JSON and is not validated.

queries

output.type

filters

All filters in the list are combined with AND. There is no OR; choosing among several values is IN.

The negated operators exist so that "everything except this" can be written into the definition — slow requests excluding streaming ones, for instance, where working around it with a BETWEEN upper bound would throw away the genuinely slow requests too.

Field names

Field names resolve against a per-signal dictionary. A name that is not in it is rejected with UNKNOWN_FIELD, so that a typo cannot produce a dashboard that saves and then quietly fails to draw.

Attributes outside the dictionary are reached through prefixes.

To see which fields and values actually arrived, use the filter on the Logs, Traces, and Metrics screens — whatever autocomplete offers is what a definition may use.

aggregation

Which functions actually work on a metric depends on its type (gauge, sum, histogram). Validation only rejects names outside the list; a combination that does not fit the metric type surfaces at execution.

measures — tables with several value columns

A table like "requests, p50, p95 per endpoint" is built with measures. One query, one scan, values taken from the same rows, so the axes cannot drift apart.

{
  "id": "by-route",
  "title": "Requests by route",
  "layout": { "x": 0, "y": 0, "w": 12, "h": 8 },
  "visualization": { "type": "TABLE" },
  "queries": [
    {
      "refId": "A",
      "signal": "traces",
      "filters": [{ "field": "service.name", "operator": "IN", "value": "${service}" }],
      "groupBy": ["span.http.route"],
      "measures": [
        { "function": "COUNT",                     "alias": "requests" },
        { "function": "P50", "field": "duration_ms", "alias": "p50" },
        { "function": "P95", "field": "duration_ms", "alias": "p95" }
      ],
      "output": { "type": "TABLE" }
    }
  ]
}

records — raw rows

Returns log or trace rows as they are, without aggregating. Seeing "5 errors" is only useful if you can then read those five lines.

{
  "id": "recent",
  "title": "Recent logs",
  "layout": { "x": 0, "y": 0, "w": 12, "h": 10 },
  "visualization": { "type": "LOGS" },
  "queries": [
    {
      "refId": "A",
      "signal": "logs",
      "records": true,
      "filters": [{ "field": "level", "operator": "EQ", "value": "error" }],
      "output": { "type": "TABLE" },
      "alias": "logs"
    }
  ]
}

orderBy — ordering the raw table

orderBy looks like { "field": "timestamp", "desc": true }. Only columns carried by that table can be chosen — ordering by a column nobody can see leaves the screen unable to explain the result.

This is what makes a panel like "recent error traces" possible; with the default order alone you only ever get the slowest ones.

ratio — division

Divides two queries of the same panel. There is exactly one shape, "A ÷ B", which is what error rate and success rate need.

{
  "id": "error-rate",
  "title": "Error rate",
  "layout": { "x": 0, "y": 0, "w": 3, "h": 4 },
  "visualization": { "type": "NUMBER" },
  "queries": [
    { "refId": "A", "output": { "type": "SCALAR" },
      "ratio": { "numerator": "B", "denominator": "C" }, "alias": "error rate" },

    { "refId": "B", "signal": "traces", "aggregation": { "function": "COUNT" },
      "filters": [{ "field": "has_error", "operator": "EQ", "value": true }],
      "output": { "type": "SCALAR" } },

    { "refId": "C", "signal": "traces", "aggregation": { "function": "COUNT" },
      "output": { "type": "SCALAR" } }
  ]
}

limit

Caps how many series a time series panel draws. The largest series are chosen first and only then spread over time, so hitting the cap never truncates the time range. 0 means the default of 20, and the maximum is 100. Asking for more is rejected with OUT_OF_RANGE rather than silently folded.

Whether a result was capped is reported in the execute response as meta.truncated and meta.series_limit.

Normalization

Once a document passes validation the server normalizes it before storing, so what is stored may differ from what you sent.

Validation errors

Errors come back collected in one response. path is a JSON Pointer to the exact spot, and code is a stable identifier that survives wording changes.

{
  "valid": false,
  "schema_version": 1,
  "summary": { "panel_count": 1, "variable_count": 0, "section_count": 0 },
  "errors": [
    {
      "path": "/panels/0/queries/0/groupBy",
      "code": "REQUIRED",
      "message": "a TABLE result needs at least one group by"
    },
    {
      "path": "/panels/0/layout",
      "code": "OUT_OF_RANGE",
      "message": "panel exceeds the 12 column grid (x=8, w=6)"
    }
  ]
}

Codes raised during execution are not validation errors. The definition is stored, one query could not produce an answer, and the other panels still render.

Seeing real definitions

The built-in templates are the best examples. Create a dashboard from one and press export to get the finished definition document.