---
title: "Configuration Reference"
description: "Complete .langsight.yaml schema"
---

## Full schema

```yaml
# .langsight.yaml

# MCP servers to monitor
servers:
  - name: postgres-mcp             # required — unique identifier
    transport: stdio                # stdio | sse | streamable_http
    command: python                 # stdio only: executable
    args: [server.py]               # stdio only: arguments
    env:                            # stdio only: environment variables
      DB_HOST: localhost
    url: http://localhost:8080/sse  # sse/streamable_http only
    tags: [production, data]        # optional labels
    timeout_seconds: 5              # default: 5
    # Optional: v0.3 circuit breaker per-server override
    circuit_breaker:
      failure_threshold: 5    # open after N consecutive failures
      cooldown_seconds: 60    # disable for N seconds
      half_open_max_calls: 2  # test with N calls before closing

# Alerting configuration
alerts:
  slack_webhook: https://hooks.slack.com/...   # optional
  error_rate_threshold: 0.05                    # 5%
  latency_spike_multiplier: 3.0                 # 3x baseline
  consecutive_failures: 2                       # before DOWN alert

# Storage backend
# Valid modes: postgres | clickhouse | dual (default: dual)
# SQLite has been removed in v0.2.0 — use docker compose up -d
storage:
  mode: dual   # Postgres (metadata) + ClickHouse (analytics)

  # PostgreSQL — required for mode: postgres or dual
  # postgres_url: postgresql://user:pass@localhost:5432/langsight

  # ClickHouse — required for mode: clickhouse or dual
  clickhouse_url: http://localhost:8123
  clickhouse_database: langsight
  clickhouse_username: langsight
  clickhouse_password: ""

# LLM provider for langsight investigate
investigate:
  provider: anthropic              # anthropic | openai | gemini | ollama
  model: claude-sonnet-4-6        # optional — defaults per provider
  api_key: null                   # optional — prefer env vars
  base_url: null                  # optional — for Ollama remotes

# Tool call pricing rules for langsight costs (non-LLM tool calls)
# LLM span costs are calculated from token counts — see Settings → Model Pricing
costs:
  rules:
    - server: openai-mcp
      tool: chat_completion
      cost_per_call: 0.005
    - server: "*"
      tool: "*"
      cost_per_call: 0.001

# PII protection — omit input_args and output_result from all spans
# Disables session replay payload inspection and Playground Replay
redact_payloads: false
```

## Environment variable overrides

All settings can be overridden with environment variables using the `LANGSIGHT_` prefix:

| YAML key | Env var | Notes |
|----------|---------|-------|
| `storage.mode` | `LANGSIGHT_STORAGE_MODE` | |
| `storage.clickhouse_url` | `LANGSIGHT_CLICKHOUSE_URL` | |
| `storage.postgres_url` | `LANGSIGHT_POSTGRES_URL` | |
| `alerts.slack_webhook` | `LANGSIGHT_SLACK_WEBHOOK` | |
| `health_check_interval_seconds` | `LANGSIGHT_HEALTH_CHECK_INTERVAL_SECONDS` | |
| `redact_payloads` | `LANGSIGHT_REDACT_PAYLOADS` | `true` or `false` |
| *(admin bootstrap)* | `LANGSIGHT_ADMIN_EMAIL` | First-run only — creates admin account |
| *(admin bootstrap)* | `LANGSIGHT_ADMIN_PASSWORD` | First-run only |
| *(auth)* | `LANGSIGHT_AUTH_SECRET` | Required — shared session signing secret between Next.js and FastAPI (min 32 chars). Set the same value for both services. |
| *(CORS)* | `LANGSIGHT_CORS_ORIGINS` | Comma-separated allowed origins (default: `http://localhost:3003`). Set explicitly for production deployments. |
| *(proxy trust)* | `LANGSIGHT_TRUSTED_PROXY_CIDRS` | Comma-separated CIDRs for trusted proxy headers (default: `127.0.0.1/32,::1/128`) |
| *(ClickHouse auth)* | `CLICKHOUSE_USER` | ClickHouse username |
| *(ClickHouse auth)* | `CLICKHOUSE_PASSWORD` | ClickHouse password |

<Note>
  `LANGSIGHT_ADMIN_EMAIL` and `LANGSIGHT_ADMIN_PASSWORD` are consumed once on first run to create the initial admin user. After that, manage users via Settings → Users in the dashboard.
</Note>

<Note>
  `NEXT_PUBLIC_LANGSIGHT_API_KEY` is no longer required for the dashboard. Dashboard authentication is handled server-side via NextAuth — the session is never exposed to the browser. API keys are for SDK and CLI access only.
</Note>

