作者：刘子明（牧思）

背景

在此前，对 Golang 应用程序的监控通常需要对代码进行一定的改造，比如在代码中引入 OpenTelemetry 等 SDK^[1^]。这样的改造通常会导致运维团队与研发团队之间的分歧。运维团队表示：“研发团队如果不接入相关的监控，作为运维团队我们很难摸清楚应用的运行状态并做出相应的操作”。研发团队则会抱怨：“本来业务上的需求就很多了，还要去在代码里面做各种埋点，SDK 如果版本变化了，代码又要调整”。这就导致了 Golang 应用程序接入可观测的效率降低，本文将通过阿里云开源的 Golang Agent^[2^]，帮助用户实现“一行代码都不改”就能获取到应用产生的各种观测数据，同时提升运维团队和研发团队的幸福感。

快速开始

Golang 开发者在开发应用程序时，通常会使用 go build 命令来将源代码构建成二进制程序包，之后再将二进制程序包运行起来。而阿里云开源的 Golang Agent 可以被视作是 go build 的一个平替，用户编译 Golang 应用时，将 go build 简单地替换成 Golang Agent 这个二进制包，即可编译出具有可观测能力的二进制 Golang 程序，下面来详细介绍 Golang Agent 的构建使用流程：

Step 1：下载/构建 Golang Agent 二进制包

首先，可以进入 https://github.com/alibaba/opentelemetry-go-auto-instrumentation 页面下载最新版本的 Golang Agent 二进制包。

如果您想体验 Golang Agent 最新的未发布的能力，也可以通过以下指令从 main 分支编译最新的 Golang Agent 二进制包：

# 首先下载项目至本地
git clone https://github.com/alibaba/opentelemetry-go-auto-instrumentation.git
# 进入到agent的根目录
cd opentelemetry-go-auto-instrumentation
# 编译Golang Agent二进制包
make clean && make build
chmod u+x ./otel

执行完上述命令后，项目根目录下会出现一个名为 otel 的二进制文件，说明您已经成功编译出了 Golang Agent 的二进制包。

Step 2：使用 Golang Agent 二进制包编译 Golang 应用

在拥有了 Golang Agent 的二进制包后，即可使用该二进制包代替 go build 编译 Golang 应用的二进制程序。Golang Agent 在 https://github.com/alibaba/opentelemetry-go-auto-instrumentation/tree/main/example 目录下提供了相应的 Golang Demo：

cd ./example/demo
../../otel go build .

以 example 下 demo 目录的构建为例，原本的构建命令可能是 go build .，现在需要添加一个编译前缀 ../../otel go build . 有点类似于 Linux 系统中在原本执行的命令前添加 sudo，在执行上述命令后，即可在对应应用的根目录下找到具有可观测能力的 Golang 二进制程序。

Step3：配置上报端点，启动 Golang 应用

链路上报

首先参考 step2，在 example/demo 目录下编译出二进制文件 demo。

在上报之前，可以先启动该应用的一些依赖，此应用会去调用 MySQL 以及 Redis，所以我们先启动这两个依赖：

docker run -d -p 3306:3306 -p 33060:33060 -e MYSQL_USER=test -e MYSQL_PASSWORD=test -e MYSQL_DATABASE=test -e MYSQL_ALLOW_EMPTY_PASSWORD=yes mysql:8.0.36
docker run -d -p 6379:6379 redis:latest

之后，再启动 jaeger 来接收并展示上报的链路信息：

docker run --rm --name jaeger \
  -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
  -p 6831:6831/udp \
  -p 6832:6832/udp \
  -p 5778:5778 \
  -p 16686:16686 \
  -p 4317:4317 \
  -p 4318:4318 \
  -p 14250:14250 \
  -p 14268:14268 \
  -p 14269:14269 \
  -p 9411:9411 \
  jaegertracing/all-in-one:1.53.0

在启动完相关依赖后，我们可以根据 Otel 的规范^[^3]配置相关的上报端点，并且启动应用：

cd example/demo
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4318" 
export OTEL_EXPORTER_OTLP_INSECURE=true 
export OTEL_SERVICE_NAME=demo 
./demo

启动应用后，不断地请求应用以生成相关调用链信息：

curl localhost:9000/http-service

最后，访问 http://localhost:16686/jaeger/ui/search，在 jaeger 中搜索相关调用链信息，可以发现相关调用链已正常生成并成功串联，通过调用链可以完整地梳理整个请求的执行链路。

指标上报

首先参考 step 2，在 example/metrics 目录下编译出二进制文件 metrics。

同样地，在上报之前，可以先启动该应用的一些依赖，此应用会去通过 Otel Collector 上报指标信息至 Prometheus，所以我们通过以下命令来启动 Otel Collector 与 Prometheus：

# 进入到metrics目录
cd example/metrics
# 启动Otel Collector以及Prometheus
docker compose up --force-recreate --remove-orphans --detach

在相关依赖启动成功后，可以根据 Otel 的规范配置相关的上报端点，并且启动应用：

