作为一家在亚太地区快速扩张的 SaaS 服务提供商，我们的服务节点逐步下沉至各大区域边缘，尤其是香港，作为跨境服务的重要桥头堡，其边缘计算节点承载着大量延迟敏感型流量。

一次线上事故暴露出我们对边缘节点可观测性建设的短板——用户在香港地区访问缓慢，但中心化 APM 无法还原边缘请求链路。在反复排查之后，我决定在香港部署 OpenTelemetry，实现本地采集、链路打点与上报，从边缘节点还原全链路调用情况。

这篇文章，是我从 0 到 1 搭建 OpenTelemetry 追踪系统在香港边缘节点落地的完整实战记录，涵盖部署架构、Agent 配置、采样优化及常见坑点排查等关键环节，适用于同样面临异地、边缘部署挑战的工程团队。

一、边缘节点全链路追踪架构设计

1.1 技术选型背景

香港边缘节点环境具备如下特点：

• 部署在 Kubernetes 边缘集群中
• 资源受限（CPU、内存均为中等规格）
• 出站网络存在跨区域链路（需要优化链路延迟和数据带宽）
• 需与总部 observability 平台（基于 Grafana Tempo + Loki + Prometheus）集成

因此，架构设计上采用：

• 本地部署 otel-collector，实现采集、初步处理、批量打包
• 应用内使用 OpenTelemetry SDK 打点（Java 与 Go 两种语言）
• 利用 OTLP over gRPC 协议发送 trace 数据到本地 otel-collector
• Collector 执行采样、转码，最终异步上报 Tempo 中心节点（位于新加坡）

1.2 拓扑结构示意

[ 应用容器 (Java / Go) ]
        ↓ OTLP gRPC
[ 本地 Otel Collector (香港) ]
        ↓ HTTP
[ Tempo Collector (新加坡总部) ]
        ↓
[ Grafana 可视化 / 警报系统 ]

二、OpenTelemetry 部署步骤（香港边缘节点）

2.1 安装 Otel Collector

我选择使用 Helm 在 Kubernetes 中部署 otel-collector：

helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update

helm install otel-collector open-telemetry/opentelemetry-collector \
  --namespace observability \
  --create-namespace \
  -f values-hk.yaml

values-hk.yaml 配置关键部分如下：

config:
  receivers:
    otlp:
      protocols:
        grpc:
        http:
  processors:
    batch:
      timeout: 10s
    memory_limiter:
      limit_mib: 200
      spike_limit_mib: 50
      check_interval: 5s
  exporters:
    otlphttp:
      endpoint: "https://tempo.ap-southeast-1.company.net/api/traces"
  service:
    pipelines:
      traces:
        receivers: [otlp]
        processors: [memory_limiter, batch]
        exporters: [otlphttp]

注意事项：

• 使用 otlphttp 替代 jaeger 等协议，减少跨区连接耗时
• 配置 memory_limiter 防止边缘 Collector OOM
• 使用 batch 批量传输优化带宽使用

三、应用层打点实战（以 Go 应用为例）

3.1 引入 SDK

go get go.opentelemetry.io/otel
go get go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc

3.2 初始化 TracerProvider

func initTracer() (*sdktrace.TracerProvider, error) {
    ctx := context.Background()
    exporter, err := otlptracegrpc.New(ctx,
        otlptracegrpc.WithEndpoint("otel-collector.observability.svc:4317"),
        otlptracegrpc.WithInsecure(), // 若使用 TLS 则 WithTLSCredentials
    )
    if err != nil {
        return nil, err
    }

    bsp := sdktrace.NewBatchSpanProcessor(exporter)

    tp := sdktrace.NewTracerProvider(
        sdktrace.WithSpanProcessor(bsp),
        sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.2)), // 可调采样率
    )

    otel.SetTracerProvider(tp)
    return tp, nil
}

3.3 应用打点样例

tr := otel.Tracer("edge-service")
ctx, span := tr.Start(ctx, "handle-request")
defer span.End()

// 模拟下游请求
ctx2, span2 := tr.Start(ctx, "call-db")
time.Sleep(30 * time.Millisecond)
span2.End()

四、采样率配置与链路优化建议

边缘节点采样不宜全量，推荐配置动态或分层采样：

• 低优先级业务使用 TraceIDRatioBased(0.1)
• 异常请求（HTTP 500 等）开启 AlwaysOn
• 使用标签路由采样器（tail-based sampling 可通过 collector 配置实现）

示例采样器配置（otel-collector）：

processors:
  tail_sampling:
    decision_wait: 5s
    num_traces: 10000
    policies:
      - name: errors-sampler
        type: status_code
        status_code: {status_codes: [ERROR]}
      - name: high-priority
        type: string_attribute
        string_attribute: {key: "env", values: ["prod"], enabled: true}

五、实战中遇到的问题与解决

5.1 出现 Collector CPU 飙高，trace 丢失

原因：默认 batch 队列过小，数据爆发时积压。

解决：加大 send_batch_size，延长 timeout。

batch:
  send_batch_size: 1024
  timeout: 15s

5.2 Tempo 后端收到大量无 parent span 的 trace

原因：下游服务未传递 context。

解决：统一使用 OpenTelemetry HTTP middleware 或 gRPC interceptors，确保 context 透传。

六、最终效果与回顾

部署完成后，我们成功在香港节点监控到完整调用链，发现一处 Go 服务中未缓存 Redis 热点导致调用堆积，及时优化。

整个链路延迟控制在 300ms 以内，边缘与中心同步间隔为 1~2 秒。Grafana 中的 Trace View 也已可回溯 72 小时历史链路，对 SLA 分析帮助极大。

将 OpenTelemetry 接入边缘节点并非一件 plug-and-play 的事情，但得益于其模块化和标准化架构，我们得以在资源受限、网络高延迟的环境下依然实现了完整的全链路追踪。

关键经验总结如下：

• 边缘部署建议采用本地 Collector + 异步中心上报架构
• 使用 OTLP 协议简化传输与兼容性问题
• 配置合理采样策略，兼顾性能与覆盖率
• 所有服务都应集成 context 传递能力

如果你也在边缘环境中构建 observability，希望这份实践经验能帮你少踩坑，早日跑通！