Skip to content

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

feat: updated docs

ddux7fd5ae361c92
diff --git a/docs/pages/learn/embedded-mode.mdx b/docs/pages/learn/embedded-mode.mdx
index 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:
```bash
curl -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:
```bash
go 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:
```bash
go 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.svelte
index 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.ts
index 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.sh
new file mode 100755
index 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/"