Plugins 〉simple grpc datasource
simple grpc datasource
Grafana Simple gRPC Datasource Plugin
What is this plugin?
This back-end Grafana datasource plugin provides a user-friendly grafana experience with only a handful simple and generic parameters to configure. It comes with a dedicated API specification that requires implementation in the data provider's back-end. Implementing this API helps to decouple the front-end visualisation solution from the back-end data-layer implementation, leaving developers with the necessary freedom to update and improve the back-end without breaking the end-user experience.
The protobuf API specification can be found in the pkg/proto directory. On configuring the datasource plugin, the end-user provides an endpoint URL and optionally an API key too. The datasource will attempt to establish a gRPC connection and emit calls to the given endpoint according to the API specification.
For more information on gRPC or protobuf, see the gRPC docs.
Why gRPC?
gRPC is a fast & efficient framework for inter-service communication and provides a fool-proof and streamlined workflow for API implementation through protobuf.
gRPC also supports all essential streaming capabilities, which can be implemented in future releases.
Security
The datasource plugin establishes a secure gRPC connection through TLS. Additionally, the datasource supports API-key authorization. The API-key will be included in each API call as part of the call metadata.
Usage
Metric
The variable that is updated with new values as the stream of timeseries datapoints is appended.
Dimension
A dimension is an optional, identifying property of the measure. Each dimension is modeled as a key-value pair. A measure can have zero or many dimensions that collectively uniquely identify it.
Query Type
type | description |
---|---|
Get Metric History | gets historical timeseries values |
Get Metric Aggregate | gets aggregated timeseries |
Get Metric Value | gets the last known value |
Getting started
- start a sample grpc server locally:
docker run -p 50051:50051 innius/sample-grpc-server
install the innius-simple-grpc-datasource
enable the datasource
- configure the endpoint
localhost:50051
- configure the endpoint
configure dashboards
Implement your own backend API
This datasource plugin expects a backend to implement the Simple or the Advanced interface.
The Simple API (GrafanaQueryAPI)
This API provides the following operations:
name | description |
---|---|
ListDimensionKeys | Returns a list of all available dimension keys |
ListDimensionValues | Returns a list of all available dimension values of a dimension key |
ListMetrics | Returns a list of all metrics for a combination of dimensions. |
GetMetricValue | Returns the last known value of a metric. |
GetMetricHistory | Returns historical values of a metric |
GetMetricAggregate | Returns aggregated metric values |
A sample implementation can be found here.
This API has some limitations:
- it only supports one metric per query
- it does not support variables with multiple options
- it does not support enhanced metadata for metrics (like unit, etc.)
The Advanced API (GrafanaQueryAPIV2)
This API provides almost the same operations as the Simple API but with one major difference: it supports multiple metrics for the same query. As a result this API integrates seamlessly with grafana templating capabilities. In addition, it supports enhanced metric metadata, like unit of measure. Another difference is that it supports grafana labels.
This API provides the following operations:
name | description |
---|---|
ListDimensionKeys | Returns a list of all available dimension keys |
ListDimensionValues | Returns a list of all available dimension values of a dimension key |
ListMetrics | Returns a list of all metrics for a combination of dimensions. |
GetMetricValue | Returns the last known value for one or more metrics. |
GetMetricHistory | Returns historical values for one or more metrics |
GetMetricAggregate | Returns aggregated values for one or more metrics |
A sample implementation can be found here.
Example Use Cases:
- different time series for the same metric with different labels. For example: the temperature measure is a room. The room has four zones: north, south, east and west. The V1 API does not support this unless there are four different metrics defined for each temperature / zone combination.
The V2 API does support this scenario by returning multiple time series for the same metric
temperature
, each annotated with different labelzone
. - different time series for different metrics. For example: a room has multiple temperature sensors. The V1 API supports this by defining multiple queries for each metric. The V2 API can do this with a single query.
Important Note: in order to use the V2 API the backend server needs to support gRPC Reflection. The plugin uses this to determine if a backend supports the V2 protocol. If V2 is not supported it falls back on the Simple API implementation.
Please note gRPC is programming language agnostic which makes it possible to implement a backend in the language of your choice. Checkout the gRPC documentation of your language.
Features
- select multiple metrics in one query
- flexible dimension selection
- integrated with Grafana variables and templating
- allows backend systems to provided additional metadata, like value mappings, unit of measure, etc.
- supports notifications
- supports pagination
- supports retries for grpc calls if backend server is at maximum capacity
Roadmap
- add more authentication schemes (certificates, basic authentication etc. )
- support annotations
- support streaming queries
Grafana Cloud Pro
- $25 / user / month and includes a free trial for new users
- Available with a Grafana Cloud Pro plan
- Access to 1 Enterprise plugin
- Fully managed service (not available to self-manage)
Grafana Cloud Advanced / Grafana Enterprise
- Available with a Grafana Cloud Advanced plan or Grafana Enterprise license
- Access to all Enterprise plugins
- Run fully managed or self-manage on your own infrastructure
Installing simple grpc datasource on Grafana Cloud:
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
Installing plugins on a Grafana Cloud instance is a one-click install; same with updates. Cool, right?
Note that it could take up to 1 minute to see the plugin show up in your Grafana.
For more information, visit the docs on plugin installation.
Installing on a local Grafana:
For local instances, plugins are installed and updated via a simple CLI command. Plugins are not updated automatically, however you will be notified when updates are available right within your Grafana.
1. Install the Data Source
Use the grafana-cli tool to install simple grpc datasource from the commandline:
grafana-cli plugins install
The plugin will be installed into your grafana plugins directory; the default is /var/lib/grafana/plugins. More information on the cli tool.
Alternatively, you can manually download the .zip file for your architecture below and unpack it into your grafana plugins directory.
Alternatively, you can manually download the .zip file and unpack it into your grafana plugins directory.
2. Configure the Data Source
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 data source will be available for selection in the Type select box.
To see a list of installed data sources, click the Plugins item in the main menu. Both core data sources and installed data sources will appear.
Changelog
1.0.11
- feature: support backend value mapping
1.0.11
- fix: specify correct grafana version dependency
1.0.10
- feature: retry mechanism for backend grpc calls
- feature: add dimension value filter to VariableQueryEditor
- feature: update to latest grafana frameworks
1.0.9
- feature: imporoved dimension selection component
- feature: add variable editor which supports dimension keys and metrics
1.0.8
- bugfix: incorrect metrics when Explore is triggered from dashboard panel
- bugfix: fix dimension drop down glitch for Chrome browser
1.0.7
- feature: provide ListDimensions with selected dimensions to enable advanced backend filtering
- feature: support frame metadata to enable user notifications from backend
- bugfix: pagination for queries with multiple frames did not work properly
1.0.6
- upgrade: upgrade to latest grafana toolkit
- feature: add v2 API which better aligns with grafana dataframe API
- feature: add fieldname to display name expressions
1.0.5
- feature: add
COUNT
aggregate type to list of possible aggregations - feature: support display name expression (also known as aliasing)
- bugfix: exclude variables from metricFind query
1.0.4
- improved metric selection
- support Count aggregation type
- add grafana
intervalMS
andMaxItems
attributes to query definition
1.0.3
Hide technical grpc errors from user interface; backend plugin logs error details and returns user-friendly message for the user.
1.0.2
- Add support for GetMetricAggregate query
- Fix a few typo's in Readme
- Correct plugin id to standard grafana plugin-id conventions
1.0.0 (Unreleased)
Initial release.