接入链路追踪
链路追踪展示一次请求在多个微服务间的调用路径与耗时。数据由业务侧通过 OTLP 上报给运维平台的 Alloy,再转发进 Tempo 存储。
链路追踪面向 Kubernetes 集群部署。单机(Docker Compose)部署暂不支持。
推荐方式:Istio sidecar 自动上报
业务运行在 Istio 网格内时,sidecar 可自动生成并上报 span,无需修改业务代码。HAP/HDP 集群模式通常已接入网格。
安装 Istio 并开启 istio-injection=enabled 后,还需要配置上报地址和采样率才能生成 span。未配置时通常不会报错,但链路追踪页面没有数据。
自查:
kubectl -n istio-system get cm istio \
-o jsonpath='{.data.mesh}' | grep -A3 extensionProviders
无输出表示尚未配置,请按以下步骤补充。
第 1 步:配置 Istio 上报地址
kubectl -n istio-system edit configmap istio
mesh 的值是一段 YAML 文本。在该文本的顶层添加 extensionProviders,与 defaultConfig、rootNamespace 保持同级:
apiVersion: v1
kind: ConfigMap
metadata:
name: istio
namespace: istio-system
data:
mesh: |- # ← 注意这里是个字符串块
defaultConfig:
discoveryAddress: istiod.istio-system.svc:15012
defaultProviders:
metrics:
- prometheus
enablePrometheusMerge: true
rootNamespace: istio-system
trustDomain: cluster.local
extensionProviders: # ← 加这一整段
- name: mdis-otel
opentelemetry:
service: ops-alloy.<运维平台命名空间>.svc.cluster.local
port: 4317
meshNetworks: |-
networks: {}
配置时注意以下事项:
-
extensionProviders是 mesh 的顶层字段,不要缩进到defaultConfig中。层级错误时,istiod 会忽略该配置,不会产生 span。 -
service必须填写完整 FQDN,并使用运维平台实际所在的命名空间。默认清单使用hap-ops,实际部署时可能不同。命名空间错误时 sidecar 无法解析服务,通常也不会报错。可通过以下命令确认:
kubectl get svc -A | grep ops-alloy
opentelemetryprovider 使用 OTLP gRPC,端口为 4317。
修改后重启 istiod,使配置重新加载:
kubectl -n istio-system rollout restart deployment/istiod
kubectl -n istio-system rollout status deployment/istiod
回读配置,确认输出包含新增的配置:
kubectl -n istio-system get cm istio -o jsonpath='{.data.mesh}' | grep -A4 extensionProviders
第 2 步:开启采样
上一步仅配置 Istio 的上报地址,还需配置采样率——未创建 Telemetry 时采样率为 0, 不会产生 span。
kubectl apply -f - <<'EOF'
apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
name: mdis-tracing
namespace: istio-system # 放在 istio 根命名空间 = 全网格生效
spec:
tracing:
- providers:
- name: mdis-otel # 必须与第 1 步的 name 完全一致
randomSamplingPercentage: 100
EOF
确认 Telemetry 资源已创建:
kubectl get telemetry -A
randomSamplingPercentage 验证阶段建议设为 100(否则 10% 采样下少量请求可能无法命中采样,
容易误判为配置未生效);确认链路连通后改回 1~10——采样率越高,Tempo 的存储和写入压力越大。
修改该值不需要重启 istiod,但需重启业务 Pod 才会生效。
上例使用 telemetry.istio.io/v1(Istio 1.22+,1.29 实测可用)。更早版本的 Istio 使用
v1alpha1,其余字段相同。可通过以下命令确认当前版本:
kubectl api-resources | grep telemetry
第 3 步:重启业务 Pod
sidecar 需要重新加载配置后才会上报链路。重启业务 Pod:
kubectl -n <业务命名空间> rollout restart deployment/<名字>
确认业务命名空间已启用注入:
kubectl get ns -L istio-injection
对应行显示 enabled 才会有 sidecar。
第 4 步:确认 span 已推送到运维平台
该步骤用于确认运维平台 Alloy 是否已接收到 span:
kubectl -n <运维平台命名空间> exec deploy/ops-alloy -- \
curl -s localhost:12345/metrics | grep otelcol_receiver_accepted_spans_total
先触发几次跨服务调用,再执行一次检查。若指标增长,表示上报链路已连通:
otelcol_receiver_accepted_spans_total{...,transport="grpc"} 83
若指标持续为 0 或查询不到该指标,按下表排查:
| 现象 | 通常是 |
|---|---|
| 指标为 0 | 业务 Pod 未重启(第 3 步),或采样率过低、请求未命中采样 |
| 指标不存在 | Alloy 未开启 OTLP 接收,检查 ops-alloy Service 是否暴露 4317 |
| 指标增长但页面空 | Alloy→Tempo 链路异常,检查 ENV_TEMPO_GRPC_URL 与 ops-tempo 容器日志 |
上报端点
Alloy 接收 OTLP 的端点:
| 协议 | 端点 |
|---|---|
| OTLP gRPC | 4317 |
| OTLP HTTP | 4318 |
应用若自带 OpenTelemetry SDK,将 exporter 指向上述端点即可:集群内使用 Service DNS,如
http://ops-alloy.<运维平台命名空间>.svc.cluster.local:4317(命名空间换成运维平台实际所在的,
kubectl get svc -A | grep ops-alloy 可查)。
ops-alloy 是 ClusterIP,只在运维平台所在集群内可解析。跨集群上报需要先暴露 4317
(NodePort 或 Ingress)。链路数据量较大,暴露方式与限流策略需结合实际网络环境规划。
Alloy 转发到 Tempo 的地址由 ENV_TEMPO_GRPC_URL 控制(默认 http://ops-tempo:4317),标准部署无需改动。
数据保留与存储
链路数据保留时长由 ENV_TEMPO_RETENTION 控制,默认 30 天,详见 环境变量。
要让链路数据长期留存、不受节点磁盘限制,在部署时为 Tempo 准备对象存储桶(建议名 mdis-tempo),见 对象存储。
验证
接入后触发几次跨服务调用,到 链路追踪 页查看:顶部三张概览图(请求量/错误率/P95 延迟)出现数据、底部 Recent Traces 列表出现 Trace 明细,即接入成功。