OPSaid – OpenTelemetry

Docs: 协议规范

Fri, 22 Aug 2025 10:57:59 +0800

简要概述

OpenTelemetry是由两个重要的开源观测性项目合并而成：

OpenTracing - 由Ben Sigelman（LightStep CEO）等人发起
- 专注于分布式追踪标准化
- 提供厂商中立的追踪API
OpenCensus - 由Google开发并开源
- 提供指标(Metrics)和追踪(Tracing)的采集和导出
- 内置多种后端导出器

2019年5月，这两个项目正式合并为OpenTelemetry，由CNCF（云原生计算基金会）托管。

OpenTelemetry 指标协议被设计为传输指标数据的标准规范。为明确数据的预期用途及相关语义，指标数据流类型将融入一个双层框架：

1. 高层模型（API 层）

聚焦开发者的使用体验
处理离散的原始测量值（如计数器递增、测量记录）
对应 OpenTelemetry SDK 的 Metrics API
示例：在代码中调用 counter.Add(1) 或 recorder.Record(25.5)

2. 底层模型（导出层）

定义标准化时间序列格式
处理聚合后的输出值（如总和、平均值、分位数）
对应 OTLP 导出协议格式
示例：生成如 http_requests_total{status="200"} 1534 的时间序列

该模型专为实现现有系统的数据导入与导出而设计，现有主流指标数据格式均可无损转换为该指标数据模型，确保语义完整性与数据保真度，其中针对 Prometheus 和 Statsd 输出格式的转换规范已作出明确定义。

数据流程

OpenTelemetry 协议（OTLP）规范定义了遥测数据在数据源、中间节点（如收集器）与后端系统之间的编码方式、传输机制及投递流程，大致流程如下：

flowchart TD A[Instrumented Application
数据源] --> B[Exporter
OTLP Exporter] B --> C{传输方式选择} C -->|HTTP| D[HTTP/1.1 or HTTP/2
Application Content Headers] C -->|gRPC| E[gRPC
gRPC Metadata Headers] D --> F{序列化格式选择} E --> F F -->|Protocol Buffers| G[编码: Protocol Buffers
二进制格式] F -->|JSON| H[编码: JSON
文本格式可读性好] G --> I[Collector
OTLP Receiver] H --> I subgraph I [OpenTelemetry 收集器核心处理] direction LR I1[Receiver] --> I2[Processor
过滤/转换/批处理] --> I3[Exporter
格式转换与转发] end I --> J{后端系统投递} J -->|OTLP| K[后端系统 1
支持OTLP的后端] J -->|Prometheus| L[后端系统 2
Prometheus] J -->|Jaeger| M[后端系统 3
Jaeger] J -->|Zipkin| N[后端系统 4
Zipkin] J -->|Kafka| O[后端系统 5
消息队列/数据湖]

服务定义

指标（Metrics）

metrics_service.proto

service MetricsService {
 rpc Export(ExportMetricsServiceRequest) returns (ExportMetricsServiceResponse) {}
}

message ExportMetricsServiceRequest {
 repeated opentelemetry.proto.metrics.v1.ResourceMetrics resource_metrics = 1;
}

message ExportMetricsServiceResponse {
 ExportMetricsPartialSuccess partial_success = 1;
}

message ExportMetricsPartialSuccess {
 int64 rejected_data_points = 1;

 string error_message = 2;
}

日志（Logging）

logs_service.proto

service LogsService {
 rpc Export(ExportLogsServiceRequest) returns (ExportLogsServiceResponse) {}
}

message ExportLogsServiceRequest {
 repeated opentelemetry.proto.logs.v1.ResourceLogs resource_logs = 1;
}

message ExportLogsServiceResponse {
 ExportLogsPartialSuccess partial_success = 1;
}

message ExportLogsPartialSuccess {
 string error_message = 2;
}

追踪（Tracing）

trace_service.proto

service TraceService {
 rpc Export(ExportTraceServiceRequest) returns (ExportTraceServiceResponse) {}
}

message ExportTraceServiceRequest {
 repeated opentelemetry.proto.trace.v1.ResourceSpans resource_spans = 1;
}

message ExportTraceServiceResponse {
 ExportTracePartialSuccess partial_success = 1;
}

message ExportTracePartialSuccess {
 string error_message = 2;
}

OTLP/gRPC

客户端请求

默认服务端在 tcp 4317 端口监听，通过 grpc 协议对外。在建立连接后客户端可持续推送遥测数据至服务端。

客户端与服务端之间支持以下模式：

顺序传输模式（请求-响应-请求-响应）

也就是客户端上报数据，服务端成功接收后继续下次上报，一般在低延迟网络下使用比较简单。

高吞吐量传输

客户端持续上报数据而无需登录服务端响应成功。

理论公式：最大吞吐量 = (最大并发请求数 × 单请求最大容量) / (网络延迟 + 服务端响应时间)

示例分析（基于给定参数）：

单请求上限：100 spans
网络往返延迟：200ms
服务端处理时间：300ms
单并发吞吐量：100 spans / (0.2s+0.3s) = 200 spans/秒

服务端响应

TODO;

OTLP/HTTP

请求体编码

protobuf 编码

Content-Type: application/x-protobuf

json 编码

Content-Type: application/json

客户端请求

默认服务端在 tcp 4318 端口监听，服务是通过 grpc-gateway 对以上 grpc 做 http 转换实现，默认几个接口定义如下：

logs_service_http.yaml

type: google.api.Service
config_version: 3
http:
 rules:
 - selector: opentelemetry.proto.collector.logs.v1.LogsService.Export
 post: /v1/logs
 body: "*"

metrics_service_http.yaml

type: google.api.Service
config_version: 3
http:
 rules:
 - selector: opentelemetry.proto.collector.metrics.v1.MetricsService.Export
 post: /v1/metrics
 body: "*"

trace_service_http.yaml

type: google.api.Service
config_version: 3
http:
 rules:
 - selector: opentelemetry.proto.collector.trace.v1.TraceService.Export
 post: /v1/traces
 body: "*"

服务端响应

TODO;

Docs: Collector

Sun, 14 May 2023 11:33:11 +0800

简要概述

OpenTelemetry 支持追踪（Tracing）、指标（Metrics）、跨域传递（Baggage）、日志（Logging）和 Profiles 这五种独立的信号类型，

每种类型均由四个核心组件构成：

API 层：提供与应用代码交互的编程接口；
SDK 层：实现数据采集、处理及导出逻辑；
OTLP 协议：专为遥测数据设计的开放传输协议；
收集器（Collector）：提供数据接收、处理与转发的中枢服务。

当前以上五种信号前四个均可稳定使用，各组件状态：

追踪（Tracing）

组件	状态
API 层	stable
SDK 层	stable
OTLP 协议	stable

指标（Metrics）

组件	状态
API 层	stable
SDK 层	混合
OTLP 协议	stable

跨域传递（Baggage）

组件	状态
API 层	stable
SDK 层	stable
OTLP 协议	stable

日志（Logging）

组件	状态
API 层	stable
SDK 层	stable
OTLP 协议	stable

Profiles

组件	状态
OTLP 协议	develop

部署模式

SDK 形式

在程序端植入 sdk 采集上报。

Agent 模式

预先编译安装包

https://opentelemetry.io/docs/collector/getting-started/#linux-packaging

源码包编译安装

export GOOS=linux
export GOARCH=amd64

git clone https://github.com/open-telemetry/opentelemetry-collector.git
cd opentelemetry-collector

make install-tools
make otelcorecol
./bin/otelcorecol_* --config ./examples/local/otel-config.yaml

Gateway 模式

TODO；

配置示列

extensions:
 zpages:
 endpoint: 0.0.0.0:55679

receivers:
 otlp:
 protocols:
 grpc:
 endpoint: 0.0.0.0:4317
 http:
 endpoint: 0.0.0.0:4318

processors:
 batch:
 memory_limiter:
 # 75% of maximum memory up to 2G
 limit_mib: 1536
 # 25% of limit up to 2G
 spike_limit_mib: 512
 check_interval: 5s

exporters:
 debug:
 verbosity: detailed

service:
 pipelines:
 traces:
 receivers: [otlp]
 processors: [memory_limiter, batch]
 exporters: [debug]
 metrics:
 receivers: [otlp]
 processors: [memory_limiter, batch]
 exporters: [debug]
 logs:
 receivers: [otlp]
 processors: [memory_limiter, batch]
 exporters: [debug]

 extensions: [zpages]

配置结构

Config

github.com/open-telemetry/opentelemetry-collector/otelcol/config.go

// Config defines the configuration for the various elements of collector or agent.
type Config struct {
 // Receivers is a map of ComponentID to Receivers.
 Receivers map[component.ID]component.Config

 // Exporters is a map of ComponentID to Exporters.
 Exporters map[component.ID]component.Config

 // Processors is a map of ComponentID to Processors.
 Processors map[component.ID]component.Config

 // Connectors is a map of ComponentID to connectors.
 Connectors map[component.ID]component.Config

 // Extensions is a map of ComponentID to extensions.
 Extensions map[component.ID]component.Config

 Service service.Config
}

