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 提供以下操作

可以在此处找到示例实现。

此 API 有一些限制

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

Advanced API (GrafanaQueryAPIV3)

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

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

此 API 提供以下操作

可以在此处找到示例实现。

用例示例

• 具有不同标签的同一指标的不同时间序列。例如：温度度量是一个房间。房间有四个区域：北、南、东和西。除非为每个温度/区域组合定义了四个不同的指标，否则 V1 API 不支持这种情况。高级 API 通过为同一指标 temperature 返回多个时间序列来支持这种情况，每个时间序列都使用不同的标签 zone 进行注释。
• 不同指标的不同时间序列。例如：一个房间有多个温度传感器。V1 API 通过为每个指标定义多个查询来支持这一点。高级 API 可以通过单个查询来完成此操作。

重要提示：为了使用高级 API，后端服务器需要支持 gRPC 反射。插件使用它来确定后端是否支持 V2 或 V3 协议。如果不支持，则回退到 Simple API 实现。

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

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

最重要的区别是 V2 API 的聚合类型在 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 后端的示例实现

功能

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

路线图

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