The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
feat: updated docs
ddux7fd5ae361c92
diff --git a/docs/pages/learn/embedded-mode.mdx b/docs/pages/learn/embedded-mode.mdxindex 76590355..f98f94b5 100644--- a/docs/pages/learn/embedded-mode.mdx+++ b/docs/pages/learn/embedded-mode.mdx@@ -1,45 +1,173 @@# Embedded Mode-Traceway supports running ClickHouse **in-process** using [chdb](https://github.com/chdb-io/chdb) — no external ClickHouse server required.+Embedded mode runs a full Traceway server inside your Go process — using **SQLite** instead of PostgreSQL and **embedded ClickHouse** (via [chdb](https://github.com/chdb-io/chdb)) instead of an external server. No Docker, no infrastructure — just one `cmd.Run()` call and your app has local observability.-This is useful for:+This is intended for **local development only**. For production, use the [Docker Compose](/server/docker-compose) or [minimal](/server/minimal) deployment.-- **Local development** — get started without installing ClickHouse-- **Testing** — spin up an isolated instance per test run-- **Single-node deploys** — run everything in one binary+## Prerequisites-## Install libchdb--The embedded driver requires `libchdb` to be installed on the system. Run the official installer (supports macOS and Linux):+Install `libchdb` (the embedded ClickHouse C library). Supports macOS and Linux:```bashcurl -sL https://lib.chdb.io | bash```-## Building with the tag--The embedded ClickHouse driver is behind a build tag so it doesn't affect normal builds. Pass `-tags chdb` to include it:+All builds that use embedded mode must include the `chdb` build tag:```bashgo build -tags chdb ./...+go run -tags chdb .+```++Without the tag, the binary compiles normally and embedded mode returns an error if requested.++## Quick Start++Add the Traceway server module to your project:++```bash+go get go.tracewayapp.com/server+```++Then call `cmd.Run()` somewhere in your application startup. A common pattern is guarding it behind an environment check so it only runs in development:++```go+package main++import (+ "os"++ "github.com/gin-gonic/gin"+ "go.tracewayapp.com/server/cmd"+ tracewaygin "go.tracewayapp.com/tracewaygin"+)++func main() {+ if os.Getenv("ENV") != "production" {+ go cmd.Run(+ cmd.WithPort(8085),+ cmd.WithDefaultUser("[email protected]", "admin"),+ cmd.WithDefaultProject("Backend", "go", "backend-dev-token"),+ cmd.WithDefaultProject("Frontend", "sveltekit", "frontend-dev-token"),+ )+ }++ router := gin.Default()+ tracewaygin.Use(router, "backend-dev-token@http://localhost:8085/api/report")++ router.GET("/ping", func(c *gin.Context) {+ c.String(200, "pong")+ })+ router.Run(":3000")+}```-To run directly during development:+`WithDefaultProject` can be called multiple times to create separate projects — one for your Go backend, another for a frontend or any other service. Each project gets its own token, keeping telemetry organized in the dashboard.++Run with the build tag:```bashgo run -tags chdb .```-Without the tag, the binary compiles normally and attempting to use embedded mode returns a clear error.+The Traceway dashboard is available at `http://localhost:8085`. Log in with the credentials from `WithDefaultUser`.++## Configuration Options++All options are passed to `cmd.Run()`. When any options are provided, embedded mode is activated automatically (SQLite + embedded ClickHouse).++| Option | Description | Default |+|--------|-------------|---------|+| `WithPort(port)` | HTTP port for the Traceway server | `8082` |+| `WithServerURL(url)` | Base URL override (used in connection string output) | `http://localhost:{port}` |+| `WithSQLitePath(path)` | SQLite database file path | `:memory:` (in-memory) |+| `WithClickhousePath(path)` | ClickHouse data directory | `""` (in-memory) |+| `WithDefaultUser(email, password)` | Create a default admin user on startup | None |+| `WithDefaultProject(name, framework, token)` | Create a default project with a fixed token (can be called multiple times) | None |++## Data Persistence++By default, both databases are **in-memory** — all data is lost when your application restarts. This is fine for quick debugging sessions, but if you want data to survive restarts, set file paths:++```go+cmd.Run(+ cmd.WithSQLitePath("./traceway.db"),+ cmd.WithClickhousePath("./chdb-data"),+ cmd.WithDefaultUser("[email protected]", "admin"),+ cmd.WithDefaultProject("Backend", "go", "backend-dev-token"),+ cmd.WithDefaultProject("Frontend", "sveltekit", "frontend-dev-token"),+)+```++- `WithSQLitePath` stores users, projects, and organizations in a local SQLite file.+- `WithClickhousePath` stores traces, issues, and metrics in a local directory.-## How it works+Seeding is idempotent — if the user from `WithDefaultUser` already exists, it's skipped.++## Connecting Your App++### Go SDK++The Traceway Go SDK connects using a **connection string** in the format `<token>@<server_url>/api/report`. Use the token from `WithDefaultProject`:++```go+tracewaygin.Use(router, "backend-dev-token@http://localhost:8085/api/report")+```++Because the token is set explicitly via `WithDefaultProject`, it stays the same across restarts — your SDK config doesn't need to change.++For other Go frameworks, the connection string works the same way:++```go+// Fiber+tracewayfiber.Use(app, "backend-dev-token@http://localhost:8085/api/report")++// Chi+tracewaychi.Use(mux, "backend-dev-token@http://localhost:8085/api/report")++// net/http+tracewayhttp.Use(mux, "backend-dev-token@http://localhost:8085/api/report")+```++### OpenTelemetry++For non-Go services (or any app already using OpenTelemetry), export traces and metrics to the embedded Traceway instance over OTLP/HTTP. Use the token from the matching `WithDefaultProject` — for example, the frontend project:++| Setting | Value |+|---------|-------|+| **Traces endpoint** | `http://localhost:8085/api/otel/v1/traces` |+| **Metrics endpoint** | `http://localhost:8085/api/otel/v1/metrics` |+| **Auth header** | `Authorization: Bearer frontend-dev-token` |++#### Node.js SDK++```typescript+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";+import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";++const traceExporter = new OTLPTraceExporter({+ url: "http://localhost:8085/api/otel/v1/traces",+ headers: {+ Authorization: "Bearer frontend-dev-token",+ },+});++const metricExporter = new OTLPMetricExporter({+ url: "http://localhost:8085/api/otel/v1/metrics",+ headers: {+ Authorization: "Bearer frontend-dev-token",+ },+});+```-The `chdb` build tag controls whether the `chdb-go` driver is compiled into the binary. When the tag is present, `embedded.go` is included — it imports the chdb driver and provides the `initEmbedded()` implementation. When the tag is absent, a stub returns an error if embedded mode is requested.+#### Environment Variables-To use embedded mode at runtime, set the `CLICKHOUSE_TYPE` environment variable:+Any OTel SDK can be configured with standard environment variables instead of code:```bash-CLICKHOUSE_TYPE=embedded go run -tags chdb .+export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:8085/api/otel"+export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer frontend-dev-token"+export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"```-Optionally set `CLICKHOUSE_PATH` to persist data to a directory. Without it, chdb uses an in-memory session.+This works with Java, Python, .NET, Go, and any other language that supports the OTel environment variable spec. See the [OpenTelemetry integration guide](/client/otel) for more details.diff --git a/frontend/src/routes/settings/+page.svelte b/frontend/src/routes/settings/+page.svelteindex 27811c90..18f0ab0c 100644--- a/frontend/src/routes/settings/+page.svelte+++ b/frontend/src/routes/settings/+page.svelte@@ -6,6 +6,7 @@import OrganizationTab from './organization-tab.svelte';import UsersTab from './users-tab.svelte';import type { Component } from 'svelte';+ import { LoadingCircle } from '$lib/components/ui/loading-circle';let loading = $state(true);let error = $state<string | null>(null);@@ -60,7 +61,7 @@{#if loading}<div class="flex items-center justify-center py-12">- <div class="animate-spin rounded-full h-8 w-8 border-b-2 border-primary"></div>+ <LoadingCircle size="xlg" /></div>{:else if error}<div class="text-center py-12 text-destructive">diff --git a/frontend/vite.config.ts b/frontend/vite.config.tsindex fcd2d80c..95e4bcca 100644--- a/frontend/vite.config.ts+++ b/frontend/vite.config.ts@@ -23,7 +23,7 @@ function stubBillingImports(): Plugin {},load(id) {if (id === '\0virtual:billing-stub') {- return 'export default {}';+ return 'export default null';}}};diff --git a/scripts/build-local.sh b/scripts/build-local.shnew file mode 100755index 00000000..eff1d961--- /dev/null+++ b/scripts/build-local.sh@@ -0,0 +1,21 @@+#!/bin/bash+set -e++SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+ROOT_DIR="$(dirname "$SCRIPT_DIR")"++cd "$ROOT_DIR/frontend"++unset BILLING_PATH+unset CLOUD_MODE+unset PUBLIC_TURNSTILE_SITE_KEY+unset TRACEWAY_URL++npm install+npm run build++rm -rf "$ROOT_DIR/backend/static/dist"+mkdir -p "$ROOT_DIR/backend/static/dist"+cp -r "$ROOT_DIR/frontend/build/"* "$ROOT_DIR/backend/static/dist/"++echo "Frontend built and bundled into backend/static/dist/"