Metrics 数据模型改进设计

[liuhaoyang]

背景

在 iLogtail 中支持 Logs、Traces、Metrics 三种数据的收集和处理，在阅读源码和开发插件时，发现仍存在以下问题：

• 三种数据中仅对日志协议作为一等公民
• 日志仍使用 sls 的 pb 数据模型，sls-pb 在设计上对结构化日志的处理和社区流行的日志协议(如 otlp .)的兼容不友好
• 缺乏原生的 Metrics 、Trace 数据模型，对两种数据的处理需要先转换为 sls.pb ，对性能和兼容性的处理都较差

{
    "__name__":"metrics_mock",
    "__labels__":"field1#$#field1|field2#$#field2|tag1#$#tag1|tag2#$#tag2",
    "__time_nano__":"1658806870597391426",
    "__value__":"102",
    "__time__":"1658806870"
}

在 iLogtail 中设计新的可观测性数据模型

• 设计 Metrics 数据模型，需要很好的兼容单值(eg. Prometheus)和多值(eg. influxdb)不同的数据协议，同时也要支持对 Metrics 的原生处理

# prometheus metrics
http_requests_total{api="add_product"} 4633433
# influxdb metrics
cpu,cpu=cpu0,host=loaner time_active=202224.15999999992,time_guest=30250.35 1568760922000000000

• 设计 Trace 数据模型，需要很好的兼容 Opentrcing 和 Opentelemetry
• 设计新的 Log 数据模型，需要很好的兼容半结构化/结构化日志、社区 Opentelemetry Log 等，同时也要支持对 Log的原生处理
• 兼容目前已有的插件体系。现有的插件仍要能工作，但可以不需要兼容新的数据模型

设计

如果我们把 Pipeline 中流动的每一条数据都看做一个event，那么 event 应该具备下面的这些特性

1. 具体业务含义的Name
2. 具有纳秒精度的时间戳，需要区分event_time和process_time
3. 具有meta ，用于标记event 的元数据。如 influxdb 数据的db、SLS数据的project/logstore
4. 具有tags ，用于标记evevt 的业务附加属性。如 log_offset、host等
5. 具有event_type，用于区分event的类型，如metrics trace log

metrics trace log 都应该派生自event，具备上面event的通用字段，对于每种数据类型，还需要有一些独立的字段

1. Metrics 应该包含单个value或多个 values时序值
2. Trace 应该包含追踪上下文的数据，如traceID spanID parentSpanID startTime endTime 等
3. Log 应该包含日志级别severity\level 和日志内容body\message 等

我们还需要引入聚合的概念 event Group，来支持部分需要对数据进行分组的操作

1. 包含分组的 keys 和 values
2. 聚合事件也允许有独立的 meta和 tags，一般是从数据中提取

数据模型定义

event 和 group 接口定义

type PipelineEvent interface {
	GetName() string

	SetName(string)

	GetTags() Tags

	GetType() EventType

	GetTimestamp() uint64

	GetObservedTimestamp() uint64

	SetObservedTimestamp(uint64)
}

type GroupInfo struct {
	Metadata Metadata
	Tags     Tags
}

type PipelineGroupEvents struct {
	Group  *GroupInfo
	Events []PipelineEvent
}

Metrics Event 定义

1. metrics 的公共字段包括 Name 、MetricType、Timestamp\ObservedTimestamp、Tags、Value、TypedValue

type MetricEvent struct {
	Name              string
	MetricType        MetricType
	Timestamp         uint64
	ObservedTimestamp uint64
	Tags              Tags
	Value             MetricValue
	TypedValue        MetricTypedValues
}

2. MetricValue 设计，上文中我们提到，主流的metrics数据有单值(eg. Prometheus)和多值(eg. influxdb)两种设计，iLogtail 中也需要支持两种不同的设计，基于此设计了 MetricValue 接口和MetricSingleValue 和 MetricMultiValue 两个不同的实现。

type MetricValue interface {
	IsSingleValue() bool

	IsMultiValues() bool

	GetSingleValue() float64

	GetMultiValues() MetricFloatValues
}

type MetricSingleValue struct {
	Value float64
}

type MetricMultiValue struct {
	Values MetricFloatValues
}

通常情况下，对于 counter 、gauge 类型的 metric 会使用单值 ，Histogram 和 Summary 类型在不同的TSDB上可能使用单值或者多值，比如字节内部的 ByteTSD 2.0 原生支持多值Histogram/Summary 来节省存储空间。对于单值和多值的处理，可以使用下面的API

if metric.Value.IsSingleValue() {
    value := metric.Value.GetSingleValue()
} 

if metric.Value.IsMultiValues() {
  values := metric.Value.GetMultiValues()
  for field, value := range values.Iterator() {
    // field 为 string 类型,表示多值的字段名
    // value 为 float64 类型
  }
}

