OpenTelemetry Go（LoongSuite）¶

LoongSuite Go 是基于 OpenTelemetry 的 Go 编译期自动插桩工具。它不要求修改业务代码，只需将原来的 go build 替换为 otel go build，即可在编译期间为受支持的框架和组件注入 OpenTelemetry SDK 及插桩逻辑。

本文使用 DataKit 的 OpenTelemetry 采集器接收 LoongSuite 通过 OTLP 上报的 Trace 和 Metric，并转发到观测云：

Go 源码 -- otel go build --> 插桩后的 Go 二进制 -- OTLP --> DataKit --> 观测云

!!! note

LoongSuite 的“零代码”表示不需要修改业务代码，并不表示无需重新构建。插桩发生在编译阶段，已经生成的 Go 二进制不能直接附加 LoongSuite；必须使用 `otel go build` 重新编译并部署新的二进制。

前置条件¶

• 已安装 DataKit，且 DataKit 已连接到目标观测云工作空间；
• Go 应用到 DataKit 的网络可达：OTLP/HTTP 使用 DataKit HTTP 端口 9529，OTLP/gRPC 默认使用 4317；
• 应用可以使用标准 go build 正常编译；
• Go 版本、操作系统和架构符合 LoongSuite 的兼容性要求；
• 应用使用的框架或组件在 LoongSuite 的支持列表中。

本文以 Linux AMD64 主机为例，不包含 Kubernetes 部署。

一、开启 OpenTelemetry 采集器¶

进入 DataKit 安装目录下的 conf.d/opentelemetry。如果尚未创建采集器配置，复制示例文件：

cd /usr/local/datakit/conf.d/opentelemetry
sudo cp opentelemetry.conf.sample opentelemetry.conf

确认 opentelemetry.conf 至少包含以下接收配置：

[[inputs.opentelemetry]]
  # 如需将自定义属性作为标签保留，请在此加入白名单。
  # 属性名中的点会被转换为下划线，例如 team.name -> team_name。
  customer_tags = ["team", "project"]

  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"

  [inputs.opentelemetry.grpc]
    addr = "127.0.0.1:4317"
    max_payload = 16777216

以上配置开启以下接收地址：

如果应用与 DataKit 不在同一主机，需按实际部署调整 DataKit HTTP 监听地址、防火墙或其他网络访问控制。使用 OTLP/gRPC 时，还需要将 addr 改为应用可访问的监听地址，例如 0.0.0.0:4317。不要将 OTLP 接收端口直接暴露到公网。

重启 DataKit 使配置生效：

sudo datakit service restart

检查 DataKit HTTP 服务是否可达：

curl http://127.0.0.1:9529/v1/ping

二、应用接入 OpenTelemetry¶

安装 LoongSuite¶

从 LoongSuite 官方 GitHub Release 下载 Linux AMD64 可执行文件：

sudo curl -fL \
  https://github.com/alibaba/loongsuite-go/releases/latest/download/otel-linux-amd64 \
  -o /usr/local/bin/otel
sudo chmod +x /usr/local/bin/otel

ARM64 主机将文件名替换为 otel-linux-arm64。其他操作系统和架构请从 LoongSuite Releases 选择对应文件。

确认工具可以运行：

otel version
go version

生产环境建议使用包含明确版本号的 Release 下载地址固定 LoongSuite 版本，并在升级前检查兼容性、Release Notes，执行编译和链路回归测试。

插桩前检查¶

先用原始命令确认项目能够正常编译：

go build ./...

如果项目已经直接依赖 OpenTelemetry Go API、SDK 或 Contrib 插桩库，需要检查这些依赖与当前 LoongSuite 版本要求是否一致：

go list -m all | grep 'go.opentelemetry.io'

LoongSuite 会为应用注入 SDK 初始化逻辑，并对 OpenTelemetry 自身进行插桩。项目中已有不兼容的 OpenTelemetry 依赖或重复的 SDK 初始化逻辑时，可能出现编译失败、重复 Span 或上下文中断。此类项目应先按官方兼容性表统一依赖版本；如果应用需要自行控制 SDK，建议改用 OpenTelemetry Go SDK。

使用 LoongSuite 编译¶

进入 Go 项目目录，在原始构建命令前增加 otel：

otel go build -o ./bin/order-service ./cmd/order-service

其他常见构建方式同样保留原有 go build 参数，例如：

otel go build
otel go build -trimpath -ldflags="-s -w" -o ./bin/order-service ./cmd/order-service

LoongSuite 编译会增加预处理、插桩和依赖处理阶段，首次构建通常明显慢于原生 go build。可以配置一个可复用的 Go 构建缓存，缩短后续构建时间：

otel set -gocache=/var/tmp/loongsuite-go-cache

也可以通过环境变量为 CI 或单次构建指定缓存：

export OTELTOOL_GO_CACHE="/var/tmp/loongsuite-go-cache"
otel go build -o ./bin/order-service ./cmd/order-service

!!! warning

后续发布流程必须部署 `otel go build` 生成的二进制。如果又使用普通 `go build` 覆盖产物，运行时将不会包含 LoongSuite 自动插桩。

配置 OTLP/HTTP 并启动¶

