beego应用无法使用java apm agent，因其是go框架而java agent依赖jvm字节码增强；应通过middleware、sdk或/metrics等go原生方式集成apm，推荐opentelemetry并规范span名称、kind、状态码及采样率。
Beego 框架本身不内置 APM 能力，必须通过外部 Agent 或 SDK 集成；直接改 Beego 源码或手动埋点既不可维护，也容易破坏框架升级路径。
Beego 应用为什么不能直接用 Java APM Agent？
Beego 是 Go 语言 Web 框架，而 bee-apm、New Relic Java Agent、SkyWalking Java Agent 等都是针对 JVM 的字节码增强工具。Go 没有类加载机制，也不支持运行时字节码修改 —— 所以所有基于 javaagent 的方案对 Beego 完全无效。
- 常见错误现象：
java -javaagent:xxx.jar -jar my-beego-app启动失败，报NoClassDefFoundError或直接忽略 agent - 根本原因：Go 编译后是静态二进制，JVM 参数对它无意义
- 替代思路：必须使用 Go 原生支持的采集方式，如 HTTP 中间件、SDK 手动注入、或进程级指标暴露（如
/metrics）
Beego v2.x 推荐的 APM 集成方式
Beego v2 提供了标准的 Middleware 接口和 Controller 生命周期钩子，这是最轻量、最可控的埋点入口。不要试图 hook net/http 底层，那会绕过 Beego 的路由、参数解析和异常处理逻辑。
- 在
app.Run()前注册全局中间件：beego.InsertFilter("/*", beego.BeeApp.Handler, apmMiddleware) - 中间件中可获取：
c.Ctx.Input.URL、c.Ctx.Input.Method、c.Ctx.Input.IP()、c.Ctx.ResponseWriter.Status - 务必用
defer记录结束时间，避免 panic 导致耗时不完整：start := time.Now(); defer func() { reportTrace(c, start) }() - 避免在中间件里调用阻塞操作（如同步上报），应走异步 channel 或批量 flush
对接 OpenTelemetry 的关键配置点
OpenTelemetry 是目前 Beego 最可行的标准化接入路径，但默认配置极易踩坑。重点不是“能不能接”，而是“上报的数据是否能被后端正确解析为 Span”。
- Span 名称必须设为
c.Ctx.Input.ControllerName + "." + c.Ctx.Input.MethodName，而非固定字符串"http-server" - 必须设置
trace.SpanKindServer，否则 Jaeger / Tempo 会当成 client span 丢弃 - HTTP 状态码要写入
http.status_code属性，而不是自定义 tag；否则 Prometheus metrics 抽取失败 - 采样率别设 1.0：Beego 默认每请求都走完整生命周期，高并发下易打爆 Collector；建议用
ParentBased(TraceIDRatioBased(0.01)) - 示例关键代码片段：
span := tracer.Start(ctx, c.Ctx.Input.ControllerName+"."+c.Ctx.Input.MethodName, trace.WithSpanKind(trace.SpanKindServer))
Beego 日志与 Trace 关联的硬约束
Beego 的 logs.BeeLogger 不支持结构化字段注入，直接打日志无法自动带上 trace_id。强行 patch logger 或重写 Write 方法风险高，且 v2.1+ 版本已移除部分 hook 点。
- 安全做法：在中间件中从
span.SpanContext().TraceID().String()取值，存入c.Data["trace_id"] - 所有 Controller 中需显式调用：
c.Ctx.Input.SetData("trace_id", c.Data["trace_id"])，再透传给模板或下游服务 - 日志输出时手动拼接：
logs.Info("[trace_id:", c.GetString("trace_id"), "] user login success") - 注意：Beego 的
GetString对空值返回空字符串而非 panic，这点比直接取 map 安全
Beego 的 APM 集成难点不在“怎么加代码”，而在“加在哪、加多少、加完会不会拖慢首屏或掩盖真实瓶颈”。中间件埋点看似简单，但 Span 边界错位、属性命名不规范、日志脱钩这三类问题，占线上排查耗时的 70% 以上。
