Skip to content

API Docs

Generated API documentation from JSDoc style comments.

alertCondition.new

Returns a new condition of alert of graph panel. Currently the only condition type that exists is a Query condition that allows to specify a query letter, time range and an aggregation function.

@params

  • evaluatorParams: Value of threshold
  • evaluatorType: Type of threshold
  • operatorType: Operator between conditions
  • queryRefId: The letter defines what query to execute from the Metrics tab
  • queryTimeEnd: End of time range
  • queryTimeStart: Begging of time range
  • reducerParams: Params of an aggregation function
  • reducerType: Name of an aggregation function

@return A json that represents a condition of alert

alertlist.new

Creates an Alert list panel

@params

  • datasource: (optional)
  • description: (optional)
  • limit: (default 10) Sets the maximum number of alerts to list.
  • onlyAlertsOnDashboard: (optional) Shows alerts only from the dashboard the alert list is in
  • show: (default 'current') Whether the panel should display the current alert state or recent alert state changes.
  • sortOrder: (default '1') '1': alerting, '2': no_data, '3': pending, '4': ok, '5': paused
  • span: (optional)
  • stateFilter: (optional)
  • title: (default '')
  • transparent: (optional) Whether to display the panel without a background

annotation.datasource

barGaugePanel.new

Create a bar gauge panel,

@params

  • datasource: (optional) Panel datasource.
  • description: (optional) Panel description.
  • thresholds: (optional) An array of threashold values.
  • title: Panel title.
  • unit: (optional) The unit of the data.

@methods

  • addTarget(target): Adds a target object.
  • addTargets(targets): Adds an array of targets.

cloudmonitoring.target

Creates a Google Cloud Monitoring target

@params

  • alias: (optional)
  • crossSeriesReducer: (default 'REDUCE_MAX')
  • filters: (optional)
  • groupBys: (optional)
  • metric:
  • metricKind: (default 'CUMULATIVE')
  • perSeriesAligner: (default 'ALIGN_DELTA')
  • period: (default: 'cloud-monitoring-auto')
  • project:
  • unit: (optional)
  • valueType: (default 'INT64')

@return Panel target

cloudwatch.target

Creates a CloudWatch target

@params

  • alias: (optional)
  • datasource: (optional)
  • dimensions: (optional)
  • expression: (optional)
  • hide: (optional)
  • highResolution: (default: false)
  • id: (optional)
  • metric:
  • namespace:
  • period: (default: 'auto')
  • region:
  • statistic: (default: 'Average')

@return Panel target

dashboard.new

Creates a dashboard

@params

  • description: (optional)
  • editable: (default: false) Whether the dashboard is editable via Grafana UI.
  • graphTooltip: (default: 'default') 'default' : no shared crosshair or tooltip (0), 'shared_crosshair': shared crosshair (1), 'shared_tooltip': shared crosshair AND shared tooltip (2)
  • hideControls: (default: false)
  • refresh: (default: '') Auto-refresh interval, e.g. '30s'
  • schemaVersion: (default: 14) Version of the Grafana JSON schema, incremented each time an update brings changes. 26 for Grafana 7.1.5, 22 for Grafana 6.7.4, 16 for Grafana 5.4.5, 14 for Grafana 4.6.3. etc.
  • style: (default: 'dark') Theme of dashboard, 'dark' or 'light'
  • tags: (optional) Array of tags associated to the dashboard, e.g.['tag1','tag2']
  • time_from: (default: 'now-6h')
  • time_to: (default: 'now')
  • timepicker: (optional) See timepicker API
  • timezone: (default: 'browser') Timezone of the dashboard, 'utc' or 'browser'
  • title: The title of the dashboard
  • uid: (default: '') Unique dashboard identifier as a string (8-40), that can be chosen by users. Used to identify a dashboard to update when using Grafana REST API.