## Global payload redaction (server-side)

An admin can enforce payload redaction at the instance level, overriding individual SDK `redact_payloads` settings. When enabled, the server strips `input_args`, `output_result`, `llm_input`, and `llm_output` from **all** incoming spans before they are stored.

### Via the dashboard

Go to **Settings -> Instance -> Data Privacy** and toggle **Redact all payloads** on.

### Via the API

```bash
# Check current setting
curl http://localhost:8000/api/settings \
  -H "X-API-Key: lsk_your_key"

# Enable global redaction
curl -X PUT http://localhost:8000/api/settings \
  -H "X-API-Key: lsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"redact_payloads": true}'
```

**Settings object**:

```json
{
  "redact_payloads": true
}
```

### How it works

| Layer | Setting | Effect |
|-------|---------|--------|
| SDK | `LangSightClient(redact_payloads=True)` | Client omits payloads before sending |
| Server | `PUT /api/settings {"redact_payloads": true}` | Server strips payloads on ingestion |
| Both | Server setting wins | Even if SDK sends payloads, server strips them |

The server-side toggle is enforced in the `POST /api/traces/spans` handler before spans are written to storage. This guarantees no payload data reaches ClickHouse regardless of how individual SDK clients are configured.

<Warning>
  Enabling global redaction disables session replay payload inspection and Playground Replay across the entire instance. Span timing, status, cost, and token counts are still captured.
</Warning>

## Slack alert configuration

Slack alerts can be configured in two ways.

### Via the dashboard (recommended)

Go to **Settings → Notifications** in the dashboard:

1. Paste your Slack webhook URL into the "Slack Webhook URL" field.
2. Click **Test** to verify the webhook receives a Block Kit message.
3. Toggle each alert type on or off as needed.
4. Click **Save**.

Alert preferences and the webhook URL are stored in-memory (in the API process). **If you restart the API container the configuration is lost unless you also set the env var** (see below).

### Via environment variable

```bash
LANGSIGHT_SLACK_WEBHOOK=https://hooks.slack.com/services/T.../B.../xxx
```

When this env var is set it acts as the default webhook URL. Values saved through the dashboard UI override it at runtime but revert to the env var value on restart.

### Alert types

| Alert type | Triggered by | Default |
|---|---|---|
| `mcp_down` | MCP server health check transitions to DOWN | On |
| `mcp_recovered` | MCP server transitions from DOWN back to UP | On |
| `agent_failure` | Agent session ends with `failed_calls > 0` | On |
| `slo_breached` | SLO evaluator returns `breached` for any defined SLO | On |
| `anomaly_critical` | Z-score anomaly crosses the critical threshold (|z| >= 3) | On |
| `security_critical` | CVE or OWASP check returns a CRITICAL severity finding | On |

<Note>
  For persistent alert configuration across restarts, set `LANGSIGHT_SLACK_WEBHOOK` in your environment and manage per-type toggles via the dashboard. The next release will add persistent storage for alert preferences.
</Note>

## Prometheus scrape configuration

LangSight exposes a `GET /metrics` endpoint in Prometheus text exposition format. No authentication is required -- Prometheus scrapers can reach it directly.

Add the following job to your `prometheus.yml`:

```yaml
# prometheus.yml
scrape_configs:
  - job_name: langsight
    scrape_interval: 15s
    static_configs:
      - targets: ["localhost:8000"]  # or "api:8000" inside Docker Compose
    metrics_path: /metrics
```

If you run LangSight inside Docker Compose, use the service name as the target:

```yaml
scrape_configs:
  - job_name: langsight
    scrape_interval: 15s
    static_configs:
      - targets: ["api:8000"]
    metrics_path: /metrics
```

See [Monitoring](/monitoring) for available metrics, Grafana dashboard tips, and SSE live event feed usage.

## Dashboard authentication

The dashboard authenticates users through the following flow:

1. The user logs in via the NextAuth login page (`/auth/signin`).
2. NextAuth creates a server-side session signed with `LANGSIGHT_AUTH_SECRET`.
3. Every dashboard API call goes through the Next.js proxy at `/api/proxy/*`.
4. The proxy reads the session server-side, injects `X-User-Id` and `X-User-Role` headers, and forwards the request to FastAPI.
5. FastAPI trusts those headers only when the request originates from `localhost` (`127.0.0.1` / `::1`).

This means **no API keys are needed in the browser** and no session tokens are exposed to client-side JavaScript.

<Warning>
  FastAPI must not be directly internet-accessible. It must sit behind the Next.js proxy (or a reverse proxy you control). If FastAPI is exposed publicly, external clients could set `X-User-Id` / `X-User-Role` headers directly and bypass authentication.
</Warning>
