企业官网建设流程全解析

• 可观测性
• 后端

本篇基于仓库中的 gorilla/mux 快速上手文档（docs-content/getting-started/4_server/1_go/mux.md），完整讲清如何在基于 gorilla/mux 的 Go 后端服务中接入 Highlight：安装 Go SDK、初始化采集客户端、挂载官方 middleware、显式上报自定义错误，并在控制台的 Errors / Logs / Traces 门户验证数据上报。同时结合 sdk/highlight-go 的源码实现，解释 middleware 在每次请求中实际做了哪些事（上下文提取、span 生成、panic 恢复），帮助你理解每一步配置背后的原理。

文档定位：mux.md 在 Highlight 文档体系中的角色

mux.md 的 frontmatter 声明了它属于 Go 服务端接入系列的quickstart页面，正文仅有一行<QuickStart content={quickStartContent["server"]["go"]["mux"]}/>。这个 React 组件的实际内容定义在 mux.tsx 中，由文档站点渲染展开。该条目的products字段声明了本接入方式覆盖的三类能力：

products: ['Errors', 'Logs', 'Traces']

也就是说，按本指南配置后，一个 gorilla/mux 服务同时获得三件事：

• Errors：HTTP 处理链路中的错误与 panic 自动上报；
• Traces：每个 HTTP 请求生成一个后端 trace；
• Logs：应用日志经 OTLP 通道进入 Highlight 日志门户。

同一 Go 系列下还有 chi、echo、fiber、gin、gorm、gqlgen、logrus 以及 手动接入 等变体，它们共享同一套 SDK 初始化步骤，只是 middleware 或上报方式不同。入口文档见 1_go/1_overview.md。

第 1 步：前端初始化（可选）

快速上手内容的第一个步骤是可选的前端配置说明：如果你的应用前端已经在使用 Highlight（如 React SDK），需要确保前端已正确初始化，并且前后端之间完成了会话映射配置。映射的原理与操作步骤见 docs-content/getting-started/2_frontend-backend-mapping.md。

完成这一步后，前端会话中的用户操作可以与后端错误、trace 关联到同一个会话视图中；纯后端服务可以跳过此步，直接从安装 SDK 开始。

第 2 步：安装 Highlight Go SDK

在 Go 模块目录下执行：

go get -u github.com/highlight/highlight/sdk/highlight-go

该命令安装 Highlight 官方 Go SDK。仓库中 sdk/highlight-go 即为该包的源码；此外仓库还提供了各框架的 middleware 子包，gorilla/mux 对应的就是 sdk/highlight-go/middleware/gorillamux/middleware.go。

仓库内的 e2e/go 目录包含一个基于 Echo 和 Fiber 的端到端示例服务（e2e/go/echo.go、e2e/go/fiber.go），可作为本地联调时验证数据是否上报到 Highlight 的参考项目。

第 3 步：初始化 Highlight Go SDK

在main函数中设置 Project ID 并启动 SDK：

