一行代码都不改，Golang应用链路指标日志全知道！

2025-01-20

背景

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

快速开始

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的规范配置相关的上报端点，并且启动应用：

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

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

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