From 51003396040f994d0a0f3375ef0079ac630d154b Mon Sep 17 00:00:00 2001 From: utkarshcmu Date: Sun, 1 Nov 2015 22:58:14 -0800 Subject: [PATCH 1/8] Initialized dashboard JSON doc. --- docs/sources/reference/dashboard.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/sources/reference/dashboard.md diff --git a/docs/sources/reference/dashboard.md b/docs/sources/reference/dashboard.md new file mode 100644 index 00000000000..e69de29bb2d From 3a021a87a1df417b1e1478f39e4d209e1b22ae87 Mon Sep 17 00:00:00 2001 From: utkarshcmu Date: Sun, 1 Nov 2015 23:17:23 -0800 Subject: [PATCH 2/8] Added JSON of new dashboard --- docs/sources/reference/dashboard.md | 80 +++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) diff --git a/docs/sources/reference/dashboard.md b/docs/sources/reference/dashboard.md index e69de29bb2d..1a05ff596c8 100644 --- a/docs/sources/reference/dashboard.md +++ b/docs/sources/reference/dashboard.md @@ -0,0 +1,80 @@ +---- +page_title: Dashboard JSON +page_description: Dashboard JSON Reference +page_keywords: grafana, dashboard, json, documentation +--- + +# Dashboard JSON + +## Overview + +A dashboard in Grafana is represented by a JSON object, which stores dashboard metadata, rows of panels, panel queries, etc. + + + +> To view the JSON of a dashboard, you can click on "Manage dashboard" cog menu and select "View JSON" from it. + +## Basic fields + +A dashboard JSON object is initialized with the following fields when it is created. + +``` +{ + "id": null, + "title": "New dashboard", + "originalTitle": "New dashboard", + "tags": [], + "style": "dark", + "timezone": "browser", + "editable": true, + "hideControls": false, + "sharedCrosshair": false, + "rows": [ + { + "height": "250px", + "panels": [], + "title": "Row", + "collapse": false, + "editable": true + } + ], + "time": { + "from": "now-6h", + "to": "now" + }, + "timepicker": { + "time_options": [ + "5m", + "15m", + "1h", + "6h", + "12h", + "24h", + "2d", + "7d", + "30d" + ], + "refresh_intervals": [ + "5s", + "10s", + "30s", + "1m", + "5m", + "15m", + "30m", + "1h", + "2h", + "1d" + ] + }, + "templating": { + "list": [] + }, + "annotations": { + "list": [] + }, + "schemaVersion": 7, + "version": 0, + "links": [] +} +``` From ada641090f04284dc9ff2f6b05c37ec9d5dddf02 Mon Sep 17 00:00:00 2001 From: Utkarsh Bhatnagar Date: Sun, 1 Nov 2015 23:53:24 -0800 Subject: [PATCH 3/8] Explained basic JSON fields --- docs/sources/reference/dashboard.md | 35 ++++++++++++++++++++++++----- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/docs/sources/reference/dashboard.md b/docs/sources/reference/dashboard.md index 1a05ff596c8..c5bea813802 100644 --- a/docs/sources/reference/dashboard.md +++ b/docs/sources/reference/dashboard.md @@ -8,15 +8,19 @@ page_keywords: grafana, dashboard, json, documentation ## Overview -A dashboard in Grafana is represented by a JSON object, which stores dashboard metadata, rows of panels, panel queries, etc. +A dashboard in Grafana is represented by a JSON object, which stores metadata of its dashboard. Dashboard metadata includes dashboard properties, metadata from rows, panels, template variables, panel queries, etc. - +To view the JSON of a dashboard, follow the steps mentioned below: -> To view the JSON of a dashboard, you can click on "Manage dashboard" cog menu and select "View JSON" from it. + 1. Go to a dashboard + 2. Click on `Manage dashboard` menu on the top navigation bar + 3. Select `View JSON` from the dropdown menu ## Basic fields -A dashboard JSON object is initialized with the following fields when it is created. +When a user creates a new dashboard, a new dashboard JSON object is initialized with the following fields: + +> Note: In the following JSON, id is shown as null which is the default value assigned to it until the dashboard is not saved. Once saved, an integer value is assigned to the `id` field. ``` { @@ -26,7 +30,7 @@ A dashboard JSON object is initialized with the following fields when it is crea "tags": [], "style": "dark", "timezone": "browser", - "editable": true, + "editable": true, "hideControls": false, "sharedCrosshair": false, "rows": [ @@ -78,3 +82,24 @@ A dashboard JSON object is initialized with the following fields when it is crea "links": [] } ``` +Each field in the dashboard JSON is explained below with its usage: + +| Name | Usage | +| ---- | ----- | +| **id** | unique dashboard id, an integer | +| **title** | current title of dashboard | +| **originalTitle** | title of dashboard when saved for the first time | +| **tags** | an array of strings storing tags associated with dashboard | +| **style** | theme of dashboard, i.e. dark or light | +| **timezone** | timezone of dashboard, i.e. utc or browser | +| **editable** | whether a dashboard is editable or not | +| **hideControls** | whether row controls on the left in green are hidden or not | +| **sharedCrosshair** | TODO | +| **rows** | row metadata, see rows section for details | +| **time** | time range of dashboard, i.e. last 6 hours, last 7 days, etc | +| **timepicker** | timepicker metadata, see timepicker section for details | +| **templating** | timeplating metadata, see templating section for details | +| **annotations** | annotations metadata, see annotations section for details | +| **schemaVersion** | TODO | +| **version** | TODO | +| **links** | TODO | From 4c1b6f3059111e74464f7410a20fdc4acc3480ab Mon Sep 17 00:00:00 2001 From: utkarshcmu Date: Sun, 1 Nov 2015 23:55:03 -0800 Subject: [PATCH 4/8] Fixed a typo --- docs/sources/reference/dashboard.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sources/reference/dashboard.md b/docs/sources/reference/dashboard.md index c5bea813802..16481829f82 100644 --- a/docs/sources/reference/dashboard.md +++ b/docs/sources/reference/dashboard.md @@ -98,7 +98,7 @@ Each field in the dashboard JSON is explained below with its usage: | **rows** | row metadata, see rows section for details | | **time** | time range of dashboard, i.e. last 6 hours, last 7 days, etc | | **timepicker** | timepicker metadata, see timepicker section for details | -| **templating** | timeplating metadata, see templating section for details | +| **templating** | templating metadata, see templating section for details | | **annotations** | annotations metadata, see annotations section for details | | **schemaVersion** | TODO | | **version** | TODO | From f54615ed46a1741a5fd23928ff8874ce9f7819cd Mon Sep 17 00:00:00 2001 From: Utkarsh Bhatnagar Date: Mon, 2 Nov 2015 00:21:59 -0800 Subject: [PATCH 5/8] Included rows JSON and TODO headers --- docs/sources/reference/dashboard.md | 104 +++++++++++++++++----------- 1 file changed, 62 insertions(+), 42 deletions(-) diff --git a/docs/sources/reference/dashboard.md b/docs/sources/reference/dashboard.md index 16481829f82..cdef0c75119 100644 --- a/docs/sources/reference/dashboard.md +++ b/docs/sources/reference/dashboard.md @@ -16,11 +16,11 @@ To view the JSON of a dashboard, follow the steps mentioned below: 2. Click on `Manage dashboard` menu on the top navigation bar 3. Select `View JSON` from the dropdown menu -## Basic fields +## JSON fields When a user creates a new dashboard, a new dashboard JSON object is initialized with the following fields: -> Note: In the following JSON, id is shown as null which is the default value assigned to it until the dashboard is not saved. Once saved, an integer value is assigned to the `id` field. +> Note: In the following JSON, id is shown as null which is the default value assigned to it until a dashboard is saved. Once a dashboard is saved, an integer value is assigned to the `id` field. ``` { @@ -33,43 +33,14 @@ When a user creates a new dashboard, a new dashboard JSON object is initialized "editable": true, "hideControls": false, "sharedCrosshair": false, - "rows": [ - { - "height": "250px", - "panels": [], - "title": "Row", - "collapse": false, - "editable": true - } - ], + "rows": [], "time": { "from": "now-6h", "to": "now" }, "timepicker": { - "time_options": [ - "5m", - "15m", - "1h", - "6h", - "12h", - "24h", - "2d", - "7d", - "30d" - ], - "refresh_intervals": [ - "5s", - "10s", - "30s", - "1m", - "5m", - "15m", - "30m", - "1h", - "2h", - "1d" - ] + "time_options": [], + "refresh_intervals": [] }, "templating": { "list": [] @@ -89,17 +60,66 @@ Each field in the dashboard JSON is explained below with its usage: | **id** | unique dashboard id, an integer | | **title** | current title of dashboard | | **originalTitle** | title of dashboard when saved for the first time | -| **tags** | an array of strings storing tags associated with dashboard | -| **style** | theme of dashboard, i.e. dark or light | -| **timezone** | timezone of dashboard, i.e. utc or browser | +| **tags** | tags associated with dashboard, an array of strings | +| **style** | theme of dashboard, i.e. `dark` or `light` | +| **timezone** | timezone of dashboard, i.e. `utc` or `browser` | | **editable** | whether a dashboard is editable or not | | **hideControls** | whether row controls on the left in green are hidden or not | | **sharedCrosshair** | TODO | -| **rows** | row metadata, see rows section for details | -| **time** | time range of dashboard, i.e. last 6 hours, last 7 days, etc | -| **timepicker** | timepicker metadata, see timepicker section for details | -| **templating** | templating metadata, see templating section for details | -| **annotations** | annotations metadata, see annotations section for details | +| **rows** | row metadata, see [rows section](/dashboard/#rows) for details | +| **time** | time range for dashboard, i.e. last 6 hours, last 7 days, etc | +| **timepicker** | timepicker metadata, see [timepicker section](/dashboard/#timepicker) for details | +| **templating** | templating metadata, see [templating section](/dashboard/#templating) for details | +| **annotations** | annotations metadata, see [annotations section](/dashboard/#annotations) for details | | **schemaVersion** | TODO | | **version** | TODO | | **links** | TODO | + +### rows + +`rows` field represents an array of JSON object representing each row in a dashboard, such as shown below: + +``` + "rows": [ + { + "collapse": false, + "editable": true, + "height": "200px", + "panels": [], + "title": "New row" + }, + { + "collapse": true, + "editable": true, + "height": "300px", + "panels": [], + "title": "New row" + } + ] +``` + +Usage of the fields is explained below: + +| Name | Usage | +| ---- | ----- | +| **collapse** | whether row is collapsed or not | +| **editable** | whether a row is editable or not | +| **height** | height of the row in pixels | +| **panels** | panels metadata, see [panels section](/dashboard/#panels) for details | +| **title** | title of row | + +#### panels + +TODO + +### timepicker + +TODO + +### templating + +TODO + +### annotations + +TODO From e8c9b0806abb0ea84e3223d6a87d53f1c9171352 Mon Sep 17 00:00:00 2001 From: Utkarsh Bhatnagar Date: Mon, 2 Nov 2015 10:15:40 -0800 Subject: [PATCH 6/8] Added templating, timepicker, panel docs --- docs/sources/reference/dashboard.md | 305 +++++++++++++++++++++++++++- 1 file changed, 301 insertions(+), 4 deletions(-) diff --git a/docs/sources/reference/dashboard.md b/docs/sources/reference/dashboard.md index cdef0c75119..1a289208e3a 100644 --- a/docs/sources/reference/dashboard.md +++ b/docs/sources/reference/dashboard.md @@ -77,7 +77,7 @@ Each field in the dashboard JSON is explained below with its usage: ### rows -`rows` field represents an array of JSON object representing each row in a dashboard, such as shown below: +`rows` field consists of an array of JSON object representing each row in a dashboard, such as shown below: ``` "rows": [ @@ -110,15 +110,312 @@ Usage of the fields is explained below: #### panels -TODO +Panels are the building blocks a dashboard. It consists of datasource queries, type of graphs, aliases, etc. Panel JSON consists of an array of JSON objects, each representing a different panel in a row. Most of the fields are common for all panels but some fields depends on the panel type. Following is an example of panel JSON representing a `graph` panel type: + +``` +"panels": [ + { + "aliasColors": {}, + "bars": false, + "datasource": null, + "editable": true, + "error": false, + "fill": 0, + "grid": { + "leftLogBase": 1, + "leftMax": null, + "leftMin": null, + "rightLogBase": 1, + "rightMax": null, + "rightMin": null, + "threshold1": null, + "threshold1Color": "rgba(216, 200, 27, 0.27)", + "threshold2": null, + "threshold2Color": "rgba(234, 112, 112, 0.22)" + }, + "id": 1, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "links": [], + "nullPointMode": "connected", + "percentage": false, + "pointradius": 5, + "points": false, + "renderer": "flot", + "seriesOverrides": [], + "span": 4, + "stack": false, + "steppedLine": false, + "targets": [ + { + "aggregator": "max", + "alias": "$tag_instance_id", + "currentTagKey": "", + "currentTagValue": "", + "downsampleAggregator": "avg", + "downsampleInterval": "", + "errors": {}, + "metric": "memory.percent-used", + "refId": "A", + "shouldComputeRate": false, + "tags": { + "app": "$app", + "env": "stage", + "instance_id": "*" + } + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Memory Utilization", + "tooltip": { + "shared": true, + "value_type": "cumulative" + }, + "type": "graph", + "x-axis": true, + "y-axis": true, + "y_formats": [ + "percent", + "short" + ] + }, + { + "aliasColors": {}, + "bars": false, + "datasource": null, + "editable": true, + "error": false, + "fill": 0, + "grid": { + "leftLogBase": 1, + "leftMax": null, + "leftMin": null, + "rightLogBase": 1, + "rightMax": null, + "rightMin": null, + "threshold1": null, + "threshold1Color": "rgba(216, 200, 27, 0.27)", + "threshold2": null, + "threshold2Color": "rgba(234, 112, 112, 0.22)" + }, + "id": 2, + "legend": { + "avg": false, + "current": false, + "max": false, + "min": false, + "show": true, + "total": false, + "values": false + }, + "lines": true, + "linewidth": 1, + "links": [], + "nullPointMode": "connected", + "percentage": false, + "pointradius": 5, + "points": false, + "renderer": "flot", + "seriesOverrides": [], + "span": 4, + "stack": false, + "steppedLine": false, + "targets": [ + { + "aggregator": "avg", + "alias": "$tag_instance_id", + "currentTagKey": "", + "currentTagValue": "", + "downsampleAggregator": "avg", + "downsampleInterval": "", + "errors": {}, + "metric": "memory.percent-cached", + "refId": "A", + "shouldComputeRate": false, + "tags": { + "app": "$app", + "env": "prod", + "instance_id": "*" + } + } + ], + "timeFrom": null, + "timeShift": null, + "title": "Memory Cached", + "tooltip": { + "shared": true, + "value_type": "cumulative" + }, + "type": "graph", + "x-axis": true, + "y-axis": true, + "y_formats": [ + "short", + "short" + ] + }, +``` + +Usage of each field is explained below: + +| Name | Usage | +| ---- | ----- | +| TODO | TODO | ### timepicker -TODO +Description: TODO + +``` +"timepicker": { + "collapse": false, + "enable": true, + "notice": false, + "now": true, + "refresh_intervals": [ + "5s", + "10s", + "30s", + "1m", + "5m", + "15m", + "30m", + "1h", + "2h", + "1d" + ], + "status": "Stable", + "time_options": [ + "5m", + "15m", + "1h", + "3h", + "6h", + "12h", + "24h", + "2d", + "3d", + "4d", + "7d", + "30d" + ], + "type": "timepicker" + } +``` + +Usage of the fields is explained below: + +| Name | Usage | +| ---- | ----- | +| **collapse** | whether timepicker is collapsed or not | +| **enable** | whether timepicker is enabled or not | +| **notice** | TODO | +| **now** | TODO | +| **refresh_intervals** | TODO | +| **status** | TODO | +| **time_options** | TODO | +| **type** | TODO | ### templating -TODO +`templating` fields contains array of template variables with their saved values along with some other metadata, for example: + +``` + "templating": { + "enable": true, + "list": [ + { + "allFormat": "wildcard", + "current": { + "tags": [], + "text": "prod", + "value": "prod" + }, + "datasource": null, + "includeAll": true, + "name": "env", + "options": [ + { + "selected": false, + "text": "All", + "value": "*" + }, + { + "selected": false, + "text": "stage", + "value": "stage" + }, + { + "selected": false, + "text": "test", + "value": "test" + } + ], + "query": "tag_values(cpu.utilization.average,env)", + "refresh": false, + "refresh_on_load": false, + "type": "query" + }, + { + "allFormat": "wildcard", + "current": { + "text": "apache", + "value": "apache" + }, + "datasource": null, + "includeAll": false, + "multi": false, + "multiFormat": "glob", + "name": "app", + "options": [ + { + "selected": true, + "text": "tomcat", + "value": "tomcat" + }, + { + "selected": false, + "text": "cassandra", + "value": "cassandra" + } + ], + "query": "tag_values(cpu.utilization.average,app)", + "refresh_on_load": false, + "regex": "", + "type": "query" + } + ] + } +``` + +Usage of the above mentioned fields in the templating section is explained below: + +| Name | Usage | +| ---- | ----- | +| **enable** | whether templating is enabled or not | +| **list** | an array of objects representing, each representing one template variable | +| **allFormat** | format to use while fetching all values from datasource, eg: `wildcard`, `glob`, `regex`, `pipe`, etc. | +| **current** | shows current selected variable text/value on the dashboard | +| **datasource** | shows datasource for the variables | +| **includeAll** | whether all value option is available or not | +| **multi** | whether multiple values can be selected or not from variable value list | +| **multiFormat** | format to use while fetching timeseries from datasource | +| **name** | name of variable | +| **options** | array of variable text/value pairs available for selection on dashboard | +| **query** | datasource query used to fetch values for a variable | +| **refresh_on_load** | TODO | +| **regex** | TODO | +| **type** | type of variable, i.e. `custom`, `query` or `interval` | ### annotations From f14ef22bb6be96ed2cb1ccc0ec52a903c1e44a82 Mon Sep 17 00:00:00 2001 From: Utkarsh Bhatnagar Date: Mon, 2 Nov 2015 10:25:33 -0800 Subject: [PATCH 7/8] Fixed doc links --- docs/sources/reference/dashboard.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/sources/reference/dashboard.md b/docs/sources/reference/dashboard.md index 1a289208e3a..60064690fb2 100644 --- a/docs/sources/reference/dashboard.md +++ b/docs/sources/reference/dashboard.md @@ -66,11 +66,11 @@ Each field in the dashboard JSON is explained below with its usage: | **editable** | whether a dashboard is editable or not | | **hideControls** | whether row controls on the left in green are hidden or not | | **sharedCrosshair** | TODO | -| **rows** | row metadata, see [rows section](/dashboard/#rows) for details | +| **rows** | row metadata, see [rows section](/dashboard.md/#rows) for details | | **time** | time range for dashboard, i.e. last 6 hours, last 7 days, etc | -| **timepicker** | timepicker metadata, see [timepicker section](/dashboard/#timepicker) for details | -| **templating** | templating metadata, see [templating section](/dashboard/#templating) for details | -| **annotations** | annotations metadata, see [annotations section](/dashboard/#annotations) for details | +| **timepicker** | timepicker metadata, see [timepicker section](/dashboard.md/#timepicker) for details | +| **templating** | templating metadata, see [templating section](/dashboard.md/#templating) for details | +| **annotations** | annotations metadata, see [annotations section](/dashboard.md/#annotations) for details | | **schemaVersion** | TODO | | **version** | TODO | | **links** | TODO | @@ -105,7 +105,7 @@ Usage of the fields is explained below: | **collapse** | whether row is collapsed or not | | **editable** | whether a row is editable or not | | **height** | height of the row in pixels | -| **panels** | panels metadata, see [panels section](/dashboard/#panels) for details | +| **panels** | panels metadata, see [panels section](/dashboard.md/#panels) for details | | **title** | title of row | #### panels From 74b10a42ee66f3fa682ea139be8f560725b2f871 Mon Sep 17 00:00:00 2001 From: Utkarsh Bhatnagar Date: Mon, 2 Nov 2015 10:29:42 -0800 Subject: [PATCH 8/8] Fixed broken links in the doc page --- docs/sources/reference/dashboard.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/sources/reference/dashboard.md b/docs/sources/reference/dashboard.md index 60064690fb2..5b18b9e26ad 100644 --- a/docs/sources/reference/dashboard.md +++ b/docs/sources/reference/dashboard.md @@ -66,11 +66,11 @@ Each field in the dashboard JSON is explained below with its usage: | **editable** | whether a dashboard is editable or not | | **hideControls** | whether row controls on the left in green are hidden or not | | **sharedCrosshair** | TODO | -| **rows** | row metadata, see [rows section](/dashboard.md/#rows) for details | +| **rows** | row metadata, see [rows section](/docs/sources/reference/dashboard.md/#rows) for details | | **time** | time range for dashboard, i.e. last 6 hours, last 7 days, etc | -| **timepicker** | timepicker metadata, see [timepicker section](/dashboard.md/#timepicker) for details | -| **templating** | templating metadata, see [templating section](/dashboard.md/#templating) for details | -| **annotations** | annotations metadata, see [annotations section](/dashboard.md/#annotations) for details | +| **timepicker** | timepicker metadata, see [timepicker section](/docs/sources/reference/dashboard.md/#timepicker) for details | +| **templating** | templating metadata, see [templating section](/docs/sources/reference/dashboard.md/#templating) for details | +| **annotations** | annotations metadata, see [annotations section](/docs/sources/reference/dashboard.md/#annotations) for details | | **schemaVersion** | TODO | | **version** | TODO | | **links** | TODO | @@ -105,7 +105,7 @@ Usage of the fields is explained below: | **collapse** | whether row is collapsed or not | | **editable** | whether a row is editable or not | | **height** | height of the row in pixels | -| **panels** | panels metadata, see [panels section](/dashboard.md/#panels) for details | +| **panels** | panels metadata, see [panels section](/docs/sources/reference/dashboard.md/#panels) for details | | **title** | title of row | #### panels