作者：古琦

还在为 Go 应用的可观测性改造而烦恼？还在手动埋点、修改代码、引入 SDK？还在担心埋点影响性能？

今天，我们带来一个零代码改造的解决方案——Loongsuite Go Agent，让你的 Go 应用在编译时自动获得全链路可观测能力！

痛点：传统可观测方案的“三座大山”

在微服务架构下，可观测性（Observability）已经成为应用运维的必备能力。然而据统计，传统埋点方案需要开发者花费 20-30% 的时间在监控代码上，而且非常容易出错。总结来看，传统可观测性方案往往面临三大痛点：

▍1. 代码侵入性强

传统的埋点方案需要开发者手动在业务代码中插入监控代码：

// 传统方式：需要手动埋点func handleRequest(w http.ResponseWriter, r *http.Request) {    // 手动创建 span    ctx, span := tracer.Start(r.Context(), "handleRequest")    defer span.End()    // 业务逻辑    result := doSomething()    // 手动记录属性    span.SetAttributes(attribute.String("result", result))}

这种方式存在明显问题：

• 代码污染：业务代码和监控代码混在一起
• 维护成本高：每次修改业务逻辑都要同步更新监控代码
• 容易遗漏：开发者可能忘记在某些关键路径添加埋点

▍2. 改造工作量大

对于一个已有的 Go 应用，如果要接入可观测性，通常需要：

• 引入 OpenTelemetry SDK
• 修改每个关键函数，添加埋点代码
• 配置 exporter、采样策略等
• 测试验证埋点是否正确

这个过程可能需要数天甚至数周的工作量。

▍3. 性能开销担忧

运行时埋点虽然灵活，但会带来一定的性能开销：

• 每次调用都要执行埋点逻辑
• 序列化、网络传输等操作
• 可能影响应用性能

解决方案：编译时自动插桩

Loongsuite 是阿里巴巴开源的企业级 Go 应用可观测性解决方案，已在生产环境大规模使用。Loongsuite Go Agent采用编译时插桩（Compile-Time Instrumentation）技术，在编译阶段自动注入监控代码，实现了真正的零代码改造。

▍核心优势

零代码改造

只需在 go build 前加上 otel 前缀，无需修改任何业务代码：

# 传统方式go build -o app cmd/app# 使用 Loongsuite Go Agentotel go build -o app cmd/app

就这么简单！你的应用就自动获得了全链路可观测能力。

自动化埋点

工具会自动识别你使用的框架和库，并注入相应的监控代码：

• HTTP 框架：Gin、Echo、Fiber、FastHTTP、Hertz 等
• RPC 框架：gRPC、Dubbo-go、Kitex、Kratos 等
• 数据库：database/sql、GORM、MongoDB、Elasticsearch 等
• 缓存：go-redis、redigo 等
• 日志库：Zap、Logrus、Slog、Zerolog 等
• AI 框架：LangChain、Ollama等
• 更多：支持 50+ 主流 Go 框架和库

性能友好

编译时插桩意味着：

• 运行时开销低：监控代码在编译时已经优化
• 无反射开销：不依赖运行时反射机制
• 生产就绪：经过大量生产环境验证

实战案例：MCP 官方 SDK 自动插桩

MCP是 Google 和 Anthropic 等公司推出的协议，用于LLM 应用与外部数据源和工具集成，在 AI 应用开发中越来越重要。最近，我们为Model Context Protocol (MCP) 官方 Go SDK 实现了自动插桩支持。

▍为什么选择 MCP？

随着 AI 应用的快速发展，越来越多的开发者使用 MCP 协议来构建 LLM 应用。然而，MCP 应用的可观测性一直是个挑战：

• 协议复杂：MCP 支持多种操作（tools/call、resources/read、prompts/get 等）
• 中间件机制：官方 SDK 提供了中间件，但用户可能不会主动使用
• 时间测量：需要准确测量请求-响应的完整时间

▍我们的解决方案

我们采用了初始化时自动注入的策略，在 NewServer 和 NewClient 创建时自动注入监控中间件，确保 100% 覆盖。

▍技术挑战

MCP 官方 SDK 提供了完善的中间件机制，但如何在不修改用户代码的情况下自动注入监控中间件，是一个技术挑战。

▍解决方案

我们采用了初始化时自动注入的策略：

// 在 NewServer 创建时自动注入监控中间件func afterNewServer(call api.CallContext, s *mcp.Server) {    if s == nil {        return    }    // 自动注入监控中间件    monitoringMiddleware := createServerMonitoringMiddleware()    s.AddReceivingMiddleware(monitoringMiddleware)}// 在 NewClient 创建时自动注入监控中间件func afterNewClient(call api.CallContext, c *mcp.Client) {    if c == nil {        return    }    // 自动注入监控中间件    monitoringMiddleware := createClientMonitoringMiddleware()    c.AddReceivingMiddleware(monitoringMiddleware)}

▍实现效果

通过这种方式，我们实现了：

