Data Sources on Grafana Labs

AWS CloudWatch

Fri, 06 Mar 2026 22:21:21 +0000

Using AWS CloudWatch in Grafana

Grafana ships with built in support for CloudWatch. You just have to add it as a data source and you will be ready to build dashboards for your CloudWatch metrics.

Adding the data source

Open the side menu by clicking the Grafana icon in the top header.
In the side menu under the Dashboards link you should find a link named Data Sources.
Click the + Add data source button in the top header.
Select Cloudwatch from the Type dropdown.

NOTE: If at any moment you have issues with getting this data source to work and Grafana is giving you undescriptive errors then don’t forget to check your log file (try looking in /var/log/grafana/grafana.log).

Name	Description
Name	The data source name. This is how you refer to the data source in panels and queries.
Default	Default data source means that it will be pre-selected for new panels.
Default Region	Used in query editor to set region (can be changed on per query basis)
Custom Metrics namespace	Specify the CloudWatch namespace of Custom metrics
Auth Provider	Specify the provider to get credentials.
Credentials profile name	Specify the name of the profile to use (if you use `~/.aws/credentials` file), leave blank for default.
Assume Role Arn	Specify the ARN of the role to assume

Authentication

IAM Roles

Currently all access to CloudWatch is done server side by the Grafana backend using the official AWS SDK. If your Grafana server is running on AWS you can use IAM Roles and authentication will be handled automatically.

Checkout AWS docs on IAM Roles

NOTE: AWS Role Switching as described here it not supported at the moment.

IAM Policies

Grafana needs permissions granted via IAM to be able to read CloudWatch metrics and EC2 tags/instances/regions. You can attach these permissions to IAM roles and utilize Grafana’s built-in support for assuming roles.

Here is a minimal policy example:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowReadingMetricsFromCloudWatch",
            "Effect": "Allow",
            "Action": [
                "cloudwatch:DescribeAlarmsForMetric",
                "cloudwatch:ListMetrics",
                "cloudwatch:GetMetricStatistics",
                "cloudwatch:GetMetricData"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowReadingTagsInstancesRegionsFromEC2",
            "Effect": "Allow",
            "Action": [
                "ec2:DescribeTags",
                "ec2:DescribeInstances",
                "ec2:DescribeRegions"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowReadingResourcesForTags",
            "Effect" : "Allow",
            "Action" : "tag:GetResources",
            "Resource" : "*"
        }
    ]
}

AWS credentials

If Auth Provider is Credentials file, Grafana try to get credentials by following order.

Environment variables. (AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY)
Hard-code credentials.
Shared credentials file.
IAM role for Amazon EC2.

Checkout AWS docs on Configuring the AWS SDK for Go

AWS credentials file

Create a file at ~/.aws/credentials. That is the HOME path for user running grafana-server. > NOTE: If you think you have the credentials file in the right place but it is still not working then you might try moving your .aws file to ‘/usr/share/grafana/’ and make sure your credentials file has at most 0644 permissions.

Example content:

[default]
aws_access_key_id = asdsadasdasdasd
aws_secret_access_key = dasdasdsadasdasdasdsa
region = us-west-2

Metric Query Editor

You need to specify a namespace, metric, at least one stat, and at least one dimension.

Metric Math

You can now create new time series metrics by operating on top of Cloudwatch metrics using mathematical functions. Arithmetic operators, unary subtraction and other functions are supported to be applied on cloudwatch metrics. More details on the available functions can be found on AWS Metric Math

As an example, if you want to apply arithmetic operator on a metric, you can do it by giving an alias(a unique string) to the raw metric as shown below. Then you can use this alias and apply arithmetic operator to it in the Expression field of created metric.

Templated queries

Instead of hard-coding things like server, application and sensor name in you metric queries you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns makes it easy to change the data being displayed in your dashboard.

Checkout the Templating documentation for an introduction to the templating feature and the different types of template variables.

Query variable

CloudWatch data source plugin provides the following queries you can specify in the Query field in the Variable edit view. They allow you to fill a variable’s options list with things like region, namespaces, metric names and dimension keys/values.

In place of region you can specify default to use the default region configured in the data source for the query, e.g. metrics(AWS/DynamoDB, default) or dimension_values(default, ..., ..., ...).

Read more about the available dimensions in the CloudWatch Metrics and Dimensions Reference.

Name	Description
regions()	Returns a list of regions AWS provides their service.
namespaces()	Returns a list of namespaces CloudWatch support.
metrics(namespace, [region])	Returns a list of metrics in the namespace. (specify region or use “default” for custom metrics)
dimension_keys(namespace)	Returns a list of dimension keys in the namespace.
dimension_values(region, namespace, metric, dimension_key, [filters])	Returns a list of dimension values matching the specified `region`, `namespace`, `metric`, `dimension_key` or you can use dimension `filters` to get more specific result as well.
ebs_volume_ids(region, instance_id)	Returns a list of volume ids matching the specified `region`, `instance_id`.
ec2_instance_attribute(region, attribute_name, filters)	Returns a list of attributes matching the specified `region`, `attribute_name`, `filters`.
resource_arns(region, resource_type, tags)	Returns a list of ARNs matching the specified `region`, `resource_type` and `tags`.

For details about the metrics CloudWatch provides, please refer to the CloudWatch documentation.

Examples templated Queries

Example dimension queries which will return list of resources for individual AWS Services:

Query	Service
dimension_values(us-east-1,AWS/ELB,RequestCount,LoadBalancerName)	ELB
dimension_values(us-east-1,AWS/ElastiCache,CPUUtilization,CacheClusterId)	ElastiCache
dimension_values(us-east-1,AWS/Redshift,CPUUtilization,ClusterIdentifier)	RedShift
dimension_values(us-east-1,AWS/RDS,CPUUtilization,DBInstanceIdentifier)	RDS
dimension_values(us-east-1,AWS/S3,BucketSizeBytes,BucketName)	S3
dimension_values(us-east-1,CWAgent,disk_used_percent,device,{“InstanceId”:"$instance_id"})	CloudWatch Agent
resource_arns(eu-west-1,elasticloadbalancing:loadbalancer,{“elasticbeanstalk:environment-name”:[“myApp-dev”,“myApp-prod”]})	ELB
resource_arns(eu-west-1,ec2:instance,{“elasticbeanstalk:environment-name”:[“myApp-dev”,“myApp-prod”]})	EC2

ec2_instance_attribute examples

JSON filters

The ec2_instance_attribute query takes filters in JSON format. You can specify pre-defined filters of ec2:DescribeInstances. Note that the actual filtering takes place on Amazon’s servers, not in Grafana.

Filters syntax:

{ filter_name1: [ filter_value1 ], filter_name2: [ filter_value2 ] }

Example ec2_instance_attribute() query

ec2_instance_attribute(us-east-1, InstanceId, { "tag:Environment": [ "production" ] })

Selecting Attributes

Only 1 attribute per instance can be returned. Any flat attribute can be selected (i.e. if the attribute has a single value and isn’t an object or array). Below is a list of available flat attributes:

AmiLaunchIndex
Architecture
ClientToken
EbsOptimized
EnaSupport
Hypervisor
IamInstanceProfile
ImageId
InstanceId
InstanceLifecycle
InstanceType
KernelId
KeyName
LaunchTime
Platform
PrivateDnsName
PrivateIpAddress
PublicDnsName
PublicIpAddress
RamdiskId
RootDeviceName
RootDeviceType
SourceDestCheck
SpotInstanceRequestId
SriovNetSupport
SubnetId
VirtualizationType
VpcId

Tags can be selected by prepending the tag name with Tags.

Example ec2_instance_attribute() query

ec2_instance_attribute(us-east-1, Tags.Name, { "tag:Team": [ "sysops" ] })

Using json format template variables

Some of query takes JSON format filter. Grafana support to interpolate template variable to JSON format string, it can use as filter string.

If env = 'production', 'staging', following query will return ARNs of EC2 instances which Environment tag is production or staging.

resource_arns(us-east-1, ec2:instance, {"Environment":${env:json}})

Cost

Amazon provides 1 million CloudWatch API requests each month at no additional charge. Past this, it costs $0.01 per 1,000 GetMetricStatistics or ListMetrics requests. For each query Grafana will issue a GetMetricStatistics request and every time you pick a dimension in the query editor Grafana will issue a ListMetrics request.

Configure the data source with provisioning

It’s now possible to configure data sources using config files with Grafana’s provisioning system. You can read more about how it works and all the settings you can set for data sources on the provisioning docs page

Here are some provisioning examples for this data source.

Using a credentials file

apiVersion: 1

datasources:
  - name: Cloudwatch
    type: cloudwatch
    jsonData:
      authType: credentials
      defaultRegion: eu-west-2

Using accessKey and secretKey

apiVersion: 1

datasources:
  - name: Cloudwatch
    type: cloudwatch
    jsonData:
      authType: keys
      defaultRegion: eu-west-2
    secureJsonData:
      accessKey: "<your access key>"
      secretKey: "<your secret key>"

TestData

Fri, 06 Mar 2026 22:21:21 +0000

Grafana TestData

The purpose of this data sources is to make it easier to create fake data for any panel. Using Grafana TestData you can build your own time series and have any panel render it. This make is much easier to verify functionally since the data can be shared very easily.

Enable