Receivers

github.com/open-telemetry/opentelemetry-collector/receiver

receivers:
 ${component.ID}:
 ${component.Config}
 ......

默认主代码仓库仅支持 otlp 数据源，其他均在扩展仓库 opentelemetry-collector-contrib 根据实际情况在编译时引入。

otlp

github.com/open-telemetry/opentelemetry-collector/receiver/otlpreceiver

receivers:
 otlp:
 protocols:
 grpc:
 # <configgrpc.GRPCServerSettings>
 http:
 # <confighttp.HTTPServerSettings>

// Protocols is the configuration for the supported protocols.
type Protocols struct {
 GRPC *configgrpc.GRPCServerSettings `mapstructure:"grpc"`
 HTTP *confighttp.HTTPServerSettings `mapstructure:"http"`
}

// Config defines configuration for OTLP receiver.
type Config struct {
 // Protocols is the configuration for the supported protocols, currently gRPC and HTTP (Proto and JSON).
 Protocols `mapstructure:"protocols"`
}

Exporters

github.com/open-telemetry/opentelemetry-collector/exporter

根据 Config 转换 yaml 配置如下：

exporters:
 ${component.ID}:
 ${component.Config}
 ......

存在以下几个内置的 exporter

exporter/debugexporter
exporter/loggingexporter
exporter/otlpexporter
exporter/otlphttpexporter

还有大量第三方组件见 opentelemetry-collector-contrib 仓库。

类型 otlpexporter 配置

配置代码见 exporter/otlpexporter/config.go

// Config defines configuration for OTLP exporter.
type Config struct {
 exporterhelper.TimeoutSettings `mapstructure:",squash"` // squash ensures fields are correctly decoded in embedded struct.
 exporterhelper.QueueSettings `mapstructure:"sending_queue"`
 exporterhelper.RetrySettings `mapstructure:"retry_on_failure"`

 configgrpc.GRPCClientSettings `mapstructure:",squash"` // squash ensures fields are correctly decoded in embedded struct.
}

类型 otlphttpexporter 配置

配置代码见 exporter/otlphttpexporter/config.go

// Config defines configuration for OTLP/HTTP exporter.
type Config struct {
 confighttp.HTTPClientSettings `mapstructure:",squash"` // squash ensures fields are correctly decoded in embedded struct.
 exporterhelper.QueueSettings `mapstructure:"sending_queue"`
 exporterhelper.RetrySettings `mapstructure:"retry_on_failure"`

 // The URL to send traces to. If omitted the Endpoint + "/v1/traces" will be used.
 TracesEndpoint string `mapstructure:"traces_endpoint"`

 // The URL to send metrics to. If omitted the Endpoint + "/v1/metrics" will be used.
 MetricsEndpoint string `mapstructure:"metrics_endpoint"`

 // The URL to send logs to. If omitted the Endpoint + "/v1/logs" will be used.
 LogsEndpoint string `mapstructure:"logs_endpoint"`
}

Processors

github.com/open-telemetry/opentelemetry-collector/processor

用于在组件 Receivers 接收数据和 Exporters 导出数据之间运行，该部分是可选的，但建议根据实际情况使用一些。

同样的仅在这里配置是不会启用它，也需要在 Service 中配置 pipelines 来启用。

存在以下几个内置的 processor

processor/batchprocessor
processor/memorylimiterprocessor

还有大量第三方组件见 opentelemetry-collector-contrib 仓库。

根据 Config 转换 yaml 配置如下：

processors:
 ${component.ID}:
 ${component.Config}
 ......

启用 memory_limiter 与 batch 组件示例：

processors:
 batch:
 memory_limiter:
 # 75% of maximum memory up to 4G
 limit_mib: 1536
 # 25% of limit up to 2G
 spike_limit_mib: 512
 check_interval: 5s

service:
 pipelines:
 traces:
 processors: [memory_limiter, batch]
 metrics:
 processors: [memory_limiter, batch]

组件 batch 配置

// Config defines configuration for batch processor.
type Config struct {
 // Timeout sets the time after which a batch will be sent regardless of size.
 // When this is set to zero, batched data will be sent immediately.
 Timeout time.Duration `mapstructure:"timeout"`

 // SendBatchSize is the size of a batch which after hit, will trigger it to be sent.
 // When this is set to zero, the batch size is ignored and data will be sent immediately
 // subject to only send_batch_max_size.
 SendBatchSize uint32 `mapstructure:"send_batch_size"`

 // SendBatchMaxSize is the maximum size of a batch. It must be larger than SendBatchSize.
 // Larger batches are split into smaller units.
 // Default value is 0, that means no maximum size.
 SendBatchMaxSize uint32 `mapstructure:"send_batch_max_size"`

 // MetadataKeys is a list of client.Metadata keys that will be
 // used to form distinct batchers. If this setting is empty,
 // a single batcher instance will be used. When this setting
 // is not empty, one batcher will be used per distinct
 // combination of values for the listed metadata keys.
 //
 // Empty value and unset metadata are treated as distinct cases.
 //
 // Entries are case-insensitive. Duplicated entries will
 // trigger a validation error.
 MetadataKeys []string `mapstructure:"metadata_keys"`

 // MetadataCardinalityLimit indicates the maximum number of
 // batcher instances that will be created through a distinct
 // combination of MetadataKeys.
 MetadataCardinalityLimit uint32 `mapstructure:"metadata_cardinality_limit"`
}

组件 memorylimiter 配置

// Config defines configuration for memory memoryLimiter processor.
type Config struct {
 // CheckInterval is the time between measurements of memory usage for the
 // purposes of avoiding going over the limits. Defaults to zero, so no
 // checks will be performed.
 CheckInterval time.Duration `mapstructure:"check_interval"`

 // MemoryLimitMiB is the maximum amount of memory, in MiB, targeted to be
 // allocated by the process.
 MemoryLimitMiB uint32 `mapstructure:"limit_mib"`

 // MemorySpikeLimitMiB is the maximum, in MiB, spike expected between the
 // measurements of memory usage.
 MemorySpikeLimitMiB uint32 `mapstructure:"spike_limit_mib"`

 // MemoryLimitPercentage is the maximum amount of memory, in %, targeted to be
 // allocated by the process. The fixed memory settings MemoryLimitMiB has a higher precedence.
 MemoryLimitPercentage uint32 `mapstructure:"limit_percentage"`

 // MemorySpikePercentage is the maximum, in percents against the total memory,
 // spike expected between the measurements of memory usage.
 MemorySpikePercentage uint32 `mapstructure:"spike_limit_percentage"`
}

Connectors

github.com/open-telemetry/opentelemetry-collector/connector

用于连接 Receivers 与 Exporters 两个组件且作为其中的管道，起点用于接收 Receivers 数据，终点用于 Exporters 导出数据。

它可以消费和发出相同数据类型或不同数据类型的数据，连接器可以生成并发送数据来汇总消耗的数据，也可以简单地复制或路由数据。

根据 Config 转换 yaml 配置如下：

connectors:
 ${component.ID}:
 ${component.Config}
 ......

还有大量第三方组件见 opentelemetry-collector-contrib 仓库。

存在以下几个内置的 connector

connector/forwardconnector

组件 forward 配置

connectors:
 forward:

TODO;

Extensions

可选部分，主要用于不涉及处理遥测数据的任务，如：运行状况监视、服务发现和数据转发等。

同样的仅在这里配置是不会启用它，也需要在 Service 中配置 pipelines 来启用。

根据 Config 转换 yaml 配置如下：

extensions:
 ${component.ID}:
 ${component.Config}
 ......

存在以下几个内置的 processor

extension/ballastextension
extension/zpagesextension

还有大量第三方组件见 opentelemetry-collector-contrib 仓库。

组件 ballast 配置

// Config has the configuration for the ballast extension.
type Config struct {
 // SizeMiB is the size, in MiB, of the memory ballast
 // to be created for this process.
 SizeMiB uint64 `mapstructure:"size_mib"`

 // SizeInPercentage is the maximum amount of memory ballast, in %, targeted to be
 // allocated. The fixed memory settings SizeMiB has a higher precedence.
 SizeInPercentage uint64 `mapstructure:"size_in_percentage"`
}

组件 zpages 配置

// Config has the configuration for the extension enabling the zPages extension.
type Config struct {
 // TCPAddr is the address and port in which the zPages will be listening to.
 // Use localhost:<port> to make it available only locally, or ":<port>" to
 // make it available on all network interfaces.
 TCPAddr confignet.TCPAddr `mapstructure:",squash"`
}

Service

由 telemetry、extensions、pipelines 三部分组成。

其中 telemetry 用于自身进程的遥感配置，而 extensions、pipelines 用于根据 Receivers、Processors、Exporters、Extensions 部分中的配置启用的组件，如果组件已配置，但未在这里定义，则不会启用该组件。

配置示例：

