Skip to content

The only tool you need to know what is happening and how to fix it.

feat: more docs updating for new frameworks

dduxd0bde101d3e5
diff --git a/docs/components/FrameworkPicker.jsx b/docs/components/FrameworkPicker.jsx
index 7b7a1db4..0f749552 100644
--- a/docs/components/FrameworkPicker.jsx
+++ b/docs/components/FrameworkPicker.jsx
@@ -9,6 +9,27 @@ const FRAMEWORKS = [
icon: '/gin.png',
href: '/client/gin-middleware',
},
+ {
+ value: 'go-chi',
+ label: 'Go Chi',
+ description: 'Lightweight Chi router with automatic request tracing and panic recovery.',
+ icon: '/chi.png',
+ href: '/client/chi-middleware',
+ },
+ {
+ value: 'go-fiber',
+ label: 'Go Fiber',
+ description: 'Express-inspired Fiber framework with request tracing and error capture.',
+ icon: '/fiber.svg',
+ href: '/client/fiber-middleware',
+ },
+ {
+ value: 'go-fasthttp',
+ label: 'Go FastHTTP',
+ description: 'High-performance FastHTTP server with request tracing and panic recovery.',
+ icon: '/fasthttp.png',
+ href: '/client/fasthttp-middleware',
+ },
{
value: 'go-http',
label: 'Go net/http',
diff --git a/docs/components/SdkContext.jsx b/docs/components/SdkContext.jsx
index 8c99249e..faddf14c 100644
--- a/docs/components/SdkContext.jsx
+++ b/docs/components/SdkContext.jsx
@@ -3,6 +3,9 @@ import { useRouter } from 'next/router'
export const SDK_OPTIONS = [
{ value: 'go-gin', label: 'Go Gin' },
+ { value: 'go-chi', label: 'Go Chi' },
+ { value: 'go-fiber', label: 'Go Fiber' },
+ { value: 'go-fasthttp', label: 'Go FastHTTP' },
{ value: 'go-http', label: 'Go Http' },
{ value: 'go-generic', label: 'Go Generic' },
]
diff --git a/docs/components/SdkSelector.jsx b/docs/components/SdkSelector.jsx
index 61cfd95e..e0fb8d5d 100644
--- a/docs/components/SdkSelector.jsx
+++ b/docs/components/SdkSelector.jsx
@@ -4,6 +4,9 @@ import { useSdk, SDK_OPTIONS } from './SdkContext'
const SDK_QUICK_START = {
'go-gin': '/client/gin-middleware',
+ 'go-chi': '/client/chi-middleware',
+ 'go-fiber': '/client/fiber-middleware',
+ 'go-fasthttp': '/client/fasthttp-middleware',
'go-http': '/client/http-middleware',
'go-generic': '/client/sdk',
}
diff --git a/docs/pages/client/_meta.json b/docs/pages/client/_meta.json
index baea3042..0f3661d5 100644
--- a/docs/pages/client/_meta.json
+++ b/docs/pages/client/_meta.json
@@ -6,6 +6,9 @@
"theme": { "sidebar": false, "pagination": false }
},
"gin-middleware": "Gin Middleware",
+ "chi-middleware": "Chi Middleware",
+ "fiber-middleware": "Fiber Middleware",
+ "fasthttp-middleware": "FastHTTP Middleware",
"http-middleware": "HTTP Middleware",
"sdk": "SDK Reference"
}
diff --git a/docs/pages/client/chi-middleware/_meta.json b/docs/pages/client/chi-middleware/_meta.json
new file mode 100644
index 00000000..a5183284
--- /dev/null
+++ b/docs/pages/client/chi-middleware/_meta.json
@@ -0,0 +1,5 @@
+{
+ "index": "Quick Start",
+ "configuration": { "display": "hidden" },
+ "error-recording": "Error Recording"
+}
diff --git a/docs/pages/client/chi-middleware/configuration.mdx b/docs/pages/client/chi-middleware/configuration.mdx
new file mode 100644
index 00000000..7db2c896
--- /dev/null
+++ b/docs/pages/client/chi-middleware/configuration.mdx
@@ -0,0 +1,156 @@
+# Chi Middleware Configuration
+
+## Middleware Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `WithRepanic(bool)` | Re-panic after capturing, letting upstream recovery handle it | `true` |
+| `WithIgnoredPaths(...string)` | Skip recording for specific URL paths | none |
+| `WithFilter(func(*http.Request) bool)` | Custom filter function — return `false` to skip recording | none |
+| `WithOnErrorRecording(RecordingFlag)` | What additional data to capture on errors | `0` (none) |
+
+## Passthrough Core Options
+
+These options are forwarded to the core `traceway` client:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `WithDebug(bool)` | Enable debug logging | `false` |
+| `WithVersion(string)` | Application version shown in dashboard | `""` |
+| `WithServerName(string)` | Server hostname identifier | Auto-detected |
+| `WithSampleRate(float64)` | Percentage of normal traces to record (0.0–1.0) | `1.0` |
+| `WithErrorSampleRate(float64)` | Percentage of error traces to record (0.0–1.0) | `1.0` |
+| `WithCollectionInterval(time.Duration)` | How often batched data is sent | `5s` |
+| `WithMaxCollectionFrames(int)` | Maximum frames to buffer | `12` |
+| `WithUploadTimeout(time.Duration)` | HTTP upload timeout | `2s` |
+| `WithMetricsInterval(time.Duration)` | System metrics collection interval | `30s` |
+
+## Repanic Behavior
+
+When `WithRepanic(true)` (default), the middleware re-panics after capturing the stack trace. This allows upstream recovery middleware (like Chi's `middleware.Recoverer`) to handle the panic as well.
+
+When `WithRepanic(false)`, the middleware responds with HTTP 500 and does not re-panic.
+
+## Path Filtering
+
+### WithIgnoredPaths
+
+Skip recording for specific paths:
+
+```go
+tracewaychi.New(
+ connectionString,
+ tracewaychi.WithIgnoredPaths("/health", "/ready", "/metrics"),
+)
+```
+
+Ignored paths are still served — the request passes through to your handler, but no trace is recorded.
+
+### WithFilter
+
+For dynamic filtering logic, use `WithFilter`. Return `false` to skip recording:
+
+```go
+tracewaychi.New(
+ connectionString,
+ tracewaychi.WithFilter(func(r *http.Request) bool {
+ // Skip internal service-to-service calls
+ if r.Header.Get("X-Internal") == "true" {
+ return false
+ }
+ // Skip static assets
+ if strings.HasPrefix(r.URL.Path, "/static/") {
+ return false
+ }
+ return true
+ }),
+)
+```
+
+When the filter returns `false`, the request is passed directly to your handler without any Traceway wrapping.
+
+## Complete Example
+
+```go
+package main
+
+import (
+ "net/http"
+ "time"
+
+ "github.com/go-chi/chi/v5"
+ traceway "go.tracewayapp.com"
+ tracewaychi "go.tracewayapp.com/tracewaychi"
+)
+
+func main() {
+ traceway.ConfigureAttributes(func(s *traceway.Attributes) {
+ s.SetTag("environment", "production")
+ s.SetTag("service", "user-api")
+ })
+
+ r := chi.NewRouter()
+
+ r.Use(tracewaychi.New(
+ "your-token@http://localhost:8082/api/report",
+ tracewaychi.WithVersion("1.2.3"),
+ tracewaychi.WithServerName("api-server-01"),
+ tracewaychi.WithRepanic(true),
+ tracewaychi.WithIgnoredPaths("/health", "/ready"),
+ tracewaychi.WithFilter(func(r *http.Request) bool {
+ return r.Header.Get("X-Internal") != "true"
+ }),
+ tracewaychi.WithOnErrorRecording(
+ tracewaychi.RecordingUrl | tracewaychi.RecordingQuery,
+ ),
+ tracewaychi.WithCollectionInterval(5 * time.Second),
+ tracewaychi.WithMetricsInterval(30 * time.Second),
+ ))
+
+ r.Get("/api/users/{id}", getUser)
+ http.ListenAndServe(":8080", r)
+}
+```
+
+## Configuration Recommendations
+
+### Development
+
+```go
+tracewaychi.New(
+ connectionString,
+ tracewaychi.WithDebug(true),
+ tracewaychi.WithOnErrorRecording(
+ tracewaychi.RecordingUrl |
+ tracewaychi.RecordingQuery |
+ tracewaychi.RecordingHeader |
+ tracewaychi.RecordingBody,
+ ),
+)
+```
+
+### Production
+
+```go
+tracewaychi.New(
+ connectionString,
+ tracewaychi.WithVersion(os.Getenv("APP_VERSION")),
+ tracewaychi.WithServerName(os.Getenv("HOSTNAME")),
+ tracewaychi.WithOnErrorRecording(
+ tracewaychi.RecordingUrl | tracewaychi.RecordingQuery,
+ ),
+)
+```
+
+### High-Traffic Services
+
+```go
+tracewaychi.New(
+ connectionString,
+ tracewaychi.WithSampleRate(0.1),
+ tracewaychi.WithErrorSampleRate(1.0),
+ tracewaychi.WithCollectionInterval(10 * time.Second),
+ tracewaychi.WithMaxCollectionFrames(20),
+ tracewaychi.WithMetricsInterval(60 * time.Second),
+)
+```
diff --git a/docs/pages/client/chi-middleware/error-recording.mdx b/docs/pages/client/chi-middleware/error-recording.mdx
new file mode 100644
index 00000000..78adcfd0
--- /dev/null
+++ b/docs/pages/client/chi-middleware/error-recording.mdx
@@ -0,0 +1,83 @@
+# Chi Error Recording
+
+When an exception occurs during a request, you can control what additional request data is captured alongside the stack trace.
+
+## Recording Flags
+
+Configure error recording with `WithOnErrorRecording`:
+
+```go
+tracewaychi.New(
+ connectionString,
+ tracewaychi.WithOnErrorRecording(
+ tracewaychi.RecordingUrl | tracewaychi.RecordingQuery,
+ ),
+)
+```
+
+### Available Flags
+
+| Flag | Description | Privacy Impact |
+|------|-------------|----------------|
+| `RecordingUrl` | Request URL path | Low |
+| `RecordingQuery` | Query parameters as JSON | Medium |
+| `RecordingBody` | Request body (JSON content-type only, max 64KB) | High |
+| `RecordingHeader` | Request headers as JSON | High |
+
+### Combining Flags
+
+Flags are combined with the `|` operator:
+
+```go
+// Record URL and query parameters
+tracewaychi.RecordingUrl | tracewaychi.RecordingQuery
+
+// Record everything
+tracewaychi.RecordingUrl | tracewaychi.RecordingQuery | tracewaychi.RecordingBody | tracewaychi.RecordingHeader
+```
+
+## Body Capture Details
+
+Body recording has two constraints:
+
+- **Content-Type must be `application/json`** — non-JSON bodies are not captured
+- **Maximum size is 64KB** — bodies larger than 64KB are truncated
+
+After reading the body for capture, it is **restored** so downstream handlers can still read it.
+
+## Privacy Considerations
+
+Body and header recording may capture sensitive data:
+
+- Authentication tokens in headers
+- Personal information in request bodies
+- API keys in query parameters
+
+Use minimal recording flags in production:
+
+```go
+// Production — limited data
+tracewaychi.WithOnErrorRecording(
+ tracewaychi.RecordingUrl | tracewaychi.RecordingQuery,
+)
+
+// Development — full request data
+tracewaychi.WithOnErrorRecording(
+ tracewaychi.RecordingUrl |
+ tracewaychi.RecordingQuery |
+ tracewaychi.RecordingBody |
+ tracewaychi.RecordingHeader,
+)
+```
+
+## Captured Data Format
+
+Recorded data is attached as attributes on the issue:
+
+| Attribute Key | Value |
+|---------------|-------|
+| `url` | URL path string |
+| `query` | JSON-encoded query parameters |
+| `body` | Raw request body string |
+| `headers` | JSON-encoded request headers |
+| `user agent` | User-Agent header value (always captured on error) |
diff --git a/docs/pages/client/chi-middleware/index.mdx b/docs/pages/client/chi-middleware/index.mdx
new file mode 100644
index 00000000..cb613cf0
--- /dev/null
+++ b/docs/pages/client/chi-middleware/index.mdx
@@ -0,0 +1,84 @@
+# Chi Middleware
+
+The `tracewaychi` package provides middleware for the [Chi](https://github.com/go-chi/chi) router. It automatically creates a trace for each request, captures panics, and detects client IP addresses.
+
+Chi is fully compatible with `net/http` middleware, so `tracewaychi` delegates to the `tracewayhttp` package internally while providing a Chi-specific API surface.
+
+## Installation
+
+```bash
+go get go.tracewayapp.com
+go get go.tracewayapp.com/tracewaychi
+```
+
+## Basic Setup
+
+```go
+package main
+
+import (
+ "net/http"
+
+ "github.com/go-chi/chi/v5"
+ tracewaychi "go.tracewayapp.com/tracewaychi"
+)
+
+func main() {
+ r := chi.NewRouter()
+
+ // Add Traceway middleware (must be before routes)
+ r.Use(tracewaychi.New(
+ "your-token@http://localhost:8082/api/report",
+ ))
+
+ r.Get("/api/users", getUsers)
+ r.Post("/api/users", createUser)
+
+ http.ListenAndServe(":8080", r)
+}
+```
+
+`New` returns `func(http.Handler) http.Handler` 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:
+
+1. `X-Forwarded-For` header (first IP in the list)
+2. `X-Real-IP` header
+3. `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:
+
+1. Recovers the panic
+2. Captures the full stack trace as an issue
+3. Either re-panics (default, `WithRepanic(true)`) or responds with 500
+
+## Next Steps
+
+- [Configuration](/client/chi-middleware/configuration) — All options including filtering and passthrough settings
+- [Error Recording](/client/chi-middleware/error-recording) — Control what request data is captured on errors
diff --git a/docs/pages/client/fasthttp-middleware/_meta.json b/docs/pages/client/fasthttp-middleware/_meta.json
new file mode 100644
index 00000000..a5183284
--- /dev/null
+++ b/docs/pages/client/fasthttp-middleware/_meta.json
@@ -0,0 +1,5 @@
+{
+ "index": "Quick Start",
+ "configuration": { "display": "hidden" },
+ "error-recording": "Error Recording"
+}
diff --git a/docs/pages/client/fasthttp-middleware/configuration.mdx b/docs/pages/client/fasthttp-middleware/configuration.mdx
new file mode 100644
index 00000000..12672ff9
--- /dev/null
+++ b/docs/pages/client/fasthttp-middleware/configuration.mdx
@@ -0,0 +1,163 @@
+# FastHTTP Middleware Configuration
+
+## Middleware Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `WithRepanic(bool)` | Re-panic after capturing, letting upstream recovery handle it | `true` |
+| `WithIgnoredPaths(...string)` | Skip recording for specific URL paths | none |
+| `WithFilter(func(*fasthttp.RequestCtx) bool)` | Custom filter function — return `false` to skip recording | none |
+| `WithOnErrorRecording(RecordingFlag)` | What additional data to capture on errors | `0` (none) |
+
+## Passthrough Core Options
+
+These options are forwarded to the core `traceway` client:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `WithDebug(bool)` | Enable debug logging | `false` |
+| `WithVersion(string)` | Application version shown in dashboard | `""` |
+| `WithServerName(string)` | Server hostname identifier | Auto-detected |
+| `WithSampleRate(float64)` | Percentage of normal traces to record (0.0–1.0) | `1.0` |
+| `WithErrorSampleRate(float64)` | Percentage of error traces to record (0.0–1.0) | `1.0` |
+| `WithCollectionInterval(time.Duration)` | How often batched data is sent | `5s` |
+| `WithMaxCollectionFrames(int)` | Maximum frames to buffer | `12` |
+| `WithUploadTimeout(time.Duration)` | HTTP upload timeout | `2s` |
+| `WithMetricsInterval(time.Duration)` | System metrics collection interval | `30s` |
+
+## Repanic Behavior
+
+When `WithRepanic(true)` (default), the middleware re-panics after capturing the stack trace. This allows upstream recovery handlers to handle the panic as well.
+
+When `WithRepanic(false)`, the middleware responds with HTTP 500 and does not re-panic.
+
+## Request Filtering
+
+### WithIgnoredPaths
+
+Skip recording for specific paths:
+
+```go
+tracewayfasthttp.New(
+ connectionString,
+ tracewayfasthttp.WithIgnoredPaths("/health", "/ready", "/metrics"),
+)
+```
+
+Ignored paths are still served — the request passes through to your handler, but no trace is recorded.
+
+### WithFilter
+
+For dynamic filtering logic, use `WithFilter`. Return `false` to skip recording:
+
+```go
+tracewayfasthttp.New(
+ connectionString,
+ tracewayfasthttp.WithFilter(func(ctx *fasthttp.RequestCtx) bool {
+ // Skip internal service-to-service calls
+ if string(ctx.Request.Header.Peek("X-Internal")) == "true" {
+ return false
+ }
+ // Skip static assets
+ if strings.HasPrefix(string(ctx.Path()), "/static/") {
+ return false
+ }
+ return true
+ }),
+)
+```
+
+When the filter returns `false`, the request is passed directly to your handler without any Traceway wrapping.
+
+## Complete Example
+
+```go
+package main
+
+import (
+ "strings"
+ "time"
+
+ "github.com/valyala/fasthttp"
+ traceway "go.tracewayapp.com"
+ tracewayfasthttp "go.tracewayapp.com/tracewayfasthttp"
+)
+
+func main() {
+ traceway.ConfigureAttributes(func(s *traceway.Attributes) {
+ s.SetTag("environment", "production")
+ s.SetTag("service", "user-api")
+ })
+
+ handler := func(ctx *fasthttp.RequestCtx) {
+ switch string(ctx.Path()) {
+ case "/api/users":
+ ctx.SetStatusCode(200)
+ ctx.SetBodyString(`{"users": []}`)
+ default:
+ ctx.SetStatusCode(404)
+ }
+ }
+
+ tracedHandler := tracewayfasthttp.New(
+ "your-token@http://localhost:8082/api/report",
+ tracewayfasthttp.WithVersion("1.2.3"),
+ tracewayfasthttp.WithServerName("api-server-01"),
+ tracewayfasthttp.WithRepanic(true),
+ tracewayfasthttp.WithIgnoredPaths("/health", "/ready"),
+ tracewayfasthttp.WithFilter(func(ctx *fasthttp.RequestCtx) bool {
+ return string(ctx.Request.Header.Peek("X-Internal")) != "true"
+ }),
+ tracewayfasthttp.WithOnErrorRecording(
+ tracewayfasthttp.RecordingUrl | tracewayfasthttp.RecordingQuery,
+ ),
+ tracewayfasthttp.WithCollectionInterval(5 * time.Second),
+ tracewayfasthttp.WithMetricsInterval(30 * time.Second),
+ )(handler)
+
+ fasthttp.ListenAndServe(":8080", tracedHandler)
+}
+```
+
+## Configuration Recommendations
+
+### Development
+
+```go
+tracewayfasthttp.New(
+ connectionString,
+ tracewayfasthttp.WithDebug(true),
+ tracewayfasthttp.WithOnErrorRecording(
+ tracewayfasthttp.RecordingUrl |
+ tracewayfasthttp.RecordingQuery |
+ tracewayfasthttp.RecordingHeader |
+ tracewayfasthttp.RecordingBody,
+ ),
+)
+```
+
+### Production
+
+```go
+tracewayfasthttp.New(
+ connectionString,
+ tracewayfasthttp.WithVersion(os.Getenv("APP_VERSION")),
+ tracewayfasthttp.WithServerName(os.Getenv("HOSTNAME")),
+ tracewayfasthttp.WithOnErrorRecording(
+ tracewayfasthttp.RecordingUrl | tracewayfasthttp.RecordingQuery,
+ ),
+)
+```
+
+### High-Traffic Services
+
+```go
+tracewayfasthttp.New(
+ connectionString,
+ tracewayfasthttp.WithSampleRate(0.1),
+ tracewayfasthttp.WithErrorSampleRate(1.0),
+ tracewayfasthttp.WithCollectionInterval(10 * time.Second),
+ tracewayfasthttp.WithMaxCollectionFrames(20),
+ tracewayfasthttp.WithMetricsInterval(60 * time.Second),
+)
+```
diff --git a/docs/pages/client/fasthttp-middleware/error-recording.mdx b/docs/pages/client/fasthttp-middleware/error-recording.mdx
new file mode 100644
index 00000000..9378b942
--- /dev/null
+++ b/docs/pages/client/fasthttp-middleware/error-recording.mdx
@@ -0,0 +1,83 @@
+# FastHTTP Error Recording
+
+When an exception occurs during a request, you can control what additional request data is captured alongside the stack trace.
+
+## Recording Flags
+
+Configure error recording with `WithOnErrorRecording`:
+
+```go
+tracewayfasthttp.New(
+ connectionString,
+ tracewayfasthttp.WithOnErrorRecording(
+ tracewayfasthttp.RecordingUrl | tracewayfasthttp.RecordingQuery,
+ ),
+)
+```
+
+### Available Flags
+
+| Flag | Description | Privacy Impact |
+|------|-------------|----------------|
+| `RecordingUrl` | Request URL path | Low |
+| `RecordingQuery` | Query parameters as JSON | Medium |
+| `RecordingBody` | Request body (JSON content-type only, max 64KB) | High |
+| `RecordingHeader` | Request headers as JSON | High |
+
+### Combining Flags
+
+Flags are combined with the `|` operator:
+
+```go
+// Record URL and query parameters
+tracewayfasthttp.RecordingUrl | tracewayfasthttp.RecordingQuery
+
+// Record everything
+tracewayfasthttp.RecordingUrl | tracewayfasthttp.RecordingQuery | tracewayfasthttp.RecordingBody | tracewayfasthttp.RecordingHeader
+```
+
+## Body Capture Details
+
+Body recording has two constraints:
+
+- **Content-Type must be `application/json`** — non-JSON bodies are not captured
+- **Maximum size is 64KB** — bodies larger than 64KB are truncated
+
+After reading the body for capture, it is restored so downstream handlers can still read it.
+
+## Privacy Considerations
+
+Body and header recording may capture sensitive data:
+
+- Authentication tokens in headers
+- Personal information in request bodies
+- API keys in query parameters
+
+Use minimal recording flags in production:
+
+```go
+// Production — limited data
+tracewayfasthttp.WithOnErrorRecording(
+ tracewayfasthttp.RecordingUrl | tracewayfasthttp.RecordingQuery,
+)
+
+// Development — full request data
+tracewayfasthttp.WithOnErrorRecording(
+ tracewayfasthttp.RecordingUrl |
+ tracewayfasthttp.RecordingQuery |
+ tracewayfasthttp.RecordingBody |
+ tracewayfasthttp.RecordingHeader,
+)
+```
+
+## Captured Data Format
+
+Recorded data is attached as attributes on the issue:
+
+| Attribute Key | Value |
+|---------------|-------|
+| `url` | URL path string |
+| `query` | JSON-encoded query parameters |
+| `body` | Raw request body string |
+| `headers` | JSON-encoded request headers |
+| `user agent` | User-Agent header value (always captured on error) |
diff --git a/docs/pages/client/fasthttp-middleware/index.mdx b/docs/pages/client/fasthttp-middleware/index.mdx
new file mode 100644
index 00000000..b53f1155
--- /dev/null
+++ b/docs/pages/client/fasthttp-middleware/index.mdx
@@ -0,0 +1,97 @@
+# FastHTTP Middleware
+
+The `tracewayfasthttp` package provides middleware for the [FastHTTP](https://github.com/valyala/fasthttp) server. It automatically creates a trace for each request, captures panics, and detects client IP addresses.
+
+## Installation
+
+```bash
+go get go.tracewayapp.com
+go get go.tracewayapp.com/tracewayfasthttp
+```
+
+## Basic Setup
+
+```go
+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:
+
+1. `X-Forwarded-For` header (first IP in the list)
+2. `X-Real-IP` header
+3. `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:
+
+1. Recovers the panic
+2. Captures the full stack trace as an issue
+3. Either re-panics (default, `WithRepanic(true)`) or responds with 500
+
+## Context Access
+
+Access Traceway context from within your handlers:
+
+```go
+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`.
+
+## Next Steps
+
+- [Configuration](/client/fasthttp-middleware/configuration) — All options including filtering and passthrough settings
+- [Error Recording](/client/fasthttp-middleware/error-recording) — Control what request data is captured on errors
diff --git a/docs/pages/client/fiber-middleware/_meta.json b/docs/pages/client/fiber-middleware/_meta.json
new file mode 100644
index 00000000..a5183284
--- /dev/null
+++ b/docs/pages/client/fiber-middleware/_meta.json
@@ -0,0 +1,5 @@
+{
+ "index": "Quick Start",
+ "configuration": { "display": "hidden" },
+ "error-recording": "Error Recording"
+}
diff --git a/docs/pages/client/fiber-middleware/configuration.mdx b/docs/pages/client/fiber-middleware/configuration.mdx
new file mode 100644
index 00000000..fa5a3f8a
--- /dev/null
+++ b/docs/pages/client/fiber-middleware/configuration.mdx
@@ -0,0 +1,163 @@
+# Fiber Middleware Configuration
+
+## Middleware Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `WithRepanic(bool)` | Re-panic after capturing, letting upstream recovery handle it | `true` |
+| `WithRecordUnmatched(bool)` | Record requests for unregistered routes (404s) | `false` |
+| `WithIgnoredPaths(...string)` | Skip recording for specific route paths | none |
+| `WithFilter(func(*fiber.Ctx) bool)` | Custom filter function — return `false` to skip recording | none |
+| `WithOnErrorRecording(RecordingFlag)` | What additional data to capture on errors | `0` (none) |
+
+## Passthrough Core Options
+
+These options are forwarded to the core `traceway` client:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `WithDebug(bool)` | Enable debug logging | `false` |
+| `WithVersion(string)` | Application version shown in dashboard | `""` |
+| `WithServerName(string)` | Server hostname identifier | Auto-detected |
+| `WithSampleRate(float64)` | Percentage of normal traces to record (0.0–1.0) | `1.0` |
+| `WithErrorSampleRate(float64)` | Percentage of error traces to record (0.0–1.0) | `1.0` |
+| `WithCollectionInterval(time.Duration)` | How often batched data is sent | `5s` |
+| `WithMaxCollectionFrames(int)` | Maximum frames to buffer | `12` |
+| `WithUploadTimeout(time.Duration)` | HTTP upload timeout | `2s` |
+| `WithMetricsInterval(time.Duration)` | System metrics collection interval | `30s` |
+
+## Repanic Behavior
+
+When `WithRepanic(true)` (default), the middleware re-panics after capturing the stack trace. This allows Fiber's built-in error handler or upstream recovery middleware to handle the panic.
+
+When `WithRepanic(false)`, the middleware returns a 500 error and does not re-panic.
+
+## Route Filtering
+
+### Unmatched Routes
+
+By default, requests to unregistered routes (404s) are **not recorded**. The request is passed through but no trace is created.
+
+```go
+tracewayfiber.WithRecordUnmatched(true) // Record 404 requests
+```
+
+### Ignored Paths
+
+Skip recording for specific route paths:
+
+```go
+tracewayfiber.New(
+ connectionString,
+ tracewayfiber.WithIgnoredPaths("/health", "/ready", "/metrics"),
+)
+```
+
+Ignored paths are still served — the request passes through to your handler, but no trace is recorded.
+
+### WithFilter
+
+For dynamic filtering logic, use `WithFilter`. Return `false` to skip recording:
+
+```go
+tracewayfiber.New(
+ connectionString,
+ tracewayfiber.WithFilter(func(c *fiber.Ctx) bool {
+ // Skip internal service-to-service calls
+ if c.Get("X-Internal") == "true" {
+ return false
+ }
+ // Skip static assets
+ if strings.HasPrefix(c.Path(), "/static/") {
+ return false
+ }
+ return true
+ }),
+)
+```
+
+When the filter returns `false`, the request is passed directly to your handler without any Traceway wrapping.
+
+## Complete Example
+
+```go
+package main
+
+import (
+ "strings"
+ "time"
+
+ "github.com/gofiber/fiber/v2"
+ traceway "go.tracewayapp.com"
+ tracewayfiber "go.tracewayapp.com/tracewayfiber"
+)
+
+func main() {
+ traceway.ConfigureAttributes(func(s *traceway.Attributes) {
+ s.SetTag("environment", "production")
+ s.SetTag("service", "user-api")
+ })
+
+ app := fiber.New()
+
+ app.Use(tracewayfiber.New(
+ "your-token@http://localhost:8082/api/report",
+ tracewayfiber.WithVersion("1.2.3"),
+ tracewayfiber.WithServerName("api-server-01"),
+ tracewayfiber.WithRepanic(true),
+ tracewayfiber.WithRecordUnmatched(false),
+ tracewayfiber.WithIgnoredPaths("/health", "/ready"),
+ tracewayfiber.WithOnErrorRecording(
+ tracewayfiber.RecordingUrl | tracewayfiber.RecordingQuery,
+ ),
+ tracewayfiber.WithCollectionInterval(5 * time.Second),
+ tracewayfiber.WithMetricsInterval(30 * time.Second),
+ ))
+
+ app.Get("/api/users/:id", getUser)
+ app.Listen(":8080")
+}
+```
+
+## Configuration Recommendations
+
+### Development
+
+```go
+tracewayfiber.New(
+ connectionString,
+ tracewayfiber.WithDebug(true),
+ tracewayfiber.WithOnErrorRecording(
+ tracewayfiber.RecordingUrl |
+ tracewayfiber.RecordingQuery |
+ tracewayfiber.RecordingHeader |
+ tracewayfiber.RecordingBody,
+ ),
+)
+```
+
+### Production
+
+```go
+tracewayfiber.New(
+ connectionString,
+ tracewayfiber.WithVersion(os.Getenv("APP_VERSION")),
+ tracewayfiber.WithServerName(os.Getenv("HOSTNAME")),
+ tracewayfiber.WithOnErrorRecording(
+ tracewayfiber.RecordingUrl | tracewayfiber.RecordingQuery,
+ ),
+)
+```
+
+### High-Traffic Services
+
+```go
+tracewayfiber.New(
+ connectionString,
+ tracewayfiber.WithSampleRate(0.1),
+ tracewayfiber.WithErrorSampleRate(1.0),
+ tracewayfiber.WithCollectionInterval(10 * time.Second),
+ tracewayfiber.WithMaxCollectionFrames(20),
+ tracewayfiber.WithMetricsInterval(60 * time.Second),
+)
+```
diff --git a/docs/pages/client/fiber-middleware/error-recording.mdx b/docs/pages/client/fiber-middleware/error-recording.mdx
new file mode 100644
index 00000000..bc84ce6d
--- /dev/null
+++ b/docs/pages/client/fiber-middleware/error-recording.mdx
@@ -0,0 +1,83 @@
+# Fiber Error Recording
+
+When an exception occurs during a request (panic, handler error, or status >= 500), you can control what additional request data is captured alongside the stack trace.
+
+## Recording Flags
+
+Configure error recording with `WithOnErrorRecording`:
+
+```go
+tracewayfiber.New(
+ connectionString,
+ tracewayfiber.WithOnErrorRecording(
+ tracewayfiber.RecordingUrl | tracewayfiber.RecordingQuery,
+ ),
+)
+```
+
+### Available Flags
+
+| Flag | Description | Privacy Impact |
+|------|-------------|----------------|
+| `RecordingUrl` | Request URL path | Low |
+| `RecordingQuery` | Query parameters as JSON | Medium |
+| `RecordingBody` | Request body (JSON content-type only, max 64KB) | High |
+| `RecordingHeader` | Request headers as JSON | High |
+
+### Combining Flags
+
+Flags are combined with the `|` operator:
+
+```go
+// Record URL and query parameters
+tracewayfiber.RecordingUrl | tracewayfiber.RecordingQuery
+
+// Record everything
+tracewayfiber.RecordingUrl | tracewayfiber.RecordingQuery | tracewayfiber.RecordingBody | tracewayfiber.RecordingHeader
+```
+
+## Body Capture Details
+
+Body recording has two constraints:
+
+- **Content-Type must be `application/json`** — non-JSON bodies are not captured
+- **Maximum size is 64KB** — bodies larger than 64KB are truncated
+
+After reading the body for capture, it is restored so downstream handlers can still read it.
+
+## Privacy Considerations
+
+Body and header recording may capture sensitive data:
+
+- Authentication tokens in headers
+- Personal information in request bodies
+- API keys in query parameters
+
+Use minimal recording flags in production:
+
+```go
+// Production — limited data
+tracewayfiber.WithOnErrorRecording(
+ tracewayfiber.RecordingUrl | tracewayfiber.RecordingQuery,
+)
+
+// Development — full request data
+tracewayfiber.WithOnErrorRecording(
+ tracewayfiber.RecordingUrl |
+ tracewayfiber.RecordingQuery |
+ tracewayfiber.RecordingBody |
+ tracewayfiber.RecordingHeader,
+)
+```
+
+## Captured Data Format
+
+Recorded data is attached as attributes on the issue:
+
+| Attribute Key | Value |
+|---------------|-------|
+| `url` | URL path string |
+| `query` | JSON-encoded query parameters |
+| `body` | Raw request body string |
+| `headers` | JSON-encoded request headers |
+| `user agent` | User-Agent header value (always captured on error) |
diff --git a/docs/pages/client/fiber-middleware/index.mdx b/docs/pages/client/fiber-middleware/index.mdx
new file mode 100644
index 00000000..dbb36a50
--- /dev/null
+++ b/docs/pages/client/fiber-middleware/index.mdx
@@ -0,0 +1,115 @@
+# Fiber Middleware
+
+The `tracewayfiber` package provides middleware for the [Fiber](https://gofiber.io/) web framework. It automatically creates a trace for each request, captures panics and handler errors, and detects client IP addresses.
+
+## Installation
+
+```bash
+go get go.tracewayapp.com
+go get go.tracewayapp.com/tracewayfiber
+```
+
+## Basic Setup
+
+```go
+package main
+
+import (
+ "github.com/gofiber/fiber/v2"
+ tracewayfiber "go.tracewayapp.com/tracewayfiber"
+)
+
+func main() {
+ app := fiber.New()
+
+ // Add Traceway middleware (must be before routes)
+ app.Use(tracewayfiber.New(
+ "your-token@http://localhost:8082/api/report",
+ ))
+
+ app.Get("/api/users", getUsers)
+ app.Post("/api/users", createUser)
+
+ app.Listen(":8080")
+}
+```
+
+`New` returns a `fiber.Handler` 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 path (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 Fiber's `c.IP()` |
+| **Panics** | Recovered and captured with full stack trace |
+| **Handler Errors** | Errors returned from handlers |
+
+## Error Detection
+
+A request is considered an error when any of these are true:
+
+- A **panic** occurred during handler execution
+- A handler **returned an error**
+- The response **status code is >= 500**
+
+Error traces use the error sample rate for sampling decisions.
+
+## Panic Recovery
+
+When a panic occurs, the middleware:
+
+1. Recovers the panic
+2. Captures the full stack trace as an issue
+3. Either re-panics (default, `WithRepanic(true)`) or returns a 500 error
+
+```go
+app.Get("/risky", func(c *fiber.Ctx) error {
+ panic("something went wrong")
+ // Stack trace is captured, linked to this request's trace
+ return nil
+})
+```
+
+## Handler Errors
+
+Errors returned from Fiber handlers are captured as issues:
+
+```go
+app.Get("/api/users/:id", func(c *fiber.Ctx) error {
+ user, err := findUser(c.Params("id"))
+ if err != nil {
+ return err // Captured as an issue
+ }
+ return c.JSON(user)
+})
+```
+
+## Context Access
+
+Access Traceway context from within your handlers:
+
+```go
+app.Get("/api/users", func(c *fiber.Ctx) error {
+ // Get attributes for this request
+ attributes := tracewayfiber.GetAttributesFromCtx(c)
+ attributes.SetTag("user_id", "123")
+
+ // Get trace context
+ trace := tracewayfiber.GetTraceFromCtx(c)
+
+ return c.SendString("OK")
+})
+```
+
+Context is stored in Fiber's `Locals` store.
+
+## Next Steps
+
+- [Configuration](/client/fiber-middleware/configuration) — All options including filtering and passthrough settings
+- [Error Recording](/client/fiber-middleware/error-recording) — Control what request data is captured on errors
diff --git a/docs/public/chi.png b/docs/public/chi.png
new file mode 100644
index 00000000..eb3bf5a5
Binary files /dev/null and b/docs/public/chi.png differ
diff --git a/docs/public/fasthttp.png b/docs/public/fasthttp.png
new file mode 100644
index 00000000..f9ebe781
Binary files /dev/null and b/docs/public/fasthttp.png differ
diff --git a/docs/public/fiber.svg b/docs/public/fiber.svg
new file mode 100644
index 00000000..29466225
--- /dev/null
+++ b/docs/public/fiber.svg
@@ -0,0 +1,5 @@
+<svg viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+ <rect x="1" y="3" width="10" height="2.5" rx="0.5" fill="#00ACD7"/>
+ <rect x="1" y="6.75" width="14" height="2.5" rx="0.5" fill="#00ACD7"/>
+ <rect x="1" y="10.5" width="6" height="2.5" rx="0.5" fill="#00ACD7"/>
+</svg>
diff --git a/docs/theme.config.jsx b/docs/theme.config.jsx
index 1f63a03f..8be622d0 100644
--- a/docs/theme.config.jsx
+++ b/docs/theme.config.jsx
@@ -6,6 +6,9 @@ import { useSdk } from "./components/SdkContext";
const SDK_VISIBILITY = {
"gin-middleware": "go-gin",
+ "chi-middleware": "go-chi",
+ "fiber-middleware": "go-fiber",
+ "fasthttp-middleware": "go-fasthttp",
"http-middleware": "go-http",
};
diff --git a/frontend/src/lib/utils/framework-code.ts b/frontend/src/lib/utils/framework-code.ts
index 283a2061..14ef47b5 100644
--- a/frontend/src/lib/utils/framework-code.ts
+++ b/frontend/src/lib/utils/framework-code.ts
@@ -5,10 +5,14 @@ export function getInstallCommand(framework: Framework): string {
switch (framework) {
case 'gin':
return `${base} && go get go.tracewayapp.com/tracewaygin`;
- case 'fiber':
case 'chi':
+ return `${base} && go get go.tracewayapp.com/tracewaychi`;
+ case 'fiber':
+ return `${base} && go get go.tracewayapp.com/tracewayfiber`;
case 'fasthttp':
+ return `${base} && go get go.tracewayapp.com/tracewayfasthttp`;
case 'stdlib':
+ return `${base} && go get go.tracewayapp.com/tracewayhttp`;
case 'custom':
default:
return base;
@@ -35,42 +39,89 @@ func main() {
r.Run(":8080")
}`;
- case 'fiber':
case 'chi':
+ return `package main
+
+import (
+ "net/http"
+
+ "github.com/go-chi/chi/v5"
+ tracewaychi "go.tracewayapp.com/tracewaychi"
+)
+
+func main() {
+ r := chi.NewRouter()
+ r.Use(tracewaychi.New("${connectionString}"))
+
+ r.Get("/api/users", getUsers)
+ http.ListenAndServe(":8080", r)
+}`;
+
+ case 'fiber':
+ return `package main
+
+import (
+ "github.com/gofiber/fiber/v2"
+ tracewayfiber "go.tracewayapp.com/tracewayfiber"
+)
+
+func main() {
+ app := fiber.New()
+ app.Use(tracewayfiber.New("${connectionString}"))
+
+ app.Get("/api/users", getUsers)
+ app.Listen(":8080")
+}`;
+
case 'fasthttp':
+ return `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!")
+ }
+
+ tracedHandler := tracewayfasthttp.New("${connectionString}")(handler)
+ fasthttp.ListenAndServe(":8080", tracedHandler)
+}`;
+
case 'stdlib':
+ return `package main
+
+import (
+ "net/http"
+
+ tracewayhttp "go.tracewayapp.com/tracewayhttp"
+)
+
+func main() {
+ mux := http.NewServeMux()
+ mux.HandleFunc("/api/users", getUsers)
+
+ handler := tracewayhttp.New("${connectionString}")(mux)
+ http.ListenAndServe(":8080", handler)
+}`;
+
case 'custom':
default:
- return `// This framework is not currently supported.
-//
-// We welcome contributions! Please visit our GitHub repository
-// to help implement support for ${framework === 'custom' ? 'custom frameworks' : framework}:
-//
-// https://github.com/tracewayapp/go-client
-//
-// In the meantime, you can use the core SDK directly:
-
-package main
+ return `package main
import (
"go.tracewayapp.com"
)
func main() {
- // Initialize Traceway
traceway.Init(
"${connectionString}",
traceway.WithVersion("1.0.0"),
traceway.WithServerName("my-server"),
)
-
- // Capture exceptions manually
- // traceway.CaptureException(err)
- // traceway.CaptureExceptionWithContext(ctx, err)
-
- // Capture messages
- // traceway.CaptureMessage("Something happened")
- // traceway.CaptureMessageWithContext(ctx, "Something happened")
}`;
}
}