Grafana TestData is not enabled by default. To enable it, first navigate to the Plugins section, found in your Grafana main menu. Click the Apps tabs in the Plugins section and select the Grafana TestData App. (Or navigate to http://your_grafana_instance/plugins/testdata/edit to go directly there). Finally click the enable button to enable.

Create mock data.

Once Grafana TestData is enabled you can use it as a data source in any metric panel.

CSV

The comma separated values scenario is the most powerful one since it lets you create any kind of graph you like. Once you provided the numbers Grafana TestData will distribute them evenly based on the time range of your query.

Dashboards

Grafana TestData also contains some dashboards with example. /plugins/testdata/edit

Commit updates to the dashboards

If you want to submit a change to one of the current dashboards bundled with Grafana TestData you have to update the revision property. Otherwise the dashboard will not be updated automatically for other Grafana users.

Using test data in issues

If you post an issue on github regarding time series data or rendering of time series data we strongly advice you to use this data source to replicate the data. That makes it much easier for the developers to replicate and solve the issue you have.

Using Azure Monitor in Grafana

Fri, 06 Mar 2026 22:21:21 +0000

Using Azure Monitor in Grafana

Officially released in Grafana v6.0.0

As of Grafana 6.0, the Azure Monitor plugin has been moved into Grafana so it now ships with built-in support for Azure Monitor.

The Azure Monitor data source supports multiple services in the Azure cloud:

Azure Monitor is the platform service that provides a single source for monitoring Azure resources.
Application Insights is an extensible Application Performance Management (APM) service for web developers on multiple platforms and can be used to monitor your live web application - it will automatically detect performance anomalies.
Azure Log Analytics (or Azure Logs) gives you access to log data collected by Azure Monitor.
Application Insights Analytics allows you to query Application Insights data using the same query language used for Azure Log Analytics.

Adding the data source to Grafana

The data source can access metrics from four different services. You can configure access to the services that you use. It is also possible to use the same credentials for multiple services if that is how you have set it up in Azure AD.

Accessed from the Grafana main menu, newly installed data sources can be added immediately within the Data Sources section. Next, click the “Add data source” button in the upper right. The Azure Monitor data source will be available for selection in the Cloud section in the list of data sources.
In the name field, Grafana will automatically fill in a name for the data source - Azure Monitor or something like Azure Monitor - 3. If you are going to configure multiple data sources then change the name to something more informative.
If you are using Azure Monitor, you need 4 pieces of information from the Azure portal (see link above for detailed instructions):
- Tenant Id (Azure Active Directory -> Properties -> Directory ID)
- Client Id (Azure Active Directory -> App Registrations -> Choose your app -> Application ID)
- Client Secret ( Azure Active Directory -> App Registrations -> Choose your app -> Keys)
- Default Subscription Id (Subscriptions -> Choose subscription -> Overview -> Subscription ID)
Paste these four items into the fields in the Azure Monitor API Details section:

Azure Monitor Configuration Details
- The Subscription Id can be changed per query. Save the data source and refresh the page to see the list of subscriptions available for the specified Client Id.
If you are also using the Azure Log Analytics service, then you need to specify these two config values (or you can reuse the Client Id and Secret from the previous step).
- Client Id (Azure Active Directory -> App Registrations -> Choose your app -> Application ID)
- Client Secret (Azure Active Directory -> App Registrations -> Choose your app -> Keys -> Create a key -> Use client secret)
If you are using Application Insights, then you need two pieces of information from the Azure Portal (see link above for detailed instructions):
- Application ID
- API Key
Paste these two items into the appropriate fields in the Application Insights API Details section:

Application Insights Configuration Details
Test that the configuration details are correct by clicking on the “Save & Test” button:

Save and Test

Alternatively on step 4 if creating a new Azure Active Directory App, use the Azure CLI:

az ad sp create-for-rbac -n "http://localhost:3000"

Choose a Service

In the query editor for a panel, after choosing your Azure Monitor data source, the first option is to choose a service. There are three options here:

Azure Monitor
Application Insights
Azure Log Analytics

The query editor will change depending on which one you pick. Azure Monitor is the default.

Querying the Azure Monitor Service

The Azure Monitor service provides metrics for all the Azure services that you have running. It helps you understand how your applications on Azure are performing and to proactively find issues affecting your applications.

If your Azure Monitor credentials give you access to multiple subscriptions then choose the appropriate subscription first.

Examples of metrics that you can get from the service are:

Microsoft.Compute/virtualMachines - Percentage CPU
Microsoft.Network/networkInterfaces - Bytes sent
Microsoft.Storage/storageAccounts - Used Capacity

Formatting Legend Keys with Aliases for the Azure Monitor Service

The default legend formatting for the Azure Monitor API is:

resourceName{dimensionValue=dimensionName}.metricName

These can be quite long but this formatting can be changed using aliases. In the Legend Format field, the aliases which are defined below can be combined any way you want.

Azure Monitor Examples:

dimension: {{dimensionvalue}}
{{resourcegroup}} - {{resourcename}}

Alias Patterns for Azure Monitor

{{resourcegroup}} = replaced with the value of the Resource Group
{{namespace}} = replaced with the value of the Namespace (e.g. Microsoft.Compute/virtualMachines)
{{resourcename}} = replaced with the value of the Resource Name
{{metric}} = replaced with metric name (e.g. Percentage CPU)
{{dimensionname}} = replaced with dimension key/label (e.g. blobtype)
{{dimensionvalue}} = replaced with dimension value (e.g. BlockBlob)

Templating with Variables for the Azure Monitor Service

Note that the Azure Monitor service does not support multiple values yet. If you want to visualize multiple time series (for example, metrics for server1 and server2) then you have to add multiple queries to able to view them on the same graph or in the same table.

The Azure Monitor data source Plugin provides the following queries you can specify in the Query field in the Variable edit view. They allow you to fill a variable’s options list.

Name	Description
Subscriptions()	Returns a list of subscriptions.
ResourceGroups()	Returns a list of resource groups.
ResourceGroups(12345678-aaaa-bbbb-cccc-123456789aaa)	Returns a list of resource groups for a specified subscription.
Namespaces(aResourceGroup)	Returns a list of namespaces for the specified resource group.
Namespaces(12345678-aaaa-bbbb-cccc-123456789aaa, aResourceGroup)	Returns a list of namespaces for the specified resource group and subscription.
ResourceNames(aResourceGroup, aNamespace)	Returns a list of resource names.
ResourceNames(12345678-aaaa-bbbb-cccc-123456789aaa, aResourceGroup, aNamespace)	Returns a list of resource names for a specified subscription.
MetricNamespace(aResourceGroup, aNamespace, aResourceName)	Returns a list of metric namespaces.
MetricNamespace(12345678-aaaa-bbbb-cccc-123456789aaa, aResourceGroup, aNamespace, aResourceName)	Returns a list of metric namespaces for a specified subscription.
MetricNames(aResourceGroup, aNamespace, aResourceName)	Returns a list of metric names.
MetricNames(12345678-aaaa-bbbb-cccc-123456789aaa, aResourceGroup, aNamespace, aResourceName)	Returns a list of metric names for a specified subscription.

Examples:

Resource Groups query: ResourceGroups()
Passing in metric name variable: Namespaces(cosmo)
Chaining template variables: ResourceNames($rg, $ns)
Do not quote parameters: MetricNames(hg, Microsoft.Network/publicIPAddresses, grafanaIP)

Checkout the Templating documentation for an introduction to the templating feature and the different types of template variables.

Azure Monitor Metrics Whitelist

Not all metrics returned by the Azure Monitor API have values. The Grafana data source has a whitelist to only return metric names if it is possible they might have values. This whitelist is updated regularly as new services and metrics are added to the Azure cloud. You can find the current whitelist here.

Azure Monitor Alerting

Grafana alerting is supported for the Azure Monitor service. This is not Azure Alerts support. Read more about how alerting in Grafana works here.

Querying the Application Insights Service

Formatting Legend Keys with Aliases for the Application Insights Service

The default legend formatting is:

metric/name{group/by="groupbyvalue"}

In the Legend Format field, the aliases which are defined below can be combined any way you want.

Application Insights Examples:

server: {{groupbyvalue}}
city: {{groupbyvalue}}
{{groupbyname}}: {{groupbyvalue}}

Alias Patterns for Application Insights

{{groupbyvalue}} = replaced with the value of the group by
{{groupbyname}} = replaced with the name/label of the group by
{{metric}} = replaced with metric name (e.g. requests/count)

Filter Expressions for Application Insights

The filter field takes an OData filter expression.

Examples:

client/city eq 'Boydton'
client/city ne 'Boydton'
client/city ne 'Boydton' and client/city ne 'Dublin'
client/city eq 'Boydton' or client/city eq 'Dublin'

Templating with Variables for Application Insights

Use the one of the following queries in the Query field in the Variable edit view.

Checkout the Templating documentation for an introduction to the templating feature and the different types of template variables.

Name	Description
AppInsightsMetricNames()	Returns a list of metric names.
AppInsightsGroupBys(aMetricName)	Returns a list of group bys for the specified metric name.

Examples:

Metric Names query: AppInsightsMetricNames()
Passing in metric name variable: AppInsightsGroupBys(requests/count)
Chaining template variables: AppInsightsGroupBys($metricnames)

Application Insights Alerting

Grafana alerting is supported for Application Insights. This is not Azure Alerts support. Read more about how alerting in Grafana works here.

Querying the Azure Log Analytics Service

Queries are written in the new Azure Log Analytics (or KustoDB) Query Language. A Log Analytics Query can be formatted as Time Series data or as Table data.

Time Series queries are for the Graph Panel (and other panels like the Single Stat panel) and must contain a datetime column, a metric name column and a value column. Here is an example query that returns the aggregated count grouped by the Category column and grouped by hour:

AzureActivity
| where $__timeFilter(TimeGenerated)
| summarize count() by Category, bin(TimeGenerated, 1h)
| order by TimeGenerated asc

Table queries are mainly used in the Table panel and row a list of columns and rows. This example query returns rows with the 6 specified columns:

AzureActivity
| where $__timeFilter()
| project TimeGenerated, ResourceGroup, Category, OperationName, ActivityStatus, Caller
| order by TimeGenerated desc

If your credentials give you access to multiple subscriptions then choose the appropriate subscription first.

Azure Log Analytics Macros

To make writing queries easier there are several Grafana macros that can be used in the where clause of a query:

$__timeFilter() - Expands to TimeGenerated ≥ datetime(2018-06-05T18:09:58.907Z) and TimeGenerated ≤ datetime(2018-06-05T20:09:58.907Z) where the from and to datetimes are from the Grafana time picker.
$__timeFilter(datetimeColumn) - Expands to datetimeColumn ≥ datetime(2018-06-05T18:09:58.907Z) and datetimeColumn ≤ datetime(2018-06-05T20:09:58.907Z) where the from and to datetimes are from the Grafana time picker.
$__timeFrom() - Returns the From datetime from the Grafana picker. Example: datetime(2018-06-05T18:09:58.907Z).
$__timeTo() - Returns the From datetime from the Grafana picker. Example: datetime(2018-06-05T20:09:58.907Z).
$__escapeMulti($myVar) - is to be used with multi-value template variables that contain illegal characters. If $myVar has the following two values as a string '\\grafana-vm\Network(eth0)\Total','\\hello!', then it expands to: @'\\grafana-vm\Network(eth0)\Total', @'\\hello!'. If using single value variables there is no need for this macro, simply escape the variable inline instead - @'\$myVar'.
$__contains(colName, $myVar) - is to be used with multi-value template variables. If $myVar has the value 'value1','value2', it expands to: colName in ('value1','value2').

If using the All option, then check the Include All Option checkbox and in the Custom all value field type in the following value: all. If $myVar has value all then the macro will instead expand to 1 == 1. For template variables with a lot of options, this will increase the query performance by not building a large where..in clause.

Azure Log Analytics Builtin Variables

There are also some Grafana variables that can be used in Azure Log Analytics queries:

$__interval - Grafana calculates the minimum time grain that can be used to group by time in queries. More details on how it works here. It returns a time grain like 5m or 1h that can be used in the bin function. E.g. summarize count() by bin(TimeGenerated, $__interval)

Azure Log Analytics Alerting

Not implemented yet.

Writing Analytics Queries For the Application Insights Service

If you change the service type to “Application Insights”, the menu icon to the right adds another option, “Toggle Edit Mode”. Once clicked, the query edit mode changes to give you a full text area in which to write log analytics queries. (This is identical to how the InfluxDB data source lets you write raw queries.)

Once a query is written, the column names are automatically parsed out of the response data. You can then select them in the “X-axis”, “Y-axis”, and “Split On” dropdown menus, or just type them out.

There are some important caveats to remember:

You’ll want to order your y-axis in the query, eg. order by timestamp asc. The graph may come out looking bizarre otherwise. It’s better to have Microsoft sort it on their side where it’s faster, than to implement this in the plugin.
If you copy a log analytics query, typically they’ll end with a render instruction, like render barchart. This is unnecessary, but harmless.
Currently, four default dashboard variables are supported: $__timeFilter(), $__from, $__to, and $__interval. If you’re searching in timestamped data, replace the beginning of your where clause to where $__timeFilter(). Dashboard changes by time region are handled as you’d expect, as long as you leave the name of the timestamp column alone. Likewise, $__interval will automatically change based on the dashboard’s time region and the width of the chart being displayed. Use it in bins, so bin(timestamp,$__interval) changes into something like bin(timestamp,1s). Use $__from and $__to if you just want the formatted dates to be inserted.
Templated dashboard variables are not yet supported! They will come in a future version.

Using Elasticsearch in Grafana

Fri, 06 Mar 2026 22:21:21 +0000

Using Elasticsearch in Grafana

Grafana ships with advanced support for Elasticsearch. You can do many types of simple or complex Elasticsearch queries to visualize logs or metrics stored in Elasticsearch. You can also annotate your graphs with log events stored in Elasticsearch.

Adding the data source

Open the side menu by clicking the Grafana icon in the top header.
In the side menu under the Dashboards link you should find a link named Data Sources.
Click the + Add data source button in the top header.
Select Elasticsearch from the Type dropdown.

NOTE: If you’re not seeing the Data Sources link in your side menu it means that your current user does not have the Admin role for the current organization.

Name	Description
Name	The data source name. This is how you refer to the data source in panels and queries.
Default	Default data source means that it will be pre-selected for new panels.
Url	The HTTP protocol, IP, and port of your Elasticsearch server.
Access	Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser.

Access mode controls how requests to the data source will be handled. Server should be the preferred way if nothing else stated.

Server access mode (Default)

All requests will be made from the browser to Grafana backend/server which in turn will forward the requests to the data source and by that circumvent possible Cross-Origin Resource Sharing (CORS) requirements. The URL needs to be accessible from the grafana backend/server if you select this access mode.

Browser (Direct) access

All requests will be made from the browser directly to the data source and may be subject to Cross-Origin Resource Sharing (CORS) requirements. The URL needs to be accessible from the browser if you select this access mode.

If you select Browser access you must update your Elasticsearch configuration to allow other domains to access Elasticsearch from the browser. You do this by specifying these to options in your elasticsearch.yml config file.

http.cors.enabled: true
http.cors.allow-origin: "*"

Index settings

Here you can specify a default for the time field and specify the name of your Elasticsearch index. You can use a time pattern for the index name or a wildcard.

Elasticsearch version

Be sure to specify your Elasticsearch version in the version selection dropdown. This is very important as there are differences on how queries are composed. Currently the versions available are 2.x, 5.x, 5.6+, 6.0+ or 7.0+. The value 5.6+ means version 5.6 or higher, but lower than 6.0. The value 6.0+ means version 6.0 or higher, but lower than 7.0. Finally, 7.0+ means version 7.0 or higher, but lower than 8.0.

Min time interval

A lower limit for the auto group by time interval. Recommended to be set to write frequency, for example 1m if your data is written every minute. This option can also be overridden/configured in a dashboard panel under data source options. It’s important to note that this value needs to be formatted as a number followed by a valid time identifier, e.g. 1m (1 minute) or 30s (30 seconds). The following time identifiers are supported:

Identifier	Description
`y`	year
`M`	month
`w`	week
`d`	day
`h`	hour
`m`	minute
`s`	second
`ms`	millisecond

Logs (BETA)

Only available in Grafana v6.3+.

There are two parameters, Message field name and Level field name, that can optionally be configured from the data source settings page that determine which fields will be used for log messages and log levels when visualizing logs in Explore.

For example, if you’re using a default setup of Filebeat for shipping logs to Elasticsearch the following configuration should work:

Message field name: message
Level field name: fields.level

Metric Query editor

The Elasticsearch query editor allows you to select multiple metrics and group by multiple terms or filters. Use the plus and minus icons to the right to add/remove metrics or group by clauses. Some metrics and group by clauses haves options, click the option text to expand the row to view and edit metric or group by options.

Series naming and alias patterns

You can control the name for time series via the Alias input field.

Pattern	Description
{{term fieldname}}	replaced with value of a term group by
{{metric}}	replaced with metric name (ex. Average, Min, Max)
{{field}}	replaced with the metric field name

Pipeline metrics

Some metric aggregations are called Pipeline aggregations, for example, Moving Average and Derivative. Elasticsearch pipeline metrics require another metric to be based on. Use the eye icon next to the metric to hide metrics from appearing in the graph. This is useful for metrics you only have in the query for use in a pipeline metric.

Templating

Checkout the Templating documentation for an introduction to the templating feature and the different types of template variables.

Query variable

The Elasticsearch data source supports two types of queries you can use in the Query field of Query variables. The query is written using a custom JSON string.

Query	Description
{“find”: “fields”, “type”: “keyword”}	Returns a list of field names with the index type `keyword`.
{“find”: “terms”, “field”: “@hostname”, “size”: 1000}	Returns a list of values for a field using term aggregation. Query will use current dashboard time range as time range for query.
{“find”: “terms”, “field”: “@hostname”, “query”: ‘’}	Returns a list of values for a field using term aggregation and a specified lucene query filter. Query will use current dashboard time range as time range for query.

There is a default size limit of 500 on terms queries. Set the size property in your query to set a custom limit. You can use other variables inside the query. Example query definition for a variable named $host.

{"find": "terms", "field": "@hostname", "query": "@source:$source"}

In the above example, we use another variable named $source inside the query definition. Whenever you change, via the dropdown, the current value of the $source variable, it will trigger an update of the $host variable so it now only contains hostnames filtered by in this case the @source document property.

These queries by default return results in term order (which can then be sorted alphabetically or numerically as for any variable). To produce a list of terms sorted by doc count (a top-N values list), add an orderBy property of “doc_count”. This automatically selects a descending sort; using “asc” with doc_count (a bottom-N list) can be done by setting order: "asc" but is discouraged as it “increases the error on document counts”. To keep terms in the doc count order, set the variable’s Sort dropdown to Disabled; you might alternatively still want to use e.g. Alphabetical to re-sort them.

{"find": "terms", "field": "@hostname", "orderBy": "doc_count"}

Using variables in queries

There are two syntaxes:

$<varname> Example: @hostname:$hostname
[[varname]] Example: @hostname:[[hostname]]

Why two ways? The first syntax is easier to read and write but does not allow you to use a variable in the middle of a word. When the Multi-value or Include all value options are enabled, Grafana converts the labels from plain text to a lucene compatible condition.

In the above example, we have a lucene query that filters documents based on the @hostname property using a variable named $hostname. It is also using a variable in the Terms group by field input box. This allows you to use a variable to quickly change how the data is grouped.

Example dashboard: Elasticsearch Templated Dashboard

Annotations

Annotations allows you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. Grafana can query any Elasticsearch index for annotation events.

Name	Description
Query	You can leave the search query blank or specify a lucene query
Time	The name of the time field, needs to be date field.
Time End	Optional name of the time end field, needs to be date field. If set, then annotations will be marked as a regions between time and time-end.
Text	Event description field.
Tags	Optional field name to use for event tags (can be an array or a CSV string).

Querying Logs (BETA)

Only available in Grafana v6.3+.

Querying and displaying log data from Elasticsearch is available via Explore.

Select the Elasticsearch data source, change to Logs using the Metrics/Logs switcher, and then optionally enter a lucene query into the query field to filter the log messages.

Finally, press the Enter key or the Run Query button to display your logs.

Log Queries

Once the result is returned, the log panel shows a list of log rows and a bar chart where the x-axis shows the time and the y-axis shows the frequency/count.

Note that the fields used for log message and level is based on an optional data source configuration.

Filter Log Messages

Optionally enter a lucene query into the query field to filter the log messages. For example, using a default Filebeat setup you should be able to use fields.level:error to only show error log messages.

Configure the data source with provisioning

Here are some provisioning examples for this data source.

apiVersion: 1

datasources:
  - name: Elastic
    type: elasticsearch
    access: proxy
    database: "[metrics-]YYYY.MM.DD"
    url: http://localhost:9200
    jsonData:
      interval: Daily
      timeField: "@timestamp"

or, for logs:

apiVersion: 1

datasources:
  - name: elasticsearch-v7-filebeat
    type: elasticsearch
    access: proxy
    database: "[filebeat-]YYYY.MM.DD"
    url: http://localhost:9200
    jsonData:
      interval: Daily
      timeField: "@timestamp"
      esVersion: 70
      logMessageField: message
      logLevelField: fields.level

Using Graphite in Grafana

Fri, 06 Mar 2026 22:21:21 +0000

Using Graphite in Grafana

Grafana has an advanced Graphite query editor that lets you quickly navigate the metric space, add functions, change function parameters and much more. The editor can handle all types of graphite queries. It can even handle complex nested queries through the use of query references.

Adding the data source

Open the side menu by clicking the Grafana icon in the top header.
In the side menu under the Configuration link you should find a link named Data Sources.
Click the + Add data source button in the top header.
Select Graphite from the Type dropdown.

NOTE: If you’re not seeing the Data Sources link in your side menu it means that your current user does not have the Admin role for the current organization.

Name	Description
Name	The data source name. This is how you refer to the data source in panels and queries.
Default	Default data source means that it will be pre-selected for new panels.
Url	The HTTP protocol, IP, and port of your graphite-web or graphite-api install.
Access	Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser.

Access mode controls how requests to the data source will be handled. Server should be the preferred way if nothing else stated.

Server access mode (Default)

Browser access mode

Metric editor

Navigate metric segments

Click the Select metric link to start navigating the metric space. One you start you can continue using the mouse or keyboard arrow keys. You can select a wildcard and still continue.

Functions

Click the plus icon to the right to add a function. You can search for the function or select it from the menu. Once a function is selected it will be added and your focus will be in the text box of the first parameter. To later change a parameter just click on it and it will turn into a text box. To delete a function click the function name followed by the x icon.

Optional parameters

Some functions like aliasByNode support an optional second argument. To add this parameter specify for example 3,-2 as the first parameter and the function editor will adapt and move the -2 to a second parameter. To remove the second optional parameter just click on it and leave it blank and the editor will remove it.

Nested Queries

You can reference queries by the row “letter” that they’re on (similar to Microsoft Excel). If you add a second query to a graph, you can reference the first query simply by typing in #A. This provides an easy and convenient way to build compounded queries.

Point consolidation

All Graphite metrics are consolidated so that Graphite doesn’t return more data points than there are pixels in the graph. By default, this consolidation is done using avg function. You can control how Graphite consolidates metrics by adding the Graphite consolidateBy function.

Notice This means that legend summary values (max, min, total) cannot be all correct at the same time. They are calculated client side by Grafana. And depending on your consolidation function only one or two can be correct at the same time.

Templating

Checkout the Templating documentation for an introduction to the templating feature and the different types of template variables.

Graphite 1.1 introduced tags and Grafana added support for Graphite queries with tags in version 5.0. To create a variable using tag values, then you need to use the Grafana functions tags and tag_values.

Query	Description
tags()	Returns all tags.
tags(server=~backend)*	Returns only tags that occur in series matching the filter expression.
tag_values(server)	Return tag values for the specified tag.
tag_values(server, server=~backend)*	Returns filtered tag values that occur for the specified tag in series matching those expressions.
tag_values(server, server=~~backend, app=~~${apps:regex})*	Multiple filter expressions and expressions can contain other variables.

For more details, see the Graphite docs on the autocomplete api for tags.

Query variable

The query you specify in the query field should be a metric find type of query. For example, a query like prod.servers.* will fill the variable with all possible values that exist in the wildcard position.

You can also create nested variables that use other variables in their definition. For example apps.$app.servers.* uses the variable $app in its query definition.

Using `__searchFilter` to filter results in Query Variable

Available from Grafana 6.5 and above

Using __searchFilter in the query field will filter the query result based on what the user types in the dropdown select box. When nothing has been entered by the user the default value for __searchFilter is * and `` when used as part of a regular expression.

The example below shows how to use __searchFilter as part of the query field to enable searching for server while the user types in the dropdown select box.

Query

apps.$app.servers.$__searchFilter

TagValues

tag_values(server, server=~${__searchFilter:regex})

Variable Usage

You can use a variable in a metric node path or as a parameter to a function.

There are two syntaxes:

$<varname> Example: apps.frontend.$server.requests.count
[[varname]] Example: apps.frontend.[[server]].requests.count

Why two ways? The first syntax is easier to read and write but does not allow you to use a variable in the middle of a word. Use the second syntax in expressions like my.server[[serverNumber]].count.

Example: Graphite Templated Dashboard

Variable Usage in Tag Queries

Multi-value variables in tag queries use the advanced formatting syntax introduced in Grafana 5.0 for variables: {var:regex}. Non-tag queries will use the default glob formatting for multi-value variables.

Example of a tag expression with regex formatting and using the Equal Tilde operator, =~:

server=~${servers:regex}

Checkout the Advanced Formatting Options section in the Variables documentation for examples and details.

Annotations

Annotations allows you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view.

Graphite supports two ways to query annotations. A regular metric query, for this you use the Graphite query textbox. A Graphite events query, use the Graphite event tags textbox, specify a tag or wildcard (leave empty should also work)

Configure the data source with provisioning

Here are some provisioning examples for this data source.

apiVersion: 1

datasources:
  - name: Graphite
    type: graphite
    access: proxy
    url: http://localhost:8080
    jsonData:
      graphiteVersion: "1.1"

Using InfluxDB in Grafana

Fri, 06 Mar 2026 22:21:21 +0000

Using InfluxDB in Grafana

Grafana ships with very feature rich data source plugin for InfluxDB. Supporting a feature rich query editor, annotation and templating queries.

Adding the data source

Open the side menu by clicking the Grafana icon in the top header.
In the side menu under the Dashboards link you should find a link named Data Sources.
Click the + Add data source button in the top header.
Select InfluxDB from the Type dropdown.

NOTE: If you’re not seeing the Data Sources link in your side menu it means that your current user does not have the Admin role for the current organization.

Name	Description
Name	The data source name. This is how you refer to the data source in panels and queries.
Default	Default data source means that it will be pre-selected for new panels.
Url	The HTTP protocol, IP address and port of your InfluxDB API (InfluxDB API port is by default 8086)
Access	Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser.
Database	Name of your InfluxDB database
User	Name of your database user
Password	Database user’s password
HTTP mode	How to query the database (`GET` or `POST` HTTP verb). The `POST` verb allows heavy queries that would return an error using the `GET` verb. Default is `GET`.

Access mode controls how requests to the data source will be handled. Server should be the preferred way if nothing else stated.

Server access mode (Default)

Browser access mode

Min time interval

Identifier	Description
`y`	year
`M`	month
`w`	week
`d`	day
`h`	hour
`m`	minute
`s`	second
`ms`	millisecond

Query Editor

You find the InfluxDB editor in the metrics tab in Graph or Singlestat panel’s edit mode. You enter edit mode by clicking the panel title, then edit. The editor allows you to select metrics and tags.

Filter data (WHERE)

To add a tag filter click the plus icon to the right of the WHERE condition. You can remove tag filters by clicking on the tag key and select --remove tag filter--.

Regex matching

You can type in regex patterns for metric names or tag filter values, be sure to wrap the regex pattern in forward slashes (/). Grafana will automatically adjust the filter tag condition to use the InfluxDB regex match condition operator (=~).

Field and Aggregation functions

In the SELECT row you can specify what fields and functions you want to use. If you have a group by time you need an aggregation function. Some functions like derivative require an aggregation function. The editor tries simplify and unify this part of the query. For example:

The above will generate the following InfluxDB SELECT clause:

SELECT derivative(mean("value"), 10s) /10 AS "REQ/s" FROM ....

Select multiple fields

Use the plus button and select Field > field to add another SELECT clause. You can also specify an asterix * to select all fields.

Group By

To group by a tag click the plus icon at the end of the GROUP BY row. Pick a tag from the dropdown that appears. You can remove the group by by clicking on the tag and then click on the x icon.

Text Editor Mode (RAW)

You can switch to raw query mode by clicking hamburger icon and then Switch editor mode.

If you use Raw Query be sure your query at minimum have WHERE $timeFilter Also please always have a group by time and an aggregation function, otherwise InfluxDB can easily return hundreds of thousands of data points that will hang the browser.

Alias patterns

$m = replaced with measurement name
$measurement = replaced with measurement name
$col = replaced with column name
$tag_exampletag = replaced with the value of the exampletag tag. The syntax is $tag_yourTagName (must start with $tag_). To use your tag as an alias in the ALIAS BY field then the tag must be used to group by in the query.
You can also use [[tag_hostname]] pattern replacement syntax. For example, in the ALIAS BY field using this text Host: [[tag_hostname]] would substitute in the hostname tag value for each legend value and an example legend value would be: Host: server1.

Table query / raw data

You can remove the group by time by clicking on the time part and then the x icon. You can change the option Format As to Table if you want to show raw data in the Table panel.

Querying Logs (BETA)

Only available in Grafana v6.3+.

Querying and displaying log data from InfluxDB is available via Explore.

Select the InfluxDB data source, change to Logs using the Metrics/Logs switcher, and then use the Measurements/Fields button to display your logs.

Log Queries

The Logs Explorer (the Measurements/Fields button) next to the query field shows a list of measurements and fields. Choose the desired measurement that contains your log data and then choose which field Explore should use to display the log message.

Once the result is returned, the log panel shows a list of log rows and a bar chart where the x-axis shows the time and the y-axis shows the frequency/count.

Filter search

To add a filter click the plus icon to the right of the Measurements/Fields button or a condition. You can remove tag filters by clicking on the first select and choosing --remove filter--.

Templating

Checkout the Templating documentation for an introduction to the templating feature and the different types of template variables.

Query variable

If you add a template variable of the type Query you can write a InfluxDB exploration (meta data) query. These queries can return things like measurement names, key names or key values.

For example you can have a variable that contains all values for tag hostname if you specify a query like this in the templating variable Query setting.

SHOW TAG VALUES WITH KEY = "hostname"

You can also create nested variables. For example if you had another variable, for example region. Then you could have the hosts variable only show hosts from the current selected region with a query like this:

SHOW TAG VALUES WITH KEY = "hostname"  WHERE region =~ /$region/

You can fetch key names for a given measurement.

SHOW TAG KEYS [FROM <measurement_name>]

If you have a variable with key names you can use this variable in a group by clause. This will allow you to change group by using the variable dropdown at the top of the dashboard.

Using variables in queries

There are two syntaxes:

$<varname> Example:

SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^$host$/ AND $timeFilter GROUP BY time($__interval), "hostname"

[[varname]] Example:

SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^[[host]]$/ AND $timeFilter GROUP BY time($__interval), "hostname"

Example Dashboard: InfluxDB Templated Dashboard

Ad hoc filters variable

InfluxDB supports the special Ad hoc filters variable type. This variable allows you to specify any number of key/value filters on the fly. These filters will automatically be applied to all your InfluxDB queries.

Annotations

Annotations allows you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view.

An example query:

SELECT title, description from events WHERE $timeFilter ORDER BY time ASC

For InfluxDB you need to enter a query like in the above example. You need to have the where $timeFilter part. If you only select one column you will not need to enter anything in the column mapping fields. The Tags field can be a comma separated string.

Configure the data source with provisioning

Here are some provisioning examples for this dat asource.

apiVersion: 1

datasources:
  - name: InfluxDB
    type: influxdb
    access: proxy
    database: site
    user: grafana
    password: grafana
    url: http://localhost:8086
    jsonData:
      httpMode: GET

Using Loki in Grafana

Fri, 06 Mar 2026 22:21:21 +0000

Using Loki in Grafana

BETA: Querying Loki data requires Grafana’s Explore section. Grafana v6.x comes with Explore enabled by default. In Grafana v5.3.x and v5.4.x. you need to enable Explore manually. Viewing Loki data in dashboard panels is supported in Grafana v6.4+.

Grafana ships with built-in support for Loki, Grafana’s log aggregation system. Just add it as a data source and you are ready to query your log data in Explore.

Adding the data source

Open Grafana and make sure you are logged in.
In the side menu under the Configuration link you should find a link named Data Sources.
Click the Add data source button at the top.
Select Loki from the list of data sources.

Note: If you’re not seeing the Data Sources link in your side menu it means that your current user does not have the Admin role for the current organization.

Name	Description
Name	The data source name. This is how you refer to the data source in panels, queries, and Explore.
Default	Default data source means that it will be pre-selected for new panels.
URL	The URL of the Loki instance, e.g., `http://localhost:3100`
Maximum lines	Upper limit for number of log lines returned by Loki (default is 1000). Decrease if your browser is sluggish when displaying logs in Explore.

Querying Logs

Querying and displaying log data from Loki is available via Explore, and with the logs panel in dashboards. Select the Loki data source, and then enter a log query to display your logs.

Log Queries

A log query consists of two parts: log stream selector, and a search expression. For performance reasons you need to start by choosing a log stream by selecting a log label.

The Logs Explorer (the Log labels button) next to the query field shows a list of labels of available log streams. An alternative way to write a query is to use the query field’s autocomplete - you start by typing a left curly brace { and the autocomplete menu will suggest a list of labels. Press the enter key to execute the query.

Once the result is returned, the log panel shows a list of log rows and a bar chart where the x-axis shows the time and the y-axis shows the frequency/count.

Your browser does not support the video tag.

Log Stream Selector

For the label part of the query expression, wrap it in curly braces {} and then use the key value syntax for selecting labels. Multiple label expressions are separated by a comma:

{app="mysql",name="mysql-backup"}

The following label matching operators are currently supported:

= exactly equal.
!= not equal.
=~ regex-match.
!~ do not regex-match.

Examples:

{name=~"mysql.+"}
{name!~"mysql.+"}

The same rules that apply for Prometheus Label Selectors apply for Loki Log Stream Selectors.

Another way to add a label selector, is in the table section, clicking on the Filter button beside a label will add the label to the query expression. This even works for multiple queries and will the label selector to each query.

Search Expression

After writing the Log Stream Selector, you can filter the results further by writing a search expression. The search expression can be just text or a regex expression.

Example queries:

{job="mysql"} |= "error"
{name="kafka"} |~ "tsdb-ops.*io:2003"
{instance=~"kafka-[23]",name="kafka"} != "kafka.server:type=ReplicaManager"

Filter operators can be chained and will sequentially filter down the expression. The resulting log lines will satisfy every filter.

Example

{job="mysql"} |= "error" != "timeout"

The following filter types are currently supported:

|= line contains string.
!= line doesn’t contain string.
|~ line matches regular expression.
!~ line does not match regular expression.

Note: For more details about LogQL, Loki’s query language, refer to the documentation

Live tailing

Loki supports Live tailing which displays logs in real-time. This feature is supported in Explore and in dashboards with a Live toggle in the query editor.

Note that Live Tailing relies on two Websocket connections: one between the browser and the Grafana server, and another between the Grafana server and the Loki server. If you run any reverse proxies, please configure them accordingly.

Note: This feature is only available in Grafana v6.3+

Log Context

When using a search expression as detailed above, you now have the ability to retrieve the context surrounding your filtered results. By clicking the Show Context link on the filtered rows, you’ll be able to investigate the log messages that came before and after the log message you’re interested in.

Note: This feature is only available in Grafana v6.3+

Templating

Instead of hard-coding things like server, application and sensor name in your metric queries, you can use variables in their place. Variables are shown as drop-down select boxes at the top of the dashboard. These drop-down boxes make it easy to change the data being displayed in your dashboard.

Checkout the Templating documentation for an introduction to the templating feature and the different types of template variables.

Annotations

You can use any non-metric Loki query as a source for annotations. Log content will be used as annotation text and your log stream labels as tags, so there is no need for additional mapping.

Note: Annotations for Loki are only available in Grafana v6.4+

Configure the data source with provisioning

You can set up the data source via config files with Grafana’s provisioning system. You can read more about how it works and all the settings you can set for data sources on the provisioning docs page

Here is an example:

apiVersion: 1

datasources:
  - name: Loki
    type: loki
    access: proxy
    url: http://localhost:3100
    jsonData:
      maxLines: 1000

Here’s another with basic auth:

apiVersion: 1

datasources:
  - name: Loki
    type: loki
    access: proxy
    url: http://localhost:3100
    basicAuth: true
    basicAuthUser: my_user
    basicAuthPassword: test_password
    jsonData:
      maxLines: 1000

Using Microsoft SQL Server in Grafana

Fri, 06 Mar 2026 22:21:21 +0000

Using Microsoft SQL Server in Grafana

Only available in Grafana v5.1+.

Grafana ships with a built-in Microsoft SQL Server (MSSQL) data source plugin that allows you to query and visualize data from any Microsoft SQL Server 2005 or newer, including Microsoft Azure SQL Database.

Adding the data source

Open the side menu by clicking the Grafana icon in the top header.
In the side menu under the Configuration link you should find a link named Data Sources.
Click the + Add data source button in the top header.
Select Microsoft SQL Server from the Type dropdown.

Data source options

Name	Description
Name	The data source name. This is how you refer to the data source in panels and queries.
Default	Default data source means that it will be pre-selected for new panels.
Host	The IP address/hostname and optional port of your MSSQL instance. If port is omitted, default 1433 will be used.
Database	Name of your MSSQL database.
User	Database user’s login/username
Password	Database user’s password
Encrypt	This option determines whether or to which extent a secure SSL TCP/IP connection will be negotiated with the server, default `false` (Grafana v5.4+).
Max open	The maximum number of open connections to the database, default `unlimited` (Grafana v5.4+).
Max idle	The maximum number of connections in the idle connection pool, default `2` (Grafana v5.4+).
Max lifetime	The maximum amount of time in seconds a connection may be reused, default `14400`/4 hours (Grafana v5.4+).

Min time interval

A lower limit for the $__interval and $__interval_ms variables. Recommended to be set to write frequency, for example 1m if your data is written every minute. This option can also be overridden/configured in a dashboard panel under data source options. It’s important to note that this value needs to be formatted as a number followed by a valid time identifier, e.g. 1m (1 minute) or 30s (30 seconds). The following time identifiers are supported:

Identifier	Description
`y`	year
`M`	month
`w`	week
`d`	day
`h`	hour
`m`	minute
`s`	second
`ms`	millisecond

Database User Permissions (Important!)

The database user you specify when you add the data source should only be granted SELECT permissions on the specified database and tables you want to query. Grafana does not validate that the query is safe. The query could include any SQL statement. For example, statements like DELETE FROM user; and DROP TABLE user; would be executed. To protect against this we Highly recommend you create a specific MSSQL user with restricted permissions.

Example:

 CREATE USER grafanareader WITH PASSWORD 'password'
 GRANT SELECT ON dbo.YourTable3 TO grafanareader

Make sure the user does not get any unwanted privileges from the public role.

Known Issues

If you’re using an older version of Microsoft SQL Server like 2008 and 2008R2 you may need to disable encryption to be able to connect. If possible, we recommend you to use the latest service pack available for optimal compatibility.

Query Editor

You find the MSSQL query editor in the metrics tab in Graph, Singlestat or Table panel’s edit mode. You enter edit mode by clicking the panel title, then edit. The editor allows you to define a SQL query to select data to be visualized.

Select Format as Time series (for use in Graph or Singlestat panel’s among others) or Table (for use in Table panel among others).
This is the actual editor where you write your SQL queries.
Show help section for MSSQL below the query editor.
Show actual executed SQL query. Will be available first after a successful query has been executed.
Add an additional query where an additional query editor will be displayed.

Macros

To simplify syntax and to allow for dynamic parts, like date range filters, the query can contain macros.

Macro example	Description
$__time(dateColumn)	Will be replaced by an expression to rename the column to time. For example, dateColumn as time
$__timeEpoch(dateColumn)	Will be replaced by an expression to convert a DATETIME column type to Unix timestamp and rename it to time. For example, DATEDIFF(second, ‘1970-01-01’, dateColumn) AS time
$__timeFilter(dateColumn)	Will be replaced by a time range filter using the specified column name. For example, dateColumn BETWEEN ‘2017-04-21T05:01:17Z’ AND ‘2017-04-21T05:06:17Z’
$__timeFrom()	Will be replaced by the start of the currently active time selection. For example, ‘2017-04-21T05:01:17Z’
$__timeTo()	Will be replaced by the end of the currently active time selection. For example, ‘2017-04-21T05:06:17Z’
$__timeGroup(dateColumn,‘5m’[, fillvalue])	Will be replaced by an expression usable in GROUP BY clause. Providing a fillValue of NULL or floating value will automatically fill empty series in timerange with that value. For example, CAST(ROUND(DATEDIFF(second, ‘1970-01-01’, time_column)/300.0, 0) as bigint)300*.
$__timeGroup(dateColumn,‘5m’, 0)	Same as above but with a fill parameter so missing points in that series will be added by grafana and 0 will be used as value.
$__timeGroup(dateColumn,‘5m’, NULL)	Same as above but NULL will be used as value for missing points.
$__timeGroup(dateColumn,‘5m’, previous)	Same as above but the previous value in that series will be used as fill value if no value has been seen yet NULL will be used (only available in Grafana 5.3+).
$__timeGroupAlias(dateColumn,‘5m’)	Will be replaced identical to $__timeGroup but with an added column alias (only available in Grafana 5.3+).
$__unixEpochFilter(dateColumn)	Will be replaced by a time range filter using the specified column name with times represented as Unix timestamp. For example, dateColumn > 1494410783 AND dateColumn < 1494497183
$__unixEpochFrom()	Will be replaced by the start of the currently active time selection as Unix timestamp. For example, 1494410783
$__unixEpochTo()	Will be replaced by the end of the currently active time selection as Unix timestamp. For example, 1494497183
$__unixEpochNanoFilter(dateColumn)	Will be replaced by a time range filter using the specified column name with times represented as nanosecond timestamp. For example, dateColumn > 1494410783152415214 AND dateColumn < 1494497183142514872
$__unixEpochNanoFrom()	Will be replaced by the start of the currently active time selection as nanosecond timestamp. For example, 1494410783152415214
$__unixEpochNanoTo()	Will be replaced by the end of the currently active time selection as nanosecond timestamp. For example, 1494497183142514872
$__unixEpochGroup(dateColumn,‘5m’, [fillmode])	Same as $__timeGroup but for times stored as Unix timestamp (only available in Grafana 5.3+).
$__unixEpochGroupAlias(dateColumn,‘5m’, [fillmode])	Same as above but also adds a column alias (only available in Grafana 5.3+).

We plan to add many more macros. If you have suggestions for what macros you would like to see, please open an issue in our GitHub repo.

The query editor has a link named Generated SQL that shows up after a query has been executed, while in panel edit mode. Click on it and it will expand and show the raw interpolated SQL string that was executed.

Table queries

If the Format as query option is set to Table then you can basically do any type of SQL query. The table panel will automatically show the results of whatever columns and rows your query returns.

Example database table:

CREATE TABLE [event] (
  time_sec bigint,
  description nvarchar(100),
  tags nvarchar(100),
)

CREATE TABLE [mssql_types] (
  c_bit bit, c_tinyint tinyint, c_smallint smallint, c_int int, c_bigint bigint, c_money money, c_smallmoney smallmoney, c_numeric numeric(10,5),
  c_real real, c_decimal decimal(10,2), c_float float,
  c_char char(10), c_varchar varchar(10), c_text text,
  c_nchar nchar(12), c_nvarchar nvarchar(12), c_ntext ntext,
  c_datetime datetime,  c_datetime2 datetime2, c_smalldatetime smalldatetime, c_date date, c_time time, c_datetimeoffset datetimeoffset
)

INSERT INTO [mssql_types]
SELECT
  1, 5, 20020, 980300, 1420070400, '$20000.15', '£2.15', 12345.12,
  1.11, 2.22, 3.33,
  'char10', 'varchar10', 'text',
  N'☺nchar12☺', N'☺nvarchar12☺', N'☺text☺',
  GETDATE(), CAST(GETDATE() AS DATETIME2), CAST(GETDATE() AS SMALLDATETIME), CAST(GETDATE() AS DATE), CAST(GETDATE() AS TIME), SWITCHOFFSET(CAST(GETDATE() AS DATETIMEOFFSET), '-07:00'))

Query editor with example query:

The query:

SELECT * FROM [mssql_types]

You can control the name of the Table panel columns by using regular AS SQL column selection syntax. Example:

SELECT
  c_bit as [column1], c_tinyint as [column2]
FROM
  [mssql_types]

The resulting table panel:

Time series queries

If you set Format as to Time series, for use in Graph panel for example, then the query must must have a column named time that returns either a sql datetime or any numeric datatype representing Unix epoch in seconds. You may return a column named metric that is used as metric name for the value column. Any column except time and metric is treated as a value column. If you omit the metric column, the name of the value column will be the metric name. You may select multiple value columns, each will have its name as metric. If you return multiple value columns and a column named metric then this column is used as prefix for the series name (only available in Grafana 5.3+).

Resultsets of time series queries need to be sorted by time.

Example database table:

CREATE TABLE [event] (
  time_sec bigint,
  description nvarchar(100),
  tags nvarchar(100),
)

CREATE TABLE metric_values (
  time datetime,
  measurement nvarchar(100),
  valueOne int,
  valueTwo int,
)

INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 12:30:00', 'Metric A', 62, 6)
INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 12:30:00', 'Metric B', 49, 11)
...
INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 13:55:00', 'Metric A', 14, 25)
INSERT metric_values (time, measurement, valueOne, valueTwo) VALUES('2018-03-15 13:55:00', 'Metric B', 48, 10)

Example with one value and one metric column.

SELECT
  time,
  valueOne,
  measurement as metric
FROM
  metric_values
WHERE
  $__timeFilter(time)
ORDER BY 1

When above query are used in a graph panel the result will be two series named Metric A and Metric B with value of valueOne and valueTwo plotted over time.

Example with multiple value columns:

SELECT
  time,
  valueOne,
  valueTwo
FROM
  metric_values
WHERE
  $__timeFilter(time)
ORDER BY 1

When above query are used in a graph panel the result will be two series named valueOne and valueTwo with value of valueOne and valueTwo plotted over time.

Example using the $__timeGroup macro:

SELECT
  $__timeGroup(time, '3m') as time,
  measurement as metric,
  avg(valueOne)
FROM
  metric_values
WHERE
  $__timeFilter(time)
GROUP BY
  $__timeGroup(time, '3m'),
  measurement
ORDER BY 1

When above query are used in a graph panel the result will be two series named Metric A and Metric B with an average of valueOne plotted over time. Any two series lacking a value in a 3 minute window will render a line between those two lines. You’ll notice that the graph to the right never goes down to zero.

Example using the $__timeGroup macro with fill parameter set to zero:

SELECT
  $__timeGroup(time, '3m', 0) as time,
  measurement as metric,
  sum(valueTwo)
FROM
  metric_values
WHERE
  $__timeFilter(time)
GROUP BY
  $__timeGroup(time, '3m'),
  measurement
ORDER BY 1

When above query are used in a graph panel the result will be two series named Metric A and Metric B with a sum of valueTwo plotted over time. Any series lacking a value in a 3 minute window will have a value of zero which you’ll see rendered in the graph to the right.

Templating

Checkout the Templating documentation for an introduction to the templating feature and the different types of template variables.

Query Variable

If you add a template variable of the type Query, you can write a MSSQL query that can return things like measurement names, key names or key values that are shown as a dropdown select box.

For example, you can have a variable that contains all values for the hostname column in a table if you specify a query like this in the templating variable Query setting.

SELECT hostname FROM host

A query can return multiple columns and Grafana will automatically create a list from them. For example, the query below will return a list with values from hostname and hostname2.

SELECT [host].[hostname], [other_host].[hostname2] FROM host JOIN other_host ON [host].[city] = [other_host].[city]

Another option is a query that can create a key/value variable. The query should return two columns that are named __text and __value. The __text column value should be unique (if it is not unique then the first value is used). The options in the dropdown will have a text and value that allows you to have a friendly name as text and an id as the value. An example query with hostname as the text and id as the value:

SELECT hostname __text, id __value FROM host

You can also create nested variables. For example if you had another variable named region. Then you could have the hosts variable only show hosts from the current selected region with a query like this (if region is a multi-value variable then use the IN comparison operator rather than = to match against multiple values):

SELECT hostname FROM host WHERE region IN ($region)

Using Variables in Queries

From Grafana 4.3.0 to 4.6.0, template variables are always quoted automatically so if it is a string value do not wrap them in quotes in where clauses.

From Grafana 5.0.0, template variable values are only quoted when the template variable is a multi-value.

If the variable is a multi-value variable then use the IN comparison operator rather than = to match against multiple values.

There are two syntaxes:

$<varname> Example with a template variable named hostname:

SELECT
  atimestamp time,
  aint value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in($hostname)
ORDER BY atimestamp

[[varname]] Example with a template variable named hostname:

SELECT
  atimestamp as time,
  aint as value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
ORDER BY atimestamp

Disabling Quoting for Multi-value Variables

Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if server01 and server02 are selected then it will be formatted as: 'server01', 'server02'. Do disable quoting, use the csv formatting option for variables:

${servers:csv}

Read more about variable formatting options in the Variables documentation.

Annotations

Annotations allows you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view.

Columns:

Name	Description
time	The name of the date/time field. Could be a column with a native sql date/time data type or epoch value.
text	Event description field.
tags	Optional field name to use for event tags as a comma separated string.

Example database tables:

CREATE TABLE [events] (
  time_sec bigint,
  description nvarchar(100),
  tags nvarchar(100),
)

We also use the database table defined in Time series queries.

Example query using time column with epoch values:

SELECT
  time_sec as time,
  description as [text],
  tags
FROM
  [events]
WHERE
  $__unixEpochFilter(time_sec)
ORDER BY 1

Example query using time column of native sql date/time data type:

SELECT
  time,
  measurement as text,
  convert(varchar, valueOne) + ',' + convert(varchar, valueTwo) as tags
FROM
  metric_values
WHERE
  $__timeFilter(time_column)
ORDER BY 1

Stored procedure support

Stored procedures have been verified to work. However, please note that we haven’t done anything special to support this why there may exist edge cases where it won’t work as you would expect. Stored procedures should be supported in table, time series and annotation queries as long as you use the same naming of columns and return data in the same format as describe above under respective section.

Please note that any macro function will not work inside a stored procedure.

Examples

For the following examples the database table defined in Time series queries. Let’s say that we want to visualize 4 series in a graph panel, i.e. all combinations of columns valueOne, valueTwo and measurement. Graph panel to the right visualizes what we want to achieve. To solve this we actually need to use two queries:

First query:

SELECT
  $__timeGroup(time, '5m') as time,
  measurement + ' - value one' as metric,
  avg(valueOne) as valueOne
FROM
  metric_values
WHERE
  $__timeFilter(time)
GROUP BY
  $__timeGroup(time, '5m'),
  measurement
ORDER BY 1

Second query:

SELECT
  $__timeGroup(time, '5m') as time,
  measurement + ' - value two' as metric,
  avg(valueTwo) as valueTwo
FROM
  metric_values
GROUP BY
  $__timeGroup(time, '5m'),
  measurement
ORDER BY 1

Stored procedure using time in epoch format

We can define a stored procedure that will return all data we need to render 4 series in a graph panel like above. In this case the stored procedure accepts two parameters @from and @to of int data types which should be a timerange (from-to) in epoch format which will be used to filter the data to return from the stored procedure.

We’re mimicking the $__timeGroup(time, '5m') in the select and group by expressions and that’s why there’s a lot of lengthy expressions needed - these could be extracted to MSSQL functions, if wanted.

CREATE PROCEDURE sp_test_epoch(
  @from int,
  @to 	int
)	AS
BEGIN
  SELECT
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int) as time,
    measurement + ' - value one' as metric,
    avg(valueOne) as value
  FROM
    metric_values
  WHERE
    time >= DATEADD(s, @from, '1970-01-01') AND time <= DATEADD(s, @to, '1970-01-01')
  GROUP BY
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int),
    measurement
  UNION ALL
  SELECT
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int) as time,
    measurement + ' - value two' as metric,
    avg(valueTwo) as value
  FROM
    metric_values
  WHERE
    time >= DATEADD(s, @from, '1970-01-01') AND time <= DATEADD(s, @to, '1970-01-01')
  GROUP BY
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, DATEADD(second, DATEDIFF(second,GETDATE(),GETUTCDATE()), time))/600 as int)*600 as int),
    measurement
  ORDER BY 1
