### Install @rustrak/client

Source: https://rustrak.github.io/rustrak/sdks/client

Installation commands for common package managers.

```bash
npm install @rustrak/client
# or
pnpm add @rustrak/client
# or
yarn add @rustrak/client
```

--------------------------------

### Clone and install project dependencies

Source: https://rustrak.github.io/rustrak/reference/contributing

Initial steps to download the repository and install required Node.js packages.

```bash
git clone https://github.com/AbianS/rustrak.git
cd rustrak
pnpm install
```

--------------------------------

### Start development services

Source: https://rustrak.github.io/rustrak/reference/contributing

Commands to launch the PostgreSQL database and start the server and dashboard applications.

```bash
# Start PostgreSQL
docker compose -f docker-compose.dev.yml up -d postgres
 
# Run server
cd apps/server && cargo run
 
# Run dashboard (separate terminal)
cd apps/webview-ui && pnpm dev
```

--------------------------------

### Run documentation locally

Source: https://rustrak.github.io/rustrak/reference/contributing

Command to start the documentation development server.

```bash
cd apps/docs
pnpm dev
```

--------------------------------

### Install Sentry SDKs

Source: https://rustrak.github.io/rustrak/getting-started/quickstart

Commands to install the Sentry SDK for various programming languages.

```bash
# JavaScript / Node.js
npm install @sentry/browser
# or
npm install @sentry/node
 
# Python
pip install sentry-sdk
 
# Go
go get github.com/getsentry/sentry-go
 
# Rust
cargo add sentry
```

--------------------------------

### Start Docker Compose services

Source: https://rustrak.github.io/rustrak/getting-started/installation

Command to initialize and start the defined services in the background.

```bash
docker compose up -d
```

--------------------------------

### Install or Run @rustrak/mcp

Source: https://rustrak.github.io/rustrak/sdks/mcp

Commands to execute the server directly via npx or install it globally.

```bash
npx @rustrak/mcp   # run directly with npx (no install needed)
# or install globally
npm install -g @rustrak/mcp
```

--------------------------------

### Initialize and Use RustrakClient

Source: https://rustrak.github.io/rustrak/sdks/client

Basic setup and usage pattern for the Rustrak client, demonstrating the Result return type handling.

```typescript
import { RustrakClient } from '@rustrak/client';
 
const client = new RustrakClient({
  baseUrl: 'https://your-rustrak-instance.example.com',
  token: process.env.RUSTRAK_API_TOKEN!,
});
 
const projects = await client.projects.list();
if (!projects.success) {
  console.error(projects.error.kind); // 'unauthenticated' | 'network' | ...
  return;
}
 
console.log(projects.data.items);
```

--------------------------------

### Retrieve a Project

Source: https://rustrak.github.io/rustrak/sdks/client

Example of fetching a project by ID and handling the response success state.

```javascript
const project = await client.projects.get(1);
if (!project.success) {
  console.error('Could not load the project:', project.error.message);
  return;
}
 
console.log(project.data.dsn);
```

--------------------------------

### Initialize Rustrak Environment and Services

Source: https://rustrak.github.io/rustrak/blog/introducing-rustrak

Generate a session secret and start the services using Docker Compose.

```bash
SESSION_SECRET_KEY=$(openssl rand -hex 32)
CREATE_SUPERUSER=admin@example.com:changeme123
docker compose up -d
```

--------------------------------

### Conventional commit examples

Source: https://rustrak.github.io/rustrak/reference/contributing

Examples of commit messages following the conventional commits specification.

```text
feat: Add issue muting
fix: Correct rate limit calculation
docs: Update deployment guide
```

--------------------------------

### Display DSN format

Source: https://rustrak.github.io/rustrak/getting-started/quickstart

Example of the Data Source Name (DSN) format provided after creating a project.

```text
http://a1b2c3d4e5f6@localhost:8080/1
```

--------------------------------

### GET /api/storage/summary

Source: https://rustrak.github.io/rustrak/usage/storage

Retrieves an instance-wide summary of storage usage.

```APIDOC
## GET /api/storage/summary

### Description
Retrieves an instance-wide summary of storage usage.

### Method
GET

### Endpoint
/api/storage/summary
```

--------------------------------

### Run Rustrak UI via Docker

Source: https://rustrak.github.io/rustrak/troubleshooting/common-issues

Use this command to start the dashboard container and point it to your remote API server.

```bash
docker run -p 3000:3000 \
  -e RUSTRAK_API_URL=https://your-server.com \
  rustrak/rustrak-ui:latest
```

--------------------------------

### GET /docs

Source: https://rustrak.github.io/rustrak/reference/api

Accesses the Scalar interactive API documentation UI.

```APIDOC
## GET /docs

### Description
Serves the Scalar interactive UI for browsing API endpoints and schemas. This endpoint is public and does not require authentication.

### Method
GET

### Endpoint
/docs
```

--------------------------------

### GET /api/storage/projects

Source: https://rustrak.github.io/rustrak/usage/storage

Retrieves a storage breakdown per project.

```APIDOC
## GET /api/storage/projects

### Description
Retrieves a storage breakdown per project.

### Method
GET

### Endpoint
/api/storage/projects
```

