VictoriaMetrics 原生接入 OpenTelemetry OTLP 指标协议端点、命名清洗与属性提升全解析【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetricsVictoriaMetrics 对 OpenTelemetry ProtocolOTLP指标提供了原生数据接入能力无论是单机版 VictoriaMetrics、集群版中的 vminsert还是统一采集器 vmagent都可以在/opentelemetry/v1/metrics端点直接接收 OTLP 协议编码的指标数据。本文基于仓库中的 集成文档 及对应源码实现系统讲解 OTLP 接入方式、指标名与标签的 Prometheus 兼容性清洗、Instrumentation Scope 与 Resource Attributes 的提升规则以及指数直方图转换与 Delta 时序处理等关键配置帮助你以最小改动将 OpenTelemetry 生态的指标平滑汇入 VictoriaMetrics。OTLP 指标接入端点与请求格式VictoriaMetrics 通过 HTTP 协议接收 OTLP metrics 数据默认端点路径为/opentelemetry/v1/metrics接入方式具有以下特征编码格式该端点期望收到protobuf 编码的请求即 OTLP 二进制协议而非 JSON。压缩支持对于 gzip 压缩后的负载需要设置 HTTP 请求头Content-Encoding: gzipVictoriaMetrics 会自动解压后解析。适用组件这些接入能力同时存在于 VictoriaMetrics 单机版、集群版 vminsert 以及 vmagent 三个组件中。从源码注册表可以看到vminsert 实际注册了两个端点路径/opentelemetry/api/v1/push与/opentelemetry/v1/metrics两者共用同一个 opentelemetry.InsertHandler 处理函数case /opentelemetry/api/v1/push, /opentelemetry/v1/metrics: opentelemetryPushRequests.Inc() if err : opentelemetry.InsertHandler(r); err ! nil { opentelemetryPushErrors.Inc() }在 vminsert 的请求处理器 内部一个值得注意的实现细节是普通 JSON 编码的 OTLP 请求不被接受——只有当请求带有X-Amz-Firehose-Protocol-Version头时才会走 AWS Firehose 的请求体预处理流程否则直接返回json encoding isnt supported for opentelemetry format. Use protobuf encoding错误。因此使用 OTLP 直推时务必使用 protobuf 编码。指标名与标签的命名清洗Label Sanitization默认情况下VictoriaMetrics不对通过 OTLP 摄入的指标点metric points做任何转换即原样存储。但 OpenTelemetry 的命名规范与 Prometheus 存在差异例如 OTLP 指标名支持.与/等字符属性名含service.name这种点分形式因此提供了以下清洗开关Flag作用范围示例-usePromCompatibleNaming所有摄入协议process.cpu.time{service.namefoo}→process_cpu_time{service_namefoo}-opentelemetry.usePrometheusNaming仅 OTLP 指标process.cpu.time{service.namefoo}→process_cpu_time_seconds_total{service_namefoo}-opentelemetry.convertMetricNamesToPrometheus仅 OTLP 指标、仅指标名process.cpu.time{service.namefoo}→process_cpu_time_seconds_total{service.namefoo}标签不变-opentelemetry.labelNameUnderscoreSanitization与usePrometheusNaming配合_mylabel→key_mylabel要点说明-usePromCompatibleNaming是全局开关影响所有通过 VictoriaMetrics 摄入的协议Prometheus、InfluxDB、Graphite 等其行为是简单地把不兼容字符替换为_-opentelemetry.usePrometheusNaming严格遵循 OTLP Metric Points 到 Prometheus 的官方转换规范不仅替换字符还会依据指标单位与指标类型重组指标名例如 Counter 追加_total后缀、带单位时追加_seconds等单位后缀同时清洗标签名-opentelemetry.convertMetricNamesToPrometheus只处理指标名保留标签原名适合希望在查询层看到 Prometheus 风格指标名、但又不想改动标签的场景-opentelemetry.labelNameUnderscoreSanitization控制是否对以_开头的标签名做key前缀处理保留标签以__开头不受影响。源码级实现单位映射与命名重组上述usePrometheusNaming与convertMetricNamesToPrometheus的底层实现位于 lib/protoparser/opentelemetry/stream/sanitize.go。其中维护了两张单位映射表unitMap主单位映射例如s→seconds、ms→milliseconds、By→bytes、KiBy→kibibytes、%→percent、Cel→celsius等见 sanitize.go 中的 unitMapperUnitMap比率分母单位映射例如s→second、m→minute、h→hour、d→day、w→week、mo→month、y→year见 perUnitMap。指标名清洗流程大致如下sanitizePrometheusMetricName见 sanitize.go#L125-L165按/、_、.、-、:、空格将指标名切分为 token解析单位中的/拆分主单位与 per 单位分别查表并追加为 token如m/s→meters_per_second若指标类型为 Counter将total移动/追加到 token 末尾若单位为1且类型为 Gauge追加ratio最后用_重新拼接 token 得到最终指标名。标签清洗sanitizePrometheusLabelName见 sanitize.go#L94-L107) 则遵循先做通用字符清洗再对数字开头的标签名追加key_前缀对单下划线开头的标签名在开关开启时追加key前缀而__开头的保留标签跳过处理。这些规则在 sanitize_test.go 中有完整的用例佐证例如foo_bar/baz:abc→foo_bar_baz_abc1foo→key_1foo_foo→key_foo__bar→__barfoo单位sCounter→foo_seconds_totalfoo单位m/s→foo_meters_per_secondInstrumentation Scope 元数据提升OpenTelemetry 的 Instrumentation Scope仪表化范围携带了产生指标库的名称、版本、schema URL 及属性。默认情况下VictoriaMetrics会将 OTel Scope 元数据提升为指标标签方便在查询时按上报来源库过滤。该行为由-opentelemetry.promoteScopeMetadata控制默认值为true如需关闭显式设置-opentelemetry.promoteScopeMetadatafalse在源码中该 flag 定义于 streamparser.go#L24并在InitDecodeOptions中通过defaultDecodeMetricsOptions.DisableScopeMetadata !*promoteScopeMetadata传递给底层解码器见 streamparser.go#L31-L48。Resource Attributes 属性提升OpenTelemetry Resource资源描述指标所来源的实体如服务、主机、容器其属性默认会被全部提升为标签并附加到所有 OTLP 指标上。三个相关 flag 共同构成资源属性的精细控制Flag默认值说明-opentelemetry.promoteAllResourceAttributestrue提升所有资源属性为标签但可配合 ignore 名单排除-opentelemetry.promoteResourceAttributes空数组仅提升指定列表中的资源属性为标签-opentelemetry.ignoreResourceAttributes空数组指定要忽略的资源属性仅当 promoteAllResourceAttributes 开启时可用两个关键约束在 InitDecodeOptions 中通过logger.Fatalf强制校验不能同时设置-opentelemetry.promoteAllResourceAttributes与-opentelemetry.promoteResourceAttributes互斥-opentelemetry.ignoreResourceAttributes只有在-opentelemetry.promoteAllResourceAttributestrue时才能设置。例如只想提升service.name与host.name两个资源属性同时关闭全量提升-opentelemetry.promoteAllResourceAttributesfalse \ -opentelemetry.promoteResourceAttributesservice.name \ -opentelemetry.promoteResourceAttributeshost.name又或者保持全量提升但排除敏感属性-opentelemetry.promoteAllResourceAttributestrue \ -opentelemetry.ignoreResourceAttributesprocess.command_line指数直方图的自动转换OpenTelemetry 的 Exponential Histogram指数直方图在摄入时会被自动转换为 VictoriaMetrics 的直方图格式即以vmrange标签形式存储的直方图桶。这样做的收益是转换后的指标可以直接使用 VictoriaMetrics 内置的直方图相关函数如histogram_quantile进行分位数计算与 Prometheus 直方图在查询语义上保持一致。Delta Temporality 与累积时序的取舍在 OpenTelemetry 中Sum、Histogram、Exponential Histogram 等指标类型支持delta增量与cumulative累积两种聚合时序Temporality推荐方案VictoriaMetrics 与 cumulative累积时序配合效果最佳官方建议以累积时序导出指标若数据源只产生 delta 时序可在链路上使用 OpenTelemetry Collector 的deltatocumulativeprocessor 将其转换为累积时序后再推送该 processor 在仓库 vendor 目录中有完整实现见 vendor/github.com/open-telemetry/opentelemetry-collector-contrib/processor/deltatocumulativeprocessor。直接存储自 v1.132.0 起VictoriaMetrics 也支持按原样存储 delta 时序的指标值之后可以通过sum_over_time()或rate_over_sum()等 MetricsQL 函数 进行查询聚合。需要特别注意的是不要对 delta 时序的指标应用去重deduplication或降采样downsampling因为这两个功能基于累积语义设计作用于 delta 数据可能导致数据丢失。相关功能说明参见 单机版 VictoriaMetrics 文档。端到端接入示例从 OpenTelemetry Collector 到 VictoriaMetrics直接推送单机版 / vminsert / vmagent将 OpenTelemetry Collector 的 OTLP HTTP exporter 指向 VictoriaMetrics 的写入端点即可exporters: otlphttp: endpoint: http://victoriametrics-host:8428 tls: insecure: true compression: gzipVictoriaMetrics 侧的写入地址为http://victoriametrics-host:8428/opentelemetry/v1/metrics若要开启 Prometheus 兼容命名启动时添加./victoria-metrics-prod -opentelemetry.usePrometheusNaming更完整的 Collector 配置包括 exporter 的headers、retry_on_failure、sending_queue等生产参数可参考仓库中的 OpenTelemetry Collector 接入指南。Kubernetes / Helm 部署场景在 Getting Started with OpenTelemetry 指南 中展示了通过 Helm 安装 VictoriaMetrics 单机版并开启 OTLP 命名转换的完整流程。首先通过extraArgs注入 flagcat EOF vm-values.yaml server: extraArgs: opentelemetry.usePrometheusNaming: true EOF然后安装helm repo add vm https://victoriametrics.github.io/helm-charts/ helm repo update helm install victoria-metrics vm/victoria-metrics-single -f vm-values.yaml安装完成后集群内的 OTLP 写入端点为http://victoria-metrics-victoria-metrics-single-server.default.svc.cluster.local.:8428/opentelemetry/v1/metricsvmagent 统一接入在需要先集中采集、再转发到远程存储或集群版多租户环境的场景下可以直接把 OTLP 数据推给 vmagent 的/opentelemetry/v1/metrics端点。vmagent 的实现位于 app/vmagent/opentelemetry/request_handler.go与 vminsert 一样支持 protobuf gzip 解析解析后的数据进入 remotewrite 队列统一转发且该处理函数支持租户级指标计数vmagent_tenant_inserted_rows_total{typeopentelemetry}。vmagent 还支持通过-remoteWrite.label追加额外标签、-remoteWrite.relabelConfig做标签重写实现 OTLP 指标到多后端的分流与整形。实现细节与可观测性指标请求解析与内存控制从 streamparser.go 的 ParseStream 可以看到解析链路请求体经ReadUncompressedData按-opentelemetry.maxRequestSize默认64 MiB读取并解压随后由pb.DecodeMetricsData解码为统一的prompb.TimeSeries。两个值得关注的内存优化点当解析缓冲区超过4 MiB时会提前 flush 已解析的时序避免大请求导致内存过度分配见 streamparser.go#L187-L197请求处理上下文使用sync.Pool复用且当缓冲区容量远大于实际使用量时不再归还池中避免内存被个别超大请求撑大见 streamparser.go#L242-L251。内置指标VictoriaMetrics 为 OTLP 接入暴露了完善的内部指标可在/metrics端查看vm_protoparser_rows_read_total{typeopentelemetry}OTLP 协议解析出的时序行数vm_rows_inserted_total{typeopentelemetry}vminsert与vmagent_rows_inserted_total{typeopentelemetry}vmagent成功写入/转发的行数vm_rows_per_insert{typeopentelemetry}单次请求携带行数的直方图vm_metadata_rows_inserted_total{typeopentelemetry}指标元数据Help/Type/Unit写入行数vm_http_requests_total{path/opentelemetry/v1/metrics, protocolopentelemetry}与对应的 errors 计数器端点请求与错误统计定义于 app/vminsert/main.go#L438-L439。小结VictoriaMetrics 对 OTLP 指标的原生支持可以概括为零转换存储 按需兼容清洗默认原样存储保持语义完整而通过-opentelemetry.usePrometheusNaming、-opentelemetry.convertMetricNamesToPrometheus、资源属性提升、指数直方图自动转换等开关可以按业务需要逐步对齐 Prometheus 生态的查询习惯。无论你是从 OpenTelemetry Collector 直推、在 K8s 中用 Helm 部署还是通过 vmagent 做统一采集转发只需把写入端点指向/opentelemetry/v1/metrics并选择合适的清洗与提升策略即可完成接入。延伸阅读OpenTelemetry Collector 完整接入配置OpenTelemetry 指标 日志端到端实战指南MetricsQL 聚合函数sum_over_time / rate_over_sumOTLP 命名清洗实现源码 与 解析器实现源码【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