END

Then we can use the following query for our graph panel.

DECLARE
  @from int = $__unixEpochFrom(),
  @to int = $__unixEpochTo()

EXEC dbo.sp_test_epoch @from, @to

Stored procedure using time in datetime format

We can define a stored procedure that will return all data we need to render 4 series in a graph panel like above. In this case the stored procedure accepts two parameters @from and @to of datetime data types which should be a timerange (from-to) which will be used to filter the data to return from the stored procedure.

CREATE PROCEDURE sp_test_datetime(
  @from datetime,
  @to 	datetime
)	AS
BEGIN
  SELECT
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int) as time,
    measurement + ' - value one' as metric,
    avg(valueOne) as value
  FROM
    metric_values
  WHERE
    time >= @from AND time <= @to
  GROUP BY
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int),
    measurement
  UNION ALL
  SELECT
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int) as time,
    measurement + ' - value two' as metric,
    avg(valueTwo) as value
  FROM
    metric_values
  WHERE
    time >= @from AND time <= @to
  GROUP BY
    cast(cast(DATEDIFF(second, {d '1970-01-01'}, time)/600 as int)*600 as int),
    measurement
  ORDER BY 1
END

Then we can use the following query for our graph panel.

DECLARE
  @from datetime = $__timeFrom(),
  @to datetime = $__timeTo()