service:
 telemetry:
 logs:
 level: debug
 initial_fields:
 service: my-instance
 metrics:
 level: detailed
 address: 0.0.0.0:8888

 extensions: [health_check, pprof]

 pipelines:
 traces:
 receivers: [otlp]
 exporters: [otlp]

数据结构

component.ID

go.opentelemetry.io/collector/component.ID

// ID represents the identity for a component. It combines two values:
// * type - the Type of the component.
// * name - the name of that component.
// The component ID (combination type + name) is unique for a given component.Kind.
type ID struct {
 typeVal Type `mapstructure:"-"`
 nameVal string `mapstructure:"-"`
}

component.Config

go.opentelemetry.io/collector/component.Config

// Config defines the configuration for a component.Component.
//
// Implementations and/or any sub-configs (other types embedded or included in the Config implementation)
// MUST implement the ConfigValidator if any validation is required for that part of the configuration
// (e.g. check if a required field is present).
//
// A valid implementation MUST pass the check componenttest.CheckConfigStruct (return nil error).
type Config any

builtin/builtin.go

// any is an alias for interface{} and is equivalent to interface{} in all ways.
type any = interface{}

在 go1.18 新增了 any 类型，为 interface{} 的别名。

service.Config

github.com/open-telemetry/opentelemetry-collector/service/config.go

// Config defines the configurable components of the Service.
type Config struct {
 // Telemetry is the configuration for collector's own telemetry.
 Telemetry telemetry.Config `mapstructure:"telemetry"`

 // Extensions are the ordered list of extensions configured for the service.
 Extensions extensions.Config `mapstructure:"extensions"`

 // Pipelines are the set of data pipelines configured for the service.
 Pipelines pipelines.Config `mapstructure:"pipelines"`
}

configgrpc.GRPCClientSettings

github.com/open-telemetry/opentelemetry-collector/config/configgrpc

// GRPCClientSettings defines common settings for a gRPC client configuration.
type GRPCClientSettings struct {
 // The target to which the exporter is going to send traces or metrics,
 // using the gRPC protocol. The valid syntax is described at
 // https://github.com/grpc/grpc/blob/master/doc/naming.md.
 Endpoint string `mapstructure:"endpoint"`

 // The compression key for supported compression types within collector.
 Compression configcompression.CompressionType `mapstructure:"compression"`

 // TLSSetting struct exposes TLS client configuration.
 TLSSetting configtls.TLSClientSetting `mapstructure:"tls"`

 // The keepalive parameters for gRPC client. See grpc.WithKeepaliveParams.
 // (https://godoc.org/google.golang.org/grpc#WithKeepaliveParams).
 Keepalive *KeepaliveClientConfig `mapstructure:"keepalive"`

 // ReadBufferSize for gRPC client. See grpc.WithReadBufferSize.
 // (https://godoc.org/google.golang.org/grpc#WithReadBufferSize).
 ReadBufferSize int `mapstructure:"read_buffer_size"`

 // WriteBufferSize for gRPC gRPC. See grpc.WithWriteBufferSize.
 // (https://godoc.org/google.golang.org/grpc#WithWriteBufferSize).
 WriteBufferSize int `mapstructure:"write_buffer_size"`

 // WaitForReady parameter configures client to wait for ready state before sending data.
 // (https://github.com/grpc/grpc/blob/master/doc/wait-for-ready.md)
 WaitForReady bool `mapstructure:"wait_for_ready"`

 // The headers associated with gRPC requests.
 Headers map[string]configopaque.String `mapstructure:"headers"`

 // Sets the balancer in grpclb_policy to discover the servers. Default is pick_first.
 // https://github.com/grpc/grpc-go/blob/master/examples/features/load_balancing/README.md
 BalancerName string `mapstructure:"balancer_name"`

 // WithAuthority parameter configures client to rewrite ":authority" header
 // (godoc.org/google.golang.org/grpc#WithAuthority)
 Authority string `mapstructure:"authority"`

 // Auth configuration for outgoing RPCs.
 Auth *configauth.Authentication `mapstructure:"auth"`
}

configgrpc.GRPCServerSettings

github.com/open-telemetry/opentelemetry-collector/config/configgrpc

// GRPCServerSettings defines common settings for a gRPC server configuration.
type GRPCServerSettings struct {
 // Server net.Addr config. For transport only "tcp" and "unix" are valid options.
 NetAddr confignet.NetAddr `mapstructure:",squash"`

 // Configures the protocol to use TLS.
 // The default value is nil, which will cause the protocol to not use TLS.
 TLSSetting *configtls.TLSServerSetting `mapstructure:"tls"`

 // MaxRecvMsgSizeMiB sets the maximum size (in MiB) of messages accepted by the server.
 MaxRecvMsgSizeMiB uint64 `mapstructure:"max_recv_msg_size_mib"`

 // MaxConcurrentStreams sets the limit on the number of concurrent streams to each ServerTransport.
 // It has effect only for streaming RPCs.
 MaxConcurrentStreams uint32 `mapstructure:"max_concurrent_streams"`

 // ReadBufferSize for gRPC server. See grpc.ReadBufferSize.
 // (https://godoc.org/google.golang.org/grpc#ReadBufferSize).
 ReadBufferSize int `mapstructure:"read_buffer_size"`

 // WriteBufferSize for gRPC server. See grpc.WriteBufferSize.
 // (https://godoc.org/google.golang.org/grpc#WriteBufferSize).
 WriteBufferSize int `mapstructure:"write_buffer_size"`

 // Keepalive anchor for all the settings related to keepalive.
 Keepalive *KeepaliveServerConfig `mapstructure:"keepalive"`

 // Auth for this receiver
 Auth *configauth.Authentication `mapstructure:"auth"`

 // Include propagates the incoming connection's metadata to downstream consumers.
 // Experimental: *NOTE* this option is subject to change or removal in the future.
 IncludeMetadata bool `mapstructure:"include_metadata"`
}

confighttp.HTTPClientSettings

github.com/open-telemetry/opentelemetry-collector/config/confighttp/confighttp.go

// HTTPClientSettings defines settings for creating an HTTP client.
type HTTPClientSettings struct {
 // The target URL to send data to (e.g.: http://some.url:9411/v1/traces).
 Endpoint string `mapstructure:"endpoint"`

 // TLSSetting struct exposes TLS client configuration.
 TLSSetting configtls.TLSClientSetting `mapstructure:"tls"`

 // ReadBufferSize for HTTP client. See http.Transport.ReadBufferSize.
 ReadBufferSize int `mapstructure:"read_buffer_size"`

 // WriteBufferSize for HTTP client. See http.Transport.WriteBufferSize.
 WriteBufferSize int `mapstructure:"write_buffer_size"`

 // Timeout parameter configures `http.Client.Timeout`.
 Timeout time.Duration `mapstructure:"timeout"`

 // Additional headers attached to each HTTP request sent by the client.
 // Existing header values are overwritten if collision happens.
 // Header values are opaque since they may be sensitive.
 Headers map[string]configopaque.String `mapstructure:"headers"`

 // Custom Round Tripper to allow for individual components to intercept HTTP requests
 CustomRoundTripper func(next http.RoundTripper) (http.RoundTripper, error)

 // Auth configuration for outgoing HTTP calls.
 Auth *configauth.Authentication `mapstructure:"auth"`

 // The compression key for supported compression types within collector.
 Compression configcompression.CompressionType `mapstructure:"compression"`

 // MaxIdleConns is used to set a limit to the maximum idle HTTP connections the client can keep open.
 // There's an already set value, and we want to override it only if an explicit value provided
 MaxIdleConns *int `mapstructure:"max_idle_conns"`

 // MaxIdleConnsPerHost is used to set a limit to the maximum idle HTTP connections the host can keep open.
 // There's an already set value, and we want to override it only if an explicit value provided
 MaxIdleConnsPerHost *int `mapstructure:"max_idle_conns_per_host"`

 // MaxConnsPerHost limits the total number of connections per host, including connections in the dialing,
 // active, and idle states.
 // There's an already set value, and we want to override it only if an explicit value provided
 MaxConnsPerHost *int `mapstructure:"max_conns_per_host"`

 // IdleConnTimeout is the maximum amount of time a connection will remain open before closing itself.
 // There's an already set value, and we want to override it only if an explicit value provided
 IdleConnTimeout *time.Duration `mapstructure:"idle_conn_timeout"`

 // DisableKeepAlives, if true, disables HTTP keep-alives and will only use the connection to the server
 // for a single HTTP request.
 //
 // WARNING: enabling this option can result in significant overhead establishing a new HTTP(S)
 // connection for every request. Before enabling this option please consider whether changes
 // to idle connection settings can achieve your goal.
 DisableKeepAlives bool `mapstructure:"disable_keep_alives"`
}

confignet.NetAddr

