数据模型

iLogtail 目前支持 SLS Log Protocol 和 Pipeline Event 两种数据模型，两种模型的描述和对比如下：
| | SLS Log Protocol | Pipeline Event | | ---- | ---- | ---- | | 描述 | SLS 日志的专用处理结构 | 可扩展的可观测性数据模型，支持Metrics、Trace、Logging、Bytes、Profile等 | | 流水线配置版本 | v1 | v2 | | Logging 数据结构 | 支持 | 支持 | | Metric 数据结构 | 不支持 | 支持 | | Trace 数据结构 | 不支持 | 支持 | | ByteArray 数据结构 | 不支持 | 支持 | | Profile 数据结构 | 不支持 | 支持 | | 自定义数据结构 | 不支持 | 支持 |

SLS Log Protocol

参考 SLS 协议

Pipeline Event

PipelineEvent 是数据处理管道中的抽象数据接口，定义如下

type PipelineEvent interface {
 GetName() string

 SetName(string)

 GetTags() Tags

 GetType() EventType

 GetTimestamp() uint64

 GetObservedTimestamp() uint64

 SetObservedTimestamp(uint64)

 Clone() PipelineEvent
}

我们还需要引入聚合的概念 PipelineGroupEvents，来支持部分需要对数据进行分组的操作，聚合事件也允许有独立的 meta 和 tags，一般是从数据中提取

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

type GroupInfo struct {
 Metadata Metadata
 Tags     Tags
}

Metric 模型

Metric模型定义如下：

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

主流的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上可能使用单值或者多值，对于单值和多值的处理，可以使用下面的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 类型
  }
}

TypedValue 设计。MetricValue 不管是单值还是多值的value类型都是float64，在一些 TSDB 中比如 influxdb，除了数值类型，还支持string bool 等非数值类型 influxdb field-value 。为此，我们扩展了一个额外的 TypedValue 字段用来存储非数值的 field 值。

type TypedValue struct {
        Type  ValueType
        Value interface{}
}

type MetricTypedValues interface {
        KeyValues[*TypedValue]
}

Trace 模型

目前主流的开源 tracing 模型有opentracing opentelemetry skywalking 等几种不同的规范。 不管在哪种 trace 模型中，trace 都是由多个 Span 组成的，(不同的是在 skywalking 和许多私有协议中，trace 和 span 中间还有一个 segment 或者 transaction 概念）。
在 Span 中，一般还会定义携带数据语义的 Tags ，和记录一些关键事件发生的 logs 或 events 。
其中zipkin jaeger 都是 opentracing 的一种实现，而opentelemetry 可以认为是在opentracing的基础上扩展的新规范和超集（兼容 w3c 和定义了明确的 OTLP 协议）。 所以我们定义的 Span 结构要兼容上面提到的几种开源协议，具体的结构如下

type SpanLink struct {
    TraceID    string
    SpanID     string
    TraceState string
    Tags       Tags
}

type SpanEvent struct {
    Timestamp int64
    Name      string
}

type Span struct {
    TraceID      string
    SpanID       string
    ParentSpanID string
    Name         string
    TraceState   string

    StartTime         uint64
    EndTime           uint64
    ObservedTimestamp uint64

    Kind   SpanKind
    Status StatusCode
    Tags   Tags
    Links  []*SpanLink
    Events []*SpanEvent
}

Log 模型

Log 模型可以兼容非结构化和结构化日志，并且预留链路信息记录的字段。

• 其中 Offset 记录了日志文件采集时，日志在文件中的偏移量，可选
• Name 对 Log 也是可选的
• SpanID 、TraceID 在数据关联时使用，可选
• Contents 在日志结构化的场景使用，存储从 Body 原始日志文本分析的 KV

type LogContents KeyValues[string]

type Log struct {
    Name              string
    Level             string
    SpanID            string
    TraceID           string
    Tags              Tags
    Timestamp         uint64
    ObservedTimestamp uint64
    Offset            uint64
    Contents          LogContents
}

其中Level字段，对齐Open Telemetry Logs，支持以下等级： Trace, Trace2, Trace3, Trace4, Debug, Debug2, Debug3, Debug4, Info, Info2, Info3, Info4, Warn, Warn2, Warn3, Warn4, Error, Error2, Error3, Error4, Fatal, Fatal2, Fatal3, Fatal4, Unspecified.