免去繁琐的手动埋点，Gin 框架可观测性最佳实践

阿里云云原生2025-03-28 19:06

作者：牧思

背景

在云原生时代的今天，Golang 编程语言越来越成为开发者们的首选，而对于 Golang 开发者来说，最著名的 Golang Web 框架莫过于 Gin [ 1] 框架了，Gin 框架作为 Golang 编程语言官方的推荐框架 [ 2] ，其提供了丰富的路由与中间件功能，使得 Golang 开发者可以轻松地构建复杂的 Web 应用。对于如此重要的 Web 框架，如何去快速而全面地对 Gin 应用进行监控成为了一大难题，本文将着重介绍 Gin 框架官方推荐的几种可观测性方案并进行对比，从而得出 Gin 框架可观测性的最佳实践。

观测方案一览

Gin 官方提供了丰富的插件来帮助开发者快速地搭建 Web 应用，在官方提供的插件列表 [ 3] 中，提供了对 OpenTelemetry 的几种支持方案，分别是 SDK 手动埋点方案 [ 4] ，编译时注入方案 [ 5] ，以及 eBPF 方案 [6 ] ，下面分别来对官方推荐的三种观测方案进行实践：

前置准备

  1. 首先使用 Gin 框架编写一个简单的 Golang 应用：
go 复制代码 
package main

import (
        "io"
        "log"
        "net/http"
        "time"

        "github.com/gin-gonic/gin"
)

func main() {
        r := gin.Default()
        r.GET("/hello-gin", func(c *gin.Context) {
                c.String(http.StatusOK, "hello\n")
        })
        go func() {
                _ = r.Run()
        }()

        // give time for auto-instrumentation to start up
        time.Sleep(5 * time.Second)
        for {
          resp, err := http.Get("http://localhost:8080/hello-gin")
          if err != nil {
                  log.Fatal(err)
          }
          body, err := io.ReadAll(resp.Body)
          if err != nil {
                  log.Fatal(err)
          }

          log.Printf("Body: %s\n", string(body))
          _ = resp.Body.Close()

          // give time for auto-instrumentation to report signal
          time.Sleep(5 * time.Second)
        }
}
  1. 根据文档 [ 7] 快速拉起 OpenTelemetry 的各种服务端依赖，比如 OpenTelemetry Collector，Jaeger，Prometheus 等等。

手动埋点

手动埋点方案即是利用了 Gin 框架的 Middleware 机制，在 Gin 的请求处理过程中为本次请求生成 span，我们需要基于以上代码进行改造：

scss 复制代码 
const (
  SERVICE_NAME       = ""
  SERVICE_VERSION    = ""
  DEPLOY_ENVIRONMENT = ""
  HTTP_ENDPOINT      = ""
  HTTP_URL_PATH      = ""
)

// 设置应用资源
func newResource(ctx context.Context) *resource.Resource {
  hostName, _ := os.Hostname()

  r, err := resource.New(
    ctx,
    resource.WithFromEnv(),
    resource.WithProcess(),
    resource.WithTelemetrySDK(),
    resource.WithHost(),
    resource.WithAttributes(
      semconv.ServiceNameKey.String(SERVICE_NAME), // 应用名
      semconv.ServiceVersionKey.String(SERVICE_VERSION), // 应用版本
      semconv.DeploymentEnvironmentKey.String(DEPLOY_ENVIRONMENT), // 部署环境
      semconv.HostNameKey.String(hostName), // 主机名
    ),
  )

  if err != nil {
    log.Fatalf("%s: %v", "Failed to create OpenTelemetry resource", err)
  }
  return r
}

func newHTTPExporterAndSpanProcessor(ctx context.Context) (*otlptrace.Exporter, sdktrace.SpanProcessor) {

  traceExporter, err := otlptrace.New(ctx, otlptracehttp.NewClient(
    otlptracehttp.WithEndpoint(HTTP_ENDPOINT),
    otlptracehttp.WithURLPath(HTTP_URL_PATH),
    otlptracehttp.WithInsecure(),
    otlptracehttp.WithCompression(1)))

  if err != nil {
    log.Fatalf("%s: %v", "Failed to create the OpenTelemetry trace exporter", err)
  }

  batchSpanProcessor := sdktrace.NewBatchSpanProcessor(traceExporter)

  return traceExporter, batchSpanProcessor
}

