SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场opentelemetry

opentelemetry

部署与运维

查看项目

更新于 10-15 12:38

技能介绍

用途

OpenTelemetry（OTel）是一个与厂商无关的可观测性框架，用于生成、收集和导出遥测数据。它定义三种信号：Traces（跨服务跟踪请求，由带时间、状态和关系的 span 组成）、Metrics（按时间聚合的数值测量：Counter、Histogram、Gauge）、Logs（结构化事件记录，通过 trace/span ID 与链路关联）。三种信号共享通用上下文传播机制，可相互关联。主要用于在生产系统中实现分布式追踪、指标和日志的可观测性。

主要能力

  • Traces：span 表示工作单元，关键字段包括 name（操作）、kind（CLIENT/SERVER/PRODUCER/CONSUMER/INTERNAL）、start_time/end_time、status（OK/ERROR/UNSET）、attributes（键值对）、events（带时间戳的条目）、links（相关 span）。上下文传播通过 W3C traceparent 标头跨进程边界传递：00-<trace-id>-<span-id>-<trace-flags>，自动埋点会为 HTTP 处理。
  • Metrics：支持 Counter（单调递增计数）、UpDownCounter（可增可减的值）、Histogram（值的分布）、Gauge（通过回调获取的时点值）。
  • OTLP 导出器配置：支持 gRPC（端口 4317）与 HTTP/protobuf（端口 4318），可通过 OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_PROTOCOL 及各信号专用端点、OTEL_EXPORTER_OTLP_HEADERS 认证标头进行配置。
  • Collector 设置：Collector 在管道中接收、处理和导出遥测数据，配置包括 receivers（otlp）、processors（batch、memory_limiter、resource）、exporters（otlp/jaeger、prometheus、debug）与 service pipelines（traces、metrics）。
  • 常见后端：Jaeger（Traces，原生 OTLP 支持）、Prometheus + Grafana（Metrics）、Datadog（All）、Honeycomb（Traces、Logs，原生 OTLP）、Grafana Tempo（Traces）。
  • 采样策略：always_on（仅限开发）、always_off、traceidratio（按 trace ID 百分比采样）、parentbased_always_on、parentbased_traceidratio。生产环境常用 parentbased_traceidratio 配合 0.01-0.1。可通过 OTEL_TRACES_SAMPLER 和 OTEL_TRACES_SAMPLER_ARG 环境变量或编程方式配置。
  • Baggage：跨服务边界传播键值对而不将其加入 span，适用于租户 ID、功能标志或路由提示；以 HTTP 标头传输，不应放入敏感数据，条目应保持精简。

使用方式

Node.js 自动埋点：安装 @opentelemetry/sdk-node、@opentelemetry/auto-instrumentations-node、@opentelemetry/exporter-trace-otlp-grpc、@opentelemetry/exporter-metrics-otlp-grpc，创建必须在应用代码之前加载的 tracing.ts，使用 NodeSDK 配置 traceExporter、metricReader（PeriodicExportingMetricReader）和 instrumentations，并以 node --require ./tracing.js app.js 运行。手动 span 使用 @opentelemetry/api 的 trace 与 SpanStatusCode。

Python 自动埋点：安装 opentelemetry-distro opentelemetry-exporter-otlp，运行 opentelemetry-bootstrap -a install，然后使用 opentelemetry-instrument --service_name my-service --exporter_otlp_endpoint http://localhost:4317 python app.py。编程式设置使用 TracerProvider、BatchSpanProcessor、OTLPSpanExporter、MeterProvider、PeriodicExportingMetricReader、OTLPMetricExporter 和 Resource。

本地开发：通过 Docker Compose 启动 otel-collector 与 jaeger 服务，Collector 暴露 4317（OTLP gRPC）、4318（OTLP HTTP）、8889（Prometheus 指标），Jaeger UI 位于 16686，应用指向 http://localhost:4317 或 http://localhost:4318。

环境变量：包括 OTEL_SERVICE_NAME、OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_PROTOCOL、OTEL_EXPORTER_OTLP_HEADERS、OTEL_TRACES_SAMPLER、OTEL_TRACES_SAMPLER_ARG、OTEL_RESOURCE_ATTRIBUTES、OTEL_LOG_LEVEL、OTEL_PROPAGATORS。

适用场景

适用于在生产系统中引入分布式追踪、指标与日志；当用户提及 "opentelemetry"、"otel"、"distributed tracing" 等关键词时使用。常见埋点模式包括追踪 HTTP 请求（自动埋点覆盖多数 HTTP 库，通过中间件补充业务上下文）、追踪数据库查询（自动埋点处理 pg、mysql2、mongoose 等，手动补充业务上下文）、追踪外部 API 调用，以及使用 Baggage 进行跨服务上下文传递。为便于调试，可自定义 span 属性与事件，并遵循语义约定命名属性（如 http.request.method、db.system、rpc.service）。

限制

资料未提供 OpenTelemetry 的收费、价格、平台限制或性能影响等事实，暂未提供。