可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载本篇基于仓库中的 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 服务同时获得三件事ErrorsHTTP 处理链路中的错误与 panic 自动上报Traces每个 HTTP 请求生成一个后端 traceLogs应用日志经 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 并启动 SDKimport ( 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 中定义的完整选项集合如下选项作用底层实现WithServiceName(name)设置服务名用于在控制台区分不同后端服务写入 semconvservice.name资源属性WithServiceVersion(version)设置服务版本示例中建议传 git sha写入 semconvservice.version资源属性WithEnvironment(env)设置部署环境如 production / staging写入 semconvdeployment.environment资源属性WithSamplingRate(rate)对所有 span 种类统一设置采样率填充samplingRateMapWithSamplingRateMap(rates)按trace.SpanKind分别设置采样率直接替换samplingRateMap另外两个全局函数值得注意见 highlight.goSetOTLPEndpoint(url)覆盖默认的 OTLP 上报地址默认值为OTLPDefaultEndpoint注释中给出的格式为https://otel.highlight.io:4318这样的根 HTTP 地址。使用自部署 Highlight 或私有网关时需要调整它。SetDebugMode(logger)注入一个实现Error/Errorf的 logger用于查看 SDK 自身的错误输出默认是空实现deadLog。第 4 步挂载 Highlight 的 gorilla/mux middlewaregorilla/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) }逐行拆解highlight.InterceptRequest(r)从请求头提取上下文并注入 request 的 context。查看 InterceptRequestWithContext 的实现它做两件事通过 OTel 的TextMapPropagator.Extract从请求头中解析 W3C trace contexttraceparent等实现跨服务传播——如果上游如前端 SDK 发出的请求携带了 span 上下文后端 trace 会挂到同一个 trace 上若该 trace 不是 remote 的即由本进程发起典型场景是 Highlight 前端 SDK 同域发出的请求则读取X-Highlight-Request头按/拆分为两段写入 context 的ContextKeys.SessionSecureID与ContextKeys.RequestID见 highlight.go 的定义。这两个 ID 是后续把后端错误关联回具体前端会话的关键。middleware.GetRequestAttributes(r)从请求中派生请求的展示名requestName和一组 span 属性attrs。该函数与 echo/gin/chi/fiber 各 middleware 共享位于 sdk/highlight-go/middleware 公共包中。highlight.StartTrace(ctx, requestName)/defer highlight.EndTrace(span)为本次请求创建一个 span请求结束函数返回时关闭。这就是每个 HTTP 请求一条后端 trace的来源。defer middleware.Recoverer(span, w, r)在 handler 链外层注册 panic 恢复器。从源码结构看函数名与挂载位置它的作用是在 handler panic 时接管 panic将其记录到 span / 上报为错误使服务不因单次请求 panic 而崩溃——这是错误自动上报能力的一半来源另一半是你在 handler 中显式调用RecordError。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用于附加自定义键值对便于在错误详情页过滤与分组。文档给出的验证示例是一个故意抛错的 handlerfunc 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 步验证数据是否上报快速上手内容的最后三步都是验证步骤分别对应三类产品验证错误Errors触发上面TestErrorHandler这类上报路径访问 Highlight 控制台的错误errors门户确认后端错误被记录下来。验证日志Logs访问控制台的日志logs门户确认后端日志正在流入。日志的接入方式见 Go 系列概览1_go/1_overview.md中的 logging 部分mux 页面的日志能力依赖 SDK 基于 OTLP 的通道Go SDK 的日志导出同样走 OTLP可用SetOTLPEndpoint调整目的地。验证后端 traceTraces访问控制台的 tracetraces门户确认后端 trace 正在流入。正常情况下你会看到以请求名命名的 spansource属性为go.gorillamux如果前端也完成了接入与映射同一次用户交互的前端会话操作会出现在同一视图里。小结与延伸阅读回到本文开头的问题一个 gorilla/mux 服务接入 Highlight 的完整动作只有四件事——go get安装 SDK、SetProjectIDStart初始化、r.Use(highlightGorillaMux.Middleware)挂载中间件、按需RecordError显式上报。数据通路统一收敛到 OTLP错误与 trace 由 SDK 的 OTLP exporter 发送SetOTLPEndpoint可改写目标端点WithSamplingRate/WithSamplingRateMap控制采样。如需进一步深入可在仓库中继续查看sdk/highlight-go/middleware/gorillamux/middleware.gogorilla/mux middleware 完整实现sdk/highlight-go/highlight.goSDK 核心配置、生命周期、请求上下文提取docs-content/sdk/go.mdGo SDK 的完整 API 参考e2e/go/fiber.go仓库内置的 Go 端到端示例服务Fiber 版可仿照其结构为 mux 搭建本地验证环境。赞分享可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载相关推荐highlight.io PHP 后端集成指南使用 highlight/php-sdk 接入错误监控、日志与 Tracehighlight.io PHP 后端集成指南使用 highlight/php sdk 接入错误监控、日志与 Trace 本篇指南基于 highlight.i可观测性后端Highlight 实战指南:为 Go Chi 后端接入错误监控、日志与分布式追踪Highlight 实战指南:为 Go Chi 后端接入错误监控、日志与分布式追踪 本文基于 highlight 仓库中的 Go Chi 快速上手文档 docs可观测性后端Highlight Go SDK 的 gqlgen 集成指南在 Go GraphQL 后端中采集错误、日志与追踪Highlight Go SDK 的 gqlgen 集成指南在 Go GraphQL 后端中采集错误、日志与追踪 本指南基于 Highlight 仓库中 Go可观测性后端上一篇Popcorn Time数据库索引优化查询性能提升技巧下一篇Stable-Diffusion-NCNN动态形状支持如何实现任意分辨率AI图像生成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
