Grafana Simple gRPC 数据源插件

这个插件是什么？

这个后端 Grafana 数据源插件提供了用户友好的 Grafana 体验，只需少量简单通用的参数即可配置。它附带了一个专用的 API 规范，需要在数据提供者的后端实现。实现此 API 有助于将前端可视化解决方案与后端数据层实现解耦，让开发者有必要的自由来更新和改进后端而不会破坏最终用户体验。

protobuf API 规范可在 pkg/proto 目录中找到。在配置数据源插件时，最终用户需要提供一个端点 URL，也可以选择提供一个 API 密钥。该数据源将尝试建立 gRPC 连接，并根据 API 规范向给定的端点发出调用。

有关 gRPC 或 protobuf 的更多信息，请参阅 gRPC 文档。

为什么选择 gRPC？

gRPC 是一个快速高效的服务间通信框架，通过 protobuf 为 API 实现提供了万无一失且流程化的工作流程。

gRPC 还支持所有基本的流式传输功能，这些功能可以在未来的版本中实现。

安全性

数据源插件通过 TLS 建立安全的 gRPC 连接。此外，该数据源支持 API 密钥授权。API 密钥将作为调用元数据的一部分包含在每个 API 调用中。

使用方法

指标

随着时间序列数据点流的追加而更新新值的变量。

维度

维度是度量的可选标识属性。每个维度都建模为键值对。一个度量可以有零个或多个维度，它们共同唯一地标识该度量。

查询类型

入门

1. 本地启动一个示例 gRPC 服务器

docker run -p 50051:50051 innius/sample-grpc-server

1. 安装 innius-simple-grpc-datasource 插件

2. 启用数据源

   • 配置端点 localhost:50051

3. 配置仪表板

实现您自己的后端 API

此数据源插件要求后端实现 Simple 或 Advanced 接口。

Simple API (GrafanaQueryAPI)

此 API 提供以下操作

可在此处找到示例实现：here。

此 API 有一些限制

• 每个查询只支持一个指标
• 不支持具有多个选项的变量
• 不支持指标的增强元数据（如单位等）
• 不支持灵活的查询选项

Advanced API (GrafanaQueryAPIV3)

此 API 提供的操作与 Simple API 几乎相同，但有一个主要区别：它支持同一查询中的多个指标。因此，此 API 可与 grafana 模板化功能无缝集成。此外，它还支持增强的指标元数据，例如度量单位。另一个区别是它支持 grafana 标签。

Advanced API 支持由后端系统定义的动态查询选项。这使得可以针对特定的后端定制 grafana 查询的行为。自定义选项的一个示例是 GetMetricAggregate 查询的 Aggregate。API 的 v1 版本具有固定数量的 Aggregate，由插件定义。后端系统无法添加不同的选项。然而，V3 API 支持这一点。目前，一个选项可以是枚举类型或布尔类型。

此 API 提供以下操作

可在此处找到示例实现：here。

示例用例

• 具有不同标签的同一指标的不同时间序列。例如：温度测量值是一个房间的。该房间有四个区域：北、南、东、西。V1 API 不支持这种情况，除非为每个温度/区域组合定义了四个不同的指标。Advanced API 通过为同一指标 temperature 返回多个时间序列来支持此场景，每个时间序列都使用不同的标签 zone 进行注释。
• 不同指标的不同时间序列。例如：一个房间有多个温度传感器。V1 API 通过为每个指标定义多个查询来支持此场景。Advanced API 可以通过一个查询实现。

重要说明：为了使用 Advanced API，后端服务器需要支持 gRPC Reflection。插件使用此功能来确定后端是否支持 V2 或 V3 协议。如果不支持，则回退到 Simple API 实现。

请注意，gRPC 与编程语言无关，因此您可以用您选择的语言实现后端。请查看您所用语言的 gRPC 文档。

(GrafanaQueryAPIV2) 与 (GravanaQueryAPIV3) 之间的更改

最重要的区别是 V2 API 的 Aggregate 类型在 V3 API 中不可用，除非它们在后端定义。

后端代码需要实现类似这样的功能

const (
    // this id is important because it matches the current v2 aggregate type option 
	AggregationTypeOptionID = iota
    // these enum values are important because they match the values of the V2 options 
	AggregationTypeAverage = 0
	AggregationTypeMax     = 1
	AggregationTypeMin     = 2
	AggregationTypeCount   = 3
)
func (backend *BackendServerV3) GetQueryOptions(ctx context.Context, in *v3.GetOptionsRequest) (*v3.GetOptionsResponse, error) {
var Options []*v3.Option
switch in.GetQueryType() {
case v3.GetOptionsRequest_GetMetricAggregate:
Options = append(Options, []*v3.Option{
{
Id:          strconv.Itoa(AggregationTypeOptionID),
Label:       “Aggregate”,
Description: “Aggregate the query results”,
Type:        v3.Option_Enum,
EnumValues: []*v3.EnumValue{
{Label: “Average”, Description: “Calculate the average of the values”, Id: strconv.Itoa(AggregationTypeAverage)},
{Label: “Min”, Description: “Calculate the minimum of the values”, Id: strconv.Itoa(AggregationTypeMin)},
{Label: “Max”, Description: “Calculate the maximum of the values”, Id: strconv.Itoa(AggregationTypeMax)},
{Label: “Count”, Description: “Calculate the sum of the values”, Id: strconv.Itoa(AggregationTypeCount)},
},
},
}…)
case v3.GetOptionsRequest_GetMetricValue:
return &v3.GetOptionsResponse{}, nil
case v3.GetOptionsRequest_GetMetricHistory:
return &v3.GetOptionsResponse{}, nil
}
return &v3.GetOptionsResponse{Options: Options}, nil
}

可在此处找到 V3 后端的示例实现：here

功能特性

• 在一个查询中选择多个指标
• 灵活的维度选择
• 与 Grafana 变量和模板化功能集成
• 允许后端系统提供额外的元数据，如值映射、度量单位等。
• 支持通知
• 支持分页
• 当后端服务器达到最大容量时，支持对 gRPC 调用进行重试
• 允许后端系统定义自定义查询选项。

路线图

• 支持注解
• 支持流式查询