--------------------------------

### Example of obfuscated production stack trace

Source: https://rustrak.github.io/rustrak/blog/source-maps-in-rust

A sample stack trace showing obfuscated function names and file paths, illustrating the need for source map support.

```text
Error: {"type":"Unknown","message":"Unknown Error"}
 
04  ?
    app:///_next/server/chunks/ssr/_0bwf~zv._.js:2:239718
 
03  ?
    app:///_next/server/chunks/ssr/apps_myapp_src_lib_actions_invoices_ts_09hq4k7._.js:2:5956
 
02  process.processTicksAndRejections
    node:internal/process/task_queues:103:5
 
01  Module.k [as generateMetadata]
    app:///_next/server/chunks/ssr/[root-of-the-server]__0fitma~._.js:2:5672
```

--------------------------------

### Log response structure

Source: https://rustrak.github.io/rustrak/usage/logs

Example JSON response showing the log items array and pagination metadata.

```json
{
  "items": [
    {
      "id": "0c9b…",
      "level": "info",
      "severity_number": 9,
      "body": "User signed up",
      "trace_id": "abc123…",
      "span_id": "def456…",
      "attributes": {
        "userId": { "value": 4172, "type": "integer" },
        "plan": { "value": "pro", "type": "string" }
      },
      "timestamp": "2026-06-26T10:30:00Z",
      "ingested_at": "2026-06-26T10:30:01Z"
    }
  ],
  "total_count": 1240,
  "page": 1,
  "per_page": 50,
  "total_pages": 25
}
```

--------------------------------

### Issue Management Operations

Source: https://rustrak.github.io/rustrak/sdks/client

Examples for listing, retrieving, updating, and deleting issues within a project.

```javascript
// List with filters
const issues = await client.issues.list(projectId, {
  sort: 'last_seen',        // 'digest_order' | 'last_seen' | 'event_count'
  order: 'desc',            // 'asc' | 'desc'
  filter: 'open',           // 'open' | 'resolved' | 'muted' | 'all'
  page: 1,
  per_page: 20,
});
 
if (issues.success) {
  for (const issue of issues.data.items) {
    console.log(issue.short_id, issue.title);
  }
}
 
const issue = await client.issues.get(projectId, issueId);
if (issue.success) {
  console.log(issue.data.title);
}
 
const resolved = await client.issues.updateState(projectId, issueId, {
  is_resolved: true,
});
if (!resolved.success) {
  console.error('Could not resolve:', resolved.error.message);
}
 
const removed = await client.issues.delete(projectId, issueId);
if (!removed.success) {
  console.error('Could not delete:', removed.error.message);
}
```

--------------------------------

### Configure PUBLIC_URL for production and custom setups

Source: https://rustrak.github.io/rustrak/configuration/environment

Sets the public-facing URL used in DSN strings. Ensure the scheme is included and avoid trailing slashes.

```bash
# Production (behind reverse proxy)
PUBLIC_URL=https://api.yourcompany.com
 
# Self-hosted with custom port
PUBLIC_URL=http://192.168.1.10:9090
```

--------------------------------

### DSN Format and Example

Source: https://rustrak.github.io/rustrak/usage/projects

The DSN is the unique identifier used to connect your application to the Rustrak backend.

```text
http://<sentry_key>@<host>:<port>/<project_id>
```

```text
http://a1b2c3d4-e5f6-7890-abcd-ef1234567890@localhost:8080/1
```

--------------------------------

### Visualize Issue Event Grouping

Source: https://rustrak.github.io/rustrak/usage/issues

Example structure showing how multiple events are associated with a single issue.

```text

Issue: TypeError in checkout.js
├── Event #1 - Jan 15, 10:30 AM
├── Event #2 - Jan 15, 10:45 AM
├── Event #3 - Jan 15, 11:02 AM
└── Event #4 - Jan 15, 11:15 AM
```

--------------------------------

### RustrakClient Initialization

Source: https://rustrak.github.io/rustrak/sdks/client

How to instantiate the Rustrak client with required configuration parameters.

```APIDOC
## RustrakClient Initialization

### Description
Initializes the Rustrak client instance with the necessary base URL and authentication token.

### Configuration Parameters
- **baseUrl** (string) - Required - The base URL of the Rustrak instance.
- **token** (string) - Required - The bearer token for authentication.
- **timeout** (number) - Optional - Request timeout in milliseconds (default: 30000).
- **maxRetries** (number) - Optional - Maximum number of retries (default: 2).
- **headers** (object) - Optional - Custom headers to include in requests.
```

--------------------------------

### Configure Superuser Bootstrap

Source: https://rustrak.github.io/rustrak/configuration/environment

Sets the credentials for the initial admin user created during startup. This only executes if the database is empty.

```bash
CREATE_SUPERUSER="admin@example.com:secure-password"
```

--------------------------------

### Configure Admin User

Source: https://rustrak.github.io/rustrak/getting-started/installation

Set the initial admin credentials in your environment configuration.

```bash
# In your .env file
CREATE_SUPERUSER=admin@example.com:yourpassword
```

--------------------------------

### GET /api-docs/openapi.json

Source: https://rustrak.github.io/rustrak/reference/api

