Gin Middleware

⚠️

The Traceway Go SDK is no longer the recommended way to integrate with Traceway. For new projects, instrument with OpenTelemetry — it works across languages and Traceway natively ingests OTLP. The Go SDK is still supported, but new features land in the OTel path first.

The tracewaygin package provides middleware for the Gin (opens in a new tab) web framework. It automatically creates a trace for each request, captures panics, and detects errors from Gin's error chain.

Installation

go get go.tracewayapp.com
go get go.tracewayapp.com/tracewaygin

Basic Setup

package main
 
import (
    "github.com/gin-gonic/gin"
    tracewaygin "go.tracewayapp.com/tracewaygin"
)
 
func main() {
    router := gin.Default()
 
    // Add Traceway middleware (must be before routes)
    router.Use(tracewaygin.New(
        "your-token@http://localhost:8082/api/report",
    ))
 
    router.GET("/api/users", getUsers)
    router.POST("/api/users", createUser)
 
    router.Run(":8080")
}

New returns a gin.HandlerFunc and calls traceway.Init internally — do not call Init separately.

What Gets Captured

The middleware automatically captures for every request:

Data	Description
Endpoint	HTTP method + route template (e.g., `GET /api/users/:id`)
Duration	Request processing time
Status Code	HTTP response status
Body Size	Response body size in bytes
Client IP	From Gin's `ClientIP()`
Panics	Recovered and captured with full stack trace
Gin Errors	Errors added via `c.Error()`

Error Detection

A request is considered an error when any of these are true:

A panic occurred during handler execution
Gin context errors exist (c.Errors is non-empty)
The response status code is >= 500

Error traces use the error sample rate for sampling decisions.

Panic Recovery

When a panic occurs, the middleware:

Recovers the panic
Captures the full stack trace as an issue
Either re-panics (default, WithRepanic(true)) or calls c.AbortWithStatus(500)

func riskyHandler(c *gin.Context) {
    panic("something went wrong")
    // Stack trace is captured, linked to this request's trace
}

Gin Error Chain

Errors added via c.Error() are captured as separate issues:

func handler(c *gin.Context) {
    if err := doSomething(); err != nil {
        c.Error(err) // Captured as an issue
        c.AbortWithStatus(500)
        return
    }
}

If the error wraps a StackTraceError (from traceway.NewStackTraceErrorf), the embedded stack frames are used. Otherwise, the error type and message are recorded.

Connection package

The connection page in the sidebar will have your projects unique API key and the integration instructions.

Next Steps

Configuration — All options including route filtering and passthrough settings
Error Recording — Control what request data is captured on errors

Error Recording