@methods

  • addAnnotation(annotation): Add an annotation
  • addInput(name,: label, type, pluginId, pluginName, description, value)
  • addLink(link): Adds a dashboard link
  • addLinks(dashboardLink): Adds an array of dashboard links
  • addPanel(panel,gridPos): Appends a panel, with an optional grid position in grid coordinates, e.g. gridPos={'x':0, 'y':0, 'w':12, 'h': 9}
  • addPanels(panels): Appends an array of panels
  • addRequired(type,: name, id, version)
  • addRow(row): Adds a row. This is the legacy row concept from Grafana < 5, when rows were needed for layout. Rows should now be added via addPanel.
  • addTemplate(template): Add a template variable
  • addTemplates(templates): Adds an array of template variables

dashlist.new

Creates a dashlist panel. It requires the dashlist panel plugin in grafana, which is built-in.

@params

  • description: (optional) Description of the panel
  • headings: (default true) Chosen list selection(starred, recently Viewed, search) is shown as a heading
  • limit: (default 10) Set maximum items in a list
  • query: (optional) Query to search by
  • recent: (default true) Displays recently viewed dashboards
  • search: (default false) Description of the panel
  • starred: (default false) Displays starred dashboards
  • tags: (optional) Array of tag(s) to search by
  • title: The title of the dashlist panel.

@return A json that represents a dashlist panel

elasticsearch.target

Creates an Elasticsearch target

@params

  • alias: (optional)
  • bucketAggs: (optional)
  • datasource: (optional)
  • id: (optional)
  • metrics: (optional)
  • query:
  • timeField:

gaugePanel.new

Creates a gauge panel.

@params

  • allValues: (default false) Show all values instead of reducing to one.
  • datasource: (optional) Panel datasource.
  • decimals: Number of decimal places to show.
  • description: (optional) Panel description.
  • displayName: Change the field or series name.
  • fields: (default '') Fields that should be included in the panel.
  • max: (optional) Leave empty to calculate based on all values.
  • min: (optional) Leave empty to calculate based on all values.
  • noValue: (optional) What to show when there is no value.
  • pluginVersion: (default '7') Plugin version the panel should be modeled for. This has been tested with the default, '7', and '6.7'.
  • reducerFunction: (default 'mean') Function to use to reduce values to when using single value.
  • repeat: (optional) Name of variable that should be used to repeat this panel.
  • repeatDirection: (default 'h') 'h' for horizontal or 'v' for vertical.
  • repeatMaxPerRow: (optional) Maximum panels per row in repeat mode.
  • showThresholdLabels: (default false) Render the threshold values around the gauge bar.
  • showThresholdMarkers: (default true) Render the thresholds as an outer bar.
  • thresholdsMode: (default 'absolute') 'absolute' or 'percentage'.
  • timeFrom: (optional)
  • title: Panel title.
  • transparent: (default false) Whether to display the panel without a background.
  • unit: (default 'percent') Panel unit field option.
  • valueLimit: (optional) Limit of values in all values mode.

@methods

  • addDataLink(link): Adds a data link.
  • addDataLinks(links): Adds an array of data links.
  • addLink(link): Adds a panel link. Argument format: { title: 'Link Title', url: 'https://...', targetBlank: true }.
  • addLinks(links): Adds an array of links.
  • addMapping(mapping): Adds a value mapping.
  • addMappings(mappings): Adds an array of value mappings.
  • addTarget(target): Adds a target object.
  • addTargets(targets): Adds an array of targets.
  • addThreshold(step): Adds a threshold step. Argument format: { color: 'green', value: 0 }.
  • addThresholds(steps): Adds an array of threshold steps.

grafana

graphPanel.new

Creates a graph panel. It requires the graph panel plugin in grafana, which is built-in.