1. 100% 覆盖：无论用户是否手动调用 AddReceivingMiddleware，监控中间件都会被自动注入

2. 时间测量准确：中间件在请求处理前后都能执行，可以准确测量完整的请求-响应时间

3. 自动记录关键信息：

• MCP 方法名（initialize、tools/call、resources/read 等）
• 工具名称、资源 URI、提示词名称等
• 请求参数和响应结果
• 错误信息和耗时统计

▍使用示例

用户代码完全不需要修改：

// 用户代码：创建 MCP 服务器server := mcp.NewServer(&mcp.Implementation{    Name: "my-server",    Version: "1.0.0",}, nil)// 添加工具（用户正常使用）mcp.AddTool(server, &mcp.Tool{    Name: "greet",    Description: "Say hi",}, handler)// 运行服务器server.Run(ctx, transport)

使用 otel go build 编译后，所有的 MCP 请求都会自动被监控，包括：

• 客户端调用工具（tools/call）
• 读取资源（resources/read）
• 获取提示词（prompts/get）
• 初始化连接（initialize）

技术原理：编译时插桩

▍工作流程

Loongsuite Go Agent 在编译时添加了两个关键阶段：

传统 Go 编译流程：源码解析 → 类型检查 → 语义分析 → 代码优化 → 代码生成 → 链接使用 Loongsuite Go Agent：预处理 → 插桩 → 源码解析 → 类型检查 → 语义分析 → 代码优化 → 代码生成 → 链接

1. 预处理阶段：分析依赖，选择适用的插桩规则

2. 插桩阶段：根据规则生成代码，注入到源码中

▍核心技术

• go:linkname：将插桩函数链接到目标包的命名空间
• AST 操作：修改抽象语法树，注入监控代码
• 规则驱动：通过 JSON 规则文件定义插桩行为

▍插桩方式

根据框架特性，我们支持多种插桩方式：

1. 中间件注入（如 MCP、gRPC）：在初始化时注入中间件

2. Hook 机制（如 Redis、Kafka）：利用框架的 Hook 接口

3. 直接函数插桩（如 OpenAI SDK）：在关键函数上直接插桩

4. 结构体字段注入（如 database/sql）：注入字段存储元数据

快速开始：5 分钟上手

Step 1：安装工具（1 分钟）

# Linux/MacOS（推荐）sudo curl -fsSL https://cdn.jsdelivr.net/gh/alibaba/loongsuite-go-agent@main/install.sh | sudo bash# 或手动下载wget https://github.com/alibaba/loongsuite-go-agent/releases/latest/download/otel-linux-amd64chmod +x otel-linux-amd64sudo mv otel-linux-amd64 /usr/local/bin/otel

Step 2：编译应用（1 分钟）

# 只需在 go build 前加 otel 前缀！otel go build -o app cmd/app

Step 3：配置导出（1 分钟）

# 导出到 Jaeger（开发环境）export OTEL_EXPORTER_JAEGER_ENDPOINT=http://localhost:14268/api/traces# 或导出到 OTLP（生产环境）export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

Step 4：运行应用（1 分钟）

./app

就这么简单！你的应用已经具备了全链路可观测能力！

效果展示

使用后，你可以在 Jaeger、Zipkin 或其他支持 OpenTelemetry 的可观测性平台看到：

• 完整的调用链：从 HTTP 请求到数据库查询，一目了然
• 详细的性能指标：每个操作的耗时、错误率
• 丰富的上下文信息：请求参数、响应结果、错误信息

支持的导出方式

工具支持多种导出方式，只需配置环境变量：

更多配置选项请查看官方文档：https://alibaba.github.io/loongsuite-go-agent/

▍支持的框架

Loongsuite Go Agent 支持 50+ 主流 Go 框架和库，包括：

完整列表请查看 GitHub 仓库：https://github.com/alibaba/loongsuite-go-agent

▍性能表现：生产级性能

编译时插桩带来的性能优势：

关键优势：

• 运行时开销低：监控代码在编译时已优化，无需运行时反射
• 生产验证：已在阿里巴巴等公司的大规模生产环境验证
• 性能友好：根据基准测试，插桩后的应用性能开销通常小于 3%

提示：虽然编译时间会增加，但这只在开发/构建阶段发生，不影响运行时性能！

社区与支持

▍开源地址

• GitHub：https://github.com/alibaba/loongsuite-go-agent
• 文档：https://alibaba.github.io/loongsuite-go-agent/

▍加入社区

• 钉钉群：102565007776
• GitHub Issues：反馈问题和建议
• 贡献代码：欢迎提交 PR！

对比总结

相关资源：

• GitHub：https://github.com/alibaba/loongsuite-go-agent
• 文档：https://alibaba.github.io/loongsuite-go-agent/
• 商业版：https://help.aliyun.com/zh/arms/application-monitoring/getting-started/monitoring-the-golang-applications

如果觉得有用，欢迎点击下方链接 Star ⭐ 和分享！

https://github.com/alibaba/loongsuite-go-agent