// NetAddr represents a network endpoint address.
type NetAddr struct {
 // Endpoint configures the address for this network connection.
 // For TCP and UDP networks, the address has the form "host:port". The host must be a literal IP address,
 // or a host name that can be resolved to IP addresses. The port must be a literal port number or a service name.
 // If the host is a literal IPv6 address it must be enclosed in square brackets, as in "[2001:db8::1]:80" or
 // "[fe80::1%zone]:80". The zone specifies the scope of the literal IPv6 address as defined in RFC 4007.
 Endpoint string `mapstructure:"endpoint"`

 // Transport to use. Known protocols are "tcp", "tcp4" (IPv4-only), "tcp6" (IPv6-only), "udp", "udp4" (IPv4-only),
 // "udp6" (IPv6-only), "ip", "ip4" (IPv4-only), "ip6" (IPv6-only), "unix", "unixgram" and "unixpacket".
 Transport string `mapstructure:"transport"`
}

configtls.TLSServerSetting

// TLSServerSetting contains TLS configurations that are specific to server
// connections in addition to the common configurations. This should be used by
// components configuring TLS server connections.
type TLSServerSetting struct {
 // squash ensures fields are correctly decoded in embedded struct.
 TLSSetting `mapstructure:",squash"`

 // These are config options specific to server connections.

 // Path to the TLS cert to use by the server to verify a client certificate. (optional)
 // This sets the ClientCAs and ClientAuth to RequireAndVerifyClientCert in the TLSConfig. Please refer to
 // https://godoc.org/crypto/tls#Config for more information. (optional)
 ClientCAFile string `mapstructure:"client_ca_file"`

 // Reload the ClientCAs file when it is modified
 // (optional, default false)
 ReloadClientCAFile bool `mapstructure:"client_ca_file_reload"`
}

// TLSSetting exposes the common client and server TLS configurations.
// Note: Since there isn't anything specific to a server connection. Components
// with server connections should use TLSSetting.
type TLSSetting struct {
 // Path to the CA cert. For a client this verifies the server certificate.
 // For a server this verifies client certificates. If empty uses system root CA.
 // (optional)
 CAFile string `mapstructure:"ca_file"`

 // Path to the TLS cert to use for TLS required connections. (optional)
 CertFile string `mapstructure:"cert_file"`

 // Path to the TLS key to use for TLS required connections. (optional)
 KeyFile string `mapstructure:"key_file"`

 // MinVersion sets the minimum TLS version that is acceptable.
 // If not set, TLS 1.2 will be used. (optional)
 MinVersion string `mapstructure:"min_version"`

 // MaxVersion sets the maximum TLS version that is acceptable.
 // If not set, refer to crypto/tls for defaults. (optional)
 MaxVersion string `mapstructure:"max_version"`

 // ReloadInterval specifies the duration after which the certificate will be reloaded
 // If not set, it will never be reloaded (optional)
 ReloadInterval time.Duration `mapstructure:"reload_interval"`
}

KeepaliveServerConfig

// KeepaliveServerConfig is the configuration for keepalive.
type KeepaliveServerConfig struct {
 ServerParameters *KeepaliveServerParameters `mapstructure:"server_parameters"`
 EnforcementPolicy *KeepaliveEnforcementPolicy `mapstructure:"enforcement_policy"`
}

// KeepaliveServerParameters allow configuration of the keepalive.ServerParameters.
// The same default values as keepalive.ServerParameters are applicable and get applied by the server.
// See https://godoc.org/google.golang.org/grpc/keepalive#ServerParameters for details.
type KeepaliveServerParameters struct {
 MaxConnectionIdle time.Duration `mapstructure:"max_connection_idle"`
 MaxConnectionAge time.Duration `mapstructure:"max_connection_age"`
 MaxConnectionAgeGrace time.Duration `mapstructure:"max_connection_age_grace"`
 Time time.Duration `mapstructure:"time"`
 Timeout time.Duration `mapstructure:"timeout"`
}

// KeepaliveEnforcementPolicy allow configuration of the keepalive.EnforcementPolicy.
// The same default values as keepalive.EnforcementPolicy are applicable and get applied by the server.
// See https://godoc.org/google.golang.org/grpc/keepalive#EnforcementPolicy for details.
type KeepaliveEnforcementPolicy struct {
 MinTime time.Duration `mapstructure:"min_time"`
 PermitWithoutStream bool `mapstructure:"permit_without_stream"`
}

configauth.Authentication

// Authentication defines the auth settings for the receiver.
type Authentication struct {
 // AuthenticatorID specifies the name of the extension to use in order to authenticate the incoming data point.
 AuthenticatorID component.ID `mapstructure:"authenticator"`
}

confighttp.HTTPServerSettings

// HTTPServerSettings defines settings for creating an HTTP server.
type HTTPServerSettings struct {
 // Endpoint configures the listening address for the server.
 Endpoint string `mapstructure:"endpoint"`

 // TLSSetting struct exposes TLS client configuration.
 TLSSetting *configtls.TLSServerSetting `mapstructure:"tls"`

 // CORS configures the server for HTTP cross-origin resource sharing (CORS).
 CORS *CORSSettings `mapstructure:"cors"`

 // Auth for this receiver
 Auth *configauth.Authentication `mapstructure:"auth"`

 // MaxRequestBodySize sets the maximum request body size in bytes
 MaxRequestBodySize int64 `mapstructure:"max_request_body_size"`

 // IncludeMetadata propagates the client metadata from the incoming requests to the downstream consumers
 // Experimental: *NOTE* this option is subject to change or removal in the future.
 IncludeMetadata bool `mapstructure:"include_metadata"`
}

CORSSettings

// CORSSettings configures a receiver for HTTP cross-origin resource sharing (CORS).
// See the underlying https://github.com/rs/cors package for details.
type CORSSettings struct {
 // AllowedOrigins sets the allowed values of the Origin header for
 // HTTP/JSON requests to an OTLP receiver. An origin may contain a
 // wildcard (*) to replace 0 or more characters (e.g.,
 // "http://*.domain.com", or "*" to allow any origin).
 AllowedOrigins []string `mapstructure:"allowed_origins"`

 // AllowedHeaders sets what headers will be allowed in CORS requests.
 // The Accept, Accept-Language, Content-Type, and Content-Language
 // headers are implicitly allowed. If no headers are listed,
 // X-Requested-With will also be accepted by default. Include "*" to
 // allow any request header.
 AllowedHeaders []string `mapstructure:"allowed_headers"`

 // MaxAge sets the value of the Access-Control-Max-Age response header.
 // Set it to the number of seconds that browsers should cache a CORS
 // preflight response for.
 MaxAge int `mapstructure:"max_age"`
}

telemetry.Config

github.com/open-telemetry/opentelemetry-collector/service/telemetry

// Config defines the configurable settings for service telemetry.
type Config struct {
 Logs LogsConfig `mapstructure:"logs"`
 Metrics MetricsConfig `mapstructure:"metrics"`
 Traces TracesConfig `mapstructure:"traces"`

 // Resource specifies user-defined attributes to include with all emitted telemetry.
 // Note that some attributes are added automatically (e.g. service.version) even
 // if they are not specified here. In order to suppress such attributes the
 // attribute must be specified in this map with null YAML value (nil string pointer).
 Resource map[string]*string `mapstructure:"resource"`
}

本收集器自身的遥测配置，如：

service:
 telemetry:
 logs:
 level: debug
 initial_fields:
 service: my-instance
 metrics:
 level: detailed
 address: 0.0.0.0:8888

extensions.Config

github.com/open-telemetry/opentelemetry-collector/service/extensions

// Config represents the ordered list of extensions configured for the service.
type Config []component.ID

service:
 extensions: [health_check, pprof, zpages]

pipelines.Config

github.com/open-telemetry/opentelemetry-collector/service/pipelines

// Config defines the configurable settings for service telemetry.
type Config map[component.ID]*PipelineConfig

// PipelineConfig defines the configuration of a Pipeline.
type PipelineConfig struct {
 Receivers []component.ID `mapstructure:"receivers"`
 Processors []component.ID `mapstructure:"processors"`
 Exporters []component.ID `mapstructure:"exporters"`
}

以上 map[component.ID]*PipelineConfig 中的 “component.ID” 可配置为以下三种类型：

traces
metrics
logs

Docs: Sampling

Mon, 23 Oct 2023 11:50:44 +0800

简要概述

采样频率是限制系统生成 Span 以及上报的数量，根据实际情况，通常在应用启动前就决定并配置好。一般在开发、测试环境设置为 trace.AlwaysSample() 以便把所有请求产生的 Span 均做记录。需要临时关闭则使用 trace.NeverSample() 方法。

在应用程序使用 sdk go.opentelemetry.io/otel/sdk/trace 设置采集频率。

采样频率

方法	示例	说明
AlwaysSample()	-	总是采集不会遗漏任何 Span，也等于 TraceIDRatioBased(1)
NeverSample()	-	关闭采集不会上报任何 Span，也等于 TraceIDRatioBased(0)
TraceIDRatioBased(fraction float64)	0.5	给定一个 0 至 1 之间的分数决定采样频率
ParentBased(root Sampler) Sampler	-	复合采样器

应用场景

对所有请求进行采样

provider := trace.NewTracerProvider(
 trace.WithSampler(trace.AlwaysSample()),
)

对 50% 请求 Span 进行采样