EXEC dbo.sp_test_datetime @from, @to

Alerting

Time series queries should work in alerting conditions. Table formatted queries are not yet supported in alert rule conditions.

Configure the data source with provisioning

Here are some provisioning examples for this data source.

apiVersion: 1

datasources:
  - name: MSSQL
    type: mssql
    url: localhost:1433
    database: grafana
    user: grafana
    jsonData:
      maxOpenConns: 0         # Grafana v5.4+
      maxIdleConns: 2         # Grafana v5.4+
      connMaxLifetime: 14400  # Grafana v5.4+
    secureJsonData:
      password: "Password!"

Using MySQL in Grafana

Fri, 06 Mar 2026 22:21:21 +0000

Using MySQL in Grafana

Only available in Grafana v4.3+.

Starting from Grafana v5.1 you can name the time column time in addition to earlier supported time_sec. Usage of time_sec will eventually be deprecated.

Grafana ships with a built-in MySQL data source plugin that allow you to query any visualize data from a MySQL compatible database.

Adding the data source

Open the side menu by clicking the Grafana icon in the top header.
In the side menu under the Dashboards link you should find a link named Data Sources.
Click the + Add data source button in the top header.
Select MySQL from the Type dropdown.

Data source options

Name	Description
Name	The data source name. This is how you refer to the data source in panels and queries.
Default	Default data source means that it will be pre-selected for new panels.
Host	The IP address/hostname and optional port of your MySQL instance.
Database	Name of your MySQL database.
User	Database user’s login/username
Password	Database user’s password
Max open	The maximum number of open connections to the database, default `unlimited` (Grafana v5.4+).
Max idle	The maximum number of connections in the idle connection pool, default `2` (Grafana v5.4+).
Max lifetime	The maximum amount of time in seconds a connection may be reused, default `14400`/4 hours. This should always be lower than configured wait_timeout in MySQL (Grafana v5.4+).

