Skip to content

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

Had claude-code update the CLAUDE.md file with the current setup and common components hopefully leading to better default code generation

dduxa5baf4f14324
diff --git a/CLAUDE.md b/CLAUDE.md
index 9ddf8fea..0281119d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5,11 +5,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview
Traceway is an error tracking and monitoring platform consisting of:
-- **Frontend**: SvelteKit 5 dashboard application
+- **Frontend**: SvelteKit 2 dashboard application with Svelte 5
- **Backend**: Go/Gin API server with ClickHouse database
-- **Go Client**: Distributed tracing SDK for Go applications
+- **Go Client SDK**: Distributed tracing SDK for Go applications (external repo)
-## Quick Reference
+---
+
+## Quick Start
### Development Commands
| Component | Command | Description |
@@ -18,26 +20,69 @@ Traceway is an error tracking and monitoring platform consisting of:
| Frontend | `npm run build` | Production build |
| Frontend | `npm run check` | TypeScript checking |
| Backend | `cd backend && go run .` | API server (port 8082) |
-| Client | `cd clients/go-client && go build ./...` | Build SDK |
+| Go Client | External repo at `/Users/dusanstanojevic/Documents/workspace/go-client` | Build with `go build ./...` |
### Tech Stack
-- Frontend: SvelteKit 2.49, Svelte 5.45, Tailwind 4, shadcn-svelte
-- Backend: Go 1.25, Gin 1.11, ClickHouse
-- Client SDK: Go 1.25, Gin middleware
+- **Frontend**: SvelteKit 2.49, Svelte 5.45, Tailwind CSS v4, shadcn-svelte, Vite 7
+- **Backend**: Go 1.25, Gin 1.11, ClickHouse
+- **Client SDK**: Go 1.25, Gin middleware support
+
+### Environment Variables (Backend)
+```
+APP_TOKEN=<dashboard auth token>
+CLICKHOUSE_SERVER=localhost:9000
+CLICKHOUSE_DATABASE=traceway
+CLICKHOUSE_USERNAME=default
+CLICKHOUSE_PASSWORD=
+CLICKHOUSE_TLS=false
+```
+
+---
+
+## Architecture Overview
+
+### Data Flow
+```
+Go Application → [traceway SDK] → GZIP POST /api/report → Backend → ClickHouse
+ ↓
+Dashboard ← [SvelteKit Frontend] ← JSON API ← Gin Controllers
+```
+
+### Authentication
+Two-tier system:
+1. **Client Auth**: Project bearer tokens (SDK telemetry via `Authorization: Bearer <token>`)
+2. **App Auth**: `APP_TOKEN` env var (dashboard authentication)
---
## Frontend (`/frontend`)
-### Architecture
+### Framework & Build
- **Framework**: SvelteKit 2 with Svelte 5 runes API
- **Styling**: Tailwind CSS v4 with shadcn-svelte components
- **Build**: Vite 7, static adapter with SPA fallback
-- **SSR**: Disabled - pure client-side SPA
+- **SSR**: Disabled - pure client-side SPA (`ssr = false` in `+layout.ts`)
+
+### Project Structure
+```
+frontend/
+├── src/
+│ ├── routes/ # SvelteKit pages
+│ ├── lib/
+│ │ ├── api.ts # API client with auth
+│ │ ├── state/ # Svelte 5 state management
+│ │ ├── components/
+│ │ │ ├── ui/ # shadcn-svelte base components
+│ │ │ └── traceway/ # Custom Traceway components
+│ │ └── utils/ # Helpers (formatting, sorting)
+│ └── app.css # Tailwind + global styles
+├── static/ # Static assets
+└── svelte.config.js # SvelteKit config
+```
-### Key Patterns
+### State Management (Svelte 5 Runes)
-#### State Management (Svelte 5 Runes)
+#### Runes Pattern
```typescript
// Use $state() for reactive state
let data = $state<Type>(initial)
@@ -50,31 +95,120 @@ $effect(() => { /* reactive code */ })
```
#### State Files
-- `src/lib/state/auth.svelte.ts` - Token auth, localStorage sync
-- `src/lib/state/projects.svelte.ts` - Multi-project management
-- `src/lib/state/theme.svelte.ts` - Dark/light mode
+| File | Purpose | Persistence |
+|------|---------|-------------|
+| `src/lib/state/auth.svelte.ts` | Token auth, login/logout | localStorage |
+| `src/lib/state/projects.svelte.ts` | Multi-project management | localStorage |
+| `src/lib/state/theme.svelte.ts` | Dark/light mode toggle | localStorage |
+| `src/lib/state/timezone.svelte.ts` | UTC/local timezone toggle | localStorage |
+
+#### Singleton Pattern
+State files export class instances as singletons:
+```typescript
+// src/lib/state/auth.svelte.ts
+class AuthState {
+ token = $state<string | null>(null)
+ isAuthenticated = $derived(!!this.token)
+
+ constructor() {
+ // Load from localStorage on init
+ this.token = localStorage.getItem('token')
+ }
+}
+export const authState = new AuthState()
+```
+
+### API Client (`src/lib/api.ts`)
+
+The API client automatically:
+- Includes `Authorization: Bearer <token>` header
+- Includes `projectId` in POST request bodies
+- Handles 401 responses by logging out and redirecting to `/login`
-#### API Client (`src/lib/api.ts`)
-- Auto-includes Authorization header
-- Auto-includes projectId in requests
-- 401 responses trigger logout + redirect to /login
+```typescript
+// Usage
+const data = await api.post<ResponseType>('/endpoint', { body })
+const data = await api.get<ResponseType>('/endpoint')
+```
+
+### Component Patterns
+
+#### Table System
+Tables use shadcn-svelte base components with custom Traceway wrappers:
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `Table`, `TableHeader`, etc. | `src/lib/components/ui/table/` | Base shadcn components |
+| `TracewayTableHeader` | `src/lib/components/traceway/traceway-table-header.svelte` | Adds sorting + tooltips |
+| `TableEmptyState` | `src/lib/components/traceway/table-empty-state.svelte` | Empty state display |
+| `PaginationFooter` | `src/lib/components/traceway/pagination-footer.svelte` | Pagination controls |
+
+#### Sorting Storage
+Table sorting persists to localStorage using a consistent pattern:
+
+```typescript
+// Key format: traceway_sort_{pageKey}
+// Example: traceway_sort_issues, traceway_sort_transactions
+
+// In +page.svelte
+let orderBy = $state(loadSortFromStorage('issues', 'last_seen desc'))
+
+// After sort change
+function handleSortClick(column: string) {
+ orderBy = handleSortClickUtil(orderBy, column, 'issues')
+}
+```
+
+The `handleSortClick` utility (`src/lib/utils/sorting.ts`):
+1. Toggles sort direction if same column
+2. Defaults to descending for new column
+3. Saves to localStorage
+4. Returns new `orderBy` string in backend format: `"column_name asc|desc"`
+
+#### TracewayTableHeader Component
+```svelte
+<TracewayTableHeader
+ label="Last Seen"
+ column="last_seen"
+ tooltip="When this issue was last reported"
+ {orderBy}
+ onclick={() => handleSortClick('last_seen')}
+/>
+```
+
+### URL State Management
+
+Time range and filters persist in URL query params:
+```typescript
+// src/lib/utils/url-state.ts
+// Presets: 1h, 6h, 24h, 7d, 30d, custom
+
+// Reading from URL
+const range = getTimeRangeFromUrl(url.searchParams)
+
+// Updating URL (preserves other params)
+goto(updateUrlWithTimeRange(url, newRange))
+```
### Routes
```
-/ Dashboard (protected)
-/login Login page (public)
-/issues Issues list with filtering
-/issues/[hash] Exception details
-/issues/[hash]/events Exception events timeline
-/transactions Endpoint analytics
-/transactions/[endpoint] Endpoint details
-/metrics System metrics dashboard
-/connection SDK integration guide
+/ Dashboard (protected) - overview metrics
+/login Login page (public)
+/issues Issues list with filtering/sorting
+/issues/[hash] Exception details view
+/issues/[hash]/events Exception events timeline
+/transactions Endpoint analytics with P50/P95/P99
+/transactions/[endpoint] Single endpoint details
+/metrics System metrics dashboard (CPU, memory, etc.)
+/connection SDK integration guide
```
### UI Components
Location: `src/lib/components/ui/*`
-Uses shadcn-svelte registry with bits-ui primitives
+Uses shadcn-svelte registry with bits-ui primitives. Key components:
+- `button`, `card`, `table`, `badge`, `tooltip`
+- `select`, `input`, `checkbox`
+- `sheet` (slide-out panels), `dialog` (modals)
---
@@ -82,171 +216,540 @@ Uses shadcn-svelte registry with bits-ui primitives
### Architecture
- **Framework**: Gin Gonic HTTP framework
-- **Database**: ClickHouse (columnar OLAP)
+- **Database**: ClickHouse (columnar OLAP database)
- **Port**: 8082
- **Pattern**: Repository pattern with singleton controllers
### Project Structure
```
backend/
-├── main.go # Entry point
+├── main.go # Entry point, DB init, server start
├── app/
-│ ├── controllers/ # API handlers
-│ │ ├── routes.go # Route registration
-│ │ └── clientcontrollers/ # Telemetry ingestion
-│ ├── repositories/ # ClickHouse queries
-│ ├── models/ # Data structures
-│ ├── middleware/ # Auth, gzip
-│ ├── cache/ # In-memory project cache
-│ └── migrations/ch/ # Database migrations
+│ ├── controllers/
+│ │ ├── routes.go # Route registration
+│ │ ├── dashboard.go # Dashboard metrics
+│ │ ├── auth.go # Login handler
+│ │ ├── projects.go # Project CRUD
+│ │ └── clientcontrollers/
+│ │ └── report.go # Telemetry ingestion (/api/report)
+│ ├── repositories/ # ClickHouse queries
+│ │ ├── transactions.go
+│ │ ├── exceptions.go
+│ │ ├── metrics.go
+│ │ └── projects.go
+│ ├── models/ # Data structures
+│ ├── middleware/
+│ │ ├── auth.go # Token validation
+│ │ └── gzip.go # Request decompression
+│ ├── cache/ # In-memory project token cache
+│ └── migrations/ch/ # ClickHouse migrations
```
### API Endpoints
+
| Method | Endpoint | Auth | Purpose |
|--------|----------|------|---------|
-| POST | /api/report | Client | Telemetry ingestion |
-| POST | /api/login | None | App authentication |
-| GET/POST | /api/projects | App | Project CRUD |
-| GET | /api/dashboard | App | Dashboard metrics |
-| GET | /api/dashboard/overview | App | Recent issues + endpoints |
-| POST | /api/transactions | App | Transaction search |
-| POST | /api/transactions/grouped | App | Endpoint aggregates |
-| POST | /api/exception-stack-traces | App | Exception search |
+| POST | `/api/report` | Client | Telemetry ingestion (gzipped) |
+| POST | `/api/login` | None | Dashboard authentication |
+| GET | `/api/projects` | App | List projects |
+| POST | `/api/projects` | App | Create project |
+| GET | `/api/dashboard` | App | Dashboard metrics |
+| GET | `/api/dashboard/overview` | App | Recent issues + top endpoints |
+| POST | `/api/transactions` | App | Transaction search |
+| POST | `/api/transactions/grouped` | App | Endpoint aggregates (P50/P95/P99) |
+| POST | `/api/exception-stack-traces` | App | Exception search |
+| POST | `/api/exception-stack-traces/grouped` | App | Grouped exception list |
+| GET | `/api/exception-stack-traces/:hash` | App | Single exception details |
+
+### Data Ingestion Flow (`/api/report`)
+
+1. **Gzip Middleware**: Decompresses request body (SDK sends gzipped data)
+2. **Auth Middleware**: Validates `Authorization: Bearer <project_token>`
+3. **Parse Frame**: JSON decode into `models.Frame` (transactions, exceptions, metrics)
+4. **Batch Insert**: Repository methods insert batches into ClickHouse
-### Authentication
-Two-tier system:
-1. **Client Auth**: Project bearer tokens (for SDK telemetry)
-2. **App Auth**: APP_TOKEN env var (for dashboard)
-
-### Environment Variables
+```go
+// backend/app/controllers/clientcontrollers/report.go
+func (c *ReportController) Report(ctx *gin.Context) {
+ var frame models.Frame
+ ctx.BindJSON(&frame)
+
+ // Insert each data type
+ transactionRepo.BatchInsert(frame.Transactions)
+ exceptionRepo.BatchInsert(frame.Exceptions)
+ metricRepo.BatchInsert(frame.Metrics)
+}
```
-APP_TOKEN=<dashboard auth token>
-CLICKHOUSE_SERVER=localhost:9000
-CLICKHOUSE_DATABASE=traceway
-CLICKHOUSE_USERNAME=default
-CLICKHOUSE_PASSWORD=
-CLICKHOUSE_TLS=false
+
+### Database Schema
+
+#### Tables
+| Table | Purpose | Partitioning |
+|-------|---------|--------------|
+| `projects` | Multi-tenant project config + tokens | None |
+| `transactions` | HTTP request metadata | Monthly (`toYYYYMM(timestamp)`) |
+| `exception_stack_traces` | Exceptions with stack traces | Monthly |
+| `metric_records` | Time-series system metrics | Monthly |
+| `endpoints` | Endpoint aggregates (materialized) | None |
+| `archived_exceptions` | Archived/resolved exceptions | None |
+
+#### Key Columns - transactions
+```sql
+project_id UUID,
+timestamp DateTime64(3),
+trace_id String,
+endpoint String, -- normalized: "GET /api/users"
+duration_ms Float64,
+status_code UInt16,
+app_version String,
+server_name String,
+-- Indexes: bloom_filter(trace_id), tokenbf_v1(endpoint)
```
-### Database Tables
-- `projects` - Multi-tenant projects with tokens
-- `transactions` - HTTP request metadata (partitioned by month)
-- `metric_records` - Time-series system metrics
-- `exception_stack_traces` - Exceptions with hash grouping
+#### Key Columns - exception_stack_traces
+```sql
+project_id UUID,
+timestamp DateTime64(3),
+hash String, -- normalized hash for grouping
+type String, -- error type (e.g., "RuntimeError")
+value String, -- error message
+stacktrace String, -- full stack trace
+tags Map(String, String), -- contextual tags from scope
+```
### Database Migrations
-**Important**:
-- Each migration file must contain exactly ONE SQL statement
-- Only create `.up.sql` files (no down migrations)
-- Each migration must have a unique numbered name
-Example - Adding two columns requires two separate migrations:
+**CRITICAL RULES:**
+1. Each migration file must contain **exactly ONE SQL statement**
+2. Only create `.up.sql` files (no down migrations)
+3. Use sequential numbering: `NNNN_description.up.sql`
+
+**Why one statement per file?** ClickHouse migration runner executes each file as a single statement. Multiple statements will fail.
+
+**Example - Adding two columns requires TWO files:**
```
-0013_add_app_version_to_transactions.up.sql # ALTER TABLE ... ADD COLUMN app_version
-0014_add_server_name_to_transactions.up.sql # ALTER TABLE ... ADD COLUMN server_name
+backend/app/migrations/ch/
+├── 0013_add_app_version_to_transactions.up.sql
+│ └── ALTER TABLE transactions ADD COLUMN app_version String DEFAULT ''
+├── 0014_add_server_name_to_transactions.up.sql
+│ └── ALTER TABLE transactions ADD COLUMN server_name String DEFAULT ''
```
### Exception Hash Normalization
-The backend normalizes stack traces before hashing:
-- Removes error message content (keeps type only)
-- Removes absolute paths (keeps filename:line)
-- Replaces hex addresses with `<hex>`
-- Replaces UUIDs with `<uuid>`
-- Replaces IPs with `<ip>`
-- Result: Same errors grouped despite different runtime values
+
+The backend normalizes stack traces before hashing to group identical errors despite different runtime values. This happens in `backend/app/repositories/exceptions.go`.
+
+**Normalization Steps:**
+1. Extract error type only (remove error message content)
+2. Remove absolute file paths (keep `filename:line` only)
+3. Replace hexadecimal addresses with `<hex>`
+4. Replace UUIDs with `<uuid>`
+5. Replace IP addresses with `<ip>`
+6. Replace timestamps with `<timestamp>`
+7. Replace numeric IDs in paths with `<id>`
+8. Normalize whitespace
+9. Remove ANSI color codes
+10. Hash the normalized string with SHA-256, truncate to 16 chars
+
+**Result:** Same logical error gets same hash, even if:
+- Error message contains different user IDs
+- Stack trace has different memory addresses
+- File paths differ between environments
+
+### Repository Patterns
+
+#### Singleton Pattern
+```go
+// backend/app/repositories/transactions.go
+var transactionRepoInstance *TransactionRepository
+var transactionRepoOnce sync.Once
+
+func GetTransactionRepository() *TransactionRepository {
+ transactionRepoOnce.Do(func() {
+ transactionRepoInstance = &TransactionRepository{db: GetDB()}
+ })
+ return transactionRepoInstance
+}
+```
+
+#### Batch Insert
+```go
+func (r *TransactionRepository) BatchInsert(txns []models.Transaction) error {
+ batch, _ := r.db.PrepareBatch(ctx, "INSERT INTO transactions ...")
+ for _, txn := range txns {
+ batch.Append(txn.ProjectID, txn.Timestamp, ...)
+ }
+ return batch.Send()
+}
+```
+
+#### Aggregation with Quantiles
+```go
+// P50, P95, P99 percentiles
+query := `
+ SELECT
+ endpoint,
+ count() as count,
+ quantile(0.5)(duration_ms) as p50,
+ quantile(0.95)(duration_ms) as p95,
+ quantile(0.99)(duration_ms) as p99
+ FROM transactions
+ WHERE project_id = ? AND timestamp BETWEEN ? AND ?
+ GROUP BY endpoint
+ ORDER BY count DESC
+`
+```
---
-## Go Client SDK (`/clients/go-client`)
+## Go Client SDK
-### Purpose
-Distributed tracing SDK for Go applications. Captures:
-- HTTP transactions (endpoint, duration, status code)
-- Exceptions/panics with stack traces
-- System metrics (CPU, memory, goroutines)
+**Location:** External repository at `/Users/dusanstanojevic/Documents/workspace/go-client`
+
+The SDK is a separate Go module that applications import to send telemetry to Traceway.
### Installation
```go
import (
- "traceway"
- "traceway/traceway_gin"
+ "github.com/user/traceway" // Core SDK
+ "github.com/user/traceway/traceway_gin" // Gin middleware
)
```
-### Gin Integration
-```go
-router := gin.Default()
-traceway_gin.Use(router, "myapp", "token@http://host:8082/api/report")
+### Connection String Format
```
+<project_token>@<server_url>
+
+Examples:
+abc123@http://localhost:8082/api/report
+abc123@https://traceway.example.com/api/report
+```
+
+### Architecture
+
+#### Ring Buffer Batching
+The SDK uses a ring buffer to batch telemetry data:
+1. Data collected into current "frame" (transactions, exceptions, metrics)
+2. Frame rotates every 5 seconds (configurable via `WithCollectionInterval`)
+3. Completed frames uploaded async via HTTP POST
+4. Failed uploads retry with exponential backoff
+
+#### Data Types Collected
+- **Transactions**: HTTP requests (endpoint, duration, status code)
+- **Exceptions**: Errors/panics with full stack traces
+- **Metrics**: System metrics (CPU, memory, Go runtime)
+
+### Gin Middleware Integration
-### Manual Capture
```go
-// Metrics
-traceway.CaptureMetric("custom.metric", 42.0)
+package main
+
+import (
+ "github.com/gin-gonic/gin"
+ "traceway"
+ "traceway/traceway_gin"
+)
+
+func main() {
+ router := gin.Default()
+
+ // Initialize with app name and connection string
+ traceway_gin.Use(router, "myapp", "token@http://localhost:8082/api/report")
+
+ // Or with options
+ traceway_gin.Use(router, "myapp", "token@http://localhost:8082/api/report",
+ traceway.WithDebug(true),
+ traceway.WithCollectionInterval(10 * time.Second),
+ )
+
+ router.GET("/api/users", getUsers)
+ router.Run(":8080")
+}
+```
+
+The middleware automatically:
+- Tracks request duration and status code
+- Captures endpoint as `"METHOD /path"` (e.g., `"GET /api/users"`)
+- Recovers from panics and reports them as exceptions
+- Attaches request scope for contextual tags
-// Exceptions
+### Capture Methods
+
+#### Exceptions
+```go
+// Basic capture
traceway.CaptureException(err)
+
+// With additional scope
traceway.CaptureExceptionWithScope(err, scope)
-// Panic recovery
+// Panic recovery (use in defer)
defer traceway.Recover()
+
+// Recover with custom scope
+defer traceway.RecoverWithScope(scope)
+```
+
+#### Metrics
+```go
+// Capture custom metric
+traceway.CaptureMetric("custom.metric.name", 42.0)
+
+// Metrics are batched and sent with the next frame
```
-### Scope (Contextual Tags)
+#### Transactions (Manual)
+```go
+// For non-HTTP transactions or custom tracking
+txn := traceway.StartTransaction("operation_name")
+defer txn.End()
+
+// Add segments for sub-operations
+seg := txn.StartSegment("database_query")
+// ... do work ...
+seg.End()
+```
+
+#### Tasks and Segments
+```go
+// Capture a task with duration
+traceway.CaptureTask("background_job", startTime, endTime, nil)
+
+// Measure a function
+result := traceway.MeasureTask("compute", func() interface{} {
+ return heavyComputation()
+})
+
+// Segments within tasks
+traceway.CaptureSegment(taskID, "subtask", startTime, endTime)
+```
+
+### Scope System
+
+Scopes attach contextual tags to exceptions and transactions.
+
+#### Global Scope
```go
-// Global scope
+// Configure tags that apply to all telemetry
traceway.ConfigureScope(func(s *traceway.Scope) {
s.SetTag("environment", "production")
+ s.SetTag("version", "1.2.3")
+ s.SetTag("region", "us-east-1")
})
+```
+
+#### Request Scope (Gin)
+```go
+func handler(c *gin.Context) {
+ // Get request-scoped scope from Gin context
+ scope := traceway_gin.GetScopeFromGin(c)
+
+ // Tags only apply to this request
+ scope.SetTag("user_id", userID)
+ scope.SetTag("tenant", tenantID)
+
+ // Any exceptions captured in this request will include these tags
+}
+```
-// Request scope (Gin)
-scope := traceway_gin.GetScopeFromGin(c)
-scope.SetTag("user_id", "123")
+#### Scope Methods
+```go
+scope.SetTag("key", "value") // Set a single tag
+scope.SetTags(map[string]string{ // Set multiple tags
+ "key1": "value1",
+ "key2": "value2",
+})
+scope.SetUser(userID) // Shorthand for user_id tag
+scope.SetExtra("key", anyValue) // Set extra data (serialized to JSON)
```
### Configuration Options
+
```go
-traceway.Init(app, connString,
+traceway.Init(appName, connectionString,
+ // Debug mode - logs all telemetry to stdout
traceway.WithDebug(true),
+
+ // Max frames to keep in ring buffer (default: 20)
traceway.WithMaxCollectionFrames(20),
- traceway.WithCollectionInterval(10 * time.Second),
+
+ // How often to rotate frames (default: 5s)
+ traceway.WithCollectionInterval(5 * time.Second),
+
+ // HTTP upload timeout (default: 3s)
traceway.WithUploadTimeout(3 * time.Second),
+
+ // Metric collection interval (default: 30s)
+ traceway.WithMetricInterval(30 * time.Second),
+
+ // Disable automatic metric collection
+ traceway.WithMetricsDisabled(),
+
+ // Custom HTTP transport
+ traceway.WithTransport(customTransport),
)
```
-### Default Metrics Collected
-- `cpu.used_pcnt` - CPU percentage
-- `mem.used` - Memory in MB
-- `mem.used_pcnt` - Memory percentage
-- `go.go_routines` - Goroutine count
-- `go.heap_objects` - Heap object count
-- `go.num_gc` - GC cycle count
-- `go.gc_pause` - GC pause time (ns)
-
-### Data Flow
-1. SDK collects data into in-memory ring buffer
-2. Batches into "frames" every 5 seconds (configurable)
-3. GZIP compresses and POSTs to /api/report
-4. Backend normalizes, hashes, stores to ClickHouse
+### Default Collected Metrics
+
+| Metric | Description | Unit |
+|--------|-------------|------|
+| `cpu.used_pcnt` | CPU usage percentage | % |
+| `mem.used` | Memory usage | MB |
+| `mem.used_pcnt` | Memory usage percentage | % |
+| `go.go_routines` | Active goroutine count | count |
+| `go.heap_objects` | Heap object count | count |
+| `go.num_gc` | Total GC cycles | count |
+| `go.gc_pause` | Last GC pause time | nanoseconds |
+
+### Data Format (Frame)
+
+The SDK sends data as gzipped JSON:
+```json
+{
+ "app": "myapp",
+ "transactions": [
+ {
+ "trace_id": "abc123",
+ "endpoint": "GET /api/users",
+ "duration_ms": 45.2,
+ "status_code": 200,
+ "timestamp": "2024-01-15T10:30:00Z"
+ }
+ ],
+ "exceptions": [
+ {
+ "type": "RuntimeError",
+ "value": "connection refused",
+ "stacktrace": "...",
+ "tags": {"user_id": "123"},
+ "timestamp": "2024-01-15T10:30:00Z"
+ }
+ ],
+ "metrics": [
+ {
+ "name": "cpu.used_pcnt",
+ "value": 45.2,
+ "timestamp": "2024-01-15T10:30:00Z"
+ }
+ ]
+}
+```
---
## Common Patterns
### Adding a New API Endpoint
-1. Add model in `backend/app/models/`
-2. Add repository method in `backend/app/repositories/`
-3. Add controller in `backend/app/controllers/`
-4. Register route in `backend/app/controllers/routes.go`
-5. Add frontend API call in `frontend/src/lib/api.ts` or page
+
+1. **Add model** in `backend/app/models/`
+ ```go
+ type NewEntity struct {
+ ID uuid.UUID `json:"id"`
+ Name string `json:"name"`
+ CreatedAt time.Time `json:"created_at"`
+ }
+ ```
+
+2. **Add repository** in `backend/app/repositories/`
+ ```go
+ func (r *NewEntityRepository) GetAll(projectID uuid.UUID) ([]models.NewEntity, error) {
+ // ClickHouse query
+ }
+ ```
+
+3. **Add controller** in `backend/app/controllers/`
+ ```go
+ func (c *NewEntityController) List(ctx *gin.Context) {
+ entities, err := repo.GetAll(projectID)
+ ctx.JSON(200, entities)
+ }
+ ```
+
+4. **Register route** in `backend/app/controllers/routes.go`
+ ```go
+ api.GET("/new-entities", newEntityController.List)
+ ```
+
+5. **Add frontend API call** in `frontend/src/lib/api.ts` or directly in page
### Adding a New Frontend Page
-1. Create folder in `frontend/src/routes/[name]/`
-2. Add `+page.svelte` (component) and `+page.ts` (data loading)
-3. Add navigation link in `app-sidebar.svelte`
-
-### Adding a New Dashboard Metric
-1. Ensure metric is captured by SDK (or add to `traceway.go`)
-2. Add to `MetricRecordRepository` queries
-3. Add to `DashboardController.GetDashboard()`
-4. Frontend auto-renders from API response
+
+1. **Create route folder**: `frontend/src/routes/new-page/`
+
+2. **Add page component**: `+page.svelte`
+ ```svelte
+ <script lang="ts">
+ let data = $state<DataType[]>([])
+
+ $effect(() => {
+ loadData()
+ })
+ </script>
+ ```
+
+3. **Add data loading** (optional): `+page.ts`
+ ```typescript
+ export const load = async ({ params }) => {
+ return { param: params.id }
+ }
+ ```
+
+4. **Add navigation** in `src/lib/components/app-sidebar.svelte`
+
+### Adding a New Metric to Dashboard
+
+1. **Ensure SDK captures metric** (or add to `traceway.go` metrics collection)
+
+2. **Add repository query** in `backend/app/repositories/metrics.go`
+ ```go
+ func (r *MetricRepository) GetNewMetric(projectID uuid.UUID, from, to time.Time) ([]MetricPoint, error) {
+ // Query metric_records table
+ }
+ ```
+
+3. **Add to dashboard controller** in `backend/app/controllers/dashboard.go`
+
+4. **Frontend auto-renders** from API response (metrics dashboard uses dynamic rendering)
+
+### Adding a Database Column
+
+1. **Create migration file** (remember: ONE statement per file!)
+ ```
+ backend/app/migrations/ch/0015_add_new_column.up.sql
+ ```
+ ```sql
+ ALTER TABLE transactions ADD COLUMN new_column String DEFAULT ''
+ ```
+
+2. **Update model** in `backend/app/models/`
+
+3. **Update repository queries** to include new column
+
+4. **Run migrations**: Backend runs migrations automatically on startup
+
+### Adding Table Sorting to a Page
+
+1. **Add state and load from storage**:
+ ```typescript
+ let orderBy = $state(loadSortFromStorage('page-key', 'default_column desc'))
+ ```
+
+2. **Add sort handler**:
+ ```typescript
+ function handleSortClick(column: string) {
+ orderBy = handleSortClickUtil(orderBy, column, 'page-key')
+ }
+ ```
+
+3. **Use TracewayTableHeader**:
+ ```svelte
+ <TracewayTableHeader
+ label="Column"
+ column="column_name"
+ {orderBy}
+ onclick={() => handleSortClick('column_name')}
+ />
+ ```
+
+4. **Pass orderBy to API call** - backend expects format `"column asc"` or `"column desc"`