Retrieves the raw OpenAPI 3.x JSON specification.

```APIDOC
## GET /api-docs/openapi.json

### Description
Returns the raw OpenAPI 3.x JSON specification for the server. This endpoint is public and does not require authentication.

### Method
GET

### Endpoint
/api-docs/openapi.json
```

--------------------------------

### Deploy Server and Dashboard Separately

Source: https://rustrak.github.io/rustrak/troubleshooting/common-issues

Run the server and dashboard as independent containers to optimize resource allocation.

```bash

# On server
docker run -d -p 8080:8080 rustrak/rustrak-server:latest
 
# Dashboard on another machine
docker run -d -p 3000:3000 \
  -e RUSTRAK_API_URL=https://your-server.com \
  rustrak/rustrak-ui:latest
```

--------------------------------

### GET /api/team

Source: https://rustrak.github.io/rustrak/usage/team

Retrieves a list of all team members. Requires an admin token.

```APIDOC
## GET /api/team

### Description
List all team members. Requires an admin token.

### Method
GET

### Endpoint
/api/team
```

--------------------------------

### Authenticate in Python

Source: https://rustrak.github.io/rustrak/usage/tokens

Use the requests library to send an authenticated GET request.

```python
import requests
import os
 
response = requests.get(
    'http://localhost:8080/api/projects',
    headers={'Authorization': f'Bearer {os.environ["RUSTRAK_TOKEN"]}'}
)
```

--------------------------------

### Configure superuser in .env

Source: https://rustrak.github.io/rustrak/troubleshooting/common-issues

Define the initial superuser credentials in your environment file.

```text
# In your .env file
CREATE_SUPERUSER=admin@example.com:password
```

--------------------------------

### GET /api/projects/{project_id}/agents/traces

Source: https://rustrak.github.io/rustrak/usage/agents

Retrieves a paginated list of agent traces.

```APIDOC
## GET /api/projects/{project_id}/agents/traces

### Description
Retrieves a paginated list of agent traces.

### Method
GET

### Endpoint
/api/projects/{project_id}/agents/traces

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

#### Query Parameters
- **page** (integer) - Optional - The page number.
- **per_page** (integer) - Optional - The number of items per page.

### Response
#### Success Response (200)
- **trace_id** (string) - Unique identifier for the trace
- **agent_names** (array) - List of agent names involved
- **duration_ms** (number) - Duration in milliseconds
- **total_tokens** (integer) - Total tokens used
- **tool_call_count** (integer) - Number of tool calls
- **started_at** (string) - ISO timestamp of start time
```

--------------------------------

### Build Production Binaries

Source: https://rustrak.github.io/rustrak/reference/api

Build the project with or without the openapi feature to control the inclusion of documentation endpoints.

```bash
cargo build --release                         # no openapi, no extra deps
cargo build --release --features openapi      # includes /docs and /api-docs/openapi.json
```

--------------------------------

### GET /api/projects/{project_id}/agents/tools

Source: https://rustrak.github.io/rustrak/usage/agents

Retrieves the top tools by call count.

```APIDOC
## GET /api/projects/{project_id}/agents/tools

### Description
Retrieves the top tools by call count.

### Method
GET

### Endpoint
/api/projects/{project_id}/agents/tools

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
```

--------------------------------

### Manage database migrations

Source: https://rustrak.github.io/rustrak/reference/contributing

Commands to create and apply database migrations using sqlx.

```bash
sqlx migrate add description
sqlx migrate run
```

--------------------------------

### GET /api/projects/{project_id}/agents/models/tokens

Source: https://rustrak.github.io/rustrak/usage/agents

Retrieves the top models by token usage.

```APIDOC
## GET /api/projects/{project_id}/agents/models/tokens

### Description
Retrieves the top models by token usage.

### Method
GET

### Endpoint
/api/projects/{project_id}/agents/models/tokens

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

#### Query Parameters
- **limit** (integer) - Optional - The number of models to return.
```

--------------------------------

### GET /api/projects/{project_id}/agents/models/calls

Source: https://rustrak.github.io/rustrak/usage/agents

Retrieves the top models by call count.

```APIDOC
## GET /api/projects/{project_id}/agents/models/calls

### Description
Retrieves the top models by call count.

### Method
GET

### Endpoint
/api/projects/{project_id}/agents/models/calls

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

#### Query Parameters
- **limit** (integer) - Optional - The number of models to return.
```

--------------------------------

### Build Rustrak from Source

Source: https://rustrak.github.io/rustrak/troubleshooting/faq

Compile the Rustrak server binary directly from the source code. Requires a running PostgreSQL instance.

```bash
cd apps/server
cargo build --release
./target/release/rustrak
```

--------------------------------

### Initialize Sentry SDK

Source: https://rustrak.github.io/rustrak/usage/projects

Configure the Sentry SDK by providing the project DSN obtained from the dashboard settings.

```javascript
Sentry.init({
  dsn: 'YOUR_DSN_HERE',
});
```

--------------------------------

### Run PostgreSQL Container

Source: https://rustrak.github.io/rustrak/configuration/database

Deploy the PostgreSQL-based server image. Requires an external database connection string.

