OpenTelemetry OpenTelemetry

无需修改代码即可为应用插桩:Java、Python 和 Node.js

仅通过环境变量和命令行参数附加 OpenTelemetry agent。

12 min 初级

零代码插桩在应用启动时附加一个 agent。agent 会给常用的库打补丁,比如 HTTP 服务器和客户端、数据库驱动和消息队列,并在不改动源代码的情况下产生追踪、指标和日志。配置使用标准的 OTEL_* 环境变量加上少数特定于语言的变量,所以整个设置只是 Dockerfile 里的一行和几个变量。本指南涵盖 Java、Python 和 Node.js。

先决条件:有地方发送数据

准备一个正在监听的 Collector,例如来自 Docker Compose 指南的那个,位于 otel-collector:4318(HTTP)或 :4317(gRPC)。下面的每个示例都通过 OTEL_EXPORTER_OTLP_ENDPOINT 指向它。

Java

下载一次 agent JAR,然后用 -javaagent 附加它:

curl -L -o opentelemetry-javaagent.jar \
  https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

java -javaagent:./opentelemetry-javaagent.jar \
     -Dotel.service.name=checkout \
     -jar myapp.jar

容器通常更喜欢环境变量,用 JAVA_TOOL_OPTIONS 携带该参数,这样你就不用更改入口点:

FROM eclipse-temurin:21-jre
WORKDIR /app
COPY myapp.jar .
ADD https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/<version>/opentelemetry-javaagent.jar /otel/opentelemetry-javaagent.jar
ENV JAVA_TOOL_OPTIONS="-javaagent:/otel/opentelemetry-javaagent.jar"
CMD ["java", "-jar", "myapp.jar"]

请在下载 URL 中固定 agent 版本,而不是使用 latest,这样构建是可复现的。然后在运行时配置它:

OTEL_SERVICE_NAME=checkout \
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2,deployment.environment.name=staging \
java -jar myapp.jar

agent 可以通过三种方式配置:系统属性(-Dotel.service.name=...)、环境变量,或者用 OTEL_JAVAAGENT_CONFIGURATION_FILE=/path/to/file.properties(或 -Dotel.javaagent.configuration-file)引用的 Java properties 文件。当你有许多设置时,请把 properties 文件保存在 Git 中。要调试 agent 本身,请设置 OTEL_JAVAAGENT_DEBUG=true,并预期输出会非常冗长。agent 还支持声明式 YAML 配置文件;请参见 Java agent 文档。

Python

安装发行版、OTLP exporter,以及与你已安装的包相匹配的插桩库:

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

opentelemetry-bootstrap -a install 会扫描你的环境,并为它发现的东西安装插桩,例如在安装了 Flask 时安装 Flask 插桩。不带参数运行 opentelemetry-bootstrap 可以查看它的建议而不安装。通过 opentelemetry-instrument 启动应用:

OTEL_SERVICE_NAME=checkout \
OTEL_TRACES_EXPORTER=otlp \
OTEL_METRICS_EXPORTER=otlp \
OTEL_LOGS_EXPORTER=otlp \
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf \
opentelemetry-instrument python myapp.py

注意行尾的反斜杠:每个变量必须与 opentelemetry-instrument 在同一条逻辑命令行上,否则它不会到达进程。对于 Gunicorn 或 Uvicorn 之类的服务器,请包装服务器命令:opentelemetry-instrument gunicorn app:app。一些使用 uv 包管理器的设置需要为 bootstrap 步骤使用变通办法,Python 故障排查页面有所描述。Python 中的日志导出是选择性开启的,所以如果日志没有出现,请查看 Python 文档的日志部分。

一个 Dockerfile 模式:

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt \
 && pip install opentelemetry-distro opentelemetry-exporter-otlp \
 && opentelemetry-bootstrap -a install
COPY . .
CMD ["opentelemetry-instrument", "python", "myapp.py"]

Node.js

安装 API 和自动插桩包:

npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node

在你的应用之前用 --require,或通过 NODE_OPTIONS 加载它:

export OTEL_SERVICE_NAME=checkout
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
export OTEL_NODE_RESOURCE_DETECTORS=env,host,os
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
node app.js

OTEL_NODE_RESOURCE_DETECTORS 限制运行哪些资源检测器(默认全部启用)。OTEL_NODE_ENABLED_INSTRUMENTATIONS 限制加载哪些插桩;请参见模块配置页面。OTEL_LOG_LEVEL 接受 none、error、warn、info、debug、verbose 和 all,默认值为 info。在生产环境中请保持在 info,因为调试输出会损害性能。ES 模块应用可能需要额外的 loader 选项;请根据你的模块系统遵循 Node.js 文档。

.NET、Go 及其他

.NET 有一个零代码 agent,以同样的方式配置(环境变量加启动脚本)。Go 使用基于 eBPF 的 agent,它作为特权 sidecar 运行,并且需要目标可执行文件的路径,所以它主要通过 Operator 使用。请查看文档的零代码部分了解每一种。

你能得到什么,不能得到什么

你会得到传入和传出 HTTP、数据库调用和常见消息库的 span,以及某些语言中的运行时指标。你得不到业务层面的 span,比如”计算折扣”,因为 agent 无法知道它们。在额外细节值得的地方,用 OpenTelemetry API 添加少量手动 span 或属性,其余的一切交给 agent。

验证它是否工作

  1. 在启用 Collector 的 debug exporter 的情况下启动应用。
  2. 发送一个请求:curl http://localhost:8080/。
  3. 在 Collector 的日志中查看带有你的 service.name 的 span:
docker compose logs otel-collector | grep -i 'service.name'

如果没有任何东西到达,请按以下顺序检查:端点和端口与协议匹配、该信号的 Collector 管线列出了 otlp receiver、应用可以解析 Collector 的主机名,并且没有设置 OTEL_SDK_DISABLED。故障排查指南会展开说明每一项。

生产注意事项

  • 固定 agent 和发行版的版本,并有意识地更新它们。
  • 在每个服务上设置 service.name、service.version 和 deployment.environment.name,因为仪表板依赖它们。
  • 从一个采样比例开始,而不是保留一切(参见采样指南)。
  • 在 Kubernetes 上,使用 Operator 通过注解注入 agent,而不是编辑每个 Dockerfile。

热门指南