{"id":21446914,"url":"https://github.com/innius/grafana-simple-grpc-datasource","last_synced_at":"2025-07-14T19:31:36.292Z","repository":{"id":40369737,"uuid":"375258883","full_name":"innius/grafana-simple-grpc-datasource","owner":"innius","description":"Simple grpc datasource for grafana","archived":false,"fork":false,"pushed_at":"2024-10-22T11:46:18.000Z","size":3025,"stargazers_count":14,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-22T10:37:41.873Z","etag":null,"topics":["grafana-datasource","grafana-plugin","grpc"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/innius.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-09T07:03:59.000Z","updated_at":"2024-10-25T06:36:54.000Z","dependencies_parsed_at":"2023-12-05T10:28:54.697Z","dependency_job_id":"739ef14b-2fae-40c5-9f45-736eabb95a00","html_url":"https://github.com/innius/grafana-simple-grpc-datasource","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innius%2Fgrafana-simple-grpc-datasource","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innius%2Fgrafana-simple-grpc-datasource/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innius%2Fgrafana-simple-grpc-datasource/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/innius%2Fgrafana-simple-grpc-datasource/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/innius","download_url":"https://codeload.github.com/innius/grafana-simple-grpc-datasource/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225994870,"owners_count":17556830,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["grafana-datasource","grafana-plugin","grpc"],"created_at":"2024-11-23T03:08:17.638Z","updated_at":"2024-11-23T03:08:18.152Z","avatar_url":"https://github.com/innius.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Grafana Simple gRPC Datasource Plugin\n\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/innius/grafana-simple-grpc-datasource?logo=github)\n[![Marketplace](https://img.shields.io/badge/dynamic/json?logo=grafana\u0026color=F47A20\u0026label=marketplace\u0026prefix=v\u0026query=version\u0026url=https%3A%2F%2Fgrafana.com%2Fapi%2Fplugins%2Finnius-grpc-datasource)](https://grafana.com/grafana/plugins/innius-grpc-datasource)\n[![Downloads](https://img.shields.io/badge/dynamic/json?logo=grafana\u0026color=F47A20\u0026label=downloads\u0026query=downloads\u0026url=https%3A%2F%2Fgrafana.com%2Fapi%2Fplugins%2Finnius-grpc-datasource)](https://grafana.com/grafana/plugins/innius-grpc-datasource)\n\n## What is this plugin?\n\nThis back-end Grafana datasource plugin provides a user-friendly grafana experience with only a handful simple and generic parameters to configure.\nIt comes with a dedicated API specification that requires implementation in the data provider's back-end.\nImplementing this API helps to decouple the front-end visualisation solution from the back-end data-layer implementation,\nleaving developers with the necessary freedom to update and improve the back-end without breaking the end-user experience.\n\nThe protobuf API specification can be found in the pkg/proto directory.\nOn configuring the datasource plugin, the end-user provides an endpoint URL and optionally an API key too. The datasource will\nattempt to establish a gRPC connection and emit calls to the given endpoint according to the API specification.\n\nFor more information on gRPC or protobuf, see the [gRPC docs](https://grpc.io/docs/).\n\n#### Why gRPC?\ngRPC is a fast \u0026 efficient framework for inter-service communication and provides a fool-proof and streamlined workflow for API implementation through protobuf.\n\ngRPC also supports all essential streaming capabilities, which can be implemented in future releases.\n\n#### Security\n\nThe datasource plugin establishes a secure gRPC connection through TLS. \nAdditionally, the datasource supports API-key authorization. The API-key will be included in each API call as part of the call metadata.\n\n##  Usage\n![screenshot](https://raw.githubusercontent.com/innius/grafana-simple-grpc-datasource/master/src/img/screenshots/image-1.png)\n\n#### Metric\nThe variable that is updated with new values as the stream of timeseries datapoints is appended.\n\n#### Dimension\nA dimension is an optional, identifying property of the measure. Each dimension is modeled as a key-value pair. \nA measure can have zero or many dimensions that collectively uniquely identify it.\n\n#### Query Type\n\n| type | description |\n| --- | --- |\n| Get Metric History | gets historical timeseries values |\n| Get Metric Aggregate | gets aggregated timeseries |  \n| Get Metric Value | gets the last known value |  \n\n\n## Getting started\n1. start a sample grpc server locally:\n```\ndocker run -p 50051:50051 innius/sample-grpc-server\n```\n   \n2. install the innius-simple-grpc-datasource\n\n3. enable the datasource \n    - configure the endpoint `localhost:50051`\n    \n4. configure dashboards \n\n## Implement your own backend API \n\nThis datasource plugin expects a backend to implement the [Simple][1] or the [Advanced][2] interface. \n\n### The Simple API ([GrafanaQueryAPI][1])\n\nThis API provides the following operations:\n\n| name                | description                                                         | \n|---------------------|---------------------------------------------------------------------|\n| ListDimensionKeys   | Returns a list of all available dimension keys                      |\n| ListDimensionValues | Returns a list of all available dimension values of a dimension key |\n| ListMetrics         | Returns a list of all metrics for a combination of dimensions.      |\n| GetMetricValue      | Returns the last known value of a metric.                           |\n| GetMetricHistory    | Returns historical values of a metric                               |\n| GetMetricAggregate  | Returns aggregated metric values                                    |\n\nA sample implementation can be found [here](https://bitbucket.org/innius/sample-grpc-server/src/master/).\n\nThis API has some limitations: \n- it only supports one metric per query \n- it does not support variables with multiple options \n- it does not support enhanced metadata for metrics (like unit, etc.)\n- it does not support flexible query options \n\n### The Advanced API ([GrafanaQueryAPIV3][3])\n\nThis API provides almost the same operations as the Simple API but with one major difference: it supports multiple metrics \nfor the same query. As a result this API integrates seamlessly with grafana templating capabilities. \nIn addition, it supports enhanced metric metadata, like unit of measure. Another difference is that it supports grafana labels. \n\nThe advanced API supports dynamic query options which are defined by the backend system. This makes it possible to tailor the behavior of grafana queries for specific backends. An example of a custom option is the Aggregate of the _GetMetricAggregate_ query. The v1 version of the API has a fixed number of Aggregates, defined by the plugin. It is not possible for a backend system to add a different option. With the V3 API, however, this is supported. Currently an option can be either an Enumeration or a Boolean type. \n\nThis API provides the following operations:\n\n| name                | description                                                         | \n|---------------------|---------------------------------------------------------------------|\n| ListDimensionKeys   | Returns a list of all available dimension keys                      |\n| ListDimensionValues | Returns a list of all available dimension values of a dimension key |\n| ListMetrics         | Returns a list of all metrics for a combination of dimensions.      |\n| GetMetricValue      | Returns the last known value for one or more metrics.               |\n| GetMetricHistory    | Returns historical values for one or more metrics                   |\n| GetMetricAggregate  | Returns aggregated values for one or more metrics                   |\n| GetQueryOptions     | Returns the options for a selected query type                       |\n\nA sample implementation can be found [here](https://bitbucket.org/innius/sample-grpc-server/src/master/).\n\n#### Example Use Cases: \n- 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. \nThe Advanced API does support this scenario by returning multiple time series for the same metric `temperature`, each annotated with different label `zone`. \n- 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. \nThe Advanced API can do this with a single query. \n\nImportant Note: in order to use the Advanced API the backend server needs to support [gRPC Reflection][3]. The plugin uses this to determine if a backend supports the V2 or V3 protocol. If not supported it falls back on the Simple API implementation. \n\nPlease note gRPC is programming language agnostic which makes it possible to implement a backend in the language of your choice. Checkout the gRPC [documentation](https://grpc.io/docs/languages/) of your language.\n\n#### Changes between ([GrafanaQueryAPIV2][2]) and ([GravanaQueryAPIV3][3]) \nThe most important difference is that the Aggregate types of the V2 API are not available by the V3 API unless they are defined in the backend. \n\nThe backend code has to implement something like this: \n\n```\nconst (\n    // this id is important because it matches the current v2 aggregate type option \n\tAggregationTypeOptionID = iota\n    // these enum values are important because they match the values of the V2 options \n\tAggregationTypeAverage = 0\n\tAggregationTypeMax     = 1\n\tAggregationTypeMin     = 2\n\tAggregationTypeCount   = 3\n)\n\n\nfunc (backend *BackendServerV3) GetQueryOptions(ctx context.Context, in *v3.GetOptionsRequest) (*v3.GetOptionsResponse, error) {\n\tvar Options []*v3.Option\n\tswitch in.GetQueryType() {\n\tcase v3.GetOptionsRequest_GetMetricAggregate:\n\t\tOptions = append(Options, []*v3.Option{\n\t\t\t{\n\t\t\t\tId:          strconv.Itoa(AggregationTypeOptionID),\n\t\t\t\tLabel:       \"Aggregate\",\n\t\t\t\tDescription: \"Aggregate the query results\",\n\t\t\t\tType:        v3.Option_Enum,\n\t\t\t\tEnumValues: []*v3.EnumValue{\n\t\t\t\t\t{Label: \"Average\", Description: \"Calculate the average of the values\", Id: strconv.Itoa(AggregationTypeAverage)},\n\t\t\t\t\t{Label: \"Min\", Description: \"Calculate the minimum of the values\", Id: strconv.Itoa(AggregationTypeMin)},\n\t\t\t\t\t{Label: \"Max\", Description: \"Calculate the maximum of the values\", Id: strconv.Itoa(AggregationTypeMax)},\n\t\t\t\t\t{Label: \"Count\", Description: \"Calculate the sum of the values\", Id: strconv.Itoa(AggregationTypeCount)},\n\t\t\t\t},\n\t\t\t},\n\t\t}...)\n\tcase v3.GetOptionsRequest_GetMetricValue:\n        return \u0026v3.GetOptionsResponse{}, nil\n\tcase v3.GetOptionsRequest_GetMetricHistory:\n        return \u0026v3.GetOptionsResponse{}, nil\n\t}\n\treturn \u0026v3.GetOptionsResponse{Options: Options}, nil\n}\n```\n\nA sample implementation of the V3 backend can be found [here](https://bitbucket.org/innius/sample-grpc-server/src/4dc9fd798eee92eb67c44085532e89518551a74d/server/v3/server.go#lines-44)\n\n## Features \n* select multiple metrics in one query \n* flexible dimension selection \n* integrated with Grafana variables and templating \n* allow backend systems to provided additional metadata, like value mappings, unit of measure, etc. \n* supports notifications \n* supports pagination\n* supports retries for grpc calls if backend server is at maximum capacity\n* allow backend systems to define custom query options. \n\n## Roadmap\n- support annotations\n- support streaming queries \n\n[1]: https://raw.githubusercontent.com/innius/grafana-simple-grpc-datasource/master/pkg/proto/v1/api.proto\n[2]: https://raw.githubusercontent.com/innius/grafana-simple-grpc-datasource/master/pkg/proto/v2/apiv2.proto\n[3]: https://raw.githubusercontent.com/innius/grafana-simple-grpc-datasource/master/pkg/proto/v3/apiv3.proto\n[4]: https://github.com/grpc/grpc/blob/master/doc/server-reflection.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finnius%2Fgrafana-simple-grpc-datasource","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finnius%2Fgrafana-simple-grpc-datasource","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finnius%2Fgrafana-simple-grpc-datasource/lists"}