@params

  • aliasColors: (optional) Define color mappings for graphs
  • bars: (default false) Display bars
  • dashes: (default false) Display line as dashes
  • datasource: (optional) Datasource
  • decimals: (optional) Override automatic decimal precision for legend and tooltip. If null, not added to the json output.
  • decimalsY1: (optional) Override automatic decimal precision for the first Y axis. If null, use decimals parameter.
  • decimalsY2: (optional) Override automatic decimal precision for the second Y axis. If null, use decimals parameter.
  • description: (optional) The description of the panel
  • fill: (default 1) , integer from 0 to 10
  • fillGradient: (default 0) , integer from 0 to 10
  • format: (default short) Unit of the Y axes
  • formatY1: (optional) Unit of the first Y axis
  • formatY2: (optional) Unit of the second Y axis
  • interval: (defaut: null) A lower limit for the interval.
  • labelY1: (optional) Label of the first Y axis
  • labelY2: (optional) Label of the second Y axis
  • legend_alignAsTable: (default false) Show legend as table
  • legend_avg: (default false) Show average in legend
  • legend_current: (default false) Show current in legend
  • legend_max: (default false) Show max in legend
  • legend_min: (default false) Show min in legend
  • legend_rightSide: (default false) Show legend to the right
  • legend_show: (default true) Show legend
  • legend_sideWidth: (optional) Legend width
  • legend_sort: (optional) Sort order of legend
  • legend_sortDesc: (optional) Sort legend descending
  • legend_total: (default false) Show total in legend
  • legend_values: (default false) Show values in legend
  • lines: (default true) Display lines
  • linewidth: (default 1) Line Width, integer from 0 to 10
  • logBase1Y: (default 1) Value of logarithm base of the first Y axis
  • logBase2Y: (default 1) Value of logarithm base of the second Y axis
  • max: (optional) Max of the Y axes
  • maxDataPoints: (optional) If the data source supports it, sets the maximum number of data points for each series returned.
  • min: (optional) Min of the Y axes
  • min_span: (optional) Min span
  • percentage: (defaut: false) show as percentages
  • pointradius: (default 5) Radius of the points, allowed values are 0.5 or [1 ... 10] with step 1
  • points: (default false) Display points
  • repeat: (optional) Name of variable that should be used to repeat this panel.
  • repeatDirection: (default 'h') 'h' for horizontal or 'v' for vertical.
  • shared_tooltip: (default true) Allow to group or spit tooltips on mouseover within a chart
  • span: (optional) Width of the panel
  • stack: (default false) Whether to stack values
  • staircase: (default false) Display line as staircase
  • thresholds: (optional) An array of graph thresholds
  • title: The title of the graph panel.
  • transparent: (default false) Whether to display the panel without a background.
  • value_type: (default 'individual') Type of tooltip value
  • x_axis_buckets: (optional) Restricts the x axis to this amount of buckets
  • x_axis_max: (optional) Restricts the x axis to display up to this value if supplied
  • x_axis_min: (optional) Restricts the x axis to display from this value if supplied
  • x_axis_mode: (default 'time') X axis mode, one of [time, series, histogram]
  • x_axis_values: (default 'total') Chosen value of series, one of [avg, min, max, total, count]

@methods

  • addAlert(alert): Adds an alert
  • addLink(link): Adds a panel link
  • addLinks(links): Adds an array of links.
  • addSeriesOverride(override):
  • addTarget(target): Adds a target object.
  • addTargets(targets): Adds an array of targets.
  • addYaxis(format,min,max,label,show,logBase,decimals): Adds a Y axis to the graph

graphite.target

Creates a Graphite target

@params

  • datasource: (optional) Datasource.
  • hide: (default false) Disable query on graph.
  • target: Graphite Query. Nested queries are possible by adding the query reference (refId).
  • targetFull: (optional) Expanding the @target. Used in nested queries.
  • textEditor: (default false) Enable raw query mode.

@return Panel target

heatmapPanel.new

Creates a heatmap panel. Requires the heatmap panel plugin in Grafana, which is built-in.