```bash
docker run -d \
  --name rustrak \
  -p 8080:8080 \
  -e DATABASE_URL=postgres://user:password@db-host:5432/rustrak \
  -e SESSION_SECRET_KEY=$(openssl rand -hex 32) \
  -e CREATE_SUPERUSER=admin@example.com:changeme123 \
rustrak/rustrak-server:postgres
```

--------------------------------

### GET /api/projects/{project_id}/agents/duration

Source: https://rustrak.github.io/rustrak/usage/agents

Retrieves average and p95 duration metrics for agent runs.

```APIDOC
## GET /api/projects/{project_id}/agents/duration

### Description
Retrieves average and p95 duration metrics for agent runs.

### Method
GET

### Endpoint
/api/projects/{project_id}/agents/duration

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
```

--------------------------------

### Configure Continue.dev for MCP

Source: https://rustrak.github.io/rustrak/sdks/mcp

Add the Rustrak MCP server to the Continue.dev configuration file.

```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@rustrak/mcp"],
          "env": {
            "RUSTRAK_API_URL": "https://your-rustrak-instance.example.com",
            "RUSTRAK_API_TOKEN": "your-40-char-hex-token"
          }
        }
      }
    ]
  }
}
```

--------------------------------

### GET /api/projects/{project_id}/agents/runs

Source: https://rustrak.github.io/rustrak/usage/agents

Retrieves the count of agent runs over a specified time period.

```APIDOC
## GET /api/projects/{project_id}/agents/runs

### Description
Retrieves the count of agent runs over a specified time period.

### Method
GET

### Endpoint
/api/projects/{project_id}/agents/runs

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

#### Query Parameters
- **period_hours** (integer) - Optional - The total time period in hours.
- **interval_hours** (integer) - Optional - The bucket interval in hours.
```

--------------------------------

### Project Management Methods

Source: https://rustrak.github.io/rustrak/sdks/client

Overview of available project methods and their return types.

```javascript
client.projects.list()                                  // Result<OffsetPaginatedResponse<Project>>
client.projects.get(1)                                  // Result<Project>
client.projects.create({ name: 'My App', slug: 'my-app' }) // Result<Project>
client.projects.update(1, { name: 'New Name' })         // Result<Project>
client.projects.delete(1)                               // Result<void>
```

--------------------------------

### Add database healthcheck to Docker Compose

Source: https://rustrak.github.io/rustrak/troubleshooting/common-issues

Ensure the server waits for the PostgreSQL service to be healthy before starting.

```yaml
services:
  server:
    depends_on:
      postgres:
        condition: service_healthy
```

--------------------------------

### Configure Environment via Tags

Source: https://rustrak.github.io/rustrak/usage/projects

Use the environment property to distinguish between deployment stages within a single project.

```javascript
Sentry.init({
  dsn: 'YOUR_DSN',
  environment: process.env.NODE_ENV,
});
```

--------------------------------

### Agent Trace Response Format

Source: https://rustrak.github.io/rustrak/usage/agents

Example JSON structure returned by the agent traces API endpoint.

```json
{
  "trace_id": "6c1f...b2",
  "agent_names": ["research_agent"],
  "duration_ms": 842.3,
  "total_tokens": 642,
  "tool_call_count": 1,
  "started_at": "2026-07-18T10:15:00Z"
}
```

--------------------------------

### Initialize Sentry SDK

Source: https://rustrak.github.io/rustrak/getting-started/quickstart

Initialization code for different languages to connect to the Rustrak server.

```javascript
// JavaScript (browser or Node.js)
import * as Sentry from '@sentry/browser'; // or '@sentry/node'
 
Sentry.init({
  dsn: 'YOUR_DSN_HERE', // paste your DSN
});
```

```python
# Python
import sentry_sdk
 
sentry_sdk.init(dsn="YOUR_DSN_HERE")
```

```go
// Go
import "github.com/getsentry/sentry-go"
 
sentry.Init(sentry.ClientOptions{
    Dsn: "YOUR_DSN_HERE",
})
```

```rust
// Rust
let _guard = sentry::init("YOUR_DSN_HERE");
```

--------------------------------

### Connect Sentry SDK to Rustrak

Source: https://rustrak.github.io/rustrak/blog/introducing-rustrak

Point an existing Sentry SDK initialization to the Rustrak instance URL.

```javascript
Sentry.init({ dsn: "http://<key>@localhost:8080/<project_id>" })
```

--------------------------------

### Configure Nginx for HTTPS

Source: https://rustrak.github.io/rustrak/configuration/production

Example Nginx server block to proxy traffic to the Rustrak service over HTTPS.

```nginx

# nginx example
server {
    listen 443 ssl http2;
    server_name rustrak.yourcompany.com;
 
    ssl_certificate /etc/ssl/certs/rustrak.crt;
    ssl_certificate_key /etc/ssl/private/rustrak.key;
 
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

--------------------------------

### View Migration Directory Structure

Source: https://rustrak.github.io/rustrak/configuration/database

Displays the organization of migration files for both supported backends.

```text
apps/server/migrations/
├── postgres/   # PostgreSQL migrations
└── sqlite/     # SQLite migrations
```

--------------------------------

### Configure SQLite DATABASE_URL

Source: https://rustrak.github.io/rustrak/configuration/database

Define the database location using either a named Docker volume or a host bind mount.

```text
# Named Docker volume (recommended)
DATABASE_URL=sqlite:///data/rustrak.db
 
