Graphana 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

此数据源插件期望后端实现简单或高级接口。

简单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 调用
• 允许后端系统集成自定义查询选项。

路线图

• 支持注释
• 支持流查询