@params

  • cards_cardPadding: (optional) How much padding to put between bucket cards
  • cards_cardRound: (optional) How much rounding should be applied to the bucket card shape
  • color_cardColor: (default '#b4ff00') Hex value of color used when color_colorScheme is 'opacity'
  • color_colorScale: (default 'sqrt') How to scale the color range, 'linear' or 'sqrt'
  • color_colorScheme: (default 'interpolateOranges') TODO: document
  • color_exponent: (default 0.5) TODO: document
  • color_max: (optional) The value for the end of the color range
  • color_min: (optional) The value for the beginning of the color range
  • color_mode: (default 'spectrum') How to display difference in frequency with color
  • dataFormat: (default 'timeseries') How to format the data
  • datasource: (optional) Datasource
  • description: (optional) Description of panel
  • hideZeroBuckets: (default false) Whether or not to hide empty buckets, default is false
  • highlightCards: (default true) TODO: document
  • legend_show: (default false) Show legend
  • maxDataPoints: (optional) The maximum data points per series. Used directly by some data sources and used in calculation of auto interval. With streaming data this value is used for the rolling buffer.
  • minSpan: (optional) Minimum span of the panel when repeated on a template variable
  • min_span: (optional) Min span
  • repeat: (optional) Variable used to repeat the heatmap panel
  • repeatDirection: (optional) Which direction to repeat the panel, 'h' for horizontal and 'v' for vertically
  • span: (optional) Width of the panel
  • title: The title of the heatmap panel
  • tooltipDecimals: (optional) The number of decimal places to display in the tooltip
  • tooltip_show: (default true) Whether or not to display a tooltip when hovering over the heatmap
  • tooltip_showHistogram: (default false) Whether or not to display a histogram in the tooltip
  • xAxis_show: (default true) Whether or not to show the X axis, default true
  • xBucketNumber: (optional) Number of buckets for the X axis
  • xBucketSize: (optional) Size of X axis buckets. Number or interval(10s, 15h, etc.) Has priority over xBucketNumber
  • yAxis_decimals: (optional) Override automatic decimal precision for the Y axis
  • yAxis_format: (default 'short') Unit of the Y axis
  • yAxis_logBase: (default 1) Only if dataFormat is 'timeseries'
  • yAxis_max: (optional) Only if dataFormat is 'timeseries', max of the Y axis
  • yAxis_min: (optional) Only if dataFormat is 'timeseries', min of the Y axis
  • yAxis_show: (default true) Whether or not to show the Y axis
  • yAxis_splitFactor: (optional) TODO: document
  • yBucketBound: (default 'auto') Which bound ('lower' or 'upper') of the bucket to use
  • yBucketNumber: (optional) Number of buckets for the Y axis
  • yBucketSize: (optional) Size of Y axis buckets. Has priority over yBucketNumber

@methods

  • addTarget(target): Adds a target object.
  • addTargets(targets): Adds an array of targets.

influxdb.target

Creates an InfluxDB target

@params

  • alias: (optional) 'Alias By' pattern
  • datasource: (optional) Datasource
  • fill: (default: 'none') 'Group by' missing values fill mode (works only with 'Group by time()')
  • group_tags: (optional) 'Group by' tags list
  • group_time: (default: '$__interval') 'Group by' time condition (if set to null, do not groups by time)
  • hide: (optional) Disable query on graph
  • measurement: (optional) Tagged query 'From' measurement
  • policy: (default: 'default') Tagged query 'From' policy
  • query: Raw InfluxQL statement
  • rawQuery: (optional) Enable/disable raw query mode
  • resultFormat: (default: 'time_series') Format results as 'Time series' or 'Table'

@return Panel target

link.dashboards

Creates links to navigate to other dashboards.

@params

  • asDropdown: (default: true) Whether to use a dropdown (with an optional title). If false, displays the dashboard links side by side across the top of dashboard.
  • icon: (default: 'external link') Icon displayed with the link.
  • includeVars: (default: false) Whether to include template variables currently used as query parameters in the link. Any matching templates in the linked dashboard are set to the values from the link
  • keepTime: (default: false) Whether to include the current dashboard time range in the link (e.g. from=now-3h&to=now)
  • tags: Limits the linked dashboards to only the ones with the corresponding tags. Otherwise, Grafana includes links to all other dashboards.
  • targetBlank: (default: false) Whether the link will open in a new window.
  • title: Human-readable label for the link.
  • type: (default: 'dashboards')
  • url: (default: '') URL of the link

logPanel.new

Creates a log panel. It requires the log panel plugin in grafana, which is built-in.

