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 接口。

简单 API (GrafanaQueryAPI)

此 API 提供以下操作

示例实现可以在此处找到 这里.

此 API 有一些限制

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

高级 API (GrafanaQueryAPIV3)

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

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

此 API 提供以下操作

示例实现可以在此处找到 这里.

示例用例

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

重要提示：为了使用高级API，后端服务器需要支持gRPC反射。插件使用此功能来判断后端是否支持V2或V3协议。如果不支持，则回退到简单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调用的重试
• 允许后端系统定义自定义查询选项。

路线图

• 支持注释
• 支持流查询