// InitOpenTelemetry OpenTelemetry 初始化方法
func InitOpenTelemetry() func() {
  ctx := context.Background()

  var traceExporter *otlptrace.Exporter
  var batchSpanProcessor sdktrace.SpanProcessor

  traceExporter, batchSpanProcessor = newHTTPExporterAndSpanProcessor(ctx)

  otelResource := newResource(ctx)

  traceProvider := sdktrace.NewTracerProvider(
    sdktrace.WithSampler(sdktrace.AlwaysSample()),
    sdktrace.WithResource(otelResource),
    sdktrace.WithSpanProcessor(batchSpanProcessor))

  otel.SetTracerProvider(traceProvider)
  otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(propagation.TraceContext{}, propagation.Baggage{}))

  return func() {
    cxt, cancel := context.WithTimeout(ctx, time.Second)
    defer cancel()
    if err := traceExporter.Shutdown(cxt); err != nil {
      otel.Handle(err)
    }
  }
}

func main() {
    r := gin.Default()
    // 初始化您的OpenTelemetry
    tp, err := InitOpenTelemetry()
  if err != nil {
    log.Fatal(err)
  }
  defer func() {
    if err := tp.Shutdown(context.Background()); err != nil {
      log.Printf("Error shutting down tracer provider: %v", err)
    }
  }()
    // 添加gin的OpenTelemetry中间件实现
    r.Use(otelgin.Middleware("my-server"))
    r.GET("/hello-gin", func(c *gin.Context) {
        c.String(http.StatusOK, "hello\n")
    })
}

通过在代码里面对 Gin 服务添加 OpenTelemetry 中间件，可以有效地收集到 Gin 应用本身的调用链路信息：

可以看到，手动接入的方案需要对代码进行比较大的改造，需要去手动引入依赖，初始化 SDK，并手动注入 middleware，此外，该方案只能收集到 Gin 应用本身的链路信息，对于 Gin 的上游和下游应用也需要进行代码的改造才能将整个链路进行打通和串联。

编译时注入自动埋点

除了手动埋点方案，官方还推荐了编译时自动注入方案来实现在零代码修改的观测方案，用户可以参考阿里巴巴开源的编译时自动插桩项目 [ 8] 对上述实例程序进行插桩：

step 1：下载 Golang Agent 二进制包

首先，可以进入主页 [ 9] 下载最新版本的 Golang Agent 二进制包。

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

在拥有了 Golang Agent 的二进制包后，即可使用该二进制包代替 go build 编译 Golang 应用的二进制程序。

go 复制代码 
otel-linux-amd64 go build .

在执行上述命令后，即可在对应应用的根目录下找到具有可观测能力的 Golang 二进制程序。

step 3：配置上报端点，运行二进制程序

最后，通过文档 [ 10] 配置观测数据的上报端点，并且启动上一步中编译出来的具有可观测能力的 Golang 二进制程序：

可以看到，编译出来的二进制 Golang 程序可以完整地展示出应用的调用链路。

除了链路，编译出来的二进制 Golang 程序还可以有效地收集 Gin 应用的运行时指标，比如 Gin 应用的调用耗时，GC 次数，内存申请次数等等：

eBPF 自动埋点

官方提供的最后一种 Gin 应用的观测办法是通过 OpenTelemetry 的 eBPF 方案进行自动埋点，eBPF 方式只需要在部署应用时在应用进程命名空间下添加一个特权级的 Sidecar 容器，特权级的 Sidecar 容器会自动捕捉应用容器产生的观测数据，并且进行上报。

我们还是对第一步中使用的简易 Golang 应用进行观测，在 Kubernetes 环境中部署以下 yaml：

