在 Fiber v3 项目中优雅地集成 Sentry-Go 中间件

This content originally appeared on DEV Community and was authored by Truman

本文将介绍如何在使用 Go 1.24.3 和 Fiber v3 的项目中，使用 Sentry-Go v0.34.1 集成错误监控功能，并通过自定义 sentryfiber 中间件支持 Fiber v3，增加了灵活的路径跳过配置 (SkipPaths)。

技术选型

Go 版本：1.24.3
Fiber 版本：v3
Sentry-Go 版本：0.34.1

Sentry 官方的 sentryfiber 中间件目前只支持 Fiber v2，考虑到我们项目已经升级至 Fiber v3，因此需要进行适配并重写相关中间件。

自定义中间件功能概述

我们重写的中间件新增了以下重要功能：

兼容 Fiber v3：确保所有 API 与 Fiber v3 兼容。
SkipPaths 配置：通过路径配置来忽略某些请求，避免冗余或不必要的日志上报。
自定义选项：支持如 Repanic、WaitForDelivery 和 Timeout 等常用配置，提供灵活的集成体验。

实现方式

以下为关键实现代码：

type Options struct {
    Repanic         bool
    WaitForDelivery bool
    Timeout         time.Duration
    SkipPaths       []string
}

func New(opts Options) fiber.Handler {
    if opts.Timeout == 0 {
        opts.Timeout = 2 * time.Second
    }
    skip := opts.SkipPaths

    return func(c fiber.Ctx) error {
        if len(skip) > 0 {
            path := c.Path()
            for _, s := range skip {
                if path == s || strings.HasPrefix(path, s) {
                    return c.Next()
                }
            }
        }

        hub := sentry.CurrentHub().Clone()
        ctxWithHub := sentry.SetHubOnContext(context.Background(), hub)
        c.SetContext(ctxWithHub)

        hub.Scope().SetRequest(toHTTPRequest(c))
        traceHeader := string(c.Get(sentry.SentryTraceHeader))
        baggageHeader := string(c.Get(sentry.SentryBaggageHeader))
        tx := sentry.StartTransaction(
            ctxWithHub,
            string(c.Method())+" "+c.Path(),
            sentry.WithOpName("http.server"),
            sentry.ContinueFromHeaders(traceHeader, baggageHeader),
        )
        hub.Scope().SetSpan(tx)
        defer tx.Finish()

        defer func() {
            if r := recover(); r != nil {
                hub.Recover(r)
                hub.Flush(opts.Timeout)
                if opts.Repanic {
                    panic(r)
                }
            }
        }()

        if err := c.Next(); err != nil {
            hub.CaptureException(err)
            return err
        }

        if opts.WaitForDelivery {
            hub.Flush(opts.Timeout)
        }
        return nil
    }
}

SkipPaths 的应用场景

通过配置 SkipPaths 可以有效避免特定路由请求的监控，比如健康检查接口：

app.Use(middle.New(middle.Options{
    Repanic:         true,
    WaitForDelivery: false,
    Timeout:         3 * time.Second,
    SkipPaths:       []string{"/health", "/metrics"},
}))

小结

本文通过对官方 sentryfiber 中间件的重写，提供了 Fiber v3 项目使用 Sentry-Go 的最佳实践，并显著提升了日志监控的灵活性和准确性。

This content originally appeared on DEV Community and was authored by Truman