The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
better claude support
dduxcd9227bb207b
diff --git a/CLAUDE.md b/CLAUDE.mdnew file mode 100644index 00000000..31539376--- /dev/null+++ b/CLAUDE.md@@ -0,0 +1,240 @@+# CLAUDE.md - Traceway Project++This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.++## Project Overview++Traceway is an error tracking and monitoring platform consisting of:+- **Frontend**: SvelteKit 5 dashboard application+- **Backend**: Go/Gin API server with ClickHouse database+- **Go Client**: Distributed tracing SDK for Go applications++## Quick Reference++### Development Commands+| Component | Command | Description |+|-----------|---------|-------------|+| Frontend | `cd frontend && npm run dev` | Dev server (port 5173) |+| 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 |++### 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 (`/frontend`)++### Architecture+- **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++### Key Patterns++#### State Management (Svelte 5 Runes)+```typescript+// Use $state() for reactive state+let data = $state<Type>(initial)++// Use $derived() for computed values+let computed = $derived(expression)++// Use $effect() for side effects+$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++#### API Client (`src/lib/api.ts`)+- Auto-includes Authorization header+- Auto-includes projectId in requests+- 401 responses trigger logout + redirect to /login++### 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+```++### UI Components+Location: `src/lib/components/ui/*`+Uses shadcn-svelte registry with bits-ui primitives++---++## Backend (`/backend`)++### Architecture+- **Framework**: Gin Gonic HTTP framework+- **Database**: ClickHouse (columnar OLAP)+- **Port**: 8082+- **Pattern**: Repository pattern with singleton controllers++### Project Structure+```+backend/+├── main.go # Entry point+├── 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+```++### 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 |++### Authentication+Two-tier system:+1. **Client Auth**: Project bearer tokens (for SDK telemetry)+2. **App Auth**: APP_TOKEN env var (for dashboard)++### Environment Variables+```+APP_TOKEN=<dashboard auth token>+CLICKHOUSE_SERVER=localhost:9000+CLICKHOUSE_DATABASE=traceway+CLICKHOUSE_USERNAME=default+CLICKHOUSE_PASSWORD=+CLICKHOUSE_TLS=false+```++### 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++### 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++---++## Go Client SDK (`/clients/go-client`)++### Purpose+Distributed tracing SDK for Go applications. Captures:+- HTTP transactions (endpoint, duration, status code)+- Exceptions/panics with stack traces+- System metrics (CPU, memory, goroutines)++### Installation+```go+import (+ "traceway"+ "traceway/traceway_gin"+)+```++### Gin Integration+```go+router := gin.Default()+traceway_gin.Use(router, "myapp", "token@http://host:8082/api/report")+```++### Manual Capture+```go+// Metrics+traceway.CaptureMetric("custom.metric", 42.0)++// Exceptions+traceway.CaptureException(err)+traceway.CaptureExceptionWithScope(err, scope)++// Panic recovery+defer traceway.Recover()+```++### Scope (Contextual Tags)+```go+// Global scope+traceway.ConfigureScope(func(s *traceway.Scope) {+ s.SetTag("environment", "production")+})++// Request scope (Gin)+scope := traceway_gin.GetScopeFromGin(c)+scope.SetTag("user_id", "123")+```++### Configuration Options+```go+traceway.Init(app, connString,+ traceway.WithDebug(true),+ traceway.WithMaxCollectionFrames(20),+ traceway.WithCollectionInterval(10 * time.Second),+ traceway.WithUploadTimeout(3 * time.Second),+)+```++### 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++---++## 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++### 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 responsediff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.mddeleted file mode 100644index 97e183ae..00000000--- a/frontend/CLAUDE.md+++ /dev/null@@ -1,100 +0,0 @@-# CLAUDE.md--This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.--## Project Overview--This is the frontend for Traceway, an error tracking and monitoring application. Built with SvelteKit 2 using Svelte 5's new runes API, styled with Tailwind CSS v4, and uses shadcn-svelte for UI components.--## Build & Development Commands--```bash-# Development server-npm run dev--# Production build (outputs to /build with static adapter)-npm run build--# Preview production build locally-npm run preview--# Type checking-npm run check-npm run check:watch--# Linting & formatting-npm run lint # Check formatting and run ESLint-npm run format # Format all files with Prettier-```--## Architecture--### SvelteKit Configuration-- **SSR disabled**: `ssr = false` in routes/+layout.ts-- **Prerendering enabled**: `prerender = true` for static site generation-- **Adapter**: Uses `@sveltejs/adapter-static` with `fallback: 'index.html'` for SPA behavior-- **API Proxy**: Vite dev server proxies `/api` requests to `http://localhost:8082`--### State Management (Svelte 5 Runes)-The app uses Svelte 5's new runes-based reactivity system instead of stores:--- **`src/lib/state/auth.svelte.ts`**: Authentication state using `$state` rune- - Token stored in localStorage as `APP_TOKEN`- - `$effect` for localStorage synchronization- - `isAuthenticated` derived state using `$derived`--- **`src/lib/state/theme.svelte.ts`**: Theme state management- - Tracks dark/light mode with DOM class observation- - Persists to localStorage- - Functions: `initTheme()`, `toggleTheme()`--### API Client (`src/lib/api.ts`)-Centralized API wrapper that:-- Prefixes all requests with `/api`-- Auto-includes Authorization header from authState-- Handles 401s by logging out and redirecting to `/login`-- Exports methods: `api.get()`, `api.post()`, `api.put()`, `api.delete()`--### Layout & Navigation-- **Root layout** (`src/routes/+layout.svelte`): Conditionally renders sidebar for authenticated users- - Unauthenticated users see full-screen content (login page)- - Authenticated users get sidebar + header with theme toggle and logout-- **Sidebar** (`src/lib/components/app-sidebar.svelte`): Navigation with theme-aware logo switching--### UI Components-Uses shadcn-svelte with configuration in `components.json`:-- Component path: `src/lib/components/ui/*`-- Registry: https://shadcn-svelte.com/registry-- Aliases configured: `$lib/components`, `$lib/utils`, `$lib/components/ui`, `$lib/hooks`--## Key Patterns--### Svelte 5 Runes-This codebase uses Svelte 5's modern reactivity:-- Use `$state()` for reactive state (not `writable()` stores)-- Use `$derived()` for computed values (not `derived()` stores)-- Use `$effect()` for side effects (not `$:` reactive statements)-- Use `{@render children()}` syntax in layouts--### Component Imports-```typescript-// UI components use namespace imports-import * as Sidebar from "$lib/components/ui/sidebar";--// Icons from lucide-svelte-import { Sun, Moon, LogOut } from "@lucide/svelte";-```--### Authentication Flow-1. Token stored in `authState.token`-2. API client auto-includes token in Authorization header-3. 401 responses trigger automatic logout + redirect to `/login`-4. Layout conditionally shows sidebar based on `authState.isAuthenticated`--## Routes-- `/` - Root page (redirects or shows dashboard based on auth)-- `/login` - Login page (public)-- `/issues` - Issues dashboard (protected)--## Backend Integration-Backend runs on `localhost:8082` during development. All API requests go through `/api` prefix which Vite proxies in dev mode.