FastHTTP 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 tracewayfasthttp package provides middleware for the FastHTTP (opens in a new tab) server. It automatically creates a trace for each request, captures panics, and detects client IP addresses.

Installation

go get go.tracewayapp.com
go get go.tracewayapp.com/tracewayfasthttp

Basic Setup

package main
 
import (
    "github.com/valyala/fasthttp"
    tracewayfasthttp "go.tracewayapp.com/tracewayfasthttp"
)
 
func main() {
    handler := func(ctx *fasthttp.RequestCtx) {
        ctx.SetStatusCode(200)
        ctx.SetBodyString("Hello, World!")
    }
 
    // Wrap with Traceway middleware
    tracedHandler := tracewayfasthttp.New(
        "your-token@http://localhost:8082/api/report",
    )(handler)
 
    fasthttp.ListenAndServe(":8080", tracedHandler)
}

New returns func(fasthttp.RequestHandler) fasthttp.RequestHandler 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 + URL path (e.g., `GET /api/users`)
Duration	Request processing time
Status Code	HTTP response status
Body Size	Response body size in bytes
Client IP	Detected from headers or connection
Panics	Recovered and captured with full stack trace

Client IP Detection

Client IP is resolved in this order:

X-Forwarded-For header (first IP in the list)
X-Real-IP header
RemoteAddr from the connection

Error Detection

A request is considered an error when:

A panic occurs during handler execution
The response status code is >= 500

Error traces use the error sample rate for sampling decisions.

Panic Handling

When a panic occurs, the middleware:

Recovers the panic
Captures the full stack trace as an issue
Either re-panics (default, WithRepanic(true)) or responds with 500

Context Access

Access Traceway context from within your handlers:

func handler(ctx *fasthttp.RequestCtx) {
    // Get attributes for this request
    attributes := tracewayfasthttp.GetAttributesFromCtx(ctx)
    attributes.SetTag("user_id", "123")
 
    // Get trace context
    trace := tracewayfasthttp.GetTraceFromCtx(ctx)
}

Context is stored in FastHTTP's UserValue store, not in Go's standard context.Context.

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 filtering and passthrough settings
Error Recording — Control what request data is captured on errors

Error Recording Error Recording