以下示例通过 OTLP/HTTP + Protobuf 将 Trace 和 Metric 上报到本机 DataKit。通用 endpoint 设置为 http://127.0.0.1:9529/otel 后，Exporter 会分别追加 /v1/traces 和 /v1/metrics，最终对应 DataKit 的 /otel/v1/* 接收路径。

export OTEL_SERVICE_NAME="order-service"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=prod,service.version=1.0.0,team=backend"

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:9529/otel"
export OTEL_EXPORTER_OTLP_INSECURE="true"

# 1.0 表示全量采样，仅建议在接入验证阶段使用。
export OTEL_TRACE_SAMPLER="1.0"

./bin/order-service

运行参数必须配置在插桩后二进制的实际运行环境中，而不只是配置在编译主机上。启动后请求一个受支持框架提供的接口，并触发数据库、HTTP 客户端或消息队列调用，以产生可验证的 Span 和 Metric。

使用 OTLP/gRPC¶

如需改用 OTLP/gRPC，替换协议和 endpoint；gRPC 地址不能追加 /v1/traces 等 HTTP 路径：

export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4317"
export OTEL_EXPORTER_OTLP_INSECURE="true"

三、数据上报参数¶

LoongSuite 在编译期间注入 OpenTelemetry SDK 初始化逻辑，插桩后的应用可在运行时通过环境变量调整 Exporter、endpoint、采样和资源属性。

资源和 Exporter 参数¶

使用通用 HTTP endpoint 时填写 http://<DataKit-IP>:9529/otel；如果使用信号专用 endpoint，则必须填写包含 /otel/v1/traces 或 /otel/v1/metrics 的完整路径。DataKit 的 OTLP/HTTP 采集仅支持 Protobuf，不要配置 http/json。

采样和 Metric 参数¶

!!! warning

LoongSuite 当前使用的采样变量是 `OTEL_TRACE_SAMPLER`，与 OpenTelemetry SDK 常见的 `OTEL_TRACES_SAMPLER`、`OTEL_TRACES_SAMPLER_ARG` 命名不同。请以所安装 LoongSuite 版本的 [SDK 配置说明](https://github.com/alibaba/loongsuite-go/blob/main/docs/user/sdk-config.md){:target="_blank"}为准。

生产环境应根据流量、数据预算和排障需求调整采样率。上下游服务需要保持兼容的 W3C Trace Context 传播，避免跨服务调用时产生断链。

LoongSuite 构建参数¶

以下变量只控制 LoongSuite 编译工具，不控制插桩后二进制的数据上报：

例如，临时输出详细编译日志：

export OTELTOOL_DEBUG="true"
export OTELTOOL_VERBOSE="true"
otel go build -o ./bin/order-service ./cmd/order-service

排障完成后应关闭 Debug 和 Verbose，减少日志量。

字段映射¶

LoongSuite 上报的 OTLP Span Attributes 会由 DataKit OpenTelemetry 采集器转换为链路字段。常见映射如下：

如需将 LoongSuite 上报的其他 Attributes 提升为标签，可在 DataKit opentelemetry.conf 中配置 customer_tags。customer_tags 支持正则表达式，命中的属性名会将 . 转换为 _：

[[inputs.opentelemetry]]
  customer_tags = [
    "reg:^db\\.query\\.parameter\\.",
    "reg:^kratos\\.service\\.meta\\.",
    "reg:^gen_ai\\.other_input\\.",
    "reg:^gen_ai\\.other_output\\.",
  ]

不要将用户 ID、订单号等高基数值批量提升为标签，也不要上报密码、Token、数据库完整连接串等敏感信息。

验证接入¶

1. 使用 otel go build 编译并启动新二进制；
2. 请求一个由受支持 Web 框架处理的接口，并触发数据库、HTTP 客户端或消息队列调用；
3. 使用 OTLP/HTTP 上报时，在 DataKit 主机检查接收日志：

sudo tail -f /usr/local/datakit/log/gin.log | grep '/otel/v1/'

出现 /otel/v1/traces 或 /otel/v1/metrics 的 POST 请求且响应码为 200，表示 DataKit 已收到数据。然后进入观测云的「应用性能监测 > 链路」，按 service:order-service 查询；Metric 需要等待至少一个导出周期后再查询。

如果没有数据，请依次检查：

• 部署的是否为 otel go build 生成的新二进制；
• OTEL_SERVICE_NAME、Exporter、协议和 endpoint 是否配置在实际运行进程中；
• 应用使用的框架及版本是否在 LoongSuite 支持列表中；
• LoongSuite 与项目已有 OpenTelemetry 依赖是否兼容；
• DataKit OpenTelemetry 采集器是否已开启并重启生效；
• 应用到 DataKit 的网络和端口是否可达。

如果普通 go build 成功但 otel go build 失败，可临时启用 OTELTOOL_DEBUG=true 和 OTELTOOL_VERBOSE=true，定位具体失败的插桩规则。必要时可以通过 otel set -disable=<rule-name> 暂时禁用问题规则，并向 LoongSuite Issues反馈。

参考¶

• LoongSuite Go
• LoongSuite 支持的框架和组件
• LoongSuite SDK 配置
• LoongSuite 构建工具配置
• OpenTelemetry Go 零代码插桩
• DataKit OpenTelemetry 采集器