Plugins 〉simple grpc datasource


Developer
Ron van der Wijngaard

Links

Sign up to receive occasional product news and updates:



Latest webinars
Data Source
community

simple grpc datasource

  • Overview
  • Installation
  • Change log
  • Related content

Grafana Simple gRPC Datasource Plugin

GitHub release (latest by date) Marketplace Downloads

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

screenshot

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

typedescription
Get Metric Historygets historical timeseries values
Get Metric Aggregategets aggregated timeseries
Get Metric Valuegets the last known value

Getting started

  1. start a sample grpc server locally:
docker run -p 50051:50051 innius/sample-grpc-server
  1. install the innius-simple-grpc-datasource

  2. enable the datasource

    • configure the endpoint localhost:50051
  3. 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:

namedescription
ListDimensionKeysReturns a list of all available dimension keys
ListDimensionValuesReturns a list of all available dimension values of a dimension key
ListMetricsReturns a list of all metrics for a combination of dimensions.
GetMetricValueReturns the last known value of a metric.
GetMetricHistoryReturns historical values of a metric
GetMetricAggregateReturns 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:

namedescription
ListDimensionKeysReturns a list of all available dimension keys
ListDimensionValuesReturns a list of all available dimension values of a dimension key
ListMetricsReturns a list of all metrics for a combination of dimensions.
GetMetricValueReturns the last known value for one or more metrics.
GetMetricHistoryReturns historical values for one or more metrics
GetMetricAggregateReturns 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 label zone.
  • 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

Installing simple grpc datasource on Grafana Cloud:

For more information, visit the docs on plugin installation.

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 and MaxItems 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.