yaml 复制代码 
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app.kubernetes.io/name: emoji
    app.kubernetes.io/part-of: emojivoto
    app.kubernetes.io/version: v11
  name: emoji
  namespace: emojivoto
spec:
  progressDeadlineSeconds: 600
  replicas: 1
  revisionHistoryLimit: 10
  selector:
    matchLabels:
      app: emoji-svc
      version: v11
  template:
    metadata:
      labels:
        app: emoji-svc
        version: v11
    spec:
      containers:
        - env:
            - name: HTTP
              value: '8080'
          image: 'registry.cn-hangzhou.aliyuncs.com/private-mesh/ginotel:latest'
          imagePullPolicy: Always
          name: emoji-svc
          ports:
            - containerPort: 8080
              name: grpc
              protocol: TCP
          resources:
            requests:
              cpu: 100m
          terminationMessagePath: /dev/termination-log
          terminationMessagePolicy: File
        - env:
            - name: OTEL_GO_AUTO_TARGET_EXE
              value: /usr/local/bin/app
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: 'http://jaeger.default.svc:4318'
            - name: OTEL_SERVICE_NAME
              value: emojivoto-emoji
          image: >-
            ghcr.io/open-telemetry/opentelemetry-go-instrumentation/autoinstrumentation-go:v0.19.0-alpha
          imagePullPolicy: IfNotPresent
          name: emojivoto-emoji-instrumentation
          resources: {}
          securityContext:
            privileged: true
            runAsUser: 0
          terminationMessagePath: /dev/termination-log
          terminationMessagePolicy: File
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      shareProcessNamespace: true
      terminationGracePeriodSeconds: 0

Gin 应用产生的观测数据将会被自动地收集并上报至 jaeger 中：

eBPF 方案看起来非常的美好，但是实际使用时却有着各种限制，比如其对于 Golang 的小版本非常的敏感，demo 中的应用，如果我们使用 Go 1.23.4 版本（升级 1 个小版本）来进行编译，eBPF 就将因为 Golang 的版本不匹配而无法收集到任何观测数据：

此外，eBPF 方案还有其他较多的限制，比如 client 传递的 HTTP Header 不能超过 8 个，又比如 eBPF 对操作系统的内核版本的要求较高等等，具体可以参照这篇文章。

观测方案对比

总的来说，手动埋点的自由度更高，但是接入和维护的成本也最高，适合技术能力强的用户自己完全控制。eBPF 自动埋点方案接入成本最低，但是随之而来的是性能的开销以及使用场景的各种限制。而编译时注入自动埋点的方案相对来说解决了前两种方案的各种问题，在降低了用户接入维护成本的同时也解决了插桩的性能，安全性等问题，某种程度上是目前最适合客户的 Gin 应用观测方案！

总结和展望

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

我们已经将这项创新方案开源，并成功捐赠给 OpenTelemetry 社区 [ 11] 。开源不仅促进技术共享与提升，借助社区的力量还可以持续探索该方案在更多领域上的可能。

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

相关链接：