Min time interval

Identifier	Description
`y`	year
`M`	month
`w`	week
`d`	day
`h`	hour
`m`	minute
`s`	second
`ms`	millisecond

Database User Permissions (Important!)

The database user you specify when you add the data source should only be granted SELECT permissions on the specified database and tables you want to query. Grafana does not validate that the query is safe. The query could include any SQL statement. For example, statements like USE otherdb; and DROP TABLE user; would be executed. To protect against this we Highly recommend you create a specific mysql user with restricted permissions.

Example:

 CREATE USER 'grafanaReader' IDENTIFIED BY 'password';
 GRANT SELECT ON mydatabase.mytable TO 'grafanaReader';

You can use wildcards (*) in place of database or table if you want to grant access to more databases and tables.

Query Editor

Only available in Grafana v5.4+.

You find the MySQL query editor in the metrics tab in a panel’s edit mode. You enter edit mode by clicking the panel title, then edit.

Select table, time column and metric column (FROM)

When you enter edit mode for the first time or add a new query Grafana will try to prefill the query builder with the first table that has a timestamp column and a numeric column.

In the FROM field, Grafana will suggest tables that are in the configured database. To select a table or view in another database that your database user has access to you can manually enter a fully qualified name (database.table) like otherDb.metrics.

The Time column field refers to the name of the column holding your time values. Selecting a value for the Metric column field is optional. If a value is selected, the Metric column field will be used as the series name.

The metric column suggestions will only contain columns with a text datatype (text, tinytext, mediumtext, longtext, varchar, char). If you want to use a column with a different datatype as metric column you may enter the column name with a cast: CAST(numericColumn as CHAR). You may also enter arbitrary SQL expressions in the metric column field that evaluate to a text datatype like CONCAT(column1, " ", CAST(numericColumn as CHAR)).

Columns and Aggregation functions (SELECT)

In the SELECT row you can specify what columns and functions you want to use. In the column field you may write arbitrary expressions instead of a column name like column1 * column2 / column3.

If you use aggregate functions you need to group your resultset. The editor will automatically add a GROUP BY time if you add an aggregate function.

You may add further value columns by clicking the plus button and selecting Column from the menu. Multiple value columns will be plotted as separate series in the graph panel.

Filter data (WHERE)

To add a filter click the plus icon to the right of the WHERE condition. You can remove filters by clicking on the filter and selecting Remove. A filter for the current selected timerange is automatically added to new queries.

