Plugins 〉simple grpc datasource

Data Source
community

simple grpc datasource

  • Overview
  • Installation
  • Change log
  • Related content

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

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 of a metric for the selected period
Get Metric Valuegets the current value or last known value of a specified metric.

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 GrafanaQueryAPI interface. The definition of this interface can be found here. 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.

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

For more information, visit the docs on plugin installation.

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.