# Absolute path on host (bind mount)
DATABASE_URL=sqlite:///var/lib/rustrak/rustrak.db
```

--------------------------------

### Configure Vercel AI SDK Integration

Source: https://rustrak.github.io/rustrak/usage/agents

Initialize the Sentry SDK with the Vercel AI integration to enable automatic instrumentation of LLM and tool calls.

```javascript
import * as Sentry from '@sentry/node';
 
Sentry.init({
  dsn: 'http://<sentry_key>@localhost:8080/<project_id>',
  integrations: [Sentry.vercelAIIntegration()],
});
```

--------------------------------

### Run server tests

Source: https://rustrak.github.io/rustrak/reference/contributing

Command to execute the Rust server test suite.

```bash
cd apps/server
cargo test
```

--------------------------------

### Deploy PostgreSQL with Docker Compose

Source: https://rustrak.github.io/rustrak/configuration/database

Set up a multi-container environment with a PostgreSQL service and health checks.

```yaml
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: rustrak
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: rustrak
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U rustrak -d rustrak"]
      interval: 5s
      timeout: 5s
      retries: 5
    restart: unless-stopped
 
  server:
    image: rustrak/rustrak-server:postgres
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=postgres://rustrak:${POSTGRES_PASSWORD}@postgres:5432/rustrak
      - SESSION_SECRET_KEY=${SESSION_SECRET_KEY}
      - CREATE_SUPERUSER=${CREATE_SUPERUSER}
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
 
  ui:
    image: rustrak/rustrak-ui:latest
    ports:
      - "3000:3000"
    environment:
      - RUSTRAK_API_URL=http://server:8080
    depends_on:
      - server
    restart: unless-stopped
 
volumes:
```

--------------------------------

### Disable Version Checks

Source: https://rustrak.github.io/rustrak/configuration/environment

Disables the server-side outbound request for version updates. Use this if the installation must have no outbound network traffic.

```bash
RUSTRAK_VERSION_CHECK_ENABLED=false
```

--------------------------------

### Configure Claude Desktop for MCP

Source: https://rustrak.github.io/rustrak/sdks/mcp

Add the Rustrak MCP server to the Claude Desktop configuration file.

```json
{
  "mcpServers": {
    "rustrak": {
      "command": "npx",
      "args": ["-y", "@rustrak/mcp"],
      "env": {
        "RUSTRAK_API_URL": "https://your-rustrak-instance.example.com",
        "RUSTRAK_API_TOKEN": "your-40-char-hex-token"
      }
    }
  }
}
```

--------------------------------

### GET /api/projects/{project_id}/logs

Source: https://rustrak.github.io/rustrak/usage/logs

Retrieves a list of logs for a specific project. Supports filtering by log level, trace ID, and pagination.

```APIDOC
## GET /api/projects/{project_id}/logs

### Description
Retrieve a list of logs for a project. Logs are read-only and require a bearer token for authentication.

### Method
GET

### Endpoint
/api/projects/{project_id}/logs

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

#### Query Parameters
- **level** (string) - Optional - Filter logs by severity level (e.g., error).
- **page** (integer) - Optional - The page number for pagination.
- **per_page** (integer) - Optional - The number of results per page.
- **trace_id** (string) - Optional - Filter logs by a specific trace ID.

### Response
#### Success Response (200)
- **items** (array) - List of log objects.
- **total_count** (integer) - Total number of logs available.
- **page** (integer) - Current page number.
- **per_page** (integer) - Number of items per page.
- **total_pages** (integer) - Total number of pages available.

#### Response Example
{
  "items": [
    {
      "id": "0c9b…",
      "level": "info",
      "severity_number": 9,
      "body": "User signed up",
      "trace_id": "abc123…",
      "span_id": "def456…",
      "attributes": {
        "userId": { "value": 4172, "type": "integer" },
        "plan": { "value": "pro", "type": "string" }
      },
      "timestamp": "2026-06-26T10:30:00Z",
      "ingested_at": "2026-06-26T10:30:01Z"
    }
  ],
  "total_count": 1240,
  "page": 1,
  "per_page": 50,
  "total_pages": 25
}
```

--------------------------------

### Configure HOST for local development

Source: https://rustrak.github.io/rustrak/configuration/environment

Restricts the server to the loopback interface for local development behind a proxy.

```bash
HOST=127.0.0.1  # loopback only — useful for local dev behind a local proxy
```

--------------------------------

### Run SQLite Container

Source: https://rustrak.github.io/rustrak/configuration/database

Deploy the SQLite-based server using Docker. Ensure a volume is mounted to /data to persist the database file.

```bash
docker run -d \
  --name rustrak \
  -p 8080:8080 \
  -v rustrak_data:/data \
  -e SESSION_SECRET_KEY=$(openssl rand -hex 32) \
  -e CREATE_SUPERUSER=admin@example.com:changeme123 \