Group By

To group by time or any other columns click the plus icon at the end of the GROUP BY row. The suggestion dropdown will only show text columns of your currently selected table but you may manually enter any column. You can remove the group by clicking on the item and then selecting Remove.

If you add any grouping, all selected columns need to have an aggregate function applied. The query builder will automatically add aggregate functions to all columns without aggregate functions when you add groupings.

Gap Filling

Grafana can fill in missing values when you group by time. The time function accepts two arguments. The first argument is the time window that you would like to group by, and the second argument is the value you want Grafana to fill missing items with.

Text Editor Mode (RAW)

You can switch to the raw query editor mode by clicking the hamburger icon and selecting Switch editor mode or by clicking Edit SQL below the query.

If you use the raw query editor, be sure your query at minimum has ORDER BY time and a filter on the returned time range.

Macros

To simplify syntax and to allow for dynamic parts, like date range filters, the query can contain macros.

Macro example	Description
$__time(dateColumn)	Will be replaced by an expression to convert to a UNIX timestamp and rename the column to `time_sec`. For example, UNIX_TIMESTAMP(dateColumn) as time_sec
$__timeEpoch(dateColumn)	Will be replaced by an expression to convert to a UNIX timestamp and rename the column to `time_sec`. For example, UNIX_TIMESTAMP(dateColumn) as time_sec
$__timeFilter(dateColumn)	Will be replaced by a time range filter using the specified column name. For example, dateColumn BETWEEN FROM_UNIXTIME(1494410783) AND FROM_UNIXTIME(1494410983)
$__timeFrom()	Will be replaced by the start of the currently active time selection. For example, FROM_UNIXTIME(1494410783)
$__timeTo()	Will be replaced by the end of the currently active time selection. For example, FROM_UNIXTIME(1494410983)
$__timeGroup(dateColumn,‘5m’)	Will be replaced by an expression usable in GROUP BY clause. For example, cast(cast(UNIX_TIMESTAMP(dateColumn)/(300) as signed)300 as signed),*
$__timeGroup(dateColumn,‘5m’, 0)	Same as above but with a fill parameter so missing points in that series will be added by grafana and 0 will be used as value.
$__timeGroup(dateColumn,‘5m’, NULL)	Same as above but NULL will be used as value for missing points.
$__timeGroup(dateColumn,‘5m’, previous)	Same as above but the previous value in that series will be used as fill value if no value has been seen yet NULL will be used (only available in Grafana 5.3+).
$__timeGroupAlias(dateColumn,‘5m’)	Will be replaced identical to $__timeGroup but with an added column alias (only available in Grafana 5.3+).
$__unixEpochFilter(dateColumn)	Will be replaced by a time range filter using the specified column name with times represented as Unix timestamp. For example, dateColumn > 1494410783 AND dateColumn < 1494497183
$__unixEpochFrom()	Will be replaced by the start of the currently active time selection as Unix timestamp. For example, 1494410783
$__unixEpochTo()	Will be replaced by the end of the currently active time selection as Unix timestamp. For example, 1494497183
$__unixEpochNanoFilter(dateColumn)	Will be replaced by a time range filter using the specified column name with times represented as nanosecond timestamp. For example, dateColumn > 1494410783152415214 AND dateColumn < 1494497183142514872
$__unixEpochNanoFrom()	Will be replaced by the start of the currently active time selection as nanosecond timestamp. For example, 1494410783152415214
$__unixEpochNanoTo()	Will be replaced by the end of the currently active time selection as nanosecond timestamp. For example, 1494497183142514872
$__unixEpochGroup(dateColumn,‘5m’, [fillmode])	Same as $__timeGroup but for times stored as Unix timestamp (only available in Grafana 5.3+).
$__unixEpochGroupAlias(dateColumn,‘5m’, [fillmode])	Same as above but also adds a column alias (only available in Grafana 5.3+).

We plan to add many more macros. If you have suggestions for what macros you would like to see, please open an issue in our GitHub repo.

The query editor has a link named Generated SQL that show up after a query as been executed, while in panel edit mode. Click on it and it will expand and show the raw interpolated SQL string that was executed.

Table queries

If the Format as query option is set to Table then you can basically do any type of SQL query. The table panel will automatically show the results of whatever columns and rows your query returns.

Query editor with example query:

The query:

SELECT
  title as 'Title',
  user.login as 'Created By' ,
  dashboard.created as 'Created On'
 FROM dashboard
INNER JOIN user on user.id = dashboard.created_by
WHERE $__timeFilter(dashboard.created)

You can control the name of the Table panel columns by using regular as SQL column selection syntax.

The resulting table panel:

Time series queries

If you set Format as to Time series, for use in Graph panel for example, then the query must return a column named time that returns either a sql datetime or any numeric datatype representing Unix epoch. Any column except time and metric is treated as a value column. You may return a column named metric that is used as metric name for the value column. If you return multiple value columns and a column named metric then this column is used as prefix for the series name (only available in Grafana 5.3+).

Resultsets of time series queries need to be sorted by time.

Example with metric column:

SELECT
  $__timeGroup(time_date_time,'5m'),
  min(value_double),
  'min' as metric
FROM test_data
WHERE $__timeFilter(time_date_time)
GROUP BY time
ORDER BY time

Example using the fill parameter in the $__timeGroup macro to convert null values to be zero instead:

SELECT
  $__timeGroup(createdAt,'5m',0),
  sum(value_double) as value,
  measurement
FROM test_data
WHERE
  $__timeFilter(createdAt)
GROUP BY time, measurement
ORDER BY time

Example with multiple columns:

SELECT
  $__timeGroup(time_date_time,'5m'),
  min(value_double) as min_value,
  max(value_double) as max_value
FROM test_data
WHERE $__timeFilter(time_date_time)
GROUP BY time
ORDER BY time

Currently, there is no support for a dynamic group by time based on time range and panel width. This is something we plan to add.

Templating

This feature is currently available in the nightly builds and will be included in the 5.0.0 release.

Checkout the Templating documentation for an introduction to the templating feature and the different types of template variables.

Query Variable

If you add a template variable of the type Query, you can write a MySQL query that can return things like measurement names, key names or key values that are shown as a dropdown select box.

For example, you can have a variable that contains all values for the hostname column in a table if you specify a query like this in the templating variable Query setting.

SELECT hostname FROM my_host

A query can returns multiple columns and Grafana will automatically create a list from them. For example, the query below will return a list with values from hostname and hostname2.

SELECT my_host.hostname, my_other_host.hostname2 FROM my_host JOIN my_other_host ON my_host.city = my_other_host.city

To use time range dependent macros like $__timeFilter(column) in your query the refresh mode of the template variable needs to be set to On Time Range Change.

SELECT event_name FROM event_log WHERE $__timeFilter(time_column)

SELECT hostname AS __text, id AS __value FROM my_host

SELECT hostname FROM my_host  WHERE region IN($region)

Using `__searchFilter` to filter results in Query Variable

Available from Grafana 6.5 and above

Important that you surround the __searchFilter expression with quotes as Grafana does not do this for you.

The example below shows how to use __searchFilter as part of the query field to enable searching for hostname while the user types in the dropdown select box.

Query

SELECT hostname FROM my_host  WHERE hostname LIKE '$__searchFilter'

Using Variables in Queries

From Grafana 4.3.0 to 4.6.0, template variables are always quoted automatically so if it is a string value do not wrap them in quotes in where clauses.

From Grafana 4.7.0, template variable values are only quoted when the template variable is a multi-value.

If the variable is a multi-value variable then use the IN comparison operator rather than = to match against multiple values.

There are two syntaxes:

$<varname> Example with a template variable named hostname:

SELECT
  UNIX_TIMESTAMP(atimestamp) as time,
  aint as value,
  avarchar as metric
FROM my_table
WHERE $__timeFilter(atimestamp) and hostname in($hostname)
ORDER BY atimestamp ASC

[[varname]] Example with a template variable named hostname:

SELECT
  UNIX_TIMESTAMP(atimestamp) as time,
  aint as value,
  avarchar as metric
FROM my_table
WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
ORDER BY atimestamp ASC

Disabling Quoting for Multi-value Variables

${servers:csv}

Read more about variable formatting options in the Variables documentation.

Annotations

Annotations allow you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view.

Example query using time column with epoch values:

SELECT
  epoch_time as time,
  metric1 as text,
  CONCAT(tag1, ',', tag2) as tags
FROM
  public.test_data
WHERE
  $__unixEpochFilter(epoch_time)

Example query using time column of native sql date/time data type:

SELECT
  native_date_time as time,
  metric1 as text,
  CONCAT(tag1, ',', tag2) as tags
FROM
  public.test_data
WHERE
  $__timeFilter(native_date_time)

Name	Description
time	The name of the date/time field. Could be a column with a native sql date/time data type or epoch value.
text	Event description field.
tags	Optional field name to use for event tags as a comma separated string.

Alerting

Time series queries should work in alerting conditions. Table formatted queries is not yet supported in alert rule conditions.

Configure the data source with provisioning

Here are some provisioning examples for this data source.

apiVersion: 1

datasources:
  - name: MySQL
    type: mysql
    url: localhost:3306
    database: grafana
    user: grafana
    password: password
    jsonData:
      maxOpenConns: 0         # Grafana v5.4+
      maxIdleConns: 2         # Grafana v5.4+
      connMaxLifetime: 14400  # Grafana v5.4+

Using OpenTSDB in Grafana

Fri, 06 Mar 2026 22:21:21 +0000

Using OpenTSDB in Grafana

Grafana ships with advanced support for OpenTSDB.

Adding the data source

Open the side menu by clicking the Grafana icon in the top header.
In the side menu under the Dashboards link you should find a link named Data Sources.
Click the + Add data source button in the top header.
Select OpenTSDB from the Type dropdown.

NOTE: If you’re not seeing the Data Sources link in your side menu it means that your current user does not have the Admin role for the current organization.

Name	Description
Name	The data source name. This is how you refer to the data source in panels and queries.
Default	Default data source means that it will be pre-selected for new panels.
Url	The HTTP protocol, ip and port of you opentsdb server (default port is usually 4242)
Access	Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser.
Version	Version = opentsdb version, either <=2.1 or 2.2
Resolution	Metrics from opentsdb may have datapoints with either second or millisecond resolution.

Query editor

Open a graph in edit mode by click the title. Query editor will differ if the data source has version <=2.1 or = 2.2. In the former version, only tags can be used to query OpenTSDB. But in the latter version, filters as well as tags can be used to query opentsdb. Fill Policy is also introduced in OpenTSDB 2.2.

Note: While using OpenTSDB 2.2 data source, make sure you use either Filters or Tags as they are mutually exclusive. If used together, might give you weird results.

Auto complete suggestions

As soon as you start typing metric names, tag names and tag values , you should see highlighted auto complete suggestions for them. The autocomplete only works if the OpenTSDB suggest api is enabled.

Templating queries

Checkout the Templating documentation for an introduction to the templating feature and the different types of template variables.

Query variable

Grafana’s OpenTSDB data source supports template variable queries. This means you can create template variables that fetch the values from OpenTSDB. For example, metric names, tag names, or tag values.

When using OpenTSDB with a template variable of query type you can use following syntax for lookup.

Query	Description
metrics(prefix)	Returns metric names with specific prefix (can be empty)
tag_names(cpu)	Return tag names (i.e. keys) for a specific cpu metric
tag_values(cpu, hostname)	Return tag values for metric cpu and tag key hostname
suggest_tagk(prefix)	Return tag names (i.e. keys) for all metrics with specific prefix (can be empty)
suggest_tagv(prefix)	Return tag values for all metrics with specific prefix (can be empty)

If you do not see template variables being populated in Preview of values section, you need to enable tsd.core.meta.enable_realtime_ts in the OpenTSDB server settings. Also, to populate metadata of the existing time series data in OpenTSDB, you need to run tsdb uid metasync on the OpenTSDB server.

Nested Templating

One template variable can be used to filter tag values for another template variable. First parameter is the metric name, second parameter is the tag key for which you need to find tag values, and after that all other dependent template variables. Some examples are mentioned below to make nested template queries work successfully.

Query	Description
tag_values(cpu, hostname, env=$env)	Return tag values for cpu metric, selected env tag value and tag key hostname
tag_values(cpu, hostname, env=$env, region=$region)	Return tag values for cpu metric, selected env tag value, selected region tag value and tag key hostname

For details on OpenTSDB metric queries checkout the official OpenTSDB documentation

Configure the data source with provisioning

Here are some provisioning examples for this data source.

apiVersion: 1

datasources:
  - name: OpenTsdb
    type: opentsdb
    access: proxy
    url: http://localhost:4242
    jsonData:
      tsdbResolution: 1
      tsdbVersion: 1

Using PostgreSQL in Grafana

Fri, 06 Mar 2026 22:21:21 +0000

Using PostgreSQL in Grafana

NOTE: In 9.5.18, 9.4.23, 9.6.14, 10.9, 11.4, 12-beta2 versions of PostgreSQL has a bug which prevents execution of multiple column modifications via ALTER TABLE statement. Because Grafana uses it during initial database set up and since PostgreSQL has fixed this issue, Grafana does not support these versions

Grafana ships with a built-in PostgreSQL data source plugin that allows you to query and visualize data from a PostgreSQL compatible database.

Adding the data source

Open the side menu by clicking the Grafana icon in the top header.
In the side menu under the Configuration icon you should find a link named Data Sources.
Click the + Add data source button in the top header.
Select PostgreSQL from the Type dropdown.

Data source options

