VictoriaMetrics 与 VictoriaLogs 的 OpenTelemetry 接入实战Kubernetes 部署、OTLP 采集与 Go 应用埋点【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics本指南以 docs/guides/getting-started-with-opentelemetry/README.md 为骨架完整演示如何在 Kubernetes 集群中部署 VictoriaMetrics 与 VictoriaLogs通过 OTLP 协议经 OpenTelemetry Collector 或直连采集 Go 应用的指标与日志并在 VMUI 中完成端到端验证。读完本文你将掌握两条完整的可观测性数据通路——应用 → Collector → VictoriaMetrics/VictoriaLogs与应用 → VictoriaMetrics/VictoriaLogs直连并能理解-opentelemetry.usePrometheusNaming等命名转换开关背后的源码实现原理。架构总览两条数据接入路径本指南覆盖两种上报方式均基于 OpenTelemetry 标准协议OTLP经 OpenTelemetry Collector 转发应用通过 OTLP 把指标与日志发给 CollectorCollector 经otlphttpexporter 分别转发给 VictoriaMetrics指标与 VictoriaLogs日志。这是生产环境推荐的部署形态Collector 可以承担数据加工、协议转换、deltatocumulative 归一等职责。应用直连应用 SDK 直接把 OTLP 数据写到 VictoriaMetrics 与 VictoriaLogs 的写入端点Collector 为可选组件。经 OpenTelemetry Collector 转发指标与日志的架构示意两种方式下VictoriaMetrics 与 VictoriaLogs 都原生支持 OTLP无需额外翻译器即可接收protobuf编码的请求。下文先完成基础设施部署再分别演示两条通路。前置条件开始前请准备好以下环境可用的 Kubernetes 集群可用 kind 等工具在本地搭建已安装并配置好kubectl已安装 Helm第一步在 Kubernetes 上部署 VictoriaMetrics指标存储VictoriaMetrics 提供官方 Helm chart支持通过extraArgs直接透传命令行参数。创建如下配置文件开启 OpenTelemetry 指标名的 Prometheus 规范化转换cat EOF vm-values.yaml server: extraArgs: opentelemetry.usePrometheusNaming: true EOF添加并更新 Helm 仓库然后安装单机版single-serverVictoriaMetricshelm repo add vm https://victoriametrics.github.io/helm-charts/ helm repo update helm install victoria-metrics vm/victoria-metrics-single -f vm-values.yaml确认 Pod 运行正常kubectl get pods # NAME READY STATUS RESTARTS AGE # victoria-metrics-victoria-metrics-single-server-0 1/1 Running 0 3m1sHelm chart 会输出集群内写入地址Write URLWrite URL inside the kubernetes cluster: http://victoria-metrics-victoria-metrics-single-server.default.svc.cluster.local.:8428/protocol-specific-write-endpoint针对 OpenTelemetryVictoriaMetrics 的写入端点为http://victoria-metrics-victoria-metrics-single-server.default.svc.cluster.local.:8428/opentelemetry/v1/metrics源码视角-opentelemetry.usePrometheusNaming到底做了什么这个开关不是装饰性的配置它在 VictoriaMetrics 的 OTLP 解析链路中真实生效。打开 lib/protoparser/opentelemetry/stream/sanitize.go 可以看到三个相关 flag 的定义usePrometheusNaming flag.Bool(opentelemetry.usePrometheusNaming, false, Whether to convert metric names and labels into Prometheus-compatible format ...) convertMetricNamesToPrometheus flag.Bool(opentelemetry.convertMetricNamesToPrometheus, false, ...) labelNameUnderscoreSanitization flag.Bool(opentelemetry.labelNameUnderscoreSanitization, true, ...)-opentelemetry.usePrometheusNaming按 OTLP Metric Points to Prometheus 规范同时转换指标名与标签名。例如process.cpu.time{service.namefoo}会被转换为process_cpu_time_seconds_total{service_namefoo}-opentelemetry.convertMetricNamesToPrometheus仅转换指标名标签保持不变-opentelemetry.labelNameUnderscoreSanitization当usePrometheusNaming开启时为以_开头的标签名加key前缀如_mylabel→key_mylabel以__开头的保留标签不受影响。命名转换的具体逻辑在sanitizePrometheusMetricNamesanitize.go先把指标名按/_.-:拆分为 token再根据 OTLP 的Unit字段通过unitMap如s→seconds、By→bytes、%→percent追加单位后缀Counter 类型追加_totalGauge 且 Unit 为1时追加_ratio。这正是dice.rolls这类计数器进入 VictoriaMetrics 后变成dice_rolls_total的原因。第二步部署 VictoriaLogs日志存储安装 VictoriaLogshelm install victoria-logs vm/victoria-logs-single确认 Pod 运行正常kubectl get pods # NAME READY STATUS RESTARTS AGE # victoria-logs-victoria-logs-single-server-0 1/1 Running 0 1m10sVictoriaLogs 的集群内写入地址Write URL inside the kubernetes cluster: http://victoria-logs-victoria-logs-single-server.default.svc.cluster.local.:9428/protocol-specific-write-endpoint针对 OpenTelemetryVictoriaLogs 的写入端点为http://victoria-logs-victoria-logs-single-server.default.svc.cluster.local.:9428/insert/opentelemetry/v1/logs第三步配置 OpenTelemetry Collector 对接两个后端OpenTelemetry Collector 是厂商中立的遥测接收/处理/导出代理。VictoriaMetrics 原生支持 OTLP 指标协议因此 Collector 只需用otlphttpexporter 即可直接推送。添加 Helm 仓库helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts helm repo update创建 Collector 配置文件cat EOF otel-values.yaml mode: deployment image: repository: otel/opentelemetry-collector-contrib presets: clusterMetrics: enabled: true logsCollection: enabled: true config: # deltatocumulative processor is needed to convert metrics with delta temporality to cumulative temporality. # VictoriaMetrics doesnt support delta temporality. Skip this processor if you dont use delta temporality. processors: deltatocumulative: max_stale: 5m receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 exporters: otlphttp/victoriametrics: compression: gzip encoding: proto # Setting below will work for sending data to VictoriaMetrics single-node version. # Cluster version of VictoriaMetrics will require a different URL - https://docs.victoriametrics.com/victoriametrics/cluster-victoriametrics/#url-format metrics_endpoint: http://victoria-metrics-victoria-metrics-single-server.default.svc.cluster.local:8428/opentelemetry/v1/metrics logs_endpoint: http://victoria-logs-victoria-logs-single-server.default.svc.cluster.local:9428/insert/opentelemetry/v1/logs tls: insecure: true service: pipelines: logs: receivers: [otlp] processors: [] exporters: [otlphttp/victoriametrics] metrics: receivers: [otlp] processors: [deltatocumulative] exporters: [otlphttp/victoriametrics] EOF安装 Collectorhelm upgrade -i otel open-telemetry/opentelemetry-collector -f otel-values.yaml确认 Collector Pod 运行正常kubectl get pods # NAME READY STATUS RESTARTS AGE # otel-opentelemetry-collector-7467bbb559-2pq2n 1/1 Running 0 23m配置要点解读双协议监听otlpreceiver 同时开启 gRPC4317与 HTTP4318协议兼容不同语言 SDK 的默认导出方式deltatocumulativeprocessorVictoriaMetrics 对 delta 时间性的指标支持有限官方建议优先使用 cumulative 时间性如果应用导出的是 delta 时间性必须用该 processor 归并为 cumulative再写入后端。本指南后面的 Go Collector 示例默认导出 delta 时间性因此这条 processor 必不可少单机版 vs 集群版端点上述metrics_endpoint面向 VictoriaMetrics 单机版集群版需要指定租户 ID格式为http://vminsert:8480/insert/accountID/opentelemetry/v1/metrics详见 docs/victoriametrics/data-ingestion/OpenTelemetry-Collector.md 与 Cluster-VictoriaMetrics.mdtls.insecure: true集群内部服务间通信未启用 TLS 时的必要配置。第四步验证指标与日志已被采集验证指标端口转发 VictoriaMetrics 服务kubectl port-forward svc/victoria-metrics-victoria-metrics-single-server 8428浏览器访问 VMUI查询k8s_container_ready指标Collector 的clusterMetricspreset 会采集集群自身指标http://localhost:8428/vmui/#/?g0.exprk8s_container_readyg0.tab1VictoriaMetrics UIVMUI中查询k8s_container_ready指标提示可以使用 VMUI 的 cardinality explorer高基数探索器浏览所有已采集的指标排查哪些指标进入或占用存储。验证日志端口转发 VictoriaLogs 服务kubectl port-forward svc/victoria-logs-victoria-logs-single-server 9428浏览器访问 VictoriaLogs 的 Web UI确认 Collector 采集的日志已入库http://localhost:9428/select/vmui第五步Go 应用经 OpenTelemetry Collector 上报指标与日志任何兼容 OpenTelemetry 的语言 SDK 都可以作为 instrumentation 客户端。本例使用 Go 实现一个掷骰子dice rollWeb 服务将指标与日志发给 Collector再由 Collector 转发给 VictoriaMetrics 与 VictoriaLogs。获取并运行示例代码下载示例代码 app.go-collector.example 并重命名为main.go。该示例通过 OpenTelemetry SDK 向http://localhost:4318发送数据即上一步部署的 Collector 的 OTLP HTTP 端点。首先端口转发 Collector 服务kubectl port-forward svc/otel-opentelemetry-collector 4318在与示例代码相同的目录下初始化 Go 模块并拉取依赖go mod init vm/otel go mod tidy运行应用go run .默认监听http://localhost:8080。向/rolldice端点发起请求以产生指标例如连续发送 20 次for i in seq 1 20; do curl http://localhost:8080/rolldice; done验证指标与日志几秒后在浏览器访问 VMUI 查询dice_rolls_totalhttp://localhost:8428/vmui/#/?g0.exprdice_rolls_total日志则通过 VictoriaLogs 的 Web UI 查询service.name: unknown_service:otelhttp://localhost:9428/select/vmui示例代码源码剖析打开 app.go-collector.example 可以看到三个值得注意的实现细节HTTP 全链路插桩newHTTPHandler用otelhttp.WithRouteTag为每个 handler 绑定http.route属性再用otelhttp.NewHandler包裹整个 mux使每个请求自动产生 span 与 HTTP 指标otelhttp与otelslog桥接通过go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp与go.opentelemetry.io/contrib/bridges/otelslog把标准库log/slog日志桥接到 OpenTelemetry 日志管道业务日志随 OTLP 一起上报Delta 时间性选择器newMeterProvider中的WithTemporalitySelector显式返回DeltaTemporality这正是第三步 Collector 配置里deltatocumulativeprocessor 存在的原因——delta 指标经 Collector 归并为 cumulative 后才被 VictoriaMetrics 正确处理。第六步Go 应用直连 VictoriaMetrics 与 VictoriaLogs绕过 CollectorCollector 是可选的。你可以让应用 SDK 直接与 VictoriaMetrics、VictoriaLogs 通信同样使用 OpenTelemetry 标准 instrumentation 客户端。应用通过 OTLP 直连 VictoriaMetrics 与 VictoriaLogs 的架构示意下载示例代码 app.go.example 并重命名为main.go同样执行模块初始化go mod init vm/otel go mod tidy该示例实现了一个带两个 HTTP handler 的 Web 服务/api/slow与/api/fast。启动应用go run main.go 2024/03/25 19:27:41 Starting web server... 2024/03/25 19:27:41 web server started at localhost:8081.应用默认把遥测数据写到http://localhost:8428VictoriaMetrics与http://localhost:9428VictoriaLogs。请在另一个终端端口转发这两个服务# port-forward victoriametrics to ingest metrics kubectl port-forward svc/victoria-metrics-victoria-metrics-single-server 8428 # port-forward victorialogs to ingest logs kubectl port-forward svc/victoria-logs-victoria-logs-single-server 9428向两个路由各发起若干请求触发指标与日志产生for i in seq 1 20; do curl http://localhost:8081/api/fast; done for i in seq 1 5; do curl http://localhost:8081/api/slow; done几秒后在 VMUI 查询http_requests_totalhttp://localhost:8428/vmui/#/?g0.exprhttp_requests_total提示可以通过 cardinality explorer 页面查看该应用暴露的其他指标。日志同样通过 VictoriaLogs Web UI 查询service.name: unknown_service:otelhttp://localhost:9428/select/vmui直连示例的关键源码点直连示例 app.go.example 提供了更贴近生产实践的细节可配置端点 flag-vm.endpoint默认http://localhost:8428/opentelemetry/v1/metrics、-vl.endpoint默认http://localhost:9428/insert/opentelemetry/v1/logs与-vm.pushInterval默认10s控制指标推送周期通过otlpmetrichttp.WithEndpointURL与otlploghttp.WithEndpointURL注入 exporter自定义资源属性通过resource.New给指标附加jobotlp、instancelocalhost标签VictoriaMetrics 默认会把 OTLP resource attributes 提升为标签指数直方图视图expView通过sdkmetric.NewView为http.requests.latency同时注册经典直方图与指数直方图AggregationBase2ExponentialHistogram{MaxSize: 160, MaxScale: 20}指标名http.requests.latency.exp。OpenTelemetry 指数直方图在写入 VictoriaMetrics 时会被自动转换为带vmrange标签的 VictoriaMetrics histogram 格式见 docs/victoriametrics/integrations/opentelemetry.md三类核心指标http.requestsInt64Counter 请求计数、http.requests.latencyFloat64Histogram 延迟直方图、http.requests.activeInt64ObservableGauge 并发活跃请求数通过回调读取原子计数器实现。关键技术点OTLP 指标命名转换与数据语义命名清洗开关汇总lib/protoparser/opentelemetry/stream/sanitize.go 与 docs/victoriametrics/integrations/opentelemetry.md 完整说明了各开关的差异均可作用于 vmagent、vminsert 与 VictoriaMetrics 单机版命令行参数作用范围示例转换-usePromCompatibleNaming所有接入协议process.cpu.time{service.namefoo}→process_cpu_time{service_namefoo}-opentelemetry.usePrometheusNaming仅 OTLPprocess.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默认情况下不开任何开关VictoriaMetrics原样存储OTLP metric points不做任何转换。相关 flag 的完整说明可查阅 docs/victoriametrics/vminsert_common_flags.md、docs/victoriametrics/vmagent_common_flags.md 与 docs/victoriametrics/victoria_metrics_common_flags.md。资源属性与 Instrumentation Scope默认情况下VictoriaMetrics 会把所有 OpenTelemetry resource attributes 提升为标签并附加到所有 OTLP 指标上可通过-opentelemetry.promoteResourceAttributes提升指定属性列表或-opentelemetry.promoteAllResourceAttributes提升全部属性配合-opentelemetry.ignoreResourceAttributes排除个别属性精细控制Instrumentation Scope 元数据默认也会被提升为指标标签可用-opentelemetry.promoteScopeMetadata关闭。Delta 时间性注意事项OpenTelemetry 中 sum、histogram、exponential histogram 等指标类型同时支持 delta 与 cumulative 两种 aggregation temporality。VictoriaMetrics 与 cumulative 时间性配合最佳建议要么应用端导出 cumulative要么在 Collector 中用deltatocumulativeprocessor 转换后再发送。需要特别注意的是不要对 delta 时间性指标启用去重deduplication或降采样downsampling否则可能造成数据丢失。限制与注意事项不支持实验性 JSON 编码VictoriaMetrics 与 VictoriaLogs 的 OTLP 端点只接受protobuf编码。这一点在源码中也有直接体现——app/vminsert/opentelemetry/request_handler.go 中当请求Content-Type为application/json且非 Firehose 协议时会直接返回错误json encoding isnt supported for opentelemetry format. Use protobuf encoding。gzip 压缩的负载需设置 HTTP 请求头Content-Encoding: gzip集群版 VictoriaMetrics 使用 OTLP 写入时需携带租户 IDURL 路径中的accountID单机版无需Collector 的完整配置选项以 OpenTelemetry 官方 Collector 配置文档为准。结语与延伸阅读至此你已掌握两条完整的 OTLP 数据通路一条经 OpenTelemetry Collector 汇聚转发适合生产环境与多云异构场景一条由应用 SDK 直连适合轻量快速接入。同时理解了命名清洗、时间性转换、直方图转换背后的源码机制。进一步深入可阅读仓库内相关文档docs/victoriametrics/integrations/opentelemetry.mdOTLP 指标接入的完整参数与语义说明docs/victoriametrics/data-ingestion/OpenTelemetry-Collector.mdCollector exporter 最小配置与集群版端点格式app/vminsert/opentelemetry/request_handler.govminsert 侧 OTLP 请求处理入口lib/protoparser/opentelemetry/stream/sanitize.go指标名/标签名 Prometheus 化转换实现docs/victoriametrics/Single-server-VictoriaMetrics.md单机版所有数据写入端点与 VMUI 使用说明【免费下载链接】VictoriaMetricsVictoriaMetrics: fast, cost-effective monitoring solution and time series database项目地址: https://gitcode.com/GitHub_Trending/vi/VictoriaMetrics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考