# 进入到metrics目录
cd example/metrics
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4318" 
export OTEL_EXPORTER_OTLP_INSECURE=true
export OTEL_SERVICE_NAME=metrics 
./metrics

启动应用后，不断地请求应用以生成相关指标信息：

# For Golang GC metrics
curl localhost:9000/gc-metrics
# For Golang Memory metrics
curl localhost:9000/mem-metrics

最后，访问 http://localhost:9090，在 prometheus 中搜索相关指标信息，可以发现相关指标已正常生成并上报，通过以上指标可以更好地帮助用户了解 Golang 运行时的相关信息以及 HTTP 总体的调用状况。

日志关联

Golang Agent 支持两种模式的日志关联，如果您使用了 Golang Agent 支持的日志框架^[^4]，那么 Agent 将会自动将 traceID 以及 spanID 注入至日志中。此外，您还可以通过 Otel SDK 来手动获取 traceID 以及 spanID，从而将它们打印到日志中，下面分别来简单实践一下这两种模式的日志关联：

自动日志关联

首先参考 step 2，在 example/log 目录下编译出二进制文件 test。编译成功后可以启动该应用。

# 进入到metrics目录
cd example/log
./test

启动应用后，不断地请求应用以打印相关的日志：

curl localhost:9999/log

可以看到应用打印出如下所示的日志，在日志的起始处可以看到对应的 traceID 已经 spanID 信息：

{"level":"debug","msg":"this is debug message","trace_id":"d62a8fea286cc66de9c68ca17d4faa88","span_id":"7cb6d692769ffd32"}
{"level":"info","msg":"this is info message","trace_id":"d62a8fea286cc66de9c68ca17d4faa88","span_id":"7cb6d692769ffd32"}
{"level":"warn","msg":"this is warn message","trace_id":"d62a8fea286cc66de9c68ca17d4faa88","span_id":"7cb6d692769ffd32"}
{"level":"error","msg":"this is error message","trace_id":"d62a8fea286cc66de9c68ca17d4faa88","span_id":"7cb6d692769ffd32"}
{"level":"debug","msg":"this is debug message","trace_id":"e56a6f1e7ed7af48cce8f64d045ed158","span_id":"def0b8cf10fe8844"}
{"level":"info","msg":"this is info message","trace_id":"e56a6f1e7ed7af48cce8f64d045ed158","span_id":"def0b8cf10fe8844"}
{"level":"warn","msg":"this is warn message","trace_id":"e56a6f1e7ed7af48cce8f64d045ed158","span_id":"def0b8cf10fe8844"}
{"level":"error","msg":"this is error message","trace_id":"e56a6f1e7ed7af48cce8f64d045ed158","span_id":"def0b8cf10fe8844"}

手动日志关联

除此之外，您还可以通过 Otel SDK 来手动获取 traceID 以及 spanID，并将它们打印到日志中，相关实例代码如下所示：

package main

import (
  "go.opentelemetry.io/otel/sdk/trace"
  "go.uber.org/zap"
  "net/http"
)

func main() {
  http.HandleFunc("/logwithtrace", func(w http.ResponseWriter, r *http.Request) {
    logger := zap.NewExample()
      // 通过SDK获取对应traceID以及spanID
      // 注意，这种用法必须要使用Golang Agent才能成功编译
    traceId, spanId := trace.GetTraceAndSpanId()
    logger.Info("this is info message with fileds",
      zap.String("traceId", traceId),
      zap.String("spanId", spanId),
    )
  })
  http.ListenAndServe(":9999", nil)
}

参考 step 2，在 example/log 目录下编译出二进制文件 test。编译成功后可以启动该应用。

# 进入到metrics目录
cd example/log
./test

启动应用后，不断地请求应用以打印相关的日志：

curl localhost:9999/logwithtrace

可以看到应用打印出如下所示的日志，在日志的起始处可以看到对应的 traceID 以及 spanID 信息：

{"level":"info","msg":"this is info message with fileds","traceId":"92d63797010a2040484222a74c5ce304","spanId":"5a2c84c807a6e12c"}

总结和展望

Golang Agent 成功解决了 Golang 应用监控中繁琐的手动埋点问题，并已商业化上线至阿里云公有云，为客户提供强大的监控能力。这项技术最初的设计初衷是为了让用户能够在不改动现有代码的前提下轻松地插入监控代码，从而实现对应用程序性能状态的实时监测与分析，但它的实际应用领域超越预期，包括服务治理、代码审计、应用安全、代码调试等，甚至在许多未被探索的领域中也展现出潜力。

我们决定将这项创新方案开源，并捐赠给 OpenTelemetry 社区^[^5]，后续我们的代码将迁移到 OpenTelemetry 社区仓库。开源不仅促进技术共享与提升，借助社区的力量还可以持续探索该方案在更多领域上的可能。

最后诚邀大家试用我们的商业化产品，并加入我们的钉钉群（开源群：102565007776，商业化群：35568145），共同提升 Go 应用监控与服务治理能力。通过群策群力，我们相信能为 Golang 开发者社区带来更加优质的云原生体验。