provider := trace.NewTracerProvider(
 trace.WithSampler(trace.ParentBased(trace.TraceIDRatioBased(0.5))),
)

Docs: 语义约定

Thu, 26 Oct 2023 14:07:13 +0800

简要概述

语义约定定义了一组常见的属性，这些属性在收集、生成和使用数据时为数据提供意义。

使用语义约定的好处在于遵循一个通用的命名方案，可以在代码库和平台中进行标准化，这样更容易地关联和消费数据。

如在定义 trace span 中 event 名称时，可以先查看下是否已经有公共名称了，类似需表示 HTTP 请求响应状态码，则使用 “http.response.status_code”。

span.SetAttributes(attribute.KeyValue{
 Key: "http.response.status_code",
 Value: attribute.StringValue("200")})

在以下领域定了规范：

通用语义约定；
云提供商库的语义约定；
CloudEvents规范的语义约定。
数据库操作的语义约定。
例外情况的语义约定。
功能即服务（FaaS）操作的语义约定。
特征标志评估的语义约定。
HTTP客户端和服务器操作的语义约定。
消息传递操作和系统的语义约定。
对象存储操作的语义约定。
RPC客户端和服务器操作的语义约定。
系统语义约定。

更详细的相关文档可参考官方 OpenTelemetry Semantic Conventions。

链路跟踪相关

通用语义约定

Docs: 指标模型

Thu, 02 Nov 2023 14:24:40 +0800

简要概述

兼容 prometheus

使用 OTLP 模型传输数据，然后导出到现有系统中，数据模型可以明确转换为 Prometheus Remote Write 协议，而不会丢失数据。

已明确三种保持语义的指标数据转换方式，这些转换在构建指标采集系统时能有效控制成本、保障可靠性并优化资源配置，指标数据模型支持在SDK内部数据生成阶段，或通过收集器内的再处理阶段实现以下转换：

时序重聚合

高频采集的指标数据可被重新聚合为更长的时间间隔，从而生成低分辨率时间序列数据用于预计算或替代原始指标数据。

空间重聚合

对于包含冗余属性的指标数据，可通过重聚合操作生成属性更精简的指标数据集；对不需要的属性的指标可以重新聚合，以丢弃这些属性，降低存储空间。

增量转累计

采用增量时间性的指标数据在输入输出时，可避免客户端维护高基数状态。通过使用增量数据，下游服务既可承担转换为累计时间序列的计算成本，也可直接计算速率值以规避转换开销。

示例 JSON 结构

{
 "resourceMetrics": [
 {
 "resource": {
 "attributes": [
 {
 "key": "service.name",
 "value": {
 "stringValue": "my.service"
 }
 }
 ]
 },
 "scopeMetrics": [
 {
 "scope": {
 "name": "my.library",
 "version": "1.0.0",
 "attributes": [
 {
 "key": "my.scope.attribute",
 "value": {
 "stringValue": "some scope attribute"
 }
 }
 ]
 },
 "metrics": [
 {
 "name": "my.counter",
 "unit": "1",
 "description": "I am a Counter",
 "sum": {
 "aggregationTemporality": 1,
 "isMonotonic": true,
 "dataPoints": [
 {
 "asDouble": 5,
 "startTimeUnixNano": "1544712660300000000",
 "timeUnixNano": "1544712660300000000",
 "attributes": [
 {
 "key": "my.counter.attr",
 "value": {
 "stringValue": "some value"
 }
 }
 ]
 }
 ]
 }
 },
 {
 "name": "my.gauge",
 "unit": "1",
 "description": "I am a Gauge",
 "gauge": {
 "dataPoints": [
 {
 "asDouble": 10,
 "timeUnixNano": "1544712660300000000",
 "attributes": [
 {
 "key": "my.gauge.attr",
 "value": {
 "stringValue": "some value"
 }
 }
 ]
 }
 ]
 }
 }
 ]
 }
 ]
 }
 ]
}

数据结构

ResourceMetrics

// 一个 ResourceMetrics 表示「某个资源（例如一台主机或容器）」下的一组指标
message ResourceMetrics {
 // 与此消息中指标相关联的资源信息
 // 如果该字段未设置，则表示无法确定任何资源信息
 opentelemetry.proto.resource.v1.Resource resource = 1;

 // 属于该资源的指标集合列表。
 // 每个元素表示一个来自特定 Instrumentation Scope 的指标集。
 repeated ScopeMetrics scope_metrics = 2;
}

Resource

// 资源信息。
message Resource {
 // 描述资源的属性集合。
 // 属性键必须唯一（不允许存在重复键）。
 //
 // 属性值建议遵循以下规则：
 // - 不应包含空值
 // - 不应包含字节类型
 // - 不应包含非字符串数组、布尔数组、整数数组或浮点数组的数组类型
 // - 不应包含 kvlist 类型
 // 接收端在处理违反这些规则的属性时行为可能不可预测。
 // 这些限制可能会在小版本中改变。
 // 限制来源于 OpenTelemetry 规范：
 // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute
 repeated opentelemetry.proto.common.v1.KeyValue attributes = 1;

 // 被丢弃的属性数量。如果值为 0，则表示没有属性被丢弃。
 uint32 dropped_attributes_count = 2;

ScopeMetrics

// 一组由某个 Instrumentation Scope（采集作用域）生成的指标集合
message ScopeMetrics {
 // 此消息中指标所属的 “Instrumentation Scope” 信息。
 // 如果该字段未设置，则语义上等同于 “Instrumentation Scope 名称为空（unknown）”。
 opentelemetry.proto.common.v1.InstrumentationScope scope = 1;

 // 一个指标列表，这些指标都来源于同一个 Instrumentation Library（采集库/模块）。
 repeated Metric metrics = 2;
}

Scope

// InstrumentationScope 表示采集器（instrumentation）的作用域信息
// 例如完整名称和版本号。
message InstrumentationScope {
 // 表示采集器作用域的名称。
 // 代表 SDK 或库的名称，例如 opentelemetry-go、grpc-client 等。
 string name = 1;

 // 定义采集器作用域的版本号。
 // 代表 SDK 或库的版本号，例如 1.47.0。
 string version = 2;

 // 描述作用域的附加属性 [可选]。
 // 属性键必须唯一（不允许存在重复键）。
 repeated KeyValue attributes = 3;

 // 被丢弃的属性数量。
 // 属性可能因为键过长或属性数量过多而被丢弃。
 // 如果值为 0，则表示没有属性被丢弃。
 uint32 dropped_attributes_count = 4;
}

Metric

// 表示一个指标（Metric）实体的定义。
// 每个 Metric 代表一种可测量的数据，例如请求时延、CPU 使用率、网络吞吐量等。
message Metric {
 // 指标的名称。
 string name = 1;

 // 指标的描述信息，可用于文档或可视化展示，帮助人类理解指标含义。
 string description = 2;

 // 指标值的度量单位（可选）。
 // 需遵循 https://unitsofmeasure.org/ucum.html 标准定义，
 // 例如 "s"（秒）、"By"（字节）、"1"（无单位）等。
 string unit = 3;

 // 指标的数据类型（聚合类型和取值形式）。
 // 该字段是一个 oneof（互斥字段），即同时只能出现一个。
 // 用于决定该指标属于哪种类型：
 // - Gauge（仪表盘）：表示瞬时值，例如当前内存使用量、CPU 使用率等。
 // - Sum（总和）：表示累计值，例如请求总次数、错误总次数等。
 // - Histogram（直方图）：表示分布统计，例如请求时延分布、响应大小分布等。
 // - ExponentialHistogram（指数直方图）：与直方图类似，但用于处理大范围值。
 // - Summary（摘要）：表示统计摘要，例如 95% 响应时间、99% 响应时间等。
 oneof data {
 Gauge gauge = 5;
 Sum sum = 7;
 Histogram histogram = 9;
 ExponentialHistogram exponential_histogram = 10;
 Summary summary = 11;
 }
}

指标数据点

Gauge

// 表示一种标量指标类型（scalar metric），它始终为每个数据点导出当前值（current value）。
// 当指标的聚合方式未知（unknown）时，应使用 Gauge。
//
// Gauge 不支持不同的聚合时间特性（Aggregation Temporality）。
// 因为其聚合方式未知，数据点之间无法通过相同的聚合逻辑进行合并，
// 因此 AggregationTemporality 字段不会包含在 Gauge 中。
// 同样地，这也意味着 "StartTimeUnixNano" 字段对 Gauge 数据点无效（被忽略）。
message Gauge {
 // 时间序列数据点。
 // 注意：同一时间戳可能包含多个数据点，它们具有不同属性（attributes）。
 repeated NumberDataPoint data_points = 1;
}

一组数据点，表示在给定时间的采样值，每个数据点包含一组独立的属性名称值对。

指标流中的一个点表示给定时间窗口内的最后采样事件，一般用于以下场景：

采样值（例如当前CPU温度）
对值进行采样时的时间戳（time_unix_ano）
时间戳（start_time_unix_ano），它最能代表可以记录测量的第一个可能时刻。这通常设置为度量收集系统启动时的时间戳。

使用 Gauge 进行采样的基本时间序列，在给定的时间间隔内进行多次采样，但只有最后一个值通过 OTLP 在指标流中报告。

区别于 Sum 该不提供聚合语义，而是在执行时间窗口或调整精度等操作时使用“最后样本值”。

可以通过转换为直方图或其他度量类型来聚合度量。默认情况下不会执行这些操作，并且需要直接的用户配置。

Sum

// Sum 表示标量指标类型（scalar metric），它是一个时间区间内所有上报测量值的总和。
message Sum {
 // 时间序列数据点。
 // 注意：同一时间戳可能包含多个数据点，它们具有不同属性（attributes）。
 repeated NumberDataPoint data_points = 1;

 // 描述聚合器的时间特性：
 // - DELTA: 自上次报告以来的增量
 // - CUMULATIVE: 自固定起始时间以来的累计值
 AggregationTemporality aggregation_temporality = 2;

 // 指示该 Sum 是否为单调递增（monotonic）。
 // 通常计数器指标（如网络字节数、请求总数）是单调递增的。
 bool is_monotonic = 3;
}

一组数据点，聚合方式为增量（Delta）或累积（Cumulative），每个数据点包含独立的属性名称值对。

在各种用例中，具体使用哪种聚合方式存在各种权衡，例如：

检测进程重新启动（累积值重新由 0 开始）
计算费率（计算增量，当前时间指标值 - 前一个时间指标值）
基于推送与拉取的指标报告

OTLP 支持这两种模型，并允许 API、SDK 和用户为其用例确定最佳折衷方案。

对指标做临时增量（Delta）

当聚合时间性是增量时（类似 prometheus rate 计算函数），指标流的时间窗口没有重叠，值不会出现负数。

对指标做临时累积（Cumulative）

当聚合时间性是累积时，计算自应用启动以来的时间窗口（起始，结束]）所有值的求和，值为单调递增，也就是当前值不会小于前一个。

