otelgin

Documentation

Index

• func Middleware(opts ...Option) gin.HandlerFunc
• func RequestID() gin.HandlerFunc
• type Option
  • func WithFilter(f func(*gin.Context) bool) Option

Functions

func Middleware

func Middleware(opts ...Option) gin.HandlerFunc

Middleware returns a Gin middleware that automatically traces HTTP requests.

The middleware:

1. Extracts W3C traceparent/tracestate from incoming request headers
2. Creates a server span named after the request URI (path + query string)
3. Records http.method, http.route, url.path, url.query, http.status_code as span attributes
4. Sets span status to Error for 4xx and 5xx responses
5. Injects trace context into response headers for distributed tracing

This middleware should be added after RequestID() if you want request IDs in traces.

Parameters:

• opts: Optional configuration options (e.g., WithFilter).

Returns:

• gin.HandlerFunc: A Gin middleware function.

Example:

r := gin.Default()
r.Use(otelgin.RequestID())
r.Use(otelgin.Middleware())

// Or with filter
r.Use(otelgin.Middleware(
    otelgin.WithFilter(func(c *gin.Context) bool {
        return c.Request.URL.Path == "/health"
    }),
))

func RequestID

func RequestID() gin.HandlerFunc

RequestID returns a Gin middleware that manages request IDs.

The middleware:

1. Reads X-Request-ID from the request header
2. If not present, generates a new UUID
3. Stores it in the context via tracing.WithRequestID()
4. Sets X-Request-ID on the response header

This enables request correlation across services and in logs. Use this before the tracing Middleware to include request IDs in spans.

Returns:

• gin.HandlerFunc: A Gin middleware function.

Example:

r := gin.Default()
r.Use(otelgin.RequestID())
r.Use(otelgin.Middleware())

Types

type Option

type Option func(*config)

Option configures the tracing middleware.

func WithFilter

func WithFilter(f func(*gin.Context) bool) Option

WithFilter sets a filter function that determines whether to skip tracing for a request. Return true to skip tracing for the request. This is useful for health check endpoints or other high-frequency endpoints that don't need tracing.

Parameters:

• f: A function that receives the gin.Context and returns true to skip tracing.

Example:

r.Use(otelgin.Middleware(
    otelgin.WithFilter(func(c *gin.Context) bool {
        // Skip tracing for health and metrics endpoints
        return c.Request.URL.Path == "/health" || c.Request.URL.Path == "/metrics"
    }),
))