3. TypedValue 设计。MetricValue 不管是单值还是多值的value类型都是float64，在一些 TSDB 中比如 influxdb，除了数值类型，还支持string bool 等非数值类型 (influxdb field-value)[https://docs.influxdata.com/influxdb/v1.8/concepts/glossary/#field-value] 。为此，我们扩展了一个额外的 TypedValue 字段用来存储非数值的 field 值。

type TypedValue struct {
	Type  ValueType
	Value interface{}
}

type MetricTypedValues interface {
	KeyValues[*TypedValue]
}

[yyuuttaaoo]

type Meta struct {
Meta []KeyValuePair
}

type Tags struct {
Tags []KeyValuePair
}

type MetricMultiValue struct {
Values []FieldValue
}
这种需要大胆点直接用map吗？比如之前要修改一下offset，找个值只能一个个找过来。还是说metric场景index一定都是能对齐的？
另外看结构，metric的label在哪呢？

[liuhaoyang]

type Meta struct { Meta []KeyValuePair }

type Tags struct { Tags []KeyValuePair }

type MetricMultiValue struct { Values []FieldValue } 这种需要大胆点直接用map吗？比如之前要修改一下offset，找个值只能一个个找过来。还是说metric场景index一定都是能对齐的？ 另外看结构，metric的label在哪呢？

用 map 还是 切片我们可以再讨论一下，map的优势在查询，但go 原生map是无序的，这个可能在后端处理上会有影响？

metrics 的完整定义可以看

type MetricEvent struct {
    Name      string
    Timestamp uint64
    Meta      Meta
    Tags      Tags
    Value     MetricValue
}

Tags 就是等价于 labels

[liuhaoyang]

type Meta struct { Meta []KeyValuePair }

type Tags struct { Tags []KeyValuePair }

type MetricMultiValue struct { Values []FieldValue } 这种需要大胆点直接用map吗？比如之前要修改一下offset，找个值只能一个个找过来。还是说metric场景index一定都是能对齐的？ 另外看结构，metric的label在哪呢？

提案更新。

1. tags 和 MetricValues 的存储方式从数组修改为map
2. 添加 MetricTypedValues 定义来处理 influxdb 的string bool 类型的 field

[liuhaoyang]

MetricEvent 模型的实现提交 PR #519

[kakj-go]

与其自行定义数据结构符合各种协议，不如一步到位直接使用 otlp 规范来封装

自建信号结构体

import (
	logs "go.opentelemetry.io/proto/otlp/logs/v1"
	metrics "go.opentelemetry.io/proto/otlp/metrics/v1"
	traces "go.opentelemetry.io/proto/otlp/trace/v1"
)

type OTLPSignal struct {
	metric *metrics.ResourceMetrics
	log    *logs.ResourceLogs
	span   *traces.ResourceSpans
}

Collector 增加 2 个信号的收集方法

当插件还是老的数据格式可以做一层数据适配逻辑，最终目标是吧所有插件都转换成 OTLPSignal 的数据格式

// https://github.com/alibaba/ilogtail/blob/main/collector.go
type Collector interface {
        AddOTLPSignal(s *OTLPSignal)

	AddOTLPSignalArray(s []*OTLPSignal)

	AddData(tags map[string]string,
		fields map[string]string,
		t ...time.Time)

	AddDataArray(tags map[string]string,
		columns []string,
		values []string,
		t ...time.Time)

	AddRawLog(log *protocol.Log)

	AddDataWithContext(tags map[string]string,
		fields map[string]string,
		ctx map[string]interface{},
		t ...time.Time)

	AddDataArrayWithContext(tags map[string]string,
		columns []string,
		values []string,
		ctx map[string]interface{},
		t ...time.Time)

	AddRawLogWithContext(log *protocol.Log, ctx map[string]interface{})
}

[liuhaoyang]

与其自行定义数据结构符合各种协议，不如一步到位直接使用 otlp 规范来封装

自建信号结构体

import (
	logs "go.opentelemetry.io/proto/otlp/logs/v1"
	metrics "go.opentelemetry.io/proto/otlp/metrics/v1"
	traces "go.opentelemetry.io/proto/otlp/trace/v1"
)

type OTLPSignal struct {
	metric *metrics.ResourceMetrics
	log    *logs.ResourceLogs
	span   *traces.ResourceSpans
}

Collector 增加 2 个信号的收集方法

当插件还是老的数据格式可以做一层数据适配逻辑，最终目标是吧所有插件都转换成 OTLPSignal 的数据格式

// https://github.com/alibaba/ilogtail/blob/main/collector.go
type Collector interface {
        AddOTLPSignal(s *OTLPSignal)

	AddOTLPSignalArray(s []*OTLPSignal)

	AddData(tags map[string]string,
		fields map[string]string,
		t ...time.Time)

	AddDataArray(tags map[string]string,
		columns []string,
		values []string,
		t ...time.Time)

	AddRawLog(log *protocol.Log)

	AddDataWithContext(tags map[string]string,
		fields map[string]string,
		ctx map[string]interface{},
		t ...time.Time)

	AddDataArrayWithContext(tags map[string]string,
		columns []string,
		values []string,
		ctx map[string]interface{},
		t ...time.Time)

	AddRawLogWithContext(log *protocol.Log, ctx map[string]interface{})
}

otlp 不适用的几个原因

1. otlp 的设计太冗余了，它更适合做传输协议，不适合做data pipeline内的计算模型
2. otlp 是单值的设计，对多值metrics做处理的话，性能损失比较严重。比如 influxdb 数据流入，需要先把多值拆分为单值 ，在 flusher 再聚合成多值
3. 插件数据适配逻辑，也会额外多一次转换消耗