Skip to content

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

feat: docs fully updated for the current frameworks supported

dduxb5424a756a39
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
new file mode 100644
index 00000000..76735534
--- /dev/null
+++ b/docs/CLAUDE.md
@@ -0,0 +1,12 @@
+# CLAUDE.md - Docs
+
+## Navbar
+
+- The header navbar items must always be aligned to the left (next to the logo), not centered or spread across the header. This is achieved via CSS in `styles/custom.css`.
+- Navbar order: Docs, Learn, Protocol, Self Host (controlled by key order in `pages/_meta.json`).
+
+## SDK Query Parameter
+
+- The `sdk` query parameter (e.g., `?sdk=go-gin`) must be sticky across all `/client` pages. When a user selects a framework, every sidebar link click and page navigation within `/client` must preserve the `sdk` param in the URL.
+- This is handled by the `SdkProvider` in `components/SdkContext.jsx` which listens to route changes and re-injects the `sdk` param if missing.
+- All internal links within `/client` pages should propagate `sdk` — do not create links that would drop the parameter.
diff --git a/docs/components/FrameworkPicker.jsx b/docs/components/FrameworkPicker.jsx
new file mode 100644
index 00000000..7b7a1db4
--- /dev/null
+++ b/docs/components/FrameworkPicker.jsx
@@ -0,0 +1,58 @@
+import { useRouter } from 'next/router'
+import { useSdk } from './SdkContext'
+
+const FRAMEWORKS = [
+ {
+ value: 'go-gin',
+ label: 'Go Gin',
+ description: 'Gin Gonic web framework with automatic request tracing and panic recovery.',
+ icon: '/gin.png',
+ href: '/client/gin-middleware',
+ },
+ {
+ value: 'go-http',
+ label: 'Go net/http',
+ description: 'Standard library HTTP middleware for request tracing and error capture.',
+ icon: '/stdlib.png',
+ href: '/client/http-middleware',
+ },
+ {
+ value: 'go-generic',
+ label: 'Go Generic',
+ description: 'Framework-agnostic SDK for manual instrumentation of any Go application.',
+ icon: '/custom.png',
+ href: '/client/sdk',
+ },
+]
+
+export default function FrameworkPicker() {
+ const router = useRouter()
+ const { setSdk } = useSdk()
+
+ function handleSelect(fw) {
+ setSdk(fw.value)
+ router.push(`${fw.href}?sdk=${fw.value}`)
+ }
+
+ return (
+ <div className="framework-picker">
+ <h2 className="framework-picker-heading">Choose your framework</h2>
+ <p className="framework-picker-subheading">
+ Select the framework you're using to get started with Traceway.
+ </p>
+ <div className="framework-picker-grid">
+ {FRAMEWORKS.map((fw) => (
+ <button
+ key={fw.value}
+ className="framework-picker-card"
+ onClick={() => handleSelect(fw)}
+ >
+ <img src={fw.icon} alt={fw.label} className="framework-picker-icon" />
+ <span className="framework-picker-label">{fw.label}</span>
+ <span className="framework-picker-desc">{fw.description}</span>
+ </button>
+ ))}
+ </div>
+ </div>
+ )
+}
diff --git a/docs/components/HiddenItem.jsx b/docs/components/HiddenItem.jsx
new file mode 100644
index 00000000..1c01298c
--- /dev/null
+++ b/docs/components/HiddenItem.jsx
@@ -0,0 +1,17 @@
+import { useRef, useEffect } from 'react'
+
+export default function HiddenItem() {
+ const ref = useRef(null)
+
+ useEffect(() => {
+ const li = ref.current?.closest('li')
+ if (li) {
+ li.style.display = 'none'
+ return () => {
+ li.style.display = ''
+ }
+ }
+ }, [])
+
+ return <span ref={ref} style={{ display: 'none' }} />
+}
diff --git a/docs/components/SdkContext.jsx b/docs/components/SdkContext.jsx
new file mode 100644
index 00000000..8c99249e
--- /dev/null
+++ b/docs/components/SdkContext.jsx
@@ -0,0 +1,97 @@
+import { createContext, useContext, useState, useEffect, useCallback } from 'react'
+import { useRouter } from 'next/router'
+
+export const SDK_OPTIONS = [
+ { value: 'go-gin', label: 'Go Gin' },
+ { value: 'go-http', label: 'Go Http' },
+ { value: 'go-generic', label: 'Go Generic' },
+]
+
+const STORAGE_KEY = 'traceway-docs-sdk'
+const VALID_VALUES = new Set(SDK_OPTIONS.map((o) => o.value))
+
+const SdkContext = createContext({
+ sdk: 'go-gin',
+ setSdk: () => {},
+})
+
+export function SdkProvider({ children }) {
+ const router = useRouter()
+ const [sdk, setSdkState] = useState('go-gin')
+
+ useEffect(() => {
+ const params = new URLSearchParams(window.location.search)
+ const urlSdk = params.get('sdk')
+ if (urlSdk && VALID_VALUES.has(urlSdk)) {
+ setSdkState(urlSdk)
+ localStorage.setItem(STORAGE_KEY, urlSdk)
+ return
+ }
+
+ const stored = localStorage.getItem(STORAGE_KEY)
+ if (stored && VALID_VALUES.has(stored)) {
+ setSdkState(stored)
+ }
+ }, [])
+
+ useEffect(() => {
+ const params = new URLSearchParams(window.location.search)
+ const urlSdk = params.get('sdk')
+ if (urlSdk && VALID_VALUES.has(urlSdk) && urlSdk !== sdk) {
+ setSdkState(urlSdk)
+ localStorage.setItem(STORAGE_KEY, urlSdk)
+ }
+ }, [router.asPath])
+
+ // Keep sdk param sticky on all /client pages
+ useEffect(() => {
+ function handleRouteChange(url) {
+ if (!url.startsWith('/client')) return
+
+ const [pathname, search] = url.split('?')
+ const params = new URLSearchParams(search || '')
+
+ if (pathname === '/client') {
+ if (params.has('sdk')) {
+ params.delete('sdk')
+ const qs = params.toString()
+ router.replace(pathname + (qs ? '?' + qs : ''), undefined, { shallow: true })
+ }
+ localStorage.removeItem(STORAGE_KEY)
+ setSdkState('go-gin')
+ return
+ }
+
+ if (!params.get('sdk')) {
+ const currentSdk = localStorage.getItem(STORAGE_KEY) || sdk
+ if (currentSdk && VALID_VALUES.has(currentSdk)) {
+ params.set('sdk', currentSdk)
+ router.replace(pathname + '?' + params.toString(), undefined, { shallow: true })
+ }
+ }
+ }
+
+ router.events.on('routeChangeComplete', handleRouteChange)
+ return () => router.events.off('routeChangeComplete', handleRouteChange)
+ }, [router, sdk])
+
+ const setSdk = useCallback((value) => {
+ if (!VALID_VALUES.has(value)) return
+ setSdkState(value)
+ localStorage.setItem(STORAGE_KEY, value)
+
+ const url = new URL(window.location.href)
+ url.searchParams.set('sdk', value)
+ router.replace(url.pathname + url.search, undefined, { shallow: true })
+ }, [router])
+
+ return (
+ <SdkContext.Provider value={{ sdk, setSdk }}>
+ {children}
+ </SdkContext.Provider>
+ )
+}
+
+export function useSdk() {
+ return useContext(SdkContext)
+}
diff --git a/docs/components/SdkSelector.jsx b/docs/components/SdkSelector.jsx
new file mode 100644
index 00000000..61cfd95e
--- /dev/null
+++ b/docs/components/SdkSelector.jsx
@@ -0,0 +1,98 @@
+import { useState, useRef, useEffect } from 'react'
+import { useRouter } from 'next/router'
+import { useSdk, SDK_OPTIONS } from './SdkContext'
+
+const SDK_QUICK_START = {
+ 'go-gin': '/client/gin-middleware',
+ 'go-http': '/client/http-middleware',
+ 'go-generic': '/client/sdk',
+}
+
+export default function SdkSelector() {
+ const router = useRouter()
+ const { sdk, setSdk } = useSdk()
+ const [open, setOpen] = useState(false)
+ const [search, setSearch] = useState('')
+ const ref = useRef(null)
+ const searchRef = useRef(null)
+
+ const current = SDK_OPTIONS.find((o) => o.value === sdk)
+ const filtered = SDK_OPTIONS.filter((o) =>
+ o.label.toLowerCase().includes(search.toLowerCase())
+ )
+
+ useEffect(() => {
+ function handleClick(e) {
+ if (ref.current && !ref.current.contains(e.target)) {
+ setOpen(false)
+ setSearch('')
+ }
+ }
+ document.addEventListener('mousedown', handleClick)
+ return () => document.removeEventListener('mousedown', handleClick)
+ }, [])
+
+ useEffect(() => {
+ if (open && searchRef.current) {
+ searchRef.current.focus()
+ }
+ }, [open])
+
+ return (
+ <div className="sdk-selector" ref={ref}>
+ <button
+ className="sdk-selector-trigger"
+ onClick={() => {
+ setOpen(!open)
+ setSearch('')
+ }}
+ >
+ <span>{current?.label ?? 'Select SDK'}</span>
+ <svg width="12" height="12" viewBox="0 0 12 12" fill="none">
+ <path
+ d="M3 4.5L6 7.5L9 4.5"
+ stroke="currentColor"
+ strokeWidth="1.5"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ />
+ </svg>
+ </button>
+ {open && (
+ <div className="sdk-selector-dropdown">
+ <input
+ ref={searchRef}
+ className="sdk-selector-search"
+ type="text"
+ placeholder="Search..."
+ value={search}
+ onChange={(e) => setSearch(e.target.value)}
+ />
+ <ul className="sdk-selector-list">
+ {filtered.map((option) => (
+ <li key={option.value}>
+ <button
+ className={`sdk-selector-option ${option.value === sdk ? 'active' : ''}`}
+ onClick={() => {
+ setSdk(option.value)
+ setOpen(false)
+ setSearch('')
+ const href = SDK_QUICK_START[option.value]
+ if (href) {
+ router.push(`${href}?sdk=${option.value}`)
+ }
+ }}
+ >
+ {option.label}
+ </button>
+ </li>
+ ))}
+ {filtered.length === 0 && (
+ <li className="sdk-selector-empty">No results</li>
+ )}
+ </ul>
+ </div>
+ )}
+ </div>
+ )
+}
diff --git a/docs/pages/_app.jsx b/docs/pages/_app.jsx
new file mode 100644
index 00000000..6d4f23c6
--- /dev/null
+++ b/docs/pages/_app.jsx
@@ -0,0 +1,10 @@
+import '../styles/custom.css'
+import { SdkProvider } from '../components/SdkContext'
+
+export default function App({ Component, pageProps }) {
+ return (
+ <SdkProvider>
+ <Component {...pageProps} />
+ </SdkProvider>
+ )
+}
diff --git a/docs/pages/_meta.json b/docs/pages/_meta.json
index 713176b0..7df41d20 100644
--- a/docs/pages/_meta.json
+++ b/docs/pages/_meta.json
@@ -1,9 +1,11 @@
{
- "index": "Introduction",
- "getting-started": "Getting Started",
- "architecture": "Architecture",
- "go-client": "Go Client SDK",
- "gin-middleware": "Gin Middleware",
- "http-middleware": "HTTP Middleware",
- "traceway-protocol": "Traceway Protocol"
+ "index": { "title": "Traceway", "type": "page", "display": "hidden" },
+ "client": { "title": "Docs", "type": "page", "withIndexPage": true },
+ "learn": { "title": "Learn", "type": "page" },
+ "protocol": {
+ "title": "Protocol",
+ "type": "page",
+ "theme": { "sidebar": false }
+ },
+ "server": { "title": "Self Host", "type": "page" }
}
diff --git a/docs/pages/client/_meta.json b/docs/pages/client/_meta.json
new file mode 100644
index 00000000..baea3042
--- /dev/null
+++ b/docs/pages/client/_meta.json
@@ -0,0 +1,11 @@
+{
+ "sdk-selector": { "type": "separator", "title": "sdk-selector" },
+ "index": {
+ "title": "Introduction",
+ "display": "hidden",
+ "theme": { "sidebar": false, "pagination": false }
+ },
+ "gin-middleware": "Gin Middleware",
+ "http-middleware": "HTTP Middleware",
+ "sdk": "SDK Reference"
+}
diff --git a/docs/pages/gin-middleware/_meta.json b/docs/pages/client/gin-middleware/_meta.json
similarity index 61%
rename from docs/pages/gin-middleware/_meta.json
rename to docs/pages/client/gin-middleware/_meta.json
index 00073156..a5183284 100644
--- a/docs/pages/gin-middleware/_meta.json
+++ b/docs/pages/client/gin-middleware/_meta.json
@@ -1,5 +1,5 @@
{
"index": "Quick Start",
- "configuration": "Configuration",
+ "configuration": { "display": "hidden" },
"error-recording": "Error Recording"
}
diff --git a/docs/pages/gin-middleware/configuration.mdx b/docs/pages/client/gin-middleware/configuration.mdx
similarity index 100%
rename from docs/pages/gin-middleware/configuration.mdx
rename to docs/pages/client/gin-middleware/configuration.mdx
diff --git a/docs/pages/gin-middleware/error-recording.mdx b/docs/pages/client/gin-middleware/error-recording.mdx
similarity index 100%
rename from docs/pages/gin-middleware/error-recording.mdx
rename to docs/pages/client/gin-middleware/error-recording.mdx
diff --git a/docs/pages/gin-middleware/index.mdx b/docs/pages/client/gin-middleware/index.mdx
similarity index 91%
rename from docs/pages/gin-middleware/index.mdx
rename to docs/pages/client/gin-middleware/index.mdx
index 1b16c8dc..5c35c7c2 100644
--- a/docs/pages/gin-middleware/index.mdx
+++ b/docs/pages/client/gin-middleware/index.mdx
@@ -93,5 +93,5 @@ If the error wraps a `StackTraceError` (from `traceway.NewStackTraceErrorf`), th
## Next Steps
-- [Configuration](/gin-middleware/configuration) — All options including route filtering and passthrough settings
-- [Error Recording](/gin-middleware/error-recording) — Control what request data is captured on errors
+- [Configuration](/client/gin-middleware/configuration) — All options including route filtering and passthrough settings
+- [Error Recording](/client/gin-middleware/error-recording) — Control what request data is captured on errors
diff --git a/docs/pages/http-middleware/_meta.json b/docs/pages/client/http-middleware/_meta.json
similarity index 61%
rename from docs/pages/http-middleware/_meta.json
rename to docs/pages/client/http-middleware/_meta.json
index 00073156..a5183284 100644
--- a/docs/pages/http-middleware/_meta.json
+++ b/docs/pages/client/http-middleware/_meta.json
@@ -1,5 +1,5 @@
{
"index": "Quick Start",
- "configuration": "Configuration",
+ "configuration": { "display": "hidden" },
"error-recording": "Error Recording"
}
diff --git a/docs/pages/http-middleware/configuration.mdx b/docs/pages/client/http-middleware/configuration.mdx
similarity index 100%
rename from docs/pages/http-middleware/configuration.mdx
rename to docs/pages/client/http-middleware/configuration.mdx
diff --git a/docs/pages/http-middleware/error-recording.mdx b/docs/pages/client/http-middleware/error-recording.mdx
similarity index 100%
rename from docs/pages/http-middleware/error-recording.mdx
rename to docs/pages/client/http-middleware/error-recording.mdx
diff --git a/docs/pages/http-middleware/index.mdx b/docs/pages/client/http-middleware/index.mdx
similarity index 90%
rename from docs/pages/http-middleware/index.mdx
rename to docs/pages/client/http-middleware/index.mdx
index a834755c..99643aa0 100644
--- a/docs/pages/http-middleware/index.mdx
+++ b/docs/pages/client/http-middleware/index.mdx
@@ -80,5 +80,5 @@ When a panic occurs, the middleware:
## Next Steps
-- [Configuration](/http-middleware/configuration) — All options and passthrough settings
-- [Error Recording](/http-middleware/error-recording) — Control what request data is captured on errors
+- [Configuration](/client/http-middleware/configuration) — All options and passthrough settings
+- [Error Recording](/client/http-middleware/error-recording) — Control what request data is captured on errors
diff --git a/docs/pages/client/index.mdx b/docs/pages/client/index.mdx
new file mode 100644
index 00000000..e999278c
--- /dev/null
+++ b/docs/pages/client/index.mdx
@@ -0,0 +1,7 @@
+import FrameworkPicker from "../../components/FrameworkPicker";
+
+# Traceway
+
+Traceway is an open-source error tracking and monitoring platform for Go applications. It provides real-time visibility into your application's health through exception tracking, endpoint monitoring, background tasks, and system metrics.
+
+<FrameworkPicker />
diff --git a/docs/pages/go-client/_meta.json b/docs/pages/client/sdk/_meta.json
similarity index 100%
rename from docs/pages/go-client/_meta.json
rename to docs/pages/client/sdk/_meta.json
diff --git a/docs/pages/go-client/attributes.mdx b/docs/pages/client/sdk/attributes.mdx
similarity index 100%
rename from docs/pages/go-client/attributes.mdx
rename to docs/pages/client/sdk/attributes.mdx
diff --git a/docs/pages/go-client/exceptions.mdx b/docs/pages/client/sdk/exceptions.mdx
similarity index 100%
rename from docs/pages/go-client/exceptions.mdx
rename to docs/pages/client/sdk/exceptions.mdx
diff --git a/docs/pages/go-client/index.mdx b/docs/pages/client/sdk/index.mdx
similarity index 71%
rename from docs/pages/go-client/index.mdx
rename to docs/pages/client/sdk/index.mdx
index f6bde764..7aa34834 100644
--- a/docs/pages/go-client/index.mdx
+++ b/docs/pages/client/sdk/index.mdx
@@ -19,7 +19,7 @@ go get go.tracewayapp.com
## When to Use Core vs Middleware
-**Use middleware** ([Gin](/gin-middleware) or [HTTP](/http-middleware)) when your application serves HTTP requests. The middleware handles initialization, trace creation, panic recovery, and data capture automatically.
+**Use middleware** ([Gin](/client/gin-middleware) or [HTTP](/client/http-middleware)) when your application serves HTTP requests. The middleware handles initialization, trace creation, panic recovery, and data capture automatically.
**Use the core package directly** when:
@@ -40,7 +40,7 @@ Before using the SDK, you need a project token from your Traceway instance:
## Next Steps
-- [Initialization](/go-client/initialization) — Connection string format and all configuration options
-- [Traces](/go-client/traces) — Recording HTTP requests and background tasks
-- [Exceptions](/go-client/exceptions) — Capturing errors and panics
-- [Spans](/go-client/spans) — Timing sub-operations
+- [Initialization](/client/sdk/initialization) — Connection string format and all configuration options
+- [Traces](/client/sdk/traces) — Recording HTTP requests and background tasks
+- [Exceptions](/client/sdk/exceptions) — Capturing errors and panics
+- [Spans](/client/sdk/spans) — Timing sub-operations
diff --git a/docs/pages/go-client/initialization.mdx b/docs/pages/client/sdk/initialization.mdx
similarity index 100%
rename from docs/pages/go-client/initialization.mdx
rename to docs/pages/client/sdk/initialization.mdx
diff --git a/docs/pages/go-client/messages.mdx b/docs/pages/client/sdk/messages.mdx
similarity index 100%
rename from docs/pages/go-client/messages.mdx
rename to docs/pages/client/sdk/messages.mdx
diff --git a/docs/pages/go-client/metrics.mdx b/docs/pages/client/sdk/metrics.mdx
similarity index 100%
rename from docs/pages/go-client/metrics.mdx
rename to docs/pages/client/sdk/metrics.mdx
diff --git a/docs/pages/go-client/spans.mdx b/docs/pages/client/sdk/spans.mdx
similarity index 100%
rename from docs/pages/go-client/spans.mdx
rename to docs/pages/client/sdk/spans.mdx
diff --git a/docs/pages/go-client/stack-traces.mdx b/docs/pages/client/sdk/stack-traces.mdx
similarity index 100%
rename from docs/pages/go-client/stack-traces.mdx
rename to docs/pages/client/sdk/stack-traces.mdx
diff --git a/docs/pages/go-client/traces.mdx b/docs/pages/client/sdk/traces.mdx
similarity index 100%
rename from docs/pages/go-client/traces.mdx
rename to docs/pages/client/sdk/traces.mdx
diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx
index dbb035c9..3014e91c 100644
--- a/docs/pages/index.mdx
+++ b/docs/pages/index.mdx
@@ -1,66 +1,21 @@
-# Traceway
-
-Traceway is an open-source error tracking and monitoring platform for Go applications. It provides real-time visibility into your application's health through:
-
-- **Exception Tracking**: Capture and group errors with full stack traces
-- **Endpoint Monitoring**: Track HTTP request performance with P50/P95/P99 percentiles
-- **Background Tasks**: Monitor background job execution and failures
-- **System Metrics**: Collect CPU, memory, and Go runtime statistics
-
-## Architecture
-
-Traceway consists of three main components:
-
-```
-┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
-│ Your Go App │────▶│ Traceway API │◀────│ Dashboard │
-│ + SDK Client │ │ (Backend) │ │ (Frontend) │
-└─────────────────┘ └────────┬────────┘ └─────────────────┘
- │
- ┌────────────┴────────────┐
- ▼ ▼
- ┌───────────────┐ ┌────────────────┐
- │ ClickHouse │ │ PostgreSQL │
- │ (Telemetry) │ │ (Accounts) │
- └───────────────┘ └────────────────┘
-```
-
-## Quick Start
-
-1. **Set up the backend** - Follow the [Local Setup](/getting-started/local-setup) guide
-2. **Register your account** - Create your first user and organization
-3. **Create a project** - Get your project token for the SDK
-4. **Install the SDK** - Add the Go client to your application
-5. **View your data** - Monitor your application in the dashboard
-
-## Features
-
-### For Developers
-
-- **Automatic Error Capture**: Panics and errors are automatically captured with full context
-- **Request Scoping**: Add custom tags (user ID, tenant, etc.) to correlate errors
-- **Span Tracking**: Measure sub-operations within requests (database queries, API calls)
-- **Background Task Support**: Track non-HTTP operations with the same tooling
-
-### For Operations
-
-- **Real-time Monitoring**: See errors and performance issues as they happen
-- **Smart Grouping**: Similar errors are automatically grouped by normalized stack traces
-- **Historical Analysis**: Query data across custom time ranges
-- **Multi-project Support**: Manage multiple applications from a single dashboard
-
-## Supported Frameworks
-
-Currently, Traceway provides official SDK support for:
-
-| Framework | Status | Documentation |
-| --------- | ------ | --------------------------------- |
-| Gin (Go) | Stable | [Gin Middleware](/gin-middleware) |
-| net/http | Stable | [HTTP Middleware](/http-middleware) |
-
-## Next Steps
-
-- [Local Setup](/getting-started/local-setup) - Run Traceway on your machine
-- [Docker Deployment](/getting-started/docker) - Deploy with Docker
-- [Architecture](/architecture) - Understand traces, issues, spans, and attributes
-- [Go Client SDK](/go-client) - Learn about the core SDK
+---
+title: Traceway Docs
+---
+
+import Head from 'next/head'
+import { useEffect } from 'react'
+import { useRouter } from 'next/router'
+
+export function Redirect() {
+ const router = useRouter()
+ useEffect(() => {
+ router.replace('/client')
+ }, [])
+ return (
+ <Head>
+ <meta httpEquiv="refresh" content="0;url=/client" />
+ </Head>
+ )
+}
+
+<Redirect />
diff --git a/docs/pages/architecture/_meta.json b/docs/pages/learn/_meta.json
similarity index 81%
rename from docs/pages/architecture/_meta.json
rename to docs/pages/learn/_meta.json
index 442fde9b..8559547e 100644
--- a/docs/pages/architecture/_meta.json
+++ b/docs/pages/learn/_meta.json
@@ -1,5 +1,6 @@
{
"index": "Overview",
+ "data-flow": "Data Flow",
"traces": "Traces",
"issues": "Issues",
"attributes": "Attributes",
diff --git a/docs/pages/architecture/attributes.mdx b/docs/pages/learn/attributes.mdx
similarity index 54%
rename from docs/pages/architecture/attributes.mdx
rename to docs/pages/learn/attributes.mdx
index 6d9ad130..4baaa208 100644
--- a/docs/pages/architecture/attributes.mdx
+++ b/docs/pages/learn/attributes.mdx
@@ -2,47 +2,41 @@
Attributes are key-value metadata attached to traces and issues. They provide the context you need to debug problems — who was affected, what they were doing, and in what environment.
+## Structure
+
+Attributes are key-value pairs where each key and value are a string. They can exist on both **traces** and **issues**.
+
+Examples of common attributes:
+
+| Key | Value |
+|-----|-------|
+| `user_id` | `"12345"` |
+| `environment` | `"production"` |
+| `tenant` | `"acme-corp"` |
+| `cart_items` | `'["item1", "item2", "item3"]'` |
+
## Values
-Attribute values are always strings. If the string contains valid JSON, the Traceway dashboard will display it with proper formatting (syntax highlighting, collapsible sections).
+Since all values are strings, there are two ways they get displayed in the dashboard:
-```go
-// Simple string value
-attributes.SetTag("user_id", "12345")
+- **Plain strings** — Displayed as-is, without any formatting (e.g., `"12345"`, `"production"`)
+- **JSON strings** — If the string contains valid JSON, the dashboard renders it in a JSON viewer with syntax highlighting and collapsible sections (e.g., `'{"name": "John", "age": 30}'`)
-// JSON value — displayed formatted in the dashboard
-attributes.SetTagJson("cart_items", []string{"item1", "item2", "item3"})
-```
+This means you can attach structured data to any trace or issue by serializing it to a JSON string.
## Scope Levels
### Global Attributes
-Set once at application startup. Applied to every trace and issue.
-
-```go
-traceway.ConfigureAttributes(func(s *traceway.Attributes) {
- s.SetTag("environment", "production")
- s.SetTag("region", "us-east-1")
- s.SetTag("service", "user-api")
-})
-```
+Set once at application startup. Applied to every trace and issue your application produces.
### Per-Request Attributes
-Set during request handling via middleware context. Applied to the current trace and any issues captured during that request.
-
-```go
-func handler(c *gin.Context) {
- attributes := traceway.GetAttributesFromContext(c.Request.Context())
- attributes.SetTag("user_id", c.Param("id"))
- attributes.SetTag("tenant", "acme-corp")
-}
-```
+Set during request handling via the SDK. Applied only to the current trace and any issues captured during that request.
-## Inheritance
+### Inheritance
-Per-request attributes start as a clone of the global attributes. Request-level tags override global tags if they share the same key.
+Per-request attributes start as a clone of the global attributes. Request-level values override global values if they share the same key.
```
Global Attributes Request Attributes Final Tags
@@ -54,7 +48,7 @@ service: user-api service: user-api
tenant: acme
```
-## What Carries Attributes
+## Where Attributes Appear
- **Traces** (endpoints and tasks) — attributes are recorded with the trace
- **Issues** (exceptions and messages) — attributes in scope at capture time are attached to the issue
diff --git a/docs/pages/learn/data-flow.mdx b/docs/pages/learn/data-flow.mdx
new file mode 100644
index 00000000..88b313df
--- /dev/null
+++ b/docs/pages/learn/data-flow.mdx
@@ -0,0 +1,33 @@
+# Data Flow
+
+## Endpoint Flow
+
+Here's how the concepts connect in a typical request:
+
+1. **Request arrives** → Middleware creates a new **Trace** (Automatically by the client SDK for your framework)
+2. **Auth middleware runs** → Adds `user_id` to **Attributes** (Manually done by you - Traceway does not know about your authentication)
+3. **Handler executes** → Creates **Spans** for sub-operations (DB queries, API calls, your own spans...)
+4. **Error occurs** → **Issue** captured with full attributes context, linked to the trace (Automatically by the client SDK for your framework)
+5. **Request completes** → Trace recorded with duration, status code, and all spans (Automatically by the client SDK for your framework)
+
+## Task Flow
+
+Here's how the concepts connect in a typical scheduled/async task:
+
+1. **Task starts** → Client SDK provides a wrapper function for task execution
+2. **Your task code executes** → Creates **Spans** for sub-operations (DB queries, API calls, your own spans...)
+3. **Error occurs** → **Issue** captured with full attributes context, linked to the task trace (Automatically by the client SDK for your framework)
+4. **Task completes** → Trace recorded with duration, status code, and all spans (Automatically by the client SDK for your framework)
+
+## Metrics Flow
+
+1. **Background** → System **Metrics** collected every 30 seconds (Automatically by the client SDK for your framework)
+
+## After the data collection
+
+All this data flows to your Traceway dashboard where you can:
+
+- Sort endpoints by impact to find the worst performers
+- Get notified when errors happen
+- Track task durations over time
+- Monitor system health through metrics
diff --git a/docs/pages/architecture/index.mdx b/docs/pages/learn/index.mdx
similarity index 74%
rename from docs/pages/architecture/index.mdx
rename to docs/pages/learn/index.mdx
index e62e2289..3e02ba99 100644
--- a/docs/pages/architecture/index.mdx
+++ b/docs/pages/learn/index.mdx
@@ -33,40 +33,24 @@ A **Trace** is a timed unit of work. There are two specializations:
- **Endpoints** — HTTP requests, automatically created by middleware (e.g., `GET /api/users/:id`)
- **Tasks** — Background jobs, manually created in your code (e.g., cron jobs, queue workers)
-Both carry duration, attributes, and spans. [Learn more →](/architecture/traces)
+Both carry duration, attributes, and spans. [Learn more →](/learn/traces)
### Issues
An **Issue** captures a problem — an exception, a panic, or an explicitly sent message. Issues can be **connected to a trace** via the trace's context, linking the error to the request or task that caused it.
-Similar exceptions are automatically grouped by normalized stack trace hash. [Learn more →](/architecture/issues)
+Similar exceptions are automatically grouped by normalized stack trace hash. [Learn more →](/learn/issues)
### Attributes
**Attributes** are key-value metadata attached to traces and issues. Values are strings — if the string is valid JSON, the dashboard displays it with proper formatting.
-Attributes flow from global scope to per-request scope. [Learn more →](/architecture/attributes)
+Attributes flow from global scope to per-request scope. [Learn more →](/learn/attributes)
### Spans
**Spans** are timed sub-operations within a trace. Use them to measure where time is spent — database queries, API calls, business logic steps.
-Spans display as a timeline within a trace in the dashboard. [Learn more →](/architecture/spans)
+Spans display as a timeline within a trace in the dashboard. [Learn more →](/learn/spans)
-## Request Flow
-
-Here's how the concepts connect in a typical request:
-
-1. **Request arrives** → Middleware creates a new **Trace** (Endpoint type)
-2. **Auth middleware runs** → Adds `user_id` to **Attributes**
-3. **Handler executes** → Creates **Spans** for sub-operations (DB queries, API calls)
-4. **Error occurs** → **Issue** captured with full attributes context, linked to the trace
-5. **Request completes** → Trace recorded with duration, status code, and all spans
-6. **Background** → System **Metrics** collected every 30 seconds
-
-All this data flows to your Traceway dashboard where you can:
-
-- Sort endpoints by impact to find the worst performers
-- Get notified when errors happen
-- Track task durations over time
-- Monitor system health through metrics
+See [Data Flow](/learn/data-flow) for how these concepts connect during request processing, task execution, and metrics collection.
diff --git a/docs/pages/architecture/issues.mdx b/docs/pages/learn/issues.mdx
similarity index 84%
rename from docs/pages/architecture/issues.mdx
rename to docs/pages/learn/issues.mdx
index 70400a73..a453a5a0 100644
--- a/docs/pages/architecture/issues.mdx
+++ b/docs/pages/learn/issues.mdx
@@ -6,16 +6,16 @@ Issues capture problems in your application — exceptions, panics, and explicit
An issue is created when:
-- A **panic** occurs during a traced request or task
-- An **error** is passed to `c.Error()` in Gin
-- Your code explicitly calls `CaptureException`, `CaptureMessage`, or related functions
+- A **panic** or **unhandled exception** occurs during a traced request or task
+- An **error** is reported to the client SDK during request handling
+- Your code explicitly captures an exception or message through the client SDK
## Errors vs Messages
Traceway captures two kinds of issues:
- **Errors** — Runtime exceptions with stack traces (panics, captured errors)
-- **Messages** — Explicitly captured strings via `CaptureMessage("something happened")`
+- **Messages** — Explicitly captured strings sent through the client SDK
Both appear in the Issues list with full context and attributes.
@@ -52,7 +52,7 @@ This means the same bug produces one issue, not thousands of duplicates with dif
Issues carry their own attributes — the key-value metadata that was in scope when the exception occurred. If the issue is linked to a trace, it inherits the trace's attributes.
-When error recording flags are enabled in middleware, additional context is attached:
+When error recording flags are enabled in middleware, additional context can be attached (configurable per client library):
- Request URL
- Query parameters
diff --git a/docs/pages/architecture/spans.mdx b/docs/pages/learn/spans.mdx
similarity index 62%
rename from docs/pages/architecture/spans.mdx
rename to docs/pages/learn/spans.mdx
index f20e3d23..17408346 100644
--- a/docs/pages/architecture/spans.mdx
+++ b/docs/pages/learn/spans.mdx
@@ -6,12 +6,12 @@ Spans are timed sub-operations within a trace. They show where time is spent dur
Each span records:
-| Field | Description |
-|-------|-------------|
-| ID | Unique span identifier |
-| Name | Descriptive name you provide |
-| Start Time | When the span started |
-| Duration | Time elapsed (calculated on `End()`) |
+| Field | Description |
+| ---------- | ------------------------------------ |
+| ID | Unique span identifier |
+| Name | Descriptive name you provide |
+| Start Time | When the span started |
+| Duration | Time elapsed (calculated on `End()`) |
## Use Cases
@@ -51,14 +51,11 @@ The pattern `category.resource.action` keeps span names consistent and searchabl
## Nesting
-Spans can be nested for hierarchical tracking. The parent span encompasses the child spans:
+Spans can not be nested. The nesting is achieved purely by the start time of the child spans:
```
Total: 200ms
-├── process.checkout: 200ms
-│ ├── process.checkout.validate: 20ms
-│ ├── process.checkout.charge: 150ms
-│ └── process.checkout.fulfill: 30ms
+├── process.checkout.validate: 20ms to 150ms
+├── process.checkout.charge: 150ms to 160ms
+└── process.checkout.fulfill: 160ms to 200ms
```
-
-Nesting is achieved by starting child spans before ending the parent span. All spans are attached to the same trace context.
diff --git a/docs/pages/architecture/traces.mdx b/docs/pages/learn/traces.mdx
similarity index 71%
rename from docs/pages/architecture/traces.mdx
rename to docs/pages/learn/traces.mdx
index 64773c86..23cbe89c 100644
--- a/docs/pages/architecture/traces.mdx
+++ b/docs/pages/learn/traces.mdx
@@ -18,15 +18,15 @@ Endpoints are ordered in the dashboard by **Impact**, which factors in both perf
The middleware captures:
-| Field | Description |
-|-------|-------------|
-| Endpoint | HTTP method + route template |
-| Duration | Request processing time |
-| Status Code | HTTP response status |
-| Body Size | Response body size in bytes |
-| Client IP | Request origin IP address |
-| Attributes | Key-value metadata |
-| Spans | Timed sub-operations |
+| Field | Description |
+| ----------- | ---------------------------- |
+| Endpoint | HTTP method + route template |
+| Duration | Request processing time |
+| Status Code | HTTP response status |
+| Body Size | Response body size in bytes |
+| Client IP | Request origin IP address |
+| Attributes | Key-value metadata |
+| Spans | Timed sub-operations |
### Tasks
@@ -41,7 +41,7 @@ Tasks carry the same data as endpoints (duration, attributes, spans) but without
## Trace Lifecycle
-1. A trace is created — either automatically by middleware (endpoint) or manually via `StartTrace` / `MeasureTask` (task)
+1. A trace is created — either automatically by the client sdk (endpoints) or manually by starting a trace or measuring a task
2. During execution, spans and attributes are added to the trace via context
3. If an error occurs, an issue is captured and linked to the trace via its ID
4. When the work completes, the trace is recorded with its final duration and all collected data
@@ -63,4 +63,4 @@ Not every trace needs to be recorded. Traceway supports two sample rates:
- **Sample rate** — Controls what percentage of normal traces are recorded (default: 100%)
- **Error sample rate** — Controls what percentage of error traces are recorded (default: 100%)
-Error traces (panics, status >= 500, Gin errors) use the error sample rate, which you typically keep at 100% to capture all problems.
+Error traces (exceptions, panics, status >= 500, errors) use the error sample rate, which you typically keep at 100% to capture all problems.
diff --git a/docs/pages/protocol/_meta.json b/docs/pages/protocol/_meta.json
new file mode 100644
index 00000000..ca0a2a6c
--- /dev/null
+++ b/docs/pages/protocol/_meta.json
@@ -0,0 +1,3 @@
+{
+ "index": "Overview"
+}
diff --git a/docs/pages/traceway-protocol.md b/docs/pages/protocol/index.md
similarity index 100%
rename from docs/pages/traceway-protocol.md
rename to docs/pages/protocol/index.md
diff --git a/docs/pages/getting-started/_meta.json b/docs/pages/server/_meta.json
similarity index 74%
rename from docs/pages/getting-started/_meta.json
rename to docs/pages/server/_meta.json
index c2ce9d12..50fdc858 100644
--- a/docs/pages/getting-started/_meta.json
+++ b/docs/pages/server/_meta.json
@@ -1,4 +1,5 @@
{
+ "index": "Overview",
"local-setup": "Local Setup",
"docker": "Docker Deployment"
}
diff --git a/docs/pages/getting-started/docker.mdx b/docs/pages/server/docker.mdx
similarity index 100%
rename from docs/pages/getting-started/docker.mdx
rename to docs/pages/server/docker.mdx
diff --git a/docs/pages/server/index.mdx b/docs/pages/server/index.mdx
new file mode 100644
index 00000000..496f5d5c
--- /dev/null
+++ b/docs/pages/server/index.mdx
@@ -0,0 +1,8 @@
+# Self Host
+
+Traceway is fully self-hosted — you run the entire platform on your own infrastructure. This section covers how to get Traceway up and running.
+
+## Deployment Options
+
+- [Local Setup](/server/local-setup) — Set up Traceway on your local machine for development
+- [Docker Deployment](/server/docker) — Deploy Traceway as a single Docker container
diff --git a/docs/pages/getting-started/local-setup.mdx b/docs/pages/server/local-setup.mdx
similarity index 98%
rename from docs/pages/getting-started/local-setup.mdx
rename to docs/pages/server/local-setup.mdx
index 513883db..51308112 100644
--- a/docs/pages/getting-started/local-setup.mdx
+++ b/docs/pages/server/local-setup.mdx
@@ -132,7 +132,7 @@ func main() {
}
```
-See the [Go Client documentation](/go-client) for detailed SDK usage.
+See the [SDK Reference](/client/sdk) for detailed SDK usage.
## Troubleshooting
diff --git a/docs/public/custom.png b/docs/public/custom.png
new file mode 100644
index 00000000..6512cf46
Binary files /dev/null and b/docs/public/custom.png differ
diff --git a/docs/public/gin.png b/docs/public/gin.png
new file mode 100644
index 00000000..7f20970b
Binary files /dev/null and b/docs/public/gin.png differ
diff --git a/docs/public/stdlib.png b/docs/public/stdlib.png
new file mode 100644
index 00000000..6fc50870
Binary files /dev/null and b/docs/public/stdlib.png differ
diff --git a/docs/styles/custom.css b/docs/styles/custom.css
new file mode 100644
index 00000000..84b25700
--- /dev/null
+++ b/docs/styles/custom.css
@@ -0,0 +1,249 @@
+/* Navbar - align nav items to the left (right after the logo) */
+.nextra-nav-container nav > a:first-child {
+ margin-right: 20px !important;
+}
+
+.nextra-nav-container .nextra-search {
+ margin-left: auto;
+}
+
+/* SDK Selector - injected into sidebar via separator */
+li:has(> .sdk-selector) {
+ padding: 0 !important;
+ margin: 0 0 8px 0 !important;
+ border: none !important;
+ list-style: none !important;
+}
+
+li:has(> .sdk-selector) > span:first-child {
+ display: none !important;
+}
+
+.sdk-selector {
+ position: relative;
+ width: 100%;
+ padding: 0 8px;
+}
+
+.sdk-selector-trigger {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ width: 100%;
+ padding: 8px 12px;
+ font-size: 13px;
+ font-weight: 500;
+ border: 1px solid #e5e7eb;
+ border-radius: 8px;
+ background: #fff;
+ color: #111827;
+ cursor: pointer;
+ transition: border-color 0.15s;
+}
+
+.sdk-selector-trigger:hover {
+ border-color: #9ca3af;
+}
+
+.sdk-selector-dropdown {
+ position: absolute;
+ top: calc(100% + 4px);
+ left: 8px;
+ right: 8px;
+ background: #fff;
+ border: 1px solid #e5e7eb;
+ border-radius: 8px;
+ box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+ z-index: 50;
+ overflow: hidden;
+}
+
+.sdk-selector-search {
+ width: 100%;
+ padding: 8px 12px;
+ font-size: 13px;
+ border: none;
+ border-bottom: 1px solid #e5e7eb;
+ outline: none;
+ background: transparent;
+ color: #111827;
+}
+
+.sdk-selector-search::placeholder {
+ color: #9ca3af;
+}
+
+.sdk-selector-list {
+ list-style: none !important;
+ margin: 0 !important;
+ padding: 4px !important;
+}
+
+.sdk-selector-list li {
+ margin: 0 !important;
+ padding: 0 !important;
+}
+
+.sdk-selector-option {
+ display: block;
+ width: 100%;
+ padding: 6px 8px;
+ font-size: 13px;
+ text-align: left;
+ border: none;
+ border-radius: 4px;
+ background: transparent;
+ color: #374151;
+ cursor: pointer;
+}
+
+.sdk-selector-option:hover {
+ background: #f3f4f6;
+}
+
+.sdk-selector-option.active {
+ background: #eff6ff;
+ color: #2563eb;
+ font-weight: 500;
+}
+
+.sdk-selector-empty {
+ padding: 8px 12px;
+ font-size: 13px;
+ color: #9ca3af;
+}
+
+/* Framework Picker */
+.framework-picker {
+ margin-top: 24px;
+}
+
+.framework-picker-heading {
+ font-size: 20px;
+ font-weight: 600;
+ margin: 0 0 8px 0;
+ color: #111827;
+}
+
+.framework-picker-subheading {
+ font-size: 15px;
+ color: #6b7280;
+ margin: 0 0 24px 0;
+}
+
+.framework-picker-grid {
+ display: grid;
+ grid-template-columns: repeat(3, 1fr);
+ gap: 16px;
+}
+
+@media (max-width: 768px) {
+ .framework-picker-grid {
+ grid-template-columns: 1fr;
+ }
+}
+
+.framework-picker-card {
+ display: flex;
+ flex-direction: column;
+ align-items: flex-start;
+ gap: 8px;
+ padding: 24px;
+ border: 1px solid #e5e7eb;
+ border-radius: 12px;
+ background: #fff;
+ cursor: pointer;
+ transition:
+ border-color 0.15s,
+ box-shadow 0.15s;
+ text-align: left;
+ font-family: inherit;
+}
+
+.framework-picker-card:hover {
+ border-color: #3b82f6;
+ box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
+}
+
+.framework-picker-icon {
+ width: 28px;
+ height: 28px;
+ object-fit: contain;
+}
+
+.framework-picker-label {
+ font-size: 16px;
+ font-weight: 600;
+ color: #111827;
+}
+
+.framework-picker-desc {
+ font-size: 14px;
+ color: #6b7280;
+ line-height: 1.5;
+}
+
+:is(html[class~="dark"]) .framework-picker-heading {
+ color: #e5e7eb;
+}
+
+:is(html[class~="dark"]) .framework-picker-subheading {
+ color: #9ca3af;
+}
+
+:is(html[class~="dark"]) .framework-picker-card {
+ background: #1a1a2e;
+ border-color: #374151;
+}
+
+:is(html[class~="dark"]) .framework-picker-card:hover {
+ border-color: #3b82f6;
+ box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.15);
+}
+
+:is(html[class~="dark"]) .framework-picker-label {
+ color: #e5e7eb;
+}
+
+:is(html[class~="dark"]) .framework-picker-desc {
+ color: #9ca3af;
+}
+
+/* Dark mode */
+:is(html[class~="dark"]) .sdk-selector-trigger {
+ background: #1a1a2e;
+ border-color: #374151;
+ color: #e5e7eb;
+}
+
+:is(html[class~="dark"]) .sdk-selector-trigger:hover {
+ border-color: #6b7280;
+}
+
+:is(html[class~="dark"]) .sdk-selector-dropdown {
+ background: #1a1a2e;
+ border-color: #374151;
+ box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
+}
+
+:is(html[class~="dark"]) .sdk-selector-search {
+ border-bottom-color: #374151;
+ color: #e5e7eb;
+}
+
+:is(html[class~="dark"]) .sdk-selector-search::placeholder {
+ color: #6b7280;
+}
+
+:is(html[class~="dark"]) .sdk-selector-option {
+ color: #d1d5db;
+}
+
+:is(html[class~="dark"]) .sdk-selector-option:hover {
+ background: #374151;
+}
+
+:is(html[class~="dark"]) .sdk-selector-option.active {
+ background: #1e3a5f;
+ color: #60a5fa;
+}
diff --git a/docs/theme.config.jsx b/docs/theme.config.jsx
index ee991aac..1f63a03f 100644
--- a/docs/theme.config.jsx
+++ b/docs/theme.config.jsx
@@ -1,13 +1,24 @@
+import { useState, useEffect } from "react";
import { useTheme } from "nextra-theme-docs";
+import SdkSelector from "./components/SdkSelector";
+import HiddenItem from "./components/HiddenItem";
+import { useSdk } from "./components/SdkContext";
+
+const SDK_VISIBILITY = {
+ "gin-middleware": "go-gin",
+ "http-middleware": "go-http",
+};
export default {
logoLink: "https://tracewayapp.com",
logo: function Logo() {
const { resolvedTheme } = useTheme();
+ const [mounted, setMounted] = useState(false);
+ useEffect(() => setMounted(true), []);
return (
<img
src={
- resolvedTheme === "dark"
+ mounted && resolvedTheme === "dark"
? "/traceway-logo-white.png"
: "/traceway-logo.png"
}
@@ -45,6 +56,19 @@ export default {
sidebar: {
defaultMenuCollapseLevel: 1,
toggleButton: true,
+ titleComponent({ title, type, route }) {
+ if (type === "separator" && title === "sdk-selector") {
+ return <SdkSelector />;
+ }
+
+ for (const [folder, requiredSdk] of Object.entries(SDK_VISIBILITY)) {
+ if (route && route.includes(`/${folder}`)) {
+ return <SdkGuard requiredSdk={requiredSdk}>{title}</SdkGuard>;
+ }
+ }
+
+ return <>{title}</>;
+ },
},
toc: {
backToTop: true,
@@ -56,3 +80,11 @@ export default {
content: null,
},
};
+
+function SdkGuard({ requiredSdk, children }) {
+ const { sdk } = useSdk();
+ if (sdk !== requiredSdk) {
+ return <HiddenItem />;
+ }
+ return <>{children}</>;
+}