rustrak/rustrak-server:latest
```

--------------------------------

### Separate by Environment

Source: https://rustrak.github.io/rustrak/usage/issues

Fingerprint configuration to distinguish issues occurring in different deployment environments.

```javascript

fingerprint: ['{{ default }}', process.env.NODE_ENV]
```

--------------------------------

### Deploy Rustrak Server with Docker

Source: https://rustrak.github.io/rustrak/getting-started/installation

Run the Rustrak server container with either SQLite or PostgreSQL storage backends.

```bash
docker run -d \
  --name rustrak \
  -p 8080:8080 \
  -v rustrak_data:/data \
  -e DATABASE_URL="sqlite:///data/rustrak.db" \
  -e SESSION_SECRET_KEY="$(openssl rand -hex 32)" \
  -e CREATE_SUPERUSER="admin@example.com:changeme123" \
  rustrak/rustrak-server:latest
```

```bash
docker run -d \
  --name rustrak \
  -p 8080:8080 \
  -e DATABASE_URL="postgres://user:pass@db-host:5432/rustrak" \
  -e SESSION_SECRET_KEY="$(openssl rand -hex 32)" \
  -e CREATE_SUPERUSER="admin@example.com:changeme123" \
  rustrak/rustrak-server:postgres
```

--------------------------------

### Project directory structure

Source: https://rustrak.github.io/rustrak/reference/contributing

Overview of the repository layout including server, dashboard, and documentation directories.

```text
rustrak/
├── apps/
│   ├── server/         # Rust API server
│   ├── webview-ui/     # Next.js dashboard
│   └── docs/           # Documentation
├── packages/
│   ├── client/         # TypeScript API client
│   └── test-sentry/    # Test CLI tool
└── docker-compose.yml
```

--------------------------------

### Configure SQLite Environment Variables

Source: https://rustrak.github.io/rustrak/configuration/environment

Use this configuration for local development or personal instances using a SQLite database.

```text

# .env file (SQLite — image tag: latest)
 
# Required
DATABASE_URL=sqlite:///data/rustrak.db
 
# Server
PORT=8080
RUST_LOG=info
 
# Dashboard
RUSTRAK_API_URL=http://localhost:8080
```

--------------------------------

### client.projects.list()

Source: https://rustrak.github.io/rustrak/sdks/client

Retrieves a list of projects from the Rustrak API.

```APIDOC
## client.projects.list()

### Description
Fetches a list of projects. Returns a Result object containing either the project data or an error.

### Return Type
- **Result<T, RustrakError>** - An object with a `success` boolean property. If `true`, `data` contains the items. If `false`, `error` contains the error details.
```

--------------------------------

### Deploy Rustrak Dashboard

Source: https://rustrak.github.io/rustrak/getting-started/installation

Self-host the dashboard container by pointing it to your server API URL.

```bash
docker run -d \
  --name rustrak-ui \
  -p 3000:3000 \
  -e RUSTRAK_API_URL="https://your-server.com" \
  rustrak/rustrak-ui:latest
```

--------------------------------

### Configure PostgreSQL Environment Variables

Source: https://rustrak.github.io/rustrak/configuration/environment

Use this configuration for production deployments requiring PostgreSQL, HTTPS proxy support, and email alerts.

```text

# .env file (PostgreSQL — image tag: postgres)
 
# Required
DATABASE_URL=postgres://rustrak:password@postgres:5432/rustrak
 
# Security (required for production behind HTTPS proxy)
SSL_PROXY=true
SESSION_SECRET_KEY=a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890
 
# Server
PORT=8080
RUST_LOG=info
PUBLIC_URL=https://api.yourcompany.com
 
# Database Pool
DATABASE_MAX_CONNECTIONS=20
 
# Rate Limiting
MAX_EVENTS_PER_MINUTE=1000
MAX_EVENTS_PER_HOUR=10000
 
# Dashboard
RUSTRAK_API_URL=https://rustrak.yourcompany.com
DASHBOARD_URL=https://rustrak.yourcompany.com
 
# Email Alerts (optional - can also configure per-channel)
SMTP_HOST=smtp.yourcompany.com
SMTP_PORT=587
SMTP_USERNAME=alerts@yourcompany.com
SMTP_PASSWORD=your-smtp-password
SMTP_FROM=alerts@yourcompany.com
```

--------------------------------

### Configure environment variables

Source: https://rustrak.github.io/rustrak/getting-started/installation

Required configuration settings for the Docker Compose deployment.

```text
# ===================
# Database (PostgreSQL)
# ===================
POSTGRES_USER=rustrak
POSTGRES_PASSWORD=rustrak
POSTGRES_DB=rustrak
 
# ===================
# Server
# ===================
SERVER_PORT=8080
RUST_LOG=info
 
# Session secret (required) - generate with: openssl rand -hex 32
SESSION_SECRET_KEY=your-64-char-hex-secret-here
 
# Admin user (required) - format: email:password
CREATE_SUPERUSER=admin@example.com:changeme123
 
# ===================
# Dashboard
# ===================
UI_PORT=3000
RUSTRAK_API_URL=http://server:8080
```

--------------------------------

### POST /api/storage/cleanup/preview

Source: https://rustrak.github.io/rustrak/usage/storage

Performs a dry-run of the cleanup process to see what would be removed.

```APIDOC
## POST /api/storage/cleanup/preview