Name	Description
Name	The data source name. This is how you refer to the data source in panels and queries.
Default	Default data source means that it will be pre-selected for new panels.
Host	The IP address/hostname and optional port of your PostgreSQL instance.
Database	Name of your PostgreSQL database.
User	Database user’s login/username
Password	Database user’s password
SSL Mode	This option determines whether or with what priority a secure SSL TCP/IP connection will be negotiated with the server.
Max open	The maximum number of open connections to the database, default `unlimited` (Grafana v5.4+).
Max idle	The maximum number of connections in the idle connection pool, default `2` (Grafana v5.4+).
Max lifetime	The maximum amount of time in seconds a connection may be reused, default `14400`/4 hours (Grafana v5.4+).
Version	This option determines which functions are available in the query builder (only available in Grafana 5.3+).
TimescaleDB	TimescaleDB is a time-series database built as a PostgreSQL extension. If enabled, Grafana will use `time_bucket` in the `$__timeGroup` macro and display TimescaleDB specific aggregate functions in the query builder (only available in Grafana 5.3+).

Min time interval

Identifier	Description
`y`	year
`M`	month
`w`	week
`d`	day
`h`	hour
`m`	minute
`s`	second
`ms`	millisecond

Database User Permissions (Important!)

The database user you specify when you add the data source should only be granted SELECT permissions on the specified database and tables you want to query. Grafana does not validate that the query is safe. The query could include any SQL statement. For example, statements like DELETE FROM user; and DROP TABLE user; would be executed. To protect against this we highly recommend you create a specific PostgreSQL user with restricted permissions.

Example:

 CREATE USER grafanareader WITH PASSWORD 'password';
 GRANT USAGE ON SCHEMA schema TO grafanareader;
 GRANT SELECT ON schema.table TO grafanareader;

Make sure the user does not get any unwanted privileges from the public role.

Query Editor

Only available in Grafana v5.3+.

You find the PostgreSQL query editor in the metrics tab in Graph or Singlestat panel’s edit mode. You enter edit mode by clicking the panel title, then edit.

Select table, time column and metric column (FROM)

When you enter edit mode for the first time or add a new query Grafana will try to prefill the query builder with the first table that has a timestamp column and a numeric column.

In the FROM field, Grafana will suggest tables that are in the search_path of the database user. To select a table or view not in your search_path you can manually enter a fully qualified name (schema.table) like public.metrics.

The metric column suggestions will only contain columns with a text datatype (char,varchar,text). If you want to use a column with a different datatype as metric column you may enter the column name with a cast: ip::text. You may also enter arbitrary SQL expressions in the metric column field that evaluate to a text datatype like hostname || ' ' || container_name.

Columns, Window and Aggregation functions (SELECT)

In the SELECT row you can specify what columns and functions you want to use. In the column field you may write arbitrary expressions instead of a column name like column1 * column2 / column3.

The available functions in the query editor depend on the PostgreSQL version you selected when configuring the data source. If you use aggregate functions you need to group your resultset. The editor will automatically add a GROUP BY time if you add an aggregate function.

The editor tries to simplify and unify this part of the query. For example:

The above will generate the following PostgreSQL SELECT clause:

avg(tx_bytes) OVER (ORDER BY "time" ROWS 5 PRECEDING) AS "tx_bytes"

You may add further value columns by clicking the plus button and selecting Column from the menu. Multiple value columns will be plotted as separate series in the graph panel.

Filter data (WHERE)

Group By

Gap Filling

Text Editor Mode (RAW)

You can switch to the raw query editor mode by clicking the hamburger icon and selecting Switch editor mode or by clicking Edit SQL below the query.

If you use the raw query editor, be sure your query at minimum has ORDER BY time and a filter on the returned time range.

Macros

Macros can be used within a query to simplify syntax and allow for dynamic parts.

Macro example	Description
$__time(dateColumn)	Will be replaced by an expression to rename the column to `time`. For example, dateColumn as time
$__timeSec(dateColumn)	Will be replaced by an expression to rename the column to `time` and converting the value to Unix timestamp. For example, extract(epoch from dateColumn) as time
$__timeFilter(dateColumn)	Will be replaced by a time range filter using the specified column name. For example, dateColumn BETWEEN ‘2017-04-21T05:01:17Z’ AND ‘2017-04-21T05:06:17Z’
$__timeFrom()	Will be replaced by the start of the currently active time selection. For example, ‘2017-04-21T05:01:17Z’
$__timeTo()	Will be replaced by the end of the currently active time selection. For example, ‘2017-04-21T05:06:17Z’
$__timeGroup(dateColumn,‘5m’)	Will be replaced by an expression usable in a GROUP BY clause. For example, (extract(epoch from dateColumn)/300)::bigint300*
$__timeGroup(dateColumn,‘5m’, 0)	Same as above but with a fill parameter so missing points in that series will be added by Grafana and 0 will be used as the value.
$__timeGroup(dateColumn,‘5m’, NULL)	Same as above but NULL will be used as value for missing points.
$__timeGroup(dateColumn,‘5m’, previous)	Same as above but the previous value in that series will be used as fill value. If no value has been seen yet, NULL will be used (only available in Grafana 5.3+).
$__timeGroupAlias(dateColumn,‘5m’)	Will be replaced with an expression identical to $__timeGroup, but with an added column alias (only available in Grafana 5.3+).
$__unixEpochFilter(dateColumn)	Will be replaced by a time range filter using the specified column name with times represented as Unix timestamps. For example, dateColumn >= 1494410783 AND dateColumn <= 1494497183
$__unixEpochFrom()	Will be replaced by the start of the currently active time selection as Unix timestamp. For example, 1494410783
$__unixEpochTo()	Will be replaced by the end of the currently active time selection as Unix timestamp. For example, 1494497183
$__unixEpochNanoFilter(dateColumn)	Will be replaced by a time range filter using the specified column name with times represented as nanosecond timestamps. For example, dateColumn >= 1494410783152415214 AND dateColumn <= 1494497183142514872
$__unixEpochNanoFrom()	Will be replaced by the start of the currently active time selection as nanosecond timestamp. For example, 1494410783152415214
$__unixEpochNanoTo()	Will be replaced by the end of the currently active time selection as Unix timestamp. For example, 1494497183142514872
$__unixEpochGroup(dateColumn,‘5m’, [fillmode])	Same as $__timeGroup, but for times stored as Unix timestamp (only available in Grafana 5.3+).
$__unixEpochGroupAlias(dateColumn,‘5m’, [fillmode])	Same as above, but also adds a column alias (only available in Grafana 5.3+).

We plan to add many more macros. If you have suggestions for what macros you would like to see, please open an issue in our GitHub repo.

Table queries

If the Format as query option is set to Table then you can basically do any type of SQL query. The table panel will automatically show the results of whatever columns and rows your query returns.

Query editor with example query:

The query:

SELECT
  title as "Title",
  "user".login as "Created By",
  dashboard.created as "Created On"
FROM dashboard
INNER JOIN "user" on "user".id = dashboard.created_by
WHERE $__timeFilter(dashboard.created)

You can control the name of the Table panel columns by using regular as SQL column selection syntax.

The resulting table panel:

Time series queries

If you set Format as to Time series, for use in Graph panel for example, then the query must return a column named time that returns either a SQL datetime or any numeric datatype representing Unix epoch. Any column except time and metric are treated as a value column. You may return a column named metric that is used as metric name for the value column. If you return multiple value columns and a column named metric then this column is used as prefix for the series name (only available in Grafana 5.3+).

Resultsets of time series queries need to be sorted by time.

Example with metric column:

SELECT
  $__timeGroup("time_date_time",'5m'),
  min("value_double"),
  'min' as metric
FROM test_data
WHERE $__timeFilter("time_date_time")
GROUP BY time
ORDER BY time

Example using the fill parameter in the $__timeGroup macro to convert null values to be zero instead:

SELECT
  $__timeGroup("createdAt",'5m',0),
  sum(value) as value,
  measurement
FROM test_data
WHERE
  $__timeFilter("createdAt")
GROUP BY time, measurement
ORDER BY time

Example with multiple columns:

SELECT
  $__timeGroup("time_date_time",'5m'),
  min("value_double") as "min_value",
  max("value_double") as "max_value"
FROM test_data
WHERE $__timeFilter("time_date_time")
GROUP BY time
ORDER BY time

Templating

Checkout the Templating documentation for an introduction to the templating feature and the different types of template variables.

Query Variable

If you add a template variable of the type Query, you can write a PostgreSQL query that can return things like measurement names, key names or key values that are shown as a dropdown select box.

For example, you can have a variable that contains all values for the hostname column in a table if you specify a query like this in the templating variable Query setting.

SELECT hostname FROM host

A query can return multiple columns and Grafana will automatically create a list from them. For example, the query below will return a list with values from hostname and hostname2.

SELECT host.hostname, other_host.hostname2 FROM host JOIN other_host ON host.city = other_host.city

To use time range dependent macros like $__timeFilter(column) in your query the refresh mode of the template variable needs to be set to On Time Range Change.

SELECT event_name FROM event_log WHERE $__timeFilter(time_column)

SELECT hostname AS __text, id AS __value FROM host

You can also create nested variables. Using a variable named region, you could have the hosts variable only show hosts from the current selected region with a query like this (if region is a multi-value variable then use the IN comparison operator rather than = to match against multiple values):

SELECT hostname FROM host  WHERE region IN($region)

Using `__searchFilter` to filter results in Query Variable

Available from Grafana 6.5 and above

Important that you surround the __searchFilter expression with quotes as Grafana does not do this for you.

The example below shows how to use __searchFilter as part of the query field to enable searching for hostname while the user types in the dropdown select box.

Query

SELECT hostname FROM my_host  WHERE hostname LIKE '$__searchFilter'

Using Variables in Queries

From Grafana 4.3.0 to 4.6.0, template variables are always quoted automatically. If your template variables are strings, do not wrap them in quotes in where clauses.

From Grafana 4.7.0, template variable values are only quoted when the template variable is a multi-value.

If the variable is a multi-value variable then use the IN comparison operator rather than = to match against multiple values.

There are two syntaxes:

$<varname> Example with a template variable named hostname:

SELECT
  atimestamp as time,
  aint as value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in($hostname)
ORDER BY atimestamp ASC

[[varname]] Example with a template variable named hostname:

SELECT
  atimestamp as time,
  aint as value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
ORDER BY atimestamp ASC

Disabling Quoting for Multi-value Variables

Grafana automatically creates a quoted, comma-separated string for multi-value variables. For example: if server01 and server02 are selected then it will be formatted as: 'server01', 'server02'. To disable quoting, use the csv formatting option for variables:

${servers:csv}

Read more about variable formatting options in the Variables documentation.

Annotations

Annotations allow you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view.

Example query using time column with epoch values:

SELECT
  epoch_time as time,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM
  public.test_data
WHERE
  $__unixEpochFilter(epoch_time)

Example query using time column of native sql date/time data type:

SELECT
  native_date_time as time,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM
  public.test_data
WHERE
  $__timeFilter(native_date_time)

Name	Description
time	The name of the date/time field. Could be a column with a native sql date/time data type or epoch value.
text	Event description field.
tags	Optional field name to use for event tags as a comma separated string.

Alerting

Time series queries should work in alerting conditions. Table formatted queries are not yet supported in alert rule conditions.

Configure the data source with provisioning

Here are some provisioning examples for this data source.

apiVersion: 1

datasources:
  - name: Postgres
    type: postgres
    url: localhost:5432
    database: grafana
    user: grafana
    secureJsonData:
      password: "Password!"
    jsonData:
      sslmode: "disable" # disable/require/verify-ca/verify-full
      maxOpenConns: 0         # Grafana v5.4+
      maxIdleConns: 2         # Grafana v5.4+
      connMaxLifetime: 14400  # Grafana v5.4+
      postgresVersion: 903 # 903=9.3, 904=9.4, 905=9.5, 906=9.6, 1000=10
      timescaledb: false

Using Prometheus in Grafana

Fri, 06 Mar 2026 22:21:21 +0000

Using Prometheus in Grafana

Grafana includes built-in support for Prometheus.

Adding the data source

Open the side menu by clicking the Grafana icon in the top header.
In the side menu under the Dashboards link you should find a link named Data Sources.
Click the + Add data source button in the top header.
Select Prometheus from the Type dropdown.

NOTE: If you’re not seeing the Data Sources link in your side menu it means that your current user does not have the Admin role for the current organization.

Data source options

Name	Description
Name	The data source name. This is how you refer to the data source in panels and queries.
Default	Default data source means that it will be pre-selected for new panels.
Url	The HTTP protocol, ip and port of you Prometheus server (default port is usually 9090)
Access	Server (default) = URL needs to be accessible from the Grafana backend/server, Browser = URL needs to be accessible from the browser.
Basic Auth	Enable basic authentication to the Prometheus data source.
User	Name of your Prometheus user
Password	Database user’s password
Scrape interval	This will be used as a lower limit for the Prometheus step query parameter. Default value is 15s.
Custom Query Parameters	Add custom parameters to the Prometheus query URL. For example `timeout`, `partial_response`, `dedup` or `max_source_resolution`. Multiple parameters should be concatenated together with an ‘&’.

Query editor

Open a graph in edit mode by click the title > Edit (or by pressing e key while hovering over panel).

Name	Description
Query expression	Prometheus query expression, check out the Prometheus documentation.
Legend format	Controls the name of the time series, using name or pattern. For example `{{hostname}}` will be replaced with label value for the label `hostname`.
Min step	Set a lower limit for the Prometheus step option. Step controls how big the jumps are when the Prometheus query engine performs range queries. Sadly there is no official prometheus documentation to link to for this very important option.
Resolution	Controls the step option. Small steps create high-resolution graphs but can be slow over larger time ranges, lowering the resolution can speed things up. `1/2` will try to set step option to generate 1 data point for every other pixel. A value of `1/10` will try to set step option so there is a data point every 10 pixels.
Metric lookup	Search for metric names in this input field.
Format as	Switch between Table, Time series or Heatmap. Table format will only work in the Table panel. Heatmap format is suitable for displaying metrics having histogram type on Heatmap panel. Under the hood, it converts cumulative histogram to regular and sorts series by the bucket bound.
Instant	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.

