深色模式
OTel 自动埋点
摘要：自动埋点是不改一行业务代码就能拿到链路的最快路径——Java 靠 agent 挂载，Python 靠
opentelemetry-instrument，Node.js 靠--require。本文给出三种语言的接入步骤、参数配置，以及在自动埋点之上补充业务 span 的方法。
适用环境
bash
java -version 2>&1 | head -1
python3 --version
node --version
# Collector 已就绪（自动埋点默认通过 OTLP 上报）
nc -z -w2 127.0.0.1 4317 && echo "OTLP gRPC OK"
export OTEL_SERVICE_NAME=demo-app
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:43171
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
操作步骤
1. Java：用 javaagent 挂载（最常用）
bash
# 到 Releases 页核对版本后下载 opentelemetry-javaagent.jar
curl -LO https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
java -javaagent:/path/to/opentelemetry-javaagent.jar \
-Dotel.service.name=demo-app \
-Dotel.exporter.otlp.endpoint=http://127.0.0.1:4317 \
-jar app.jar1
2
3
4
5
6
7
2
3
4
5
6
7
bash
# Kubernetes 里用 initContainer 注入 agent（Operator 方式同理）1
yaml
# deployment 片段思路：把 agent 挂到共享 volume，再通过 JAVA_TOOL_OPTIONS 引用
env:
- name: JAVA_TOOL_OPTIONS
value: "-javaagent:/otel-auto-instrumentation/javaagent.jar"
- name: OTEL_SERVICE_NAME
value: demo-app
- name: OTEL_EXPORTER_OTLP_ENDPOINT
value: http://otel-collector:43171
2
3
4
5
6
7
8
2
3
4
5
6
7
8
2. Python：命令行前缀式注入
bash
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install # 自动安装已用框架对应的 instrumentation 包
opentelemetry-instrument \
--traces_exporter otlp \
--metrics_exporter otlp \
--service_name demo-app \
python3 app.py1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
3. Node.js：预加载方式
bash
npm install --save @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register app.js
# 或用环境变量方式
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"1
2
3
4
5
2
3
4
5
4. 控制采集范围（避免无谓开销）
bash
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1
# 关闭某些 noisy 的 instrumentation（Java 示例）
export OTEL_INSTRUMENTATION_JDBC_ENABLED=false
export OTEL_INSTRUMENTATION_REDIS_ENABLED=true1
2
3
4
5
6
2
3
4
5
6
5. 在自动埋点之上补充业务 span（以 Python 为例）
python
from opentelemetry import trace
tracer = trace.get_tracer(__name__)
def create_order(user_id, sku):
with tracer.start_as_current_span("create_order") as span:
span.set_attribute("user.id", str(user_id))
span.set_attribute("sku", sku)
result = do_create(user_id, sku) # 业务逻辑
if not result.ok:
span.record_exception(result.error)
span.set_status(trace.Status(trace.StatusCode.ERROR, "create failed"))
return result1
2
3
4
5
6
7
8
9
10
11
12
13
2
3
4
5
6
7
8
9
10
11
12
13
6. 关闭健康检查等噪声链路
yaml
# Collector 里用 filter processor 丢弃健康检查 span
processors:
filter/health:
error_mode: ignore
traces:
span:
- 'attributes["http.route"] == "/healthz"'
- 'attributes["http.target"] == "/ping"'1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
验证
bash
# 1) Java 进程启动时日志出现 agent 加载信息
java -javaagent:opentelemetry-javaagent.jar -jar app.jar 2>&1 | grep -i 'opentelemetry' | head -3
# 2) 打一次请求，看 Collector 是否收到 span
curl -s http://127.0.0.1:8080/api/order -o /dev/null
# 3) 用 debug exporter 观察输出（或查后端 UI）
curl -s 'http://127.0.0.1:3200/api/search?limit=5' | head -c 200
# 4) 确认 service.name 正确而非 unknown_service
curl -s 'http://127.0.0.1:8889/metrics' | grep 'service_name' | head -31
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
常见坑
WARNING
Java agent 通过 -javaagent 挂载时必须放在 -jar 之前，且路径要对。放在后面 JVM 会忽略它，表现为"配置都对但没有数据"。
WARNING
Python 的 opentelemetry-bootstrap -a install 会尝试安装所有已检测框架的 instrumentation 包，可能与现有依赖冲突。建议先在小环境验证，再固化到镜像里。
DANGER
自动埋点会采集 HTTP 头、SQL 语句、请求参数等，其中可能包含 token、手机号等敏感信息。上线前请确认 Collector 侧已配置属性脱敏或过滤规则，否则存在数据泄露风险。