### Description
Performs a dry-run of the cleanup process to see what would be removed.

### Method
POST

### Endpoint
/api/storage/cleanup/preview

### Request Body
- **older_than_days** (integer) - Required - The age threshold in days for data to be cleaned.
```

--------------------------------

### Perform SQLite backups

Source: https://rustrak.github.io/rustrak/configuration/production

Use the online backup API to safely back up a running SQLite database.

```bash

# Use SQLite's online backup API (safe while server is running)
sqlite3 /var/lib/rustrak/rustrak.db ".backup /backups/rustrak-$(date +%Y%m%d).db"
```

--------------------------------

### Migrate DSN Configuration

Source: https://rustrak.github.io/rustrak/troubleshooting/faq

Update the Sentry SDK initialization to point to your Rustrak server instance instead of the hosted Sentry service.

```javascript
// Before
Sentry.init({ dsn: 'https://key@sentry.io/123' });
 
// After
Sentry.init({ dsn: 'http://key@your-server:8080/1' });
```

--------------------------------

### client.projects

Source: https://rustrak.github.io/rustrak/sdks/client

Methods for managing project resources.

```APIDOC
## client.projects.list()

### Description
Retrieves a paginated list of projects.

### Returns
Result<OffsetPaginatedResponse<Project>>

## client.projects.get(id)

### Description
Retrieves a specific project by its ID.

### Parameters
- **id** (number) - Required - The project ID.

### Returns
Result<Project>

## client.projects.create(data)

### Description
Creates a new project.

### Parameters
- **data** (object) - Required - Contains 'name' and 'slug'.

### Returns
Result<Project>

## client.projects.update(id, data)

### Description
Updates an existing project.

### Parameters
- **id** (number) - Required - The project ID.
- **data** (object) - Required - The fields to update.

### Returns
Result<Project>

## client.projects.delete(id)

### Description
Deletes a project by its ID.

### Parameters
- **id** (number) - Required - The project ID.

### Returns
Result<void>
```

--------------------------------

### Run dashboard tests and linting

Source: https://rustrak.github.io/rustrak/reference/contributing

Commands to execute tests and linting for the Next.js dashboard.

```bash
cd apps/webview-ui
pnpm test
pnpm lint
```

--------------------------------

### Configure Vite for Source Maps

Source: https://rustrak.github.io/rustrak/usage/source-maps

Enable sourcemaps in the build configuration and include the sentryVitePlugin to handle uploads.

```javascript
// vite.config.js
import { defineConfig } from 'vite';
import { sentryVitePlugin } from '@sentry/vite-plugin';
 
export default defineConfig({
  build: {
    sourcemap: true, // required
  },
  plugins: [
    sentryVitePlugin({
      org: 'anything',           // any value works, Rustrak ignores it
      project: 'my-project',     // must match your Rustrak project slug
      authToken: 'your-api-token',
      url: 'http://localhost:8080', // your Rustrak server URL
    }),
  ],
});
```

--------------------------------

### Manage team and project access via API

Source: https://rustrak.github.io/rustrak/usage/team

Use these cURL commands to list team members, invite new users, or assign project roles. Requires an admin-level API token.

```bash
# List the team (admin token required)
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8080/api/team
 
# Invite a member — returns a single-use invite token
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"teammate@example.com","role":"member"}' \
  http://localhost:8080/api/invitations
 
# Add a user to a project as an editor
curl -X PUT -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id":2,"role":"editor"}' \
  http://localhost:8080/api/projects/1/members
```

--------------------------------

### Run Rustrak with SQLite

Source: https://rustrak.github.io/rustrak/getting-started/installation

Deploys the Rustrak server using the default SQLite database. Data is persisted via a Docker volume.

```bash
docker run -d \
  --name rustrak \
  -p 8080:8080 \
  -v rustrak_data:/data \
  -e SESSION_SECRET_KEY=$(openssl rand -hex 32) \
  -e CREATE_SUPERUSER=admin@example.com:changeme123 \
  rustrak/rustrak-server:latest
```

--------------------------------

### Configure Rustrak SDK DSN

Source: https://rustrak.github.io/rustrak

Update the DSN configuration to point to your own servers for migration.

```javascript
Sentry.init({
−  dsn: "https://abc123@o447951.ingest.sentry.io/1234567",
+  dsn: "https://abc123@errors.yourcompany.com/1",
  tracesSampleRate: 1.0,
  environment: "production",
});
```

--------------------------------

### Configure PostgreSQL DATABASE_URL

Source: https://rustrak.github.io/rustrak/configuration/database

Connection string formats for standard and SSL-enabled PostgreSQL connections.

```text
# Basic
DATABASE_URL=postgres://username:password@host:5432/database
 
# With SSL (recommended for production)
DATABASE_URL=postgres://username:password@host:5432/database?sslmode=require
```

--------------------------------

### Fetch data in a Server Component

Source: https://rustrak.github.io/rustrak/sdks/client

Initializes the Rustrak client using environment variables and handles authentication errors by redirecting.

```typescript
import { RustrakClient } from '@rustrak/client';
import { redirect } from 'next/navigation';
 