import ( "github.com/highlight/highlight/sdk/highlight-go" ) func main() { // ... highlight.SetProjectID("<YOUR_PROJECT_ID>") highlight.Start( highlight.WithServiceName("my-app"), highlight.WithServiceVersion("git-sha"), ) defer highlight.Stop() // ... }

各部分的作用，可对照 highlight.go 的源码逐条确认：

• highlight.SetProjectID("<YOUR_PROJECT_ID>")：Project ID 是 Highlight 控制台里每个项目的唯一标识。源码中它存储在包级config结构体（见 highlight.go 的projectID字段）。设置它之后，Highlight 才能把错误归属到具体项目，并且能够记录与前端会话无关的后台任务和进程产生的错误——这正是纯后端接入的关键。
• highlight.Start(...)：启动采集服务。从源码（highlight.go）看，Start会先依次应用传入的所有Option写入全局配置，然后调用StartOTLP()创建基于 OTLP 的 exporter；之后进入started状态并启动一个 goroutine，监听SIGABRT/SIGTERM/SIGINT信号、中断通道以及传入 context 的取消，一旦触发就执行shutdown()冲刷并关闭 OTLP 通道。StartWithContext是它的 context 版本，允许通过取消自己的 context 来终止 Highlight worker。重复调用Start是幂等的：若状态已为started则直接返回。
• defer highlight.Stop()：程序退出时冲刷并关闭 SDK，确保缓冲的数据被发送出去（见 Stop 的实现：向interruptChan发送信号并执行shutdown）。

SDK 支持的配置选项

除文档示例中的WithServiceName/WithServiceVersion外，highlight.go 中定义的完整选项集合如下：

另外两个全局函数值得注意（见 highlight.go）：

• SetOTLPEndpoint(url)：覆盖默认的 OTLP 上报地址（默认值为OTLPDefaultEndpoint），注释中给出的格式为https://otel.highlight.io:4318这样的根 HTTP 地址。使用自部署 Highlight 或私有网关时需要调整它。
• SetDebugMode(logger)：注入一个实现Error/Errorf的 logger，用于查看 SDK 自身的错误输出；默认是空实现deadLog。

第 4 步：挂载 Highlight 的 gorilla/mux middleware

gorilla/mux 的接入核心只需两行代码：

import ( highlightGorillaMux "github.com/highlight/highlight/sdk/highlight-go/middleware/gorillamux" ) func main() { // ... r := mux.NewRouter() r.Use(highlightGorillaMux.Middleware) // ... }

r.Use是 gorilla/mux 注册全局中间件的标准方式，highlightGorillaMux.Middleware是符合func(http.Handler) http.Handler签名的中间件函数，注册后对路由上所有 handler 生效。

middleware 的源码实现流程

Middleware的完整实现仅 30 余行（middleware.go），每个请求按如下顺序处理：

func Middleware(next http.Handler) http.Handler { middleware.CheckStatus() fn := func(w http.ResponseWriter, r *http.Request) { ctx := highlight.InterceptRequest(r) r = r.WithContext(ctx) attrs, requestName := middleware.GetRequestAttributes(r) span, ctx := highlight.StartTrace(ctx, requestName) defer highlight.EndTrace(span) defer middleware.Recoverer(span, w, r) r = r.WithContext(ctx) next.ServeHTTP(w, r) span.SetAttributes(attribute.String(highlight.SourceAttribute, "go.gorillamux")) span.SetAttributes(attrs...) } return http.HandlerFunc(fn) }

逐行拆解：

1. highlight.InterceptRequest(r)：从请求头提取上下文并注入 request 的 context。查看 InterceptRequestWithContext 的实现，它做两件事：
   • 通过 OTel 的TextMapPropagator.Extract从请求头中解析 W3C trace context（traceparent等），实现跨服务传播——如果上游（如前端 SDK 发出的请求）携带了 span 上下文，后端 trace 会挂到同一个 trace 上；
   • 若该 trace 不是 remote 的（即由本进程发起，典型场景是 Highlight 前端 SDK 同域发出的请求），则读取X-Highlight-Request头，按/拆分为两段写入 context 的ContextKeys.SessionSecureID与ContextKeys.RequestID（见 highlight.go 的定义）。这两个 ID 是后续把后端错误关联回具体前端会话的关键。
2. middleware.GetRequestAttributes(r)：从请求中派生请求的展示名（requestName）和一组 span 属性（attrs）。该函数与 echo/gin/chi/fiber 各 middleware 共享，位于 sdk/highlight-go/middleware 公共包中。
3. highlight.StartTrace(ctx, requestName)/defer highlight.EndTrace(span)：为本次请求创建一个 span，请求结束（函数返回）时关闭。这就是"每个 HTTP 请求一条后端 trace"的来源。
4. defer middleware.Recoverer(span, w, r)：在 handler 链外层注册 panic 恢复器。从源码结构看（函数名与挂载位置），它的作用是在 handler panic 时接管 panic，将其记录到 span / 上报为错误，使服务不因单次请求 panic 而崩溃——这是"错误自动上报"能力的一半来源，另一半是你在 handler 中显式调用RecordError。
5. span.SetAttributes(...)：请求处理完成后，把highlight.SourceAttribute设为"go.gorillamux"（用于在控制台区分该 trace 来自哪个框架的 SDK 接入），并补上第 2 步得到的请求属性。

需要注意的挂载顺序：r.Use中的中间件按注册顺序执行。如果应用还有其他需要包裹整个请求生命周期的中间件（如认证、限流），建议把 Highlight middleware 放在靠前的位置，以便它记录的 span 能覆盖尽可能完整的请求耗时。

第 5 步：显式上报自定义错误（可选）

除 middleware 自动捕获的 panic 外，你还可以在业务代码中主动上报任意错误：

highlight.RecordError(ctx, err, attribute.String("key", "value"))

RecordError接收三个参数：

• ctx：请求上下文。传入 middleware 注入过SessionSecureID/RequestID的 context 时，该错误会关联到对应的前端会话与请求；
• err：标准 Goerror值；
• attribute.String(...)：变长的 OTel attribute，用于附加自定义键值对，便于在错误详情页过滤与分组。

文档给出的验证示例是一个故意抛错的 handler：

func TestErrorHandler(w http.ResponseWriter, r *http.Request) { highlight.RecordError(r.Context(), errors.New("a test error is being thrown!")) }

部署后调用一次该路由，就能在错误门户看到这条a test error is being thrown!记录，用于验证端到端链路是否打通。

第 6 步：验证数据是否上报

快速上手内容的最后三步都是验证步骤，分别对应三类产品：

1. 验证错误（Errors）：触发上面TestErrorHandler这类上报路径，访问 Highlight 控制台的错误（errors）门户，确认后端错误被记录下来。
2. 验证日志（Logs）：访问控制台的日志（logs）门户，确认后端日志正在流入。日志的接入方式见 Go 系列概览（1_go/1_overview.md）中的 logging 部分；mux 页面的日志能力依赖 SDK 基于 OTLP 的通道（Go SDK 的日志导出同样走 OTLP，可用SetOTLPEndpoint调整目的地）。
3. 验证后端 trace（Traces）：访问控制台的 trace（traces）门户，确认后端 trace 正在流入。正常情况下你会看到以请求名命名的 span，source属性为go.gorillamux；如果前端也完成了接入与映射，同一次用户交互的前端会话操作会出现在同一视图里。

小结与延伸阅读

回到本文开头的问题：一个 gorilla/mux 服务接入 Highlight 的完整动作只有四件事——go get安装 SDK、SetProjectID+Start初始化、r.Use(highlightGorillaMux.Middleware)挂载中间件、按需RecordError显式上报。数据通路统一收敛到 OTLP：错误与 trace 由 SDK 的 OTLP exporter 发送，SetOTLPEndpoint可改写目标端点，WithSamplingRate/WithSamplingRateMap控制采样。

如需进一步深入，可在仓库中继续查看：

• sdk/highlight-go/middleware/gorillamux/middleware.go：gorilla/mux middleware 完整实现；
• sdk/highlight-go/highlight.go：SDK 核心（配置、生命周期、请求上下文提取）；
• docs-content/sdk/go.md：Go SDK 的完整 API 参考；
• e2e/go/fiber.go：仓库内置的 Go 端到端示例服务（Fiber 版），可仿照其结构为 mux 搭建本地验证环境。

• 可观测性
• 后端