Histogram

// Histogram 表示一种指标类型，它在一个时间区间内对所有上报测量值进行直方图聚合。
message Histogram {
 // 时间序列数据点。
 // 注意：同一时间戳可能包含多个数据点，它们具有不同属性（attributes）。
 repeated HistogramDataPoint data_points = 1;

 // 描述聚合器的时间特性：
 // - DELTA: 自上次报告以来的增量
 // - CUMULATIVE: 自固定起始时间以来的累计值
 AggregationTemporality aggregation_temporality = 2;
}

直方图以压缩格式记录测量的总体，它将一组事件捆绑成具有总体事件计数和所有事件的总和。

指标会自动压缩聚合，默认以 “bucket” “sum” “count” 三中类型组成：

“count” 该指标被观测到的次数，计数累计值
“sum” 该指标被观测到的值总和，值累计总和
“bucket” 该指标被观测到的值被放到一个预先定义好值边界 (le1, le2] 范围内，计数累计值

以 otelgrpc 中指标 “rpc.server.duration” 为示例，并以 prometheus 风格导出：

# HELP rpc_server_duration_milliseconds 
# TYPE rpc_server_duration_milliseconds histogram
rpc_server_duration_milliseconds_bucket{rpc_grpc_status_code="0",rpc_method="Test",rpc_system="grpc",le="0"} 0
rpc_server_duration_milliseconds_bucket{rpc_grpc_status_code="0",rpc_method="Test",rpc_system="grpc",le="5"} 0
......
rpc_server_duration_milliseconds_bucket{rpc_grpc_status_code="0",rpc_method="Test",rpc_system="grpc",le="10000"} 1
rpc_server_duration_milliseconds_bucket{rpc_grpc_status_code="0",rpc_method="Test",rpc_system="grpc",le="+Inf"} 1
rpc_server_duration_milliseconds_sum{rpc_grpc_status_code="0",rpc_method="Test",rpc_system="grpc"} 369
rpc_server_duration_milliseconds_count{rpc_grpc_status_code="0",rpc_method="Test",rpc_system="grpc"} 1

Bucket 的上界是包含的（上界为 +Inf 的情况除外），而 Bucket 的下界是互斥。也就是说，bucket 表示大于其下界且小于或等于其上界的值的数量。

ExponentialHistogram

// ExponentialHistogram 表示一种指标类型，它在一个时间区间内对所有上报的 double 值进行指数直方图聚合。
message ExponentialHistogram {
 // 时间序列数据点。
 // 注意：同一时间戳可能包含多个数据点，它们具有不同属性（attributes）。
 repeated ExponentialHistogramDataPoint data_points = 1;

 // 描述聚合器的时间特性：
 // - DELTA: 自上次报告以来的增量
 // - CUMULATIVE: 自固定起始时间以来的累计值
 AggregationTemporality aggregation_temporality = 2;
}

Summary

// Summary 指标类型用于传递分位数汇总。
// Summary 数据点不能总是以有意义的方式合并。
// 虽然在某些应用场景下有用，但建议新应用使用 Histogram。
// Summary 类型没有 aggregation_temporality 字段。
// 因为 SummaryDataPoint 的 count 和 sum 字段被假定为累计值（cumulative）。
message Summary {
 // data_points:
 // 时间序列数据点。
 // 注意：同一时间戳可能包含多个数据点，它们具有不同属性（attributes）。
 repeated SummaryDataPoint data_points = 1;
}

摘要指标数据点用于传递分位数摘要信息，例如"我的HTTP服务器的第99百分位延迟是多少"，与 OpenTelemetry 中的其他点类型不同，摘要点通常无法以有意义的方式进行合并，不建议在新应用中使用此点类型，其存在主要用于兼容其他格式。

摘要包含以下组成部分：

一组数据点，每个数据点包含：

独立的属性名值对集合
数值采样时间戳（time_unix_nano）
（可选）表示摘要观测收集开始时间的时间戳（start_time_unix_nano）
数据点总体中的观测值数量计数
总体中各数值的总和
一组严格递增的分位数值，其中每个分位数包含：
- 分布的分位数，取值范围为[0.0, 1.0]。例如，数值0.9表示第90百分位
- 该分位数对应的数值，必须为非负数

特别说明：

0.0 和 1.0 分位数分别定义为等于最小值和最大值
分位数值不需要代表 start_time_unix_nano 到 time_unix_nano 期间观测到的数值，通常应基于最近时间窗口（通常是最近5-10分钟）计算得出

AggregationTemporality

// 用于定义指标聚合器（aggregator）如何报告聚合后的数值，它描述了这些数值与聚合时间区间的关系。
enum AggregationTemporality {
 // UNSPECIFIED 表示未指定的聚合时间性，作为默认值使用，但不能在实际场景中使用。
 AGGREGATION_TEMPORALITY_UNSPECIFIED = 0;

 // DELTA（增量模式）表示聚合器在每个时间区间内报告自上次报告以来的变化量。
 // 每次上报的指标值仅代表本次测量周期内的数据，与历史无关。
 //
 // 即：每次上报的度量是“本周期新增的值”，周期之间互不重叠。
 //
 // 举例：假设系统统计每秒收到的请求数量，并以 DELTA 模式上报。
 //
 // 1. 系统在时间 t₀ 启动。
 // 2. 收到一个请求，计数 +1。
 // 3. 又收到两个请求，累计 +2。
 // 4. 经过 1 秒（t₀ ~ t₀+1），系统上报本周期请求总数 = 3。
 // 5. 下个周期（t₀+1 ~ t₀+2），又收到 2 个请求。
 // 6. 上报值为 2（即这一秒内的增量）。
 //
 // DELTA 模式下，指标值仅反映当前周期内的数据变化。
 AGGREGATION_TEMPORALITY_DELTA = 1;

 // CUMULATIVE（累积模式）表示聚合器报告自固定起始时间以来的累积变化量。
 // 即：每次上报的值包含从开始时间起到当前时间为止的所有测量结果。
 //
 // 这种模式下，采集端必须维护“自启动以来”的状态；
 // 如果状态丢失（例如程序重启），则必须重置为新的起始时间。
 //
 // 举例：系统统计自启动以来累计收到的请求数量，并以 CUMULATIVE 模式上报。
 //
 // 1. 系统在时间 t₀ 启动。
 // 2. 收到 3 个请求。
 // 3. 经过 1 秒（t₀ ~ t₀+1），上报总请求数 = 3。
 // 4. 下一个周期又收到 2 个请求。
 // 5. 经过 1 秒（t₀ ~ t₀+2），上报总请求数 = 5。
 // 6. 系统故障导致状态丢失。
 // 7. 系统在时间 t₁ 恢复，重新统计。
 // 8. 收到 1 个请求。
 // 9. 新的报告周期上报总请求数 = 1（从 t₁ 开始重新计算）。
 //
 // 注意：
 // 即使在每次上报周期只包含增量时，也可以使用 CUMULATIVE；
 // 但通常不推荐这样做，因为像 Prometheus 这种系统依赖 `start_time`
 // 来判断聚合重置的时间，如果使用不当会造成指标歧义。
 AGGREGATION_TEMPORALITY_CUMULATIVE = 2;
}