export default async function ProjectsPage() {
  const client = new RustrakClient({
    baseUrl: process.env.RUSTRAK_API_URL!,
    token: process.env.RUSTRAK_API_TOKEN!,
  });
 
  const projects = await client.projects.list();
 
  if (!projects.success) {
    // `kind` decides. Redirecting on 'network' or 'server_error' turns a flaky
    // connection into a login loop that logging in cannot fix.
    if (projects.error.kind === 'unauthenticated') redirect('/auth/login');
    return <LoadFailed error={projects.error} />;
  }
 
  return <ProjectsList projects={projects.data.items} />;
}
```

--------------------------------

### Enable secure proxy settings

Source: https://rustrak.github.io/rustrak/configuration/production

Environment variables required to enable secure cookie handling when running behind a reverse proxy.

```bash

# In your .env or environment
SSL_PROXY=true
SESSION_SECRET_KEY=$(openssl rand -hex 32)
```

--------------------------------

### Generate OpenAPI Spec File

Source: https://rustrak.github.io/rustrak/reference/api

Run the generator binary with the openapi feature enabled to write the specification file.

```bash
cargo run --bin gen_openapi --features openapi
# writes apps/server/openapi.json
```

--------------------------------

### Set rate limits

Source: https://rustrak.github.io/rustrak/configuration/production

Environment variables to control event ingestion volume based on resource availability.

```bash

# High volume
MAX_EVENTS_PER_MINUTE=5000
MAX_EVENTS_PER_HOUR=50000
 
# Low volume / constrained resources
MAX_EVENTS_PER_MINUTE=100
MAX_EVENTS_PER_HOUR=1000
```

--------------------------------

### Visualize Rustrak Architecture

Source: https://rustrak.github.io/rustrak/getting-started/overview

A high-level diagram showing the flow from application to storage and dashboard.

```text
Your App → Sentry SDK → Rustrak Server → SQLite or PostgreSQL
                              ↓
                        Dashboard (optional)
```

--------------------------------

### Configure database SSL

Source: https://rustrak.github.io/rustrak/configuration/production

Connection string format to enforce SSL for PostgreSQL database connections.

```text

# Enable SSL
DATABASE_URL=postgres://user:pass@host:5432/rustrak?sslmode=require
```

--------------------------------

### Configure Rustrak with Docker Compose

Source: https://rustrak.github.io/rustrak/blog/introducing-rustrak

Use this configuration to deploy the Rustrak server and UI containers, utilizing SQLite for storage by default.

```yaml
# docker-compose.yml
services:
  server:
    image: rustrak/rustrak-server:latest
    ports:
      - "8080:8080"
    volumes:
      - rustrak_data:/data
    environment:
      - SESSION_SECRET_KEY=${SESSION_SECRET_KEY}
      - CREATE_SUPERUSER=${CREATE_SUPERUSER}
    restart: unless-stopped
 
  ui:
    image: rustrak/rustrak-ui:latest
    ports:
      - "3000:3000"
    environment:
      - RUSTRAK_API_URL=http://server:8080
    depends_on:
      - server
    restart: unless-stopped
 
volumes:
  rustrak_data:
```

--------------------------------

### Format DATABASE_URL

Source: https://rustrak.github.io/rustrak/troubleshooting/common-issues

Ensure the connection string uses the correct host depending on whether the database is local or in a Docker network.

```text
# Format
postgres://username:password@host:port/database
 
# Common mistakes
postgres://user:pass@localhost:5432/rustrak  # Wrong if using Docker
postgres://user:pass@postgres:5432/rustrak   # Correct for Docker Compose
```

--------------------------------

### Perform PostgreSQL backups

Source: https://rustrak.github.io/rustrak/configuration/production

Commands for creating and restoring PostgreSQL database dumps.

```bash

# Daily backup
pg_dump -h localhost -U rustrak rustrak > backup_$(date +%Y%m%d).sql
 
# Restore
psql -h localhost -U rustrak rustrak < backup.sql
```

--------------------------------

### Configure SvelteKit for Source Maps

Source: https://rustrak.github.io/rustrak/usage/source-maps

Use the sentrySvelteKit plugin with the sentryUrl option at the root level.

```javascript
// vite.config.js
import { sentrySvelteKit } from '@sentry/sveltekit';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig, loadEnv } from 'vite';
 
export default defineConfig(({ mode }) => {
  // Vite does NOT populate process.env in config files, see note below
  const env = loadEnv(mode, process.cwd(), '');
 
  return {
    plugins: [
      sentrySvelteKit({
        org: 'anything',                  // ignored by Rustrak
        project: 'my-project',            // must match your Rustrak project slug
        authToken: env.SENTRY_AUTH_TOKEN,
        sentryUrl: 'http://localhost:8080', // NOT `url` in this SDK
      }),
      sveltekit(),
    ],
  };
});
```

--------------------------------

### Test server connectivity

Source: https://rustrak.github.io/rustrak/troubleshooting/common-issues

Use curl to verify the Rustrak server is reachable and healthy.

```bash
# Test from your app's server/machine
curl -v http://your-rustrak-server:8080/health
```