@params

  • datasource: (optional) Datasource
  • span: (optional) Width of the panel
  • title: (default '') The title of the log panel.

@methods

  • addTarget(target): Adds a target object
  • addTargets(targets): Adds an array of targets

loki.target

Creates a Loki target

@params

  • expr:
  • hide: (optional) Disable query on graph.
  • legendFormat: (optional) Defines the legend. Defaults to ''.

pieChartPanel.new

Creates a pie chart panel. It requires the pie chart panel plugin in grafana, which needs to be explicitly installed.

@params

  • aliasColors: (optional) Define color mappings
  • datasource: (optional) Datasource
  • description: (default '') Description of the panel
  • legendType: (default 'Right side') Type of legend (one of 'Right side', 'Under graph' or 'On graph')
  • maxPerRow: (optional) Number of panels to display when repeated. Used in combination with repeat.
  • min_span: (optional) Min span
  • pieType: (default 'pie') Type of pie chart (one of pie or donut)
  • repeat: (optional) Variable used to repeat the pie chart
  • repeatDirection: (optional) Which direction to repeat the panel, 'h' for horizontal and 'v' for vertical
  • showLegend: (default true) Show legend
  • showLegendPercentage: (default true) Show percentage values in the legend
  • span: (optional) Width of the panel
  • title: The title of the pie chart panel.
  • valueName: (default `'current') Type of tooltip value

@methods

  • addTarget(target): Adds a target object.

@return A json that represents a pie chart panel

pluginlist.new

Returns a new pluginlist panel that can be added in a row. It requires the pluginlist panel plugin in grafana, which is built-in.

@params

  • description: (optional) Description of the panel
  • limit: (optional) Set maximum items in a list
  • title: The title of the pluginlist panel.

@return A json that represents a pluginlist panel

prometheus.target

Creates a Prometheus target to be added to panels.

@params

  • datasource: (optional) Name of the Prometheus datasource. Leave by default otherwise.
  • expr: PromQL query to be exercised against Prometheus. Checkout Prometheus documentation.
  • format: (default 'time_series') Switch between 'table', 'time_series' or 'heatmap'. Table will only work in the Table panel. Heatmap is suitable for displaying metrics of the Histogram type on a Heatmap panel. Under the hood, it converts cumulative histograms to regular ones and sorts series by the bucket bound.
  • hide: (optional) Set to true to hide the target from the panel.
  • instant: (optional) Perform an "instant" query, to return only the latest value that Prometheus has scraped for the requested time series. Instant queries return results much faster than normal range queries. Use them to look up label sets.
  • interval: (optional) Time span used to aggregate or group data points by time. By default Grafana uses an automatic interval calculated based on the width of the graph.
  • intervalFactor: (default 2)
  • legendFormat: (default '') Controls the name of the time series, using name or pattern. For example {{hostname}} is replaced with the label value for the label hostname.

@return A Prometheus target to be added to panels.

row.new

Creates a row. Rows are logical dividers within a dashboard and used to group panels together.

@params

  • collapse: (default false) The initial state of the row when opening the dashboard. Panels in a collapsed row are not load until the row is expanded.
  • repeat: (optional) Name of variable that should be used to repeat this row. It is recommended to use the variable in the row title as well.
  • showTitle: (default true if title is set) Whether to show the row title
  • title: The title of the row.

@methods

  • addPanel(panel,gridPos): Appends a nested panel, with an optional grid position in grid coordinates, e.g. gridPos={'x':0, 'y':0, 'w':12, 'h': 9}
  • addPanels(panels): Appends an array of nested panels

singlestat.new

Creates a singlestat panel.

@params

  • colorBackground: (default false)
  • colorValue: (default false)
  • colors: (default ['#299c46','rgba(237, 129, 40, 0.89)','#d44a3a'])
  • datasource: (optional)
  • decimals: (optional)
  • description: (default '')
  • format: (default 'none') Unit
  • gaugeMaxValue: (default 100)
  • gaugeMinValue: (default 0)
  • gaugeShow: (default false)
  • gaugeThresholdLabels: (default false)
  • gaugeThresholdMarkers: (default true)
  • height: (optional)
  • interval: (optional)
  • links: (optional)
  • mappingType: (default 1)
  • maxDataPoints: (default 100)
  • maxPerRow: (optional)
  • min_span: (optional)
  • postfix: (default '')
  • postfixFontSize: (default '50%')
  • prefix: (default '')
  • prefixFontSize: (default '50%')
  • rangeMaps: (default {value: 'null',op: '=',text: 'N/A'})
  • repeat: (optional)
  • repeatDirection: (optional)
  • span: (optional)
  • sparklineFillColor: (default 'rgba(31, 118, 189, 0.18)')
  • sparklineFull: (default false)
  • sparklineLineColor: (default 'rgb(31, 120, 193)')
  • sparklineShow: (default false)
  • tableColumn: (default '')
  • thresholds: (default '')
  • timeFrom: (optional)
  • title: The title of the singlestat panel.
  • transparent: (optional)
  • valueFontSize: (default '80%')
  • valueMaps: (default {value: 'null',op: '=',text: 'N/A'})
  • valueName: (default 'avg')

@methods

  • addTarget(target): Adds a target object.

sql.target

Creates an SQL target.

@params

  • alias: (optional)
  • datasource: (optional)
  • format: (default 'time_series')
  • rawSql: The SQL query

statPanel.new

Creates a stat panel.

@params

  • allValues: (default false) Show all values instead of reducing to one.
  • colorMode: (default 'value') 'value' or 'background'.
  • datasource: (optional) Panel datasource.
  • decimals: (optional) Number of decimal places to show.
  • description: (optional) Panel description.
  • displayName: (optional) Change the field or series name.
  • fields: (default '') Fields that should be included in the panel.
  • graphMode: (default 'area') 'none' or 'area' to enable sparkline mode.
  • justifyMode: (default 'auto') 'auto' or 'center'.
  • max: (optional) Leave empty to calculate based on all values.
  • maxPerRow: (optional) Maximum panels per row in repeat mode.
  • min: (optional) Leave empty to calculate based on all values.
  • noValue: (optional) What to show when there is no value.
  • orientation: (default 'auto') Stacking direction in case of multiple series or fields.
  • pluginVersion: (default '7') Plugin version the panel should be modeled for. This has been tested with the default, '7', and '6.7'.
  • reducerFunction: (default 'mean') Function to use to reduce values to when using single value.
  • repeat: (optional) Name of variable that should be used to repeat this panel.
  • repeatDirection: (default 'h') 'h' for horizontal or 'v' for vertical.
  • textMode: (default 'auto') Control if name and value is displayed or just name.
  • thresholdsMode: (default 'absolute') 'absolute' or 'percentage'.
  • timeFrom: (optional) Override the relative time range.
  • title: Panel title.
  • transparent: (default false) Whether to display the panel without a background.
  • unit: (default 'none') Panel unit field option.
  • valueLimit: (optional) Limit of values in all values mode.

@methods

  • addDataLink(link): Adds a data link.
  • addDataLinks(links): Adds an array of data links.
  • addLink(link): Adds a panel link. Argument format: { title: 'Link Title', url: 'https://...', targetBlank: true }.
  • addLinks(links): Adds an array of links.
  • addMapping(mapping): Adds a value mapping.
  • addMappings(mappings): Adds an array of value mappings.
  • addTarget(target): Adds a target object.
  • addTargets(targets): Adds an array of targets.
  • addThreshold(step): Adds a threshold step. Argument format: { color: 'green', value: 0 }.
  • addThresholds(steps): Adds an array of threshold steps.

table.new

Creates a table panel that can be added in a row. It requires the table panel plugin in grafana, which is built-in.

@params

  • columns: (optional) Array of columns for the panel
  • datasource: (optional) Datasource
  • description: (optional) Description of the panel
  • height: (optional) Height of the panel
  • links: (optional) Array of links for the panel.
  • min_span: (optional) Min span
  • sort: (optional) Sorting instruction for the panel
  • span: (optional) Width of the panel
  • styles: (optional) Array of styles for the panel
  • title: The title of the graph panel.
  • transform: (optional) Allow table manipulation to present data as desired
  • transparent: (default: 'false') Whether to display the panel without a background

@methods

  • addColumn(field,: style) Adds a column
  • addLink(link): Adds a link
  • addTarget(target): Adds a target object
  • addTargets(targets): Adds an array of targets
  • addTransformation(transformation): Adds a transformation object
  • addTransformations(transformations): Adds an array of transformations
  • hideColumn(field): Hides a column

@return A json that represents a table panel

template.new

Creates a template that can be added to a dashboard.

@params

  • allValues: (optional) Formatting for multi-value variables
  • current: (default null) Can be null, 'all' for all, or any other custom text value.
  • datasource: Template datasource
  • hide: (default '') '': the variable dropdown displays the variable Name or Label value. 'label': the variable dropdown only displays the selected variable value and a down arrow. Any other value: no variable dropdown is displayed on the dashboard.
  • includeAll: (default false) Whether all value option is available or not.
  • label: (optional) Display name of the variable dropdown. If null, then the dropdown label will be the variable name.
  • multi: (default false) Whether multiple values can be selected or not from variable value list.
  • name: Name of variable.
  • query: Query expression for the datasource.
  • refresh: (default 'never') 'never': variables queries are cached and values are not updated. This is fine if the values never change, but problematic if they are dynamic and change a lot. 'load': Queries the data source every time the dashboard loads. This slows down dashboard loading, because the variable query needs to be completed before dashboard can be initialized. 'time': Queries the data source when the dashboard time range changes. Only use this option if your variable options query contains a time range filter or is dependent on the dashboard time range.
  • regex: (default '') Regex expression to filter or capture specific parts of the names returned by your data source query. To see examples, refer to Filter variables with regex.
  • sort: (default 0) 0: Without Sort, 1: Alphabetical (asc), 2: Alphabetical (desc), 3: Numerical (asc), 4: Numerical (desc).
  • tagValuesQuery: (default '') Group values into selectable tags

@return A template

template.interval

Use an interval variable to represent time spans such as '1m', '1h', '1d'. You can think of them as a dashboard-wide "group by time" command. Interval variables change how the data is grouped in the visualization. You can also use the Auto Option to return a set number of data points per time span. You can use an interval variable as a parameter to group by time (for InfluxDB), date histogram interval (for Elasticsearch), or as a summarize function parameter (for Graphite).

@params

  • auto_count: (default 300) Valid only if 'auto' is defined in query. Number of times the current time range will be divided to calculate the value, similar to the Max data points query option. For example, if the current visible time range is 30 minutes, then the auto interval groups the data into 30 one-minute increments. The default value is 30 steps.
  • auto_min: (default '10s') Valid only if 'auto' is defined in query. The minimum threshold below which the step count intervals will not divide the time. To continue the 30 minute example, if the minimum interval is set to '2m', then Grafana would group the data into 15 two-minute increments.
  • current: Currently selected interval. Must be one of the values in the query. 'auto' is allowed if defined in the query.
  • hide: (default '') '': the variable dropdown displays the variable Name or Label value. 'label': the variable dropdown only displays the selected variable value and a down arrow. Any other value: no variable dropdown is displayed on the dashboard.
  • label: (optional) Display name of the variable dropdown. If null, then the dropdown label will be the variable name.
  • name: Variable name
  • query: Comma separated values without spacing of intervals available for selection. Add 'auto' in the query to turn on the Auto Option. Ex: 'auto,5m,10m,20m'.

@return A new interval variable for templating.

template.datasource

Data source variables allow you to quickly change the data source for an entire dashboard. They are useful if you have multiple instances of a data source, perhaps in different environments.

@params

  • current: Ex: 'Prometheus'.
  • hide: (default '') '': the variable dropdown displays the variable Name or Label value. 'label': the variable dropdown only displays the selected variable value and a down arrow. Any other value: no variable dropdown is displayed on the dashboard.
  • label: (optional) Display name of the variable dropdown. If null, then the dropdown label will be the variable name.
  • name: Data source variable name. Ex: 'PROMETHEUS_DS'.
  • query: Type of data source. Ex: 'prometheus'.
  • refresh: (default 'load') 'never': Variables queries are cached and values are not updated. This is fine if the values never change, but problematic if they are dynamic and change a lot. 'load': Queries the data source every time the dashboard loads. This slows down dashboard loading, because the variable query needs to be completed before dashboard can be initialized. 'time': Queries the data source when the dashboard time range changes. Only use this option if your variable options query contains a time range filter or is dependent on the dashboard time range.
  • regex: (default '') Regex filter for which data source instances to choose from in the variable value drop-down list. Leave this field empty to display all instances.

@return A data source variable.

template.custom

Use a custom variable for values that do not change.

This might be numbers, strings, or even other variables.

@params

  • allValues: (optional) Formatting for multi-value variables
  • current: Selected value
  • hide: (default '') '': the variable dropdown displays the variable Name or Label value. 'label': the variable dropdown only displays the selected variable value and a down arrow. Any other value: no variable dropdown is displayed on the dashboard.
  • includeAll: (default false) Whether all value option is available or not.
  • label: (default '') Display name of the variable dropdown. If you don’t enter a display name, then the dropdown label will be the variable name.
  • multi: (default false) Whether multiple values can be selected or not from variable value list.
  • name: Variable name
  • query: Comma separated without spacing list of selectable values.
  • refresh: (default 'never') 'never': Variables queries are cached and values are not updated. This is fine if the values never change, but problematic if they are dynamic and change a lot. 'load': Queries the data source every time the dashboard loads. This slows down dashboard loading, because the variable query needs to be completed before dashboard can be initialized. 'time': Queries the data source when the dashboard time range changes. Only use this option if your variable options query contains a time range filter or is dependent on the dashboard time range.
  • valuelabels: (default {}) Display names for values defined in query. For example, if query='new,old', then you may display them as follows valuelabels={new: 'nouveau', old: 'ancien'}.

@return A custom variable.

template.text

Text box variables display a free text input field with an optional default value. This is the most flexible variable, because you can enter any value. Use this type of variable if you have metrics with high cardinality or if you want to update multiple panels in a dashboard at the same time.

@params

  • label: (default '') Display name of the variable dropdown. If you don’t enter a display name, then the dropdown label will be the variable name.
  • name: Variable name.

@return A text box variable.

template.adhoc

Ad hoc filters allow you to add key/value filters that are automatically added to all metric queries that use the specified data source. Unlike other variables, you do not use ad hoc filters in queries. Instead, you use ad hoc filters to write filters for existing queries. Note: Ad hoc filter variables only work with InfluxDB, Prometheus, and Elasticsearch data sources.

@params

  • datasource: Target data source
  • hide: (default '') '': the variable dropdown displays the variable Name or Label value. 'label': the variable dropdown only displays the selected variable value and a down arrow. Any other value: no variable dropdown is displayed on the dashboard.
  • label: (optional) Display name of the variable dropdown. If you don’t enter a display name, then the dropdown label will be the variable name.
  • name: Variable name.

@return An ad hoc filter

text.new

Creates a text panel.

@params

  • content: (default '')
  • datasource: (optional) Panel datasource.
  • description: (optional) Panel description.
  • mode: (default 'markdown') Rendering of the content: 'markdown','html', ...
  • repeat: (optional) Name of variable that should be used to repeat this panel.
  • repeatDirection: (default 'h') 'h' for horizontal or 'v' for vertical.
  • repeatMaxPerRow: (optional) Maximum panels per row in repeat mode.
  • span: (optional)
  • title: (default '') Panel title.
  • transparent: (optional) Whether to display the panel without a background.

timepicker.new

Creates a Timepicker

@params

  • refresh_intervals: (default: ['5s','10s','30s','1m','5m','15m','30m','1h','2h','1d']) Array of time durations
  • time_options: (default: ['5m','15m','1h','6h','12h','24h','2d','7d','30d']) Array of time durations

transformation.new