1\] Gin *[github.com/gin-gonic/g...](https://link.juejin.cn?target=https%3A%2F%2Fgithub.com%2Fgin-gonic%2Fgin "https://github.com/gin-gonic/gin")* \[2\] 推荐框架 *[go.dev/doc/tutoria...](https://link.juejin.cn?target=https%3A%2F%2Fgo.dev%2Fdoc%2Ftutorial%2Fweb-service-gin "https://go.dev/doc/tutorial/web-service-gin")* \[3\] 插件列表 *[github.com/gin-gonic/c...](https://link.juejin.cn?target=https%3A%2F%2Fgithub.com%2Fgin-gonic%2Fcontrib "https://github.com/gin-gonic/contrib")* \[4\] SDK 手动埋点方案 *[github.com/open-teleme...](https://link.juejin.cn?target=https%3A%2F%2Fgithub.com%2Fopen-telemetry%2Fopentelemetry-go-contrib%2Ftree%2Fmain%2Finstrumentation%2Fgithub.com%2Fgin-gonic%2Fgin%2Fotelgin "https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/instrumentation/github.com/gin-gonic/gin/otelgin")* \[5\] 编译时注入方案 *[github.com/alibaba/ope...](https://link.juejin.cn?target=https%3A%2F%2Fgithub.com%2Falibaba%2Fopentelemetry-go-auto-instrumentation "https://github.com/alibaba/opentelemetry-go-auto-instrumentation")* \[6\] eBPF 方案 *[github.com/open-teleme...](https://link.juejin.cn?target=https%3A%2F%2Fgithub.com%2Fopen-telemetry%2Fopentelemetry-go-instrumentation "https://github.com/open-telemetry/opentelemetry-go-instrumentation")* \[7\] 文档 *[opentelemetry.io/docs/demo/k...](https://link.juejin.cn?target=https%3A%2F%2Fopentelemetry.io%2Fdocs%2Fdemo%2Fkubernetes-deployment%2F "https://opentelemetry.io/docs/demo/kubernetes-deployment/")* \[8\] 编译时自动插桩项目 *[github.com/alibaba/ope...](https://link.juejin.cn?target=https%3A%2F%2Fgithub.com%2Falibaba%2Fopentelemetry-go-auto-instrumentation "https://github.com/alibaba/opentelemetry-go-auto-instrumentation")* \[9\] 主页 *[github.com/alibaba/ope...](https://link.juejin.cn?target=https%3A%2F%2Fgithub.com%2Falibaba%2Fopentelemetry-go-auto-instrumentation "https://github.com/alibaba/opentelemetry-go-auto-instrumentation")* \[10\] 文档 *[opentelemetry.io/docs/specs/...](https://link.juejin.cn?target=https%3A%2F%2Fopentelemetry.io%2Fdocs%2Fspecs%2Fotel%2Fconfiguration%2Fsdk-environment-variables%2F "https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/")* \[11\] OpenTelemetry 社区 *[github.com/open-teleme...](https://link.juejin.cn?target=https%3A%2F%2Fgithub.com%2Fopen-telemetry%2Fopentelemetry-go-compile-instrumentation "https://github.com/open-telemetry/opentelemetry-go-compile-instrumentation")*

相关推荐
BLEACH－heiqiyihu14 分钟前
k8s-Pod生命周期
云原生·容器·kubernetes
AKAMAI6 小时前
迎难而上驾驭Kubernetes
云原生·kubernetes·云计算
玄明Hanko6 小时前
从厨房到云端：从预制菜到云原生
云原生
阿里云云原生7 小时前
利用通义灵码和魔搭 Notebook 环境快速搭建一个 AIGC 应用 | 视频课
云原生·通义灵码
东风微鸣8 小时前
向商界大佬一样管理技术工作 - 以团队换将+技术重构为例
docker·云原生·kubernetes·可观察性
孔令飞8 小时前
如何在 Go 中实现各种类型的链表？
人工智能·云原生·go
repetitiononeoneday21 小时前
云原生课程-Docker
云原生
KubeSphere 云原生21 小时前
云原生周刊：Kubernetes v1.33 正式发布
云原生·容器·kubernetes
南 阳21 小时前
从微服务到AI服务：Nacos 3.0如何重构下一代动态治理体系？
人工智能·微服务·云原生·重构
热门推荐
01KGG转MP3工具|非KGM文件|解密音频02从零安装 LLaMA-Factory 微调 Qwen 大模型成功及所有的坑03西电B测-计算机网络综合实验(含验收问题)04YOLOv8入门 | 重要性能衡量指标、训练结果评价及分析及影响mAP的因素【发论文关注的指标】05Coze扣子平台完整体验和实践（附国内和国际版对比）06DeepSeek各版本说明与优缺点分析07【VIsion Master】机器视觉软件二次开发（C#版本）学习笔记08yolov8，yolo11，yolo12 服务器训练到部署全流程 笔记09我决定放弃搞 Java 了10Python基于Flask的豆瓣电影数据分析可视化系统（附源码，文档说明）