深色模式
OpenTelemetry 入门
摘要：OpenTelemetry（OTel）是可观测性领域的统一标准：一套 API/SDK 采集指标、日志、链路，通过 OTLP 协议送给 Collector，再由 Collector 转发到任意后端。本文讲清它的核心概念与组件架构，并带你跑通一条完整的数据链路。
适用环境
bash
# 语言环境（以 Go/Python/Java 任一即可）
go version 2>/dev/null; python3 --version; java -version 2>&1 | head -1
# 确认网络可访问 Collector 端口
nc -z -w2 127.0.0.1 4317 && echo "OTLP gRPC OK"
nc -z -w2 127.0.0.1 4318 && echo "OTLP HTTP OK"1
2
3
4
5
6
2
3
4
5
6
操作步骤
1. 记住四个核心概念
- Signal 信号：Traces（链路）、Metrics（指标）、Logs（日志）三类遥测数据。
- Instrumentation 埋点：产生数据的代码，分自动埋点与手动埋点。
- Resource 资源：描述"谁在产生数据"，如
service.name、host.name、deployment.environment。 - Semantic Conventions 语义约定：统一的属性命名规范（如
http.method、db.system），保证不同语言的指标可横向对比。
2. 部署 Collector（数据的中转站与加工厂）
bash
# 到项目 Releases 页核对最新版本号
VERSION=0.100.0
curl -LO https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v${VERSION}/otelcol-contrib_${VERSION}_linux_amd64.tar.gz
mkdir -p /opt/otelcol && tar -xzf otelcol-contrib_${VERSION}_linux_amd64.tar.gz -C /opt/otelcol
sudo install -m 0755 /opt/otelcol/otelcol-contrib /usr/local/bin/1
2
3
4
5
2
3
4
5
3. 写最小 Collector 配置
yaml
# /etc/otelcol/config.yaml
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
batch: # 批量发送，显著降低网络开销
timeout: 5s
resource:
attributes:
- key: deployment.environment
value: production
action: upsert
exporters:
debug: # 先打到控制台验证链路通不通
verbosity: detailed
prometheus:
endpoint: 0.0.0.0:8889
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch, resource]
exporters: [debug]
metrics:
receivers: [otlp]
processors: [batch, resource]
exporters: [prometheus]1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
4. 启动 Collector 并校验配置
bash
/usr/local/bin/otelcol-contrib validate --config /etc/otelcol/config.yaml
/usr/local/bin/otelcol-contrib --config /etc/otelcol/config.yaml1
2
2
5. 用 SDK 发一条数据（Python 最小示例）
bash
pip install opentelemetry-api opentelemetry-sdk \
opentelemetry-exporter-otlp1
2
2
python
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.trace_exporter import OTLPSpanExporter
resource = Resource.create({"service.name": "demo-app"})
provider = TracerProvider(resource=resource)
provider.add_span_processor(
BatchSpanProcessor(OTLPSpanExporter(endpoint="http://127.0.0.1:4317", insecure=True))
)
trace.set_tracer_provider(provider)
with trace.get_tracer(__name__).start_as_current_span("hello-span") as span:
span.set_attribute("demo.attr", "quickstart")
print("trace_id:", span.get_span_context().trace_id)1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
6. 设置环境变量简化配置（生产推荐方式）
bash
export OTEL_SERVICE_NAME=demo-app
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production,service.version=1.2.3
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1 # 10% 采样1
2
3
4
5
2
3
4
5
验证
bash
# 1) Collector 配置合法
/usr/local/bin/otelcol-contrib validate --config /etc/otelcol/config.yaml
# 2) 端口已监听
ss -ltnp | grep -E '4317|4318'
# 3) 运行示例程序，Collector 控制台应打印出 span
python3 demo_otel.py
# 4) 指标端点有数据
curl -s http://127.0.0.1:8889/metrics | grep -c 'demo-app' || echo "no metric yet"1
2
3
4
5
6
7
8
9
10
11
2
3
4
5
6
7
8
9
10
11
常见坑
WARNING
service.name 没设置时，OTel 会填 unknown_service:<进程名>，导致后端里出现一堆无法归类的服务。务必通过 OTEL_SERVICE_NAME 显式配置。
WARNING
SDK 默认采样率可能是全量或全不采，表现因语言而异。上线前用 OTEL_TRACES_SAMPLER 明确指定策略，避免流量一大就压垮 Collector。
DANGER
Collector 的 otlp receiver 监听 0.0.0.0 且无任何认证，等于开放了一个可被任意写入的遥测入口。生产环境请只监听内网，并在前面加网关做认证与限流。