DataPointFlags

enum DataPointFlags {
 // 枚举的零值（默认值）。不应直接用于比较。
 // 如果需要检测标志，应使用按位“与”运算符和对应的掩码（如上例）。
 DATA_POINT_FLAGS_DO_NOT_USE = 0;

 // 表示该 DataPoint 有效，但没有记录实际数值。
 // 当需要明确表示数据缺失时应使用此标志，
 // 类似于 Prometheus 中的“陈旧标记（staleness marker）”概念。
 DATA_POINT_FLAGS_NO_RECORDED_VALUE_MASK = 1;

 // 位 2–31 保留，供未来扩展使用。
}

Exemplar

// Exemplar 表示一个示例（采样的输入测量值）。
// 它不仅包含测量值本身，还记录了测量时的环境信息，
// 例如在记录该示例时处于活动状态的 Span ID 和 Trace ID
message Exemplar {
 // 一组键值对（KeyValue），表示被聚合器过滤掉但仍被记录下来的属性。
 // 只有那些被聚合器过滤掉的属性才应包含在此字段中。
 repeated opentelemetry.proto.common.v1.KeyValue filtered_attributes = 7;

 // 表示该示例被记录时的精确时间。
 fixed64 time_unix_nano = 2;

 // 记录的测量值。
 // Exemplar 中只允许存在一个值字段（通过 oneof 定义）。
 // 若所有值字段都为空，则该 Exemplar 被视为无效。
 oneof value {
 double as_double = 3; // 浮点型测量值
 sfixed64 as_int = 6; // 整型测量值
 }

 // （可选）该示例对应追踪的 Span ID。
 // 如果测量未在追踪中记录，或该追踪未被采样，则 span_id 可能缺失。
 bytes span_id = 4;

 // （可选）该示例对应追踪的 Trace ID。
 // 如果测量未在追踪中记录，或该追踪未被采样，则 trace_id 可能缺失。
 bytes trace_id = 5;
}

NumberDataPoint

// NumberDataPoint 是时间序列 (timeseries) 中的一个单独数据点，
// 用于描述某个指标（metric）在时间变化中的标量值 (scalar value)。
message NumberDataPoint {
 // 表示该数据点的标签（key/value 对），用来唯一标识某个时间序列（Timeseries）。
 // 有以下约束说明：
 // 1. 每个数据点的标签（key/value 对）必须唯一。
 // 2. value 不应为空。
 // 3. value 不应为 bytes、kvlist 类型。
 // 4. 允许的数组类型仅限 array<string>, array<bool>, array<int>, array<double>。
 // The restrictions take origin from the OpenTelemetry specification:
 // https://github.com/open-telemetry/opentelemetry-specification/blob/v1.47.0/specification/common/README.md#attribute.
 repeated opentelemetry.proto.common.v1.KeyValue attributes = 7;

 // 可选字段
 // 数据点的起始时间（纳秒精度），表示聚合周期开始时间
 // 在累计型（Cumulative）指标中非常重要，用于标识统计区间的开始点
 // 在瞬时型（Gauge）中通常可忽略
 fixed64 start_time_unix_nano = 2;

 // 必填字段
 // 数据点的采样时间戳（纳秒精度）
 // 表示该数值被观测的时刻
 fixed64 time_unix_nano = 3;

 // 实际的指标值，二选一，可以是：
 // 1. 浮点数
 // 2. 有符号整数（sfixed64）
 oneof value {
 double as_double = 4;
 sfixed64 as_int = 6;
 }

 // 可选字段
 // 样本点，用于提供与此数据点相关的具体观测样本
 // 例如 Prometheus 的 exemplar 概念：用于把单个指标值关联到 trace/span ID
 // 方便实现 "指标 → trace" 的关联分析
 repeated Exemplar exemplars = 5;

 // 为该数据点设置的标志位，用于表示特殊状态，比如：
 // 1. 数据点是否有效（是否缺失值等）
 // 2. 数据点是否是预聚合值（是否需要特殊处理）
 uint32 flags = 8;
}

HistogramDataPoint

// 直方图数据点是时间序列中的单个数据点，用于描述直方图随时间变化的数值
// 直方图包含一组数值的汇总统计信息，可选择性地包含这些数值在不同桶中的分布情况。
// 若直方图包含数值分布信息，则必须同时定义"explicit_bounds"（显式边界）和"bucket_counts"（桶计数）字段。
// 若直方图不包含数值分布信息，则必须省略"explicit_bounds"和"bucket_counts"字段，此时仅能获取"count"（总数）和"sum"（总和）两个指标。
message HistogramDataPoint {
 reserved 1;

 // 同 NumberDataPoint
 repeated opentelemetry.proto.common.v1.KeyValue attributes = 9;
 fixed64 start_time_unix_nano = 2;
 fixed64 time_unix_nano = 3;

 // 样本总数，必须 >= 0
 // 如果提供桶分布，count 必须等于 bucket_counts 的元素和
 fixed64 count = 4;

 // 所有样本值的和（若 count=0 则 sum 必须为 0）
 // 应仅在测量非负的离散事件时填写（例如请求时延的正值、字节数等），并假定为单调（用于兼容 OpenMetrics）
 // see: https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md#histogram
 // 如果样本可能为负（例如带正负的值），不填写 sum
 optional double sum = 5;

 // 每个桶内的计数（数组）；数组长度 = len(explicit_bounds) + 1（最后一个桶是 (+infty)）
 // 若提供分布，bucket_counts 与 explicit_bounds 必须同时存在；若 bucket_counts 长度为 0，则 explicit_bounds 也必须为 0
 // 也就是：sum(bucket_counts) == count
 // 与 Prometheus 映射：对应多个 metric_bucket{le="<bound>"} 的值（上界为 explicit_bounds[i]），最后一个 le="+Inf" 为 bucket_counts[last]
 repeated fixed64 bucket_counts = 6;

 // 可选字段
 // 显式定义的桶上界数组（严格递增）
 // 上界包含（inclusive），最后桶为无限上界，与 bucket_counts 配合描述完整分布
 // 桶定义（索引 i）：
 // 1. 当 i == 0 时，桶范围为 (-∞, explicit_bounds[0]]
 // 2. 当 0 < i < n 时，桶范围为 (explicit_bounds[i-1], explicit_bounds[i]]
 // 3. 当 i == n 时，桶范围为 (explicit_bounds[n-1], +∞)
 repeated double explicit_bounds = 7;

 // 同 NumberDataPoint
 repeated Exemplar exemplars = 8;
 uint32 flags = 10;

 // 窗口内的最小值（(start_time, end_time] 区间）
 optional double min = 11;

 // 窗口内的最大值（(start_time, end_time] 区间）
 optional double max = 12;
}

ExponentialHistogramDataPoint

// 是时间序列中的一个单独数据点，用于描述双精度数值的 ExponentialHistogram 随时间变化的取值
// 包含一组数值的汇总统计信息，并且可以选择性地包含这些数值在一组桶中的分布。
// 传统直方图（HistogramDataPoint）使用固定桶边界 (explicit_bounds)
// 它对传统 HistogramDataPoint 的改进：在大数量级范围和动态分布情况下，可以用更少内存、更高精度地表达样本分布。
message ExponentialHistogramDataPoint {
 // 同 NumberDataPoint
 repeated opentelemetry.proto.common.v1.KeyValue attributes = 1;
 fixed64 start_time_unix_nano = 2;
 fixed64 time_unix_nano = 3;

 // The number of values in the population. Must be
 // non-negative. This value must be equal to the sum of the "bucket_counts"
 // values in the positive and negative Buckets plus the "zero_count" field.
 fixed64 count = 4;

 // 同 HistogramDataPoint
 optional double sum = 5;

 // 每个桶的上下界按 base 的幂递增：base = 2^(2^-scale)
 // 桶索引为整数（可以负），其值代表区间 (base^index, base^(index+1)]
 // 越大的 scale → 越多桶（更精细），越小的 scale → 越少桶（更粗略）
 sint32 scale = 6;

 // 表示恰好为零，或在允许精度范围内被视为零值区域内的数值计数
 // 此桶用于存储无法通过标准指数公式表示的数值，以及被四舍五入为零的数值。
 // 有些值接近零，但因浮点精度或量化误差无法归入正/负桶，于是：
 // zero_count：零值或“足够接近零”的样本数量；
 // zero_threshold：零区间宽度，表示 [−threshold, +threshold] 被视为零。
 // 实现方案可认为零值桶的概率质量等于（zero_count / count）
 fixed64 zero_count = 7;

 // 正数范围的桶
 Buckets positive = 8;

 // 负数范围（按绝对值同样定义）的桶
 Buckets negative = 9;

 message Buckets {
 // 第一个桶的索引
 sint32 offset = 1;

 // 从 offset 开始的连续计数
 // 其中 bucket_counts[i] 表示索引为 (offset+i) 的桶的计数值
 // bucket_counts[i] 统计的是大于 base^(offset+i) 且小于等于 base^(offset+i+1) 的数值数量
 repeated uint64 bucket_counts = 2;
 }

 // 同 HistogramDataPoint
 uint32 flags = 10;
 repeated Exemplar exemplars = 11;
 optional double min = 12;
 optional double max = 13;

 // 可选择性设置以表示零值区域的宽度，零值区域定义为闭区间 [-ZeroThreshold, ZeroThreshold]
 // 如果 zero_threshold = 0.001，那么 [-0.001, +0.001] 的值都落在零桶
 double zero_threshold = 14;
}

