The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
feat: updated lit version
ddux3e3a2a096022
diff --git a/CLAUDE.md b/CLAUDE.mdindex 6da40136..616e34b1 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -40,9 +40,15 @@ Traceway is an error tracking and monitoring platform consisting of:- **Purpose**: Lightweight generic CRUD operations for PostgreSQL#### Model Registration (required before use)+All models are registered centrally in `models/models.go` via `models.Init()`:```go-lit.RegisterModel[User](lit.PostgreSQL)+func Init() {+ lit.RegisterModel[User](lit.PostgreSQL)+ lit.RegisterModel[Project](lit.PostgreSQL)+ // ...all models registered here+}```+Repository-local result models (e.g., aggregate structs only used in one repo) can use file-level `init()` instead.#### Naming Conventions- Fields: CamelCase → snake_case (`FirstName` → `first_name`)@@ -60,7 +66,8 @@ All lit functions take `*sql.Tx` as the first argument for transactional consist| `lit.InsertExistingUuid[T](tx, &entity)` | Insert with pre-set UUID || `lit.Select[T](tx, query, args...)` | Retrieve multiple records (returns `[]*T`) || `lit.SelectSingle[T](tx, query, args...)` | Retrieve one record (returns `*T`) |-| `lit.Update[T](tx, &entity, "WHERE id = $1", id)` | Update (WHERE required) |+| `lit.Update[T](tx, &entity, "id = $1", id)` | Update (auto-prepends WHERE) |+| `lit.UpdateNative(tx, "UPDATE table SET col = $1 WHERE ...", args...)` | Raw SQL update for partial/single-field changes || `lit.Delete(tx, "DELETE FROM table WHERE id = $1", id)` | Delete records |#### Transaction Helper (`pgdb.ExecuteTransaction`)@@ -77,17 +84,17 @@ project, err := pgdb.ExecuteTransaction(func(tx *sql.Tx) (*models.Project, error})```-#### Transactional Middleware (`pgdb.Transactional`)-For auth flows and routes requiring transaction context throughout the request lifecycle, use the `Transactional()` middleware:+#### Transactional Middleware (`middleware.Transactional`)+For auth flows and routes requiring transaction context throughout the request lifecycle, use the `Transactional` middleware:```go// In routes.go - wrap routes that need transaction context-api.POST("/register", pgdb.Transactional(), authController.Register)-api.POST("/login", pgdb.Transactional(), authController.Login)+api.POST("/register", middleware.Transactional, authController.Register)+api.POST("/login", middleware.Transactional, authController.Login)// In controller - retrieve transaction from Gin contextfunc (c *AuthController) Register(ctx *gin.Context) {- tx := pgdb.GetTx(ctx) // Get transaction from context+ tx := middleware.GetTx(ctx) // Get transaction from context// Use tx for all repository callsuser, err := repositories.UserRepository.FindByEmail(tx, email)@@ -163,10 +170,8 @@ type CountResult struct {Count int `lit:"count"`}-// Register the model (in init or startup)-func init() {- lit.RegisterModel[CountResult](lit.PostgreSQL)-}+// Register in models.Init() (or file-level init() if repo-local)+lit.RegisterModel[CountResult](lit.PostgreSQL)// Use in repositoryfunc (r *userRepository) CountByOrganization(tx *sql.Tx, orgID uuid.UUID) (int, error) {@@ -490,21 +495,126 @@ backend/│ └── pg/ # PostgreSQL migrations```+### Middleware Chain Composition++| Route Type | Middleware Chain |+|-----------|-----------------|+| Read-only telemetry | `UseAppAuth, RequireProjectAccess` |+| Write telemetry | `UseAppAuth, RequireProjectAccess, RequireWriteAccess` |+| PostgreSQL CRUD (read) | `UseAppAuth, RequireProjectAccess, Transactional` |+| PostgreSQL CRUD (write) | `UseAppAuth, RequireProjectAccess, RequireWriteAccess, Transactional` |+| Admin org management | `UseAppAuth, RequireAdminAccess, Transactional` |+| Public (auth/invitations) | `Transactional` only |+| Client SDK ingestion | `CORSReport, UseClientAuth, UseGzip` |+### API Endpoints+**Client SDK Ingestion**| Method | Endpoint | Auth | Purpose ||--------|----------|------|---------|| POST | `/api/report` | Client | Telemetry ingestion (gzipped) |+| POST | `/api/otel/v1/traces` | Client | OTLP/HTTP trace ingestion |+| POST | `/api/otel/v1/metrics` | Client | OTLP/HTTP metric ingestion |++**Auth & Registration**+| Method | Endpoint | Auth | Purpose |+|--------|----------|------|---------|| POST | `/api/login` | None | Dashboard authentication |+| POST | `/api/register` | None | New user registration |+| GET | `/api/has-organizations` | None | Check if any orgs exist (self-hosted only) |+| POST | `/api/forgot-password` | None | Request password reset email |+| GET | `/api/password-reset/:token` | None | Validate reset token |+| POST | `/api/password-reset/:token` | None | Reset password with token |++**Projects**+| Method | Endpoint | Auth | Purpose |+|--------|----------|------|---------|| GET | `/api/projects` | App | List projects |-| POST | `/api/projects` | App | Create project |+| POST | `/api/projects` | App+Write | Create project |+| POST | `/api/projects/source-map-token` | App+Write | Generate source map upload token |++**Dashboard**+| Method | Endpoint | Auth | Purpose |+|--------|----------|------|---------|| 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 |+| POST | `/api/stats` | App | Homepage stats |++**Metrics**+| Method | Endpoint | Auth | Purpose |+|--------|----------|------|---------|+| GET | `/api/metrics/application` | App | Application metrics |+| GET | `/api/metrics/stats` | App | Stats metrics |+| GET | `/api/metrics/server` | App | Server metrics |+| POST | `/api/metrics/query` | App | Custom metric queries |+| GET | `/api/metrics/discover` | App | Discover available metrics |+| GET | `/api/metrics/discover/tags` | App | Discover metric tags |+| PUT | `/api/metrics/registry` | App+Write | Update metric registry entry |++**Widget Groups & Widgets**+| Method | Endpoint | Auth | Purpose |+|--------|----------|------|---------|+| GET | `/api/widget-groups` | App | List widget groups |+| POST | `/api/widget-groups` | App+Write | Create widget group |+| GET | `/api/widget-groups/:id` | App | Get group with widgets |+| PUT | `/api/widget-groups/:id` | App+Write | Update widget group |+| DELETE | `/api/widget-groups/:id` | App+Write | Delete widget group |+| POST | `/api/widget-groups/:id/widgets` | App+Write | Add widget |+| PUT | `/api/widget-groups/:id/widgets/:wid` | App+Write | Update widget |+| PUT | `/api/widget-groups/:id/widgets/:wid/move` | App+Write | Reorder widget |+| DELETE | `/api/widget-groups/:id/widgets/:wid` | App+Write | Delete widget |++**Endpoints**+| Method | Endpoint | Auth | Purpose |+|--------|----------|------|---------|+| POST | `/api/endpoints` | App | List all endpoints |+| POST | `/api/endpoints/grouped` | App | Endpoint aggregates (P50/P95/P99) |+| POST | `/api/endpoints/endpoint` | App | Single endpoint details |+| POST | `/api/endpoints/chart` | App | Stacked chart data |+| GET | `/api/endpoints/slow` | App | Get slow endpoint threshold |+| POST | `/api/endpoints/slow` | App+Write | Set slow endpoint threshold |+| POST | `/api/endpoints/:endpointId` | App | Endpoint detail view |++**Tasks**+| Method | Endpoint | Auth | Purpose |+|--------|----------|------|---------|+| POST | `/api/tasks` | App | List all tasks |+| POST | `/api/tasks/grouped` | App | Grouped by task name |+| POST | `/api/tasks/task` | App | Single task details |+| POST | `/api/tasks/:taskId` | App | Task detail view |++**Exceptions**+| Method | Endpoint | Auth | Purpose |+|--------|----------|------|---------|+| POST | `/api/exception-stack-traces` | App | Grouped exception list |+| POST | `/api/exception-stack-traces/archive` | App+Write | Archive exceptions |+| POST | `/api/exception-stack-traces/unarchive` | App+Write | Unarchive exceptions |+| POST | `/api/exception-stack-traces/by-id/:exceptionId` | App | Single exception by ID |+| POST | `/api/exception-stack-traces/:hash` | App | Exception by hash |++**Organization Management**+| Method | Endpoint | Auth | Purpose |+|--------|----------|------|---------|+| GET | `/api/organizations/:orgId/settings` | Admin | Get org settings |+| PUT | `/api/organizations/:orgId/settings` | Admin | Update org settings |+| GET | `/api/organizations/:orgId/members` | Admin | List members |+| PUT | `/api/organizations/:orgId/members/:userId` | Admin | Update member role |+| DELETE | `/api/organizations/:orgId/members/:userId` | Admin | Remove member |++**Invitations**+| Method | Endpoint | Auth | Purpose |+|--------|----------|------|---------|+| POST | `/api/organizations/:orgId/invitations` | Admin | Send invitation |+| GET | `/api/organizations/:orgId/invitations` | Admin | List invitations |+| DELETE | `/api/organizations/:orgId/invitations/:id` | Admin | Revoke invitation |+| GET | `/api/invitations/:token` | None | Get invitation info |+| POST | `/api/invitations/:token/accept` | None | Accept (new user) |+| POST | `/api/invitations/:token/accept-existing` | App | Accept (existing user) |++**Source Maps**+| Method | Endpoint | Auth | Purpose |+|--------|----------|------|---------|+| POST | `/api/sourcemaps/upload` | SourceMap | Upload source map file |### Data Ingestion Flow (`/api/report`)@@ -544,6 +654,16 @@ func (c *ReportController) Report(ctx *gin.Context) {| `organizations` | Multi-tenant organizations || `organization_users` | Junction table linking users to organizations with roles || `projects` | Project config + tokens, linked to organizations |+| `invitations` | Team invitations with token, role, expiry |+| `source_maps` | Uploaded source map files (project, version, storage key) |+| `metric_registry` | Custom metric definitions (type, unit, description) |+| `widget_groups` | Dashboard widget groups (name, default flag) |+| `widget_group_widgets` | Individual widgets within groups (type, config, position) |++#### ClickHouse vs PostgreSQL Decision Guide+- **PostgreSQL**: Relational/config data needing ACID, frequent updates, JOINs, low volume (users, organizations, projects, invitations, widgets, source maps, metric registry)+- **ClickHouse**: High-volume append-only telemetry with time-series aggregations, batch inserts only (transactions, exceptions, metric points, spans, tasks, sessions)+- Rule of thumb: "Will this data be updated after creation?" → PostgreSQL. "Is this immutable, time-stamped, high-volume data queried with aggregations?" → ClickHouse.#### Organization Roles| Role | Description |@@ -701,9 +821,14 @@ if err != nil {}```+**Validation error conventions:**+- `400 Bad Request`: Malformed requests, missing required params, type errors+- `422 Unprocessable Entity`: Business validation in form dialogs (name too long, duplicate name, required field empty). Return `c.JSON(422, gin.H{"error": "descriptive message"})`. The frontend `api.ts` extracts 422 error messages — dialogs catch and display them inline.+**Summary:**- **Stopping errors** (abort the request): `c.AbortWithError(status, traceway.NewStackTraceErrorf("reason: %w", err))`- **Non-stopping errors** (continue serving): `traceway.CaptureException(fmt.Errorf("reason: %w", err))`+- **Validation errors** (user-facing): `c.JSON(422, gin.H{"error": "message"})` for form validation- **Always** wrap errors with `traceway.NewStackTraceErrorf` or `fmt.Errorf` using `%w` — never discard the original error---@@ -979,22 +1104,89 @@ The SDK sends data as gzipped JSON:5. **Add frontend API call** in `frontend/src/lib/api.ts` or directly in page+**POST body convention:** List/search endpoints use POST with a JSON body containing filters and pagination:+```go+type ListRequest struct {+ ProjectId string `json:"projectId"`+ FromDate string `json:"fromDate"`+ ToDate string `json:"toDate"`+ OrderBy string `json:"orderBy"`+ Search string `json:"search"`+ Pagination PaginationParams `json:"pagination"`+}+```++**Paginated response:** Use `PaginatedResponse[T]` from `routes.go` for all paginated endpoints:+```go+type PaginatedResponse[T any] struct {+ Data []T `json:"data"`+ Pagination Pagination `json:"pagination"`+}++type Pagination struct {+ Page int `json:"page"`+ PageSize int `json:"pageSize"`+ Total int64 `json:"total"`+ TotalPages int64 `json:"totalPages"`+}++type PaginationParams struct {+ Page int `json:"page" binding:"min=1"`+ PageSize int `json:"pageSize" binding:"min=1,max=100"`+}+```+### Adding a New Frontend Page1. **Create route folder**: `frontend/src/routes/new-page/`-2. **Add page component**: `+page.svelte`+2. **Add page component**: `+page.svelte` with the standard loading pattern:```svelte<script lang="ts">- let data = $state<DataType[]>([])+ import { onMount } from 'svelte'+ import { api } from '$lib/api'+ import { projectsState } from '$lib/state/projects.svelte'+ import { ErrorDisplay } from '$lib/components/ui/error-display'- $effect(() => {- loadData()- })+ let data = $state<DataType[]>([])+ let loading = $state(true)+ let error = $state('')+ let notFound = $state(false)++ async function loadData() {+ loading = true+ error = ''+ try {+ const response = await api.post<ResponseType>('/endpoint', payload, {+ projectId: projectsState.currentProjectId ?? undefined+ })+ data = response.data || []+ } catch (e: any) {+ if (e.status === 404) {+ notFound = true+ } else {+ error = e.message || 'Failed to load data'+ }+ } finally {+ loading = false+ }+ }++ onMount(() => { loadData() })</script>++ {#if loading}+ <LoadingCircle size="xlg" />+ {:else if notFound}+ <ErrorDisplay status={404} title="Not Found" description="..." onRetry={() => loadData()} />+ {:else if error}+ <ErrorDisplay status={400} title="Error" description={error} onRetry={() => loadData()} />+ {:else}+ <!-- Content -->+ {/if}```-3. **Add data loading** (optional): `+page.ts`+3. **Add data loading** (optional): `+page.ts` for URL params```typescriptexport const load = async ({ params }) => {return { param: params.id }diff --git a/backend/app/models/models.go b/backend/app/models/models.goindex 2fee2710..50455721 100644--- a/backend/app/models/models.go+++ b/backend/app/models/models.go@@ -1,7 +1,7 @@package modelsimport (- "github.com/tracewayapp/go-lightning/lit"+ "github.com/tracewayapp/lit")var ExtensionModelRegistrations []func()diff --git a/backend/app/repositories/invitation.repository.go b/backend/app/repositories/invitation.repository.goindex 4eb896fc..abf9ba95 100644--- a/backend/app/repositories/invitation.repository.go+++ b/backend/app/repositories/invitation.repository.go@@ -6,7 +6,7 @@ import ("time""github.com/google/uuid"- "github.com/tracewayapp/go-lightning/lit"+ "github.com/tracewayapp/lit")type invitationRepository struct{}diff --git a/backend/app/repositories/metric_registry.repository.go b/backend/app/repositories/metric_registry.repository.goindex b0ebdad2..df50fe01 100644--- a/backend/app/repositories/metric_registry.repository.go+++ b/backend/app/repositories/metric_registry.repository.go@@ -7,7 +7,7 @@ import ("time""github.com/google/uuid"- "github.com/tracewayapp/go-lightning/lit"+ "github.com/tracewayapp/lit")type metricRegistryRepository struct {diff --git a/backend/app/repositories/organization.repository.go b/backend/app/repositories/organization.repository.goindex 61a1b750..08946cfb 100644--- a/backend/app/repositories/organization.repository.go+++ b/backend/app/repositories/organization.repository.go@@ -5,7 +5,7 @@ import ("database/sql""time"- "github.com/tracewayapp/go-lightning/lit"+ "github.com/tracewayapp/lit")type organizationRepository struct{}diff --git a/backend/app/repositories/project.repository.go b/backend/app/repositories/project.repository.goindex eb8a3320..b6602dcd 100644--- a/backend/app/repositories/project.repository.go+++ b/backend/app/repositories/project.repository.go@@ -8,7 +8,7 @@ import ("time""github.com/google/uuid"- "github.com/tracewayapp/go-lightning/lit"+ "github.com/tracewayapp/lit")type projectRepository struct{}diff --git a/backend/app/repositories/source_map.repository.go b/backend/app/repositories/source_map.repository.goindex e33203b3..3669cdc0 100644--- a/backend/app/repositories/source_map.repository.go+++ b/backend/app/repositories/source_map.repository.go@@ -6,7 +6,7 @@ import ("time""github.com/google/uuid"- "github.com/tracewayapp/go-lightning/lit"+ "github.com/tracewayapp/lit")type sourceMapRepository struct{}diff --git a/backend/app/repositories/user.repository.go b/backend/app/repositories/user.repository.goindex 4b68cd56..905975f6 100644--- a/backend/app/repositories/user.repository.go+++ b/backend/app/repositories/user.repository.go@@ -5,7 +5,7 @@ import ("database/sql""time"- "github.com/tracewayapp/go-lightning/lit"+ "github.com/tracewayapp/lit")type userRepository struct{}diff --git a/backend/app/repositories/widget_group.repository.go b/backend/app/repositories/widget_group.repository.goindex d7412bfe..c2620e2e 100644--- a/backend/app/repositories/widget_group.repository.go+++ b/backend/app/repositories/widget_group.repository.go@@ -5,7 +5,7 @@ import ("database/sql""github.com/google/uuid"- "github.com/tracewayapp/go-lightning/lit"+ "github.com/tracewayapp/lit")type widgetGroupRepository struct{}diff --git a/backend/go.mod b/backend/go.modindex 47c9885d..c85f8f3c 100644--- a/backend/go.mod+++ b/backend/go.mod@@ -10,13 +10,13 @@ require (github.com/coreos/go-systemd/v22 v22.6.0github.com/golang-jwt/jwt/v5 v5.3.0github.com/lib/pq v1.10.9- github.com/tracewayapp/go-lightning/lit v0.0.0-20260121181925-c304b0bdd0dc- go.tracewayapp.com v0.4.3+ go.tracewayapp.com v1.0.1go.tracewayapp.com/tracewaygin v0.4.3)require (github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.2 // indirect+ github.com/tracewayapp/lit v1.0.1 // indirectgoogle.golang.org/genproto/googleapis/api v0.0.0-20250825161204-c5933d9347a5 // indirectgoogle.golang.org/genproto/googleapis/rpc v0.0.0-20250825161204-c5933d9347a5 // indirectgoogle.golang.org/grpc v1.75.1 // indirectdiff --git a/backend/go.sum b/backend/go.sumindex a1937951..0a22123d 100644--- a/backend/go.sum+++ b/backend/go.sum@@ -200,8 +200,10 @@ github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29ogithub.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=github.com/tidwall/pretty v1.0.0/go.mod h1:XNkn88O1ChpSDQmQeStsy+sBenx6DDtFZJxhVysOjyk=-github.com/tracewayapp/go-lightning/lit v0.0.0-20260121181925-c304b0bdd0dc h1:NP15gcFZyggjUvxiBIQPGMtD4tkJZ2lhHpEn9i3drJY=-github.com/tracewayapp/go-lightning/lit v0.0.0-20260121181925-c304b0bdd0dc/go.mod h1:Pm1robXO3m2YLD1ImsuYVc0iDdg6r9eS6NXWQIMglRQ=+github.com/tracewayapp/lit v0.0.0-20260121181925-c304b0bdd0dc h1:NP15gcFZyggjUvxiBIQPGMtD4tkJZ2lhHpEn9i3drJY=+github.com/tracewayapp/lit v0.0.0-20260121181925-c304b0bdd0dc/go.mod h1:Pm1robXO3m2YLD1ImsuYVc0iDdg6r9eS6NXWQIMglRQ=+github.com/tracewayapp/lit v1.0.1 h1:l3cNBytH8DuO/oAQ82EldraJ/gWtl1Uhdpfxm6kUZnE=+github.com/tracewayapp/lit v1.0.1/go.mod h1:6jyNfEHuT5vwjSdHWhUO3uunyC0UulFeJdn6DKkxkMY=github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=github.com/ugorji/go/codec v1.3.0 h1:Qd2W2sQawAfG8XSvzwhBeoGq71zXOC/Q1E9y/wUcsUA=