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 of a metric for the selected period |
| Get Metric Value | gets the current value or last known value of a specified metric. |
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 GrafanaQueryAPI interface. The definition of this interface can be found here. 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.
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.
Roadmap
- add more caching
- add more authentication schemes (certificates, basic authentication etc. )
- add more tests
- better lookups for dimensions and metrics in frontend
- support annotations
- support streaming queries
Enterprise plugins, along with support and assistance from the core team behind Grafana, are available with Grafana Enterprise.
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.
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.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.
