Sentry - 💧 Mizu

Overview

The sentry middleware integrates with Sentry for error tracking, performance monitoring, and debugging. Use it when you need:

Error tracking
Performance monitoring
Issue management

Installation

import "github.com/go-mizu/mizu/middlewares/sentry"

Quick Start

app := mizu.New()

// Initialize Sentry
sentry.Init(sentry.Options{
    DSN: "https://key@sentry.io/project",
})

app.Use(sentry.Middleware())

Configuration

Options

Option	Type	Default	Description
`DSN`	`string`	Required	Sentry DSN
`Environment`	`string`	`""`	Environment name
`Release`	`string`	`""`	Release version
`SampleRate`	`float64`	`1.0`	Error sample rate
`TracesSampleRate`	`float64`	`0`	Performance sample rate

Examples

Basic Setup

sentry.Init(sentry.Options{
    DSN: os.Getenv("SENTRY_DSN"),
})

app.Use(sentry.Middleware())

With Environment

sentry.Init(sentry.Options{
    DSN:         os.Getenv("SENTRY_DSN"),
    Environment: os.Getenv("ENV"),
    Release:     "v1.0.0",
})

Performance Monitoring

sentry.Init(sentry.Options{
    DSN:              os.Getenv("SENTRY_DSN"),
    TracesSampleRate: 0.1, // 10% of transactions
})

Manual Error Capture

app.Get("/", func(c *mizu.Ctx) error {
    if err := doSomething(); err != nil {
        sentry.CaptureError(c, err)
        return c.JSON(500, map[string]string{"error": "Internal error"})
    }
    return c.JSON(200, data)
})

Add Context

app.Use(func(next mizu.Handler) mizu.Handler {
    return func(c *mizu.Ctx) error {
        sentry.SetUser(c, sentry.User{
            ID:    getUserID(c),
            Email: getEmail(c),
        })
        sentry.SetTag(c, "feature", "checkout")
        return next(c)
    }
})

API Reference

Functions

// Init initializes Sentry
func Init(opts Options) error

// Middleware creates Sentry middleware
func Middleware() mizu.Middleware

// CaptureError sends error to Sentry
func CaptureError(c *mizu.Ctx, err error)

// SetUser sets user context
func SetUser(c *mizu.Ctx, user User)

// SetTag sets a tag
func SetTag(c *mizu.Ctx, key, value string)

Technical Details

Architecture

The Sentry middleware is built around a lightweight error tracking system with the following components: Hub: Central management structure that handles event capture, storage, and transport. Each middleware instance creates a Hub that is stored in the request context. Event: Represents an error event with metadata including:

Event ID, timestamp, and severity level
Exception details with stack traces
HTTP request information (URL, method, headers, query strings)
User context, tags, and extra data
Runtime context (Go version, platform)

Transport: Interface for sending events to Sentry. Supports custom implementations via the Transport interface:

MockTransport: For testing, stores events in memory
HTTPTransport: Sends events to Sentry via HTTP
Custom transports can be implemented by satisfying the Transport interface

Event Capture Flow

Middleware wraps the handler with panic recovery
Hub is stored in request context for the lifetime of the request
Errors returned from handlers are automatically captured
Panics are caught, converted to events, and re-thrown
Events are processed through hooks (BeforeSend) before sending
Events are sent asynchronously via the configured transport

Stack Trace Capture

Stack traces are captured using Go’s runtime.Callers and runtime.CallersFrames:

Frames include filename, function name, line number, and absolute path
Configurable skip depth to exclude middleware internals
Frames are reversed to show most recent call first

Header Filtering

Sensitive headers are automatically filtered from request data:

Authorization
Cookie
X-Api-Key

Sampling

Events can be sampled based on SampleRate (0.0 to 1.0):

1.0 captures all events (default)
0.5 captures 50% of events
Sampling uses nanosecond precision for distribution

Context Management

The middleware uses Go’s context to store:

Hub instance (via hubKey)
User information (via userContextKey)
Tags (via tagsContextKey)
Extra data (via extraContextKey)

Best Practices

Use environment for staging/production
Set release for version tracking
Add user context for debugging
Sample transactions in production

Testing

The Sentry middleware includes comprehensive test coverage for all major features:

Test Case	Description	Expected Behavior
`TestNew`	Basic middleware initialization	Middleware processes requests successfully
`TestCaptureError`	Error capture from handler	Error event captured with correct message and level “error”
`TestCaptureMessage`	Manual message capture	Message event captured with level “info”
`TestCapturePanic`	Panic recovery	Panic captured as “fatal” level event and re-thrown
`TestEnvironmentAndRelease`	Environment and release configuration	Events include configured environment and release values
`TestTags`	Default tags configuration	Default tags applied to all events
`TestBeforeSend`	BeforeSend hook modification	Hook can modify events before sending
`TestBeforeSendDrop`	BeforeSend hook event dropping	Returning nil from hook prevents event capture
`TestRequestInfo`	HTTP request metadata capture	Event includes method, URL, query string, and headers
`TestSensitiveHeadersFiltered`	Sensitive header filtering	Authorization, Cookie, and X-Api-Key headers excluded
`TestStacktrace`	Stack trace generation	Events include stack trace with frames
`TestMockTransport`	Mock transport for testing	Events sent to custom transport
`TestHubEvents`	Hub event storage and clearing	Events can be retrieved and cleared from hub
`TestGetHub`	Hub retrieval from context	Hub accessible within request handlers
`TestSetUser`	User context setting	User information can be set on context
`TestSetTagAndExtra`	Dynamic tags and extra data	Tags and extra data can be set per request

recover - Panic recovery
otel - OpenTelemetry
logger - Request logging

​Overview

​Installation

​Quick Start

​Configuration

​Options

​Examples

​Basic Setup

​With Environment

​Performance Monitoring

​Manual Error Capture

​Add Context

​API Reference

​Functions

​Technical Details

​Architecture

​Event Capture Flow

​Stack Trace Capture

​Header Filtering

​Sampling

​Context Management

​Best Practices

​Testing

​Related Middlewares