SummaryDataPoint

// 是一种对连续观测值进行统计汇总的度量类型，常用于监控延迟、请求时长、处理时间等
// 和 Histogram 类似，它也是对分布进行描述，但它不需要固定 bucket，而是统计特定分位值。
// 它在一个时间段内记录：
// 1. 样本总数（count）
// 2. 样本总和（sum）
// 3. 特定分位点的数值（quantiles），例如：
// p50（中位数）
// p90（90% 的请求小于此值）
// p99（99% 的请求小于此值）
message SummaryDataPoint {
 // 同 NumberDataPoint
 repeated opentelemetry.proto.common.v1.KeyValue attributes = 7;
 fixed64 start_time_unix_nano = 2;
 fixed64 time_unix_nano = 3;

 // 样本总数，大于等于0
 fixed64 count = 4;

 // 样本总和，如果 count 为 0 则此值也必须为 0
 double sum = 5;

 // 各个分位点的值（例如 0.5 → 200ms）
 // 表示分布在给定分位数处的数值。
 // 记录最小值和最大值时遵循以下约定：
 // - 1.0 分位数等同于观测到的最大值
 // - 0.0 分位数等同于观测到的最小值
 // 记录最小值和最大值时，分位点值必须非负。
 message ValueAtQuantile {
 // 分位点，范围 [0.0, 1.0]
 double quantile = 1;

 // 对应 quantile 的值（非负）
 double value = 2;
 }

 // (Optional) list of values at different quantiles of the distribution calculated
 // from the current snapshot. The quantiles must be strictly increasing.
 repeated ValueAtQuantile quantile_values = 6;

 // Flags that apply to this specific data point. See DataPointFlags
 // for the available flags and their meaning.
 uint32 flags = 8;
}

模型详情

事件模型

是记录数据的地方，它的基础是仪器（Instruments），主要数据是指标数据点（时间戳+值），用于通过事件记录观测数据，然后将这些原始事件发送到其他系统之前以某种方式进行转换。

上图显示了仪器（Instruments）如何将事件转换为多种类型的指标流。

尽管观测事件数据可以直接报告给后端，但在生产环境中这是不建议的，因为可观测性系统中使用的数据量太大，但可用于遥测收集的网络等资源有限，所以在上报数据前最后要想办法降低指标基数，如采用直方图指标类型压缩指标等。

时间序列模型

表示后端如何存储指标数据。

时间序列由几个元数据属性组成的实体定义：

指标名称：Metric name
属性（维度）：Attributes (dimensions)
数据点的值（整数、浮点等）：Value type of the point (integer, floating point, etc)
计量单位：Unit of measurement

每个时间序列的主要数据都是按顺序排列的（时间戳、值）点，具有以下值类型之一：

计数器（单调，累计）：Counter (Monotonic, Cumulative)
测量：Gauge
直方图：Histogram
指数直方图：Exponential Histogram

这个模型类似 Prometheus Remote Write 协议，但它并不是 OTLP 映射的唯一时间序列模型。

指标流模型

通过 OpenTelemetry 协议（OTLP）定义指标数据流在事件模型和时间序列存储之间传输与处理的方式。

指标流被分组为各个度量对象，由以下各项标识：

原始资源属性 Resource
检测范围（例如，检测库名称、版本）Scope
指标流的名称 name

除名称外，指标对象还由以下属性定义：

数据点类型：Sum, Gauge, Histogram ExponentialHistogram, Summary
指标流的单位：unit
指标流的描述：description
内在数据点属性，如适用：聚合临时性、单调性

数据点类型、指标流的单位和内在数据点属性被认为是可识别的，而指标流的描述在本质上显然不是可识别的。

特定点的外在特性不被认为是可识别的；这些包括但不限于：

直方图数据点的桶边界
指数直方图数据点的刻度或桶计数。

Metric对象包含由属性集标识的各个流。在各个流中，点由一个或两个时间戳标识，细节因数据点类型而异。

在某些数据点类型（例如总和和仪表）中，允许数值点值发生变化；在这种情况下，相关的变化（即浮点与整数）不被认为是可识别的。

应用场景

Summary 与 Histogram 的对比

特性	Summary	Histogram	ExponentialHistogram
是否记录桶	❌ 否	✅ 显式桶	✅ 指数桶
是否有 exemplar	❌ 无	✅ 有	✅ 有
是否能算分位数	✅ 已直接给出	✅ 可通过桶估算	✅ 可通过桶估算
是否能算任意 quantile	❌ 只能用已有 quantiles	✅ 可插值估算	✅ 可插值估算
是否能合并	❌ 很难准确合并	✅ 容易	✅ 容易
网络体积	较小	较大	中等
用途	上报分位统计结果	分布观测、trace 关联	高精度分布观测

典型使用场景

场景	推荐类型
请求延迟分位数监控（轻量）	✅ Summary
请求延迟分布分析 + Trace 跳转	✅ Histogram
高频采样 + 跨数量级分布	✅ ExponentialHistogram
跨节点聚合 / 联邦场景	❌ 不建议 Summary（用 Histogram）

与 prometheus 类型对比

Prometheus MetricType	对应 OTLP Metric Type	OTLP message / aggregation	AggregationTemporality	说明
`METRIC_TYPE_COUNTER`	Sum	`Sum` message	通常为 `CUMULATIVE`	Counter 表示单调递增量，OTLP 的 `Sum` 设置 `is_monotonic=true`。
`METRIC_TYPE_GAUGE`	Gauge	`Gauge` message	无需 temporality	Gauge 是瞬时测量值，对应 OTLP Gauge。
`METRIC_TYPE_HISTOGRAM`	Histogram	`Histogram` message	`CUMULATIVE` 或 `DELTA`	传统桶式直方图，与 OTLP Histogram 完全对应。
`METRIC_TYPE_GAUGEHISTOGRAM`	Histogram	`Histogram` message	通常为 `DELTA` 或“快照”式	GaugeHistogram 在 Prometheus 中代表某一时刻的桶分布，OTLP 没有直接同名，但用 Histogram 表示瞬时分布。
`METRIC_TYPE_SUMMARY`	Summary	`Summary` message	始终 `CUMULATIVE`	quantile（分位数）形式的度量，OTLP 直接支持 `Summary`。
`METRIC_TYPE_INFO`	Gauge（或 `KeyValue` attribute）	`Gauge` 或 Resource Attribute	不适用	Prometheus Info 通常是静态标签值，OTLP 推荐以 `Resource` 或 `InstrumentationScope` 属性表示。
`METRIC_TYPE_STATESET`	Gauge (boolean/int)	`Gauge` message	瞬时	StateSet 表示状态机（例如连接状态），可映射为多个布尔型 Gauge 或 `Enum-like` Gauge。
`METRIC_TYPE_UNSPECIFIED`	（无对应）	无	无	未指定类型。应在数据导入时推断。

在 Go 语言中使用

同步或异步

仪器（Instruments）支持同步或异步导出指标值，且值类型为 int64 或 float64 两个类型。

同步行为

是在被调用时进行测量，测量在程序执行期间作为另一个调用来完成，就像执行其他业务函数一样。这些测量值的聚合由配置的导出器定期导出。由于测量与导出值解耦，因此导出周期可能包含零个或多个聚合测量。

异步行为

是在 SDK 导出时才会调用创建提供给仪器（Instruments）的回调函数。此回调为 SDK 提供了一个立即导出的指标值，异步仪器上的所有测量在每个输出周期执行一次。

异步主要在以下几种场景使用：

当更新指标值在函数内代价较高，并且不希望当前执行线程等待测量函数；
导出指标需要以与程序执行无关的频率发生（即当与请求生命周期联系在一起时，无法准确测量）；
测量值没有已知的时间戳。

计数器 Counter

累积计数器，支持非负增量的仪器，也就是这些值永远不会减少（服务重启时重置为0），运行期间逐渐累加：

Int64Counter
Int64ObservableCounter

Float64Counter
Float64ObservableCounter

导出为 prometheus 格式时自动添加 “_count” 后缀。

计数器 UpDown

递增或者递减计数器，允许您观察递增或递减的累积值：

Int64UpDownCounter
Int64ObservableUpDownCounter

Float64UpDownCounter
Float64ObservableUpDownCounter

导出为 prometheus 格式时同 Gauge 类型。

测量 Gauge

比较随机值非累加，当只需要传达关于异步测量的最新数据时使用：

Int64ObservableGauge
Float64ObservableGauge

直方图 Histogram

当需要传达更多关于采集周期内进行的所有同步测量的信息时，应使用直方图：

Int64Histogram
Float64Histogram