NOTE: Grafana slightly modifies the request dates for queries to align them with the dynamically calculated step. This ensures consistent display of metrics data but can result in a small gap of data at the right edge of a graph.

Instant queries

The Prometheus datasource allows you to run “instant” queries, which queries only the latest value. You can visualize the results in a table panel to see all available labels of a timeseries.

Instant query results are made up only of one datapoint per series but can be shown in the graph panel with the help of series overrides. To show them in the graph as a latest value point, add a series override and select Points > true. To show a horizontal line across the whole graph, add a series override and select Transform > constant.

Support for constant series overrides is available from Grafana v6.4

Templating

Instead of hard-coding things like server, application and sensor name in your metric queries, you can use variables in their place. Variables are shown as dropdown select boxes at the top of the dashboard. These dropdowns makes it easy to change the data being displayed in your dashboard.

Checkout the Templating documentation for an introduction to the templating feature and the different types of template variables.

Query variable

Variable of the type Query allows you to query Prometheus for a list of metrics, labels or label values. The Prometheus data source plugin provides the following functions you can use in the Query input field.

Name	Description
label_names()	Returns a list of label names.
label_values(label)	Returns a list of label values for the `label` in every metric.
label_values(metric, label)	Returns a list of label values for the `label` in the specified metric.
metrics(metric)	Returns a list of metrics matching the specified `metric` regex.
query_result(query)	Returns a list of Prometheus query result for the `query`.

For details of metric names, label names and label values are please refer to the Prometheus documentation.

Using interval and range variables

Support for $__range, $__range_s and $__range_ms only available from Grafana v5.3

It’s possible to use some global built-in variables in query variables; $__interval, $__interval_ms, $__range, $__range_s and $__range_ms, see Global built-in variables for more information. These can be convenient to use in conjunction with the query_result function when you need to filter variable queries since label_values function doesn’t support queries.

Make sure to set the variable’s refresh trigger to be On Time Range Change to get the correct instances when changing the time range on the dashboard.

Example usage:

Populate a variable with the the busiest 5 request instances based on average QPS over the time range shown in the dashboard:

Query: query_result(topk(5, sum(rate(http_requests_total[$__range])) by (instance)))
Regex: /"([^"]+)"/

Populate a variable with the instances having a certain state over the time range shown in the dashboard, using the more precise $__range_s:

Query: query_result(max_over_time(<metric>[${__range_s}s]) != <state>)
Regex:

Using variables in queries

There are two syntaxes:

$<varname> Example: rate(http_requests_total{job=~"$job"}[5m])
[[varname]] Example: rate(http_requests_total{job=~"[[job]]"}[5m])

Annotations

Annotations allows you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view.

Prometheus supports two ways to query annotations.

A regular metric query
A Prometheus query for pending and firing alerts (for details see Inspecting alerts during runtime)

The step option is useful to limit the number of events returned from your query.

Getting Grafana metrics into Prometheus

Since 4.6.0 Grafana exposes metrics for Prometheus on the /metrics endpoint. We also bundle a dashboard within Grafana so you can get started viewing your metrics faster. You can import the bundled dashboard by going to the data source edit page and click the dashboard tab. There you can find a dashboard for Grafana and one for Prometheus. Import and start viewing all the metrics!

Configure the data source with provisioning

Here are some provisioning examples for this data source.

apiVersion: 1

datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://localhost:9090

Using Stackdriver in Grafana

Fri, 06 Mar 2026 22:21:21 +0000

Using Google Stackdriver in Grafana

Available as a beta feature in Grafana v5.3.x and v5.4.x. Officially released in Grafana v6.0.0

Grafana ships with built-in support for Google Stackdriver. Just add it as a data source and you are ready to build dashboards for your Stackdriver metrics.

Adding the data source

Open the side menu by clicking the Grafana icon in the top header.
In the side menu under the Dashboards link you should find a link named Data Sources.
Click the + Add data source button in the top header.
Select Stackdriver from the Type dropdown.
Upload or paste in the Service Account Key file. See below for steps on how to create a Service Account Key file.

NOTE: If you’re not seeing the Data Sources link in your side menu it means that your current user does not have the Admin role for the current organization.

Name	Description
Name	The data source name. This is how you refer to the data source in panels and queries.
Default	Default data source means that it will be pre-selected for new panels.
Service Account Key	Service Account Key File for a GCP Project. Instructions below on how to create it.

Authentication

There are two ways to authenticate the Stackdriver plugin - either by uploading a Google JWT file, or by automatically retrieving credentials from Google metadata server. The latter option is only available when running Grafana on GCE virtual machine.

Using a Google Service Account Key File

To authenticate with the Stackdriver API, you need to create a Google Cloud Platform (GCP) Service Account for the Project you want to show data for. A Grafana data source integrates with one GCP Project. If you want to visualize data from multiple GCP Projects then you need to create one data source per GCP Project.

Enable APIs

The following APIs need to be enabled first:

Click on the links above and click the Enable button:

Create a GCP Service Account for a Project

Navigate to the APIs and Services Credentials page.
Click on the Create credentials dropdown/button and choose the Service account key option.

Create service account button
On the Create service account key page, choose key type JSON. Then in the Service Account dropdown, choose the New service account option:

Create service account key
Some new fields will appear. Fill in a name for the service account in the Service account name field and then choose the Monitoring Viewer role from the Role dropdown:

Choose role
Click the Create button. A JSON key file will be created and downloaded to your computer. Store this file in a secure place as it allows access to your Stackdriver data.
Upload it to Grafana on the data source Configuration page. You can either upload the file or paste in the contents of the file.

Upload service key file to Grafana
The file contents will be encrypted and saved in the Grafana database. Don’t forget to save after uploading the file!

Service key file is uploaded to Grafana

Using GCE Default Service Account

If Grafana is running on a Google Compute Engine (GCE) virtual machine, it is possible for Grafana to automatically retrieve default credentials from the metadata server. This has the advantage of not needing to generate a private key file for the service account and also not having to upload the file to Grafana. However for this to work, there are a few preconditions that need to be met.

First of all, you need to create a Service Account that can be used by the GCE virtual machine. See detailed instructions on how to do that here.
Make sure the GCE virtual machine instance is being run as the service account that you just created. See instructions here.
Allow access to the Stackdriver Monitoring API scope. See instructions here.

Read more about creating and enabling service accounts for GCE VM instances here.

Metric Query Editor

The Stackdriver query editor allows you to select metrics, group/aggregate by labels and by time, and use filters to specify which time series you want in the results.

Begin by choosing a Service and then a metric from the Metric dropdown. Use the plus and minus icons in the filter and group by sections to add/remove filters or group by clauses.

Stackdriver metrics can be of different kinds (GAUGE, DELTA, CUMULATIVE) and these kinds have support for different aggregation options (reducers and aligners). The Grafana query editor shows the list of available aggregation methods for a selected metric and sets a default reducer and aligner when you select the metric. Units for the Y-axis are also automatically selected by the query editor.

Filter

To add a filter, click the plus icon and choose a field to filter by and enter a filter value e.g. instance_name = grafana-1. You can remove the filter by clicking on the filter name and select --remove filter--.

Simple wildcards

When the operator is set to = or != it is possible to add wildcards to the filter value field. E.g us-* will capture all values that starts with “us-” and *central-a will capture all values that ends with “central-a”. *-central-* captures all values that has the substring of -central-. Simple wildcards are less expensive than regular expressions.

Regular expressions

When the operator is set to =~ or !=~ it is possible to add regular expressions to the filter value field. E.g us-central[1-3]-[af] would match all values that starts with “us-central”, is followed by a number in the range of 1 to 3, a dash and then either an “a” or an “f”. Leading and trailing slashes are not needed when creating regular expressions.

Aggregation

The aggregation field lets you combine time series based on common statistics. Read more about this option here.

The Aligner field allows you to align multiple time series after the same group by time interval. Read more about how it works here.

Alignment Period/Group by Time

The Alignment Period groups a metric by time if an aggregation is chosen. The default is to use the GCP Stackdriver default groupings (which allows you to compare graphs in Grafana with graphs in the Stackdriver UI). The option is called Stackdriver auto and the defaults are:

1m for time ranges < 23 hours
5m for time ranges >= 23 hours and < 6 days
1h for time ranges >= 6 days

The other automatic option is Grafana auto. This will automatically set the group by time depending on the time range chosen and the width of the graph panel. Read more about the details here.

It is also possible to choose fixed time intervals to group by, like 1h or 1d.

Group By

Group by resource or metric labels to reduce the number of time series and to aggregate the results by a group by. E.g. Group by instance_name to see an aggregated metric for a Compute instance.

Alias Patterns

The Alias By field allows you to control the format of the legend keys. The default is to show the metric name and labels. This can be long and hard to read. Using the following patterns in the alias field, you can format the legend key the way you want it.

Metric Type Patterns

Alias Pattern	Description	Example Result
`{{metric.type}}`	returns the full Metric Type	`compute.googleapis.com/instance/cpu/utilization`
`{{metric.name}}`	returns the metric name part	`instance/cpu/utilization`
`{{metric.service}}`	returns the service part	`compute`

Label Patterns

In the Group By dropdown, you can see a list of metric and resource labels for a metric. These can be included in the legend key using alias patterns.

Alias Pattern Format	Description	Alias Pattern Example	Example Result
`{{metric.label.xxx}}`	returns the metric label value	`{{metric.label.instance_name}}`	`grafana-1-prod`
`{{resource.label.xxx}}`	returns the resource label value	`{{resource.label.zone}}`	`us-east1-b`

Example Alias By: {{metric.type}} - {{metric.labels.instance_name}}

Example Result: compute.googleapis.com/instance/cpu/usage_time - server1-prod

It is also possible to resolve the name of the Monitored Resource Type.

Alias Pattern Format	Description	Example Result
`{{resource.type}}`	returns the name of the monitored resource type	`gce_instance`

Example Alias By: {{resource.type}} - {{metric.type}}

Example Result: gce_instance - compute.googleapis.com/instance/cpu/usage_time

Templating

Checkout the Templating documentation for an introduction to the templating feature and the different types of template variables.

Query Variable

Variable of the type Query allows you to query Stackdriver for various types of data. The Stackdriver data source plugin provides the following Query Types.

Name	Description
Metric Types	Returns a list of metric type names that are available for the specified service.
Labels Keys	Returns a list of keys for `metric label` and `resource label` in the specified metric.
Labels Values	Returns a list of values for the label in the specified metric.
Resource Types	Returns a list of resource types for the the specified metric.
Aggregations	Returns a list of aggregations (cross series reducers) for the the specified metric.
Aligners	Returns a list of aligners (per series aligners) for the the specified metric.
Alignment periods	Returns a list of all alignment periods that are available in Stackdriver query editor in Grafana

Using variables in queries

There are two syntaxes:

$<varname> Example: metric.label.$metric_label
[[varname]] Example: metric.label.[[metric_label]]

Annotations

Annotations allows you to overlay rich event information on top of graphs. You add annotation queries via the Dashboard menu / Annotations view. Annotation rendering is expensive so it is important to limit the number of rows returned. There is no support for showing Stackdriver annotations and events yet but it works well with custom metrics in Stackdriver.

With the query editor for annotations, you can select a metric and filters. The Title and Text fields support templating and can use data returned from the query. For example, the Title field could have the following text:

{{metric.type}} has value: {{metric.value}}

Example Result: monitoring.googleapis.com/uptime_check/http_status has this value: 502

Patterns for the Annotation Query Editor

Alias Pattern Format	Description	Alias Pattern Example	Example Result
`{{metric.value}}`	value of the metric/point	`{{metric.value}}`	`555`
`{{metric.type}}`	returns the full Metric Type	`{{metric.type}}`	`compute.googleapis.com/instance/cpu/utilization`
`{{metric.name}}`	returns the metric name part	`{{metric.name}}`	`instance/cpu/utilization`
`{{metric.service}}`	returns the service part	`{{metric.service}}`	`compute`
`{{metric.label.xxx}}`	returns the metric label value	`{{metric.label.instance_name}}`	`grafana-1-prod`
`{{resource.label.xxx}}`	returns the resource label value	`{{resource.label.zone}}`	`us-east1-b`

Configure the data source with provisioning

Here is a provisioning example using the JWT (Service Account key file) authentication type.

apiVersion: 1

datasources:
  - name: Stackdriver
    type: stackdriver
    access: proxy
    jsonData:
      tokenUri: https://oauth2.googleapis.com/token
      clientEmail: stackdriver@myproject.iam.gserviceaccount.com
      authenticationType: jwt
      defaultProject: my-project-name
    secureJsonData:
      privateKey: |
        -----BEGIN PRIVATE KEY-----
        POSEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCb1u1Srw8ICYHS
        ...
        yA+23427282348234=
        -----END PRIVATE KEY-----

Here is a provisioning example using GCE Default Service Account authentication.

apiVersion: 1

datasources:
  - name: Stackdriver
    type: stackdriver
    access: proxy
    jsonData:
      authenticationType: gce

Using the Mixed Data Source in Grafana

Fri, 06 Mar 2026 22:21:21 +0000

Mixed Data Source

This Data Source allows you to specify data source on a per query basis.

Usage

To use the Mixed Data Source, create a new panel or edit an existing panel and navigate to the Queries tab. From the Query popup, select “– Mixed –”. Click “Add Query” and select the desired source.

You cannot change an existing query to use the Mixed Data Source.