From a60bf6237262408f085fd98690644aae34fa27c7 Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Sat, 17 Oct 2026 17:22:23 -0700 Subject: [PATCH] docs: align the site and repository docs with the product A review of every site page and repository document against the code on main. Pages state current behaviour in the present tense, each fact lives in its owning page with links elsewhere, and terms match the product. - MCP: client protocol requirement, Origin validation on both mounts, identity-based tool limits, cancellation, and complete scope challenges; sign-in rate limits stay IP-based. - Dashboards and chat: the Slow operations table, combined-filter diagnoses, and empty views staying collapsed. - Operations: public URL security role, metrics privacy, insecure cookie warnings, leaked setup URL recovery, self-signup granting paid AI access, and OIDC eligibility without allowlists. - Status: the published benchmark now cites v2026.10.8 and its evidence. - Testing: service-map query reads, accessible-name checks, and the landing recording, encoding and upload steps. Generated references come from their updated sources. Claude-Session: https://claude.ai/code/session_018HfyEXHyGD1utmKF4CQtyQ --- .env.example | 8 +- CONTRIBUTING.md | 26 ++- README.md | 9 +- SECURITY.md | 7 +- cmd/fanout-docgen/main.go | 4 +- cmd/fanout-docgen/mcptools.go | 20 +-- cmd/fanout-docgen/roles.go | 10 +- cmd/fanout-docgen/routes.go | 42 ++--- docs/authentication.md | 22 ++- docs/operations.md | 3 + docs/release.md | 31 ++-- docs/testing.md | 50 +++--- internal/config/config.go | 31 ++-- internal/mcp/server.go | 2 +- site/scripts/landing-recordings.md | 7 +- .../docs/explanation/authentication-modes.mdx | 151 ++++++------------ .../docs/explanation/storage-model.mdx | 12 +- .../docs/explanation/why-one-binary.mdx | 69 +++----- .../docs/guides/back-up-and-restore.mdx | 6 +- .../content/docs/guides/build-dashboards.mdx | 52 +++--- .../content/docs/guides/connect-over-mcp.mdx | 53 +++--- .../src/content/docs/guides/set-up-alerts.mdx | 42 +++-- .../src/content/docs/guides/terminate-tls.mdx | 19 ++- site/src/content/docs/guides/troubleshoot.mdx | 70 +++----- .../content/docs/guides/tune-retention.mdx | 14 +- .../content/docs/reference/configuration.mdx | 6 +- .../content/docs/reference/data-layout.mdx | 7 +- site/src/content/docs/reference/endpoints.mdx | 13 +- .../content/docs/reference/http-routes.mdx | 48 ++---- site/src/content/docs/reference/mcp-tools.mdx | 58 +++---- site/src/content/docs/reference/roles.mdx | 11 +- .../content/docs/reference/settings/ai.mdx | 4 +- .../docs/reference/settings/ingest.mdx | 2 +- .../docs/reference/settings/server.mdx | 2 +- .../docs/reference/settings/storage.mdx | 4 +- site/src/content/docs/start/first-boot.mdx | 44 ++--- site/src/content/docs/start/install.mdx | 50 +++--- .../src/content/docs/start/send-telemetry.mdx | 46 +++--- .../src/content/docs/start/what-fanout-is.mdx | 47 +++--- site/src/content/docs/status/capabilities.mdx | 48 ++---- 40 files changed, 457 insertions(+), 693 deletions(-) diff --git a/.env.example b/.env.example index 35443f4be..096815f7a 100644 --- a/.env.example +++ b/.env.example @@ -71,12 +71,12 @@ # FANOUT_DEFAULT_NAMESPACE= # FANOUT_DUCKDB_MAX_CONNECTIONS; integer -# Caps the DuckDB connection pool. Reads scan immutable Parquet concurrently; rollup-cache writes are serialized by the query write gate. Zero means "size it from the machine" — the same spelling DuckDBThreads uses for deferring to a default. Resolution happens in resolveSizing and is reported in the startup configuration log. +# Caps the DuckDB read connection pool. Reads scan immutable Parquet concurrently; analytical and completed-batch writes use separate gates and connections. Zero selects available Go CPUs, bounded to 2–16. Startup logs and /readyz report the resolved pool size. # Default: 0 # FANOUT_DUCKDB_MAX_CONNECTIONS= # FANOUT_DUCKDB_MEMORY; string -# Caps DuckDB's memory (e.g. "8GB"). Empty means Fanout sizes it from detected memory, reserving headroom for the Go runtime; see resolveSizing. DuckDB's own default is 80% of detected RAM, which is calculated as though DuckDB owned the machine and has been observed to get the process OOM-killed once the Go heap is added on top. +# Caps DuckDB's memory (e.g. "8GB"). Empty selects 60% of detected available memory, reserving headroom for Go. If detection fails, DuckDB uses its default with a process headroom adjustment. Startup logs and /readyz report the resolved budget and detection status. Set an explicit cap when memory limit detection is incomplete. # Default: (empty) # FANOUT_DUCKDB_MEMORY= @@ -91,7 +91,7 @@ # FANOUT_INGEST_BATCH_SIZE= # FANOUT_INGEST_MAX_IN_FLIGHT_BYTES; integer -# Caps the decoded telemetry the process will hold across concurrent requests. Concurrency is HTTP/2 streams times connections and each handler holds its batch until the commit is durable, so without a ceiling a burst is bounded only by memory. Zero is unbounded. A single request is admitted when no other request holds budget, even if it exceeds the limit. +# Caps decoded telemetry held across concurrent requests until durable publication. Zero is unbounded. A single request is admitted when no other request holds budget, even if it exceeds the limit. # Default: 268435456 # FANOUT_INGEST_MAX_IN_FLIGHT_BYTES= @@ -178,7 +178,7 @@ # FANOUT_PPROF_ENABLED= # FANOUT_PUBLIC_URL; string -# Sets the external browser origin. Required for OIDC; HTTPS is required with MCP. +# Sets the external browser origin, MCP token audience, and trusted MCP request origin. Required for OIDC; HTTPS is required with MCP. # Default: (empty) # FANOUT_PUBLIC_URL= diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2db2e8322..6e5af5601 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,9 +62,8 @@ Run `just e2e` with Google Chrome installed for the separate CI browser smoke suite. See [browser smoke testing](docs/testing.md) for coverage and failure artifacts. `just install` also installs [Lefthook](https://lefthook.dev)'s Git hooks, which run -formatting and linting on commit and the full gate on push. That is the fastest -way to avoid a red CI run. -The pre-push hook may be skipped when Lefthook detects no changed files; +formatting and linting on commit and the full gate on push. The pre-push hook +may be skipped when Lefthook detects no changed files; CI runs the same `just check` unconditionally and enforces the gate. The browser workspace uses `package.json` overrides for transitive security @@ -72,7 +71,7 @@ fixes that their direct dependencies have not locked yet. Keep those overrides until the upstream ranges resolve to patched versions; `just ui-audit` accepts only the existing build-only braces advisory exception documented in the justfile. -## Things that surprise people +## Repository conventions **The browser assets are committed.** `ui/host` builds into `internal/ui/dist` and its MCP app builds into `internal/mcp/apps`; both outputs are tracked in @@ -96,15 +95,11 @@ the clone is labstack/fanout and contains the pinned revision. Archify normalize and verifies repository identity and the pinned revision during `finalize`. JSON inputs, SVG outputs, and the site copy still use your contributor checkout. -**The social preview card is generated.** `site/public/social-card.png` is -rendered from `docs/media/social-card.typ` by `just social-card`, which needs Inter on a -font path — set `FANOUT_FONT_PATH` to a directory holding it. CI has no such -directory, so nothing re-renders the card to compare it; what `site-build` does -assert is that the committed PNG exists and still matches the dimensions the -site's head advertises. If you edit the source, run the recipe and commit the -PNG in the same change. The recipe fails when the -font is missing rather than shipping a card in a substitute face, which typst -would otherwise do without complaint. +**The social preview card is generated.** `just social-card` renders +`docs/media/social-card.typ` into `site/public/social-card.png`. Set +`FANOUT_FONT_PATH` to a directory containing Inter; the recipe requires Typst +0.15.1 and fails if the font is missing. Commit the source and PNG together. +The site build checks the committed image’s dimensions; CI does not rerender it. **Runtime configuration is strict.** `internal/config/config.go` owns the schema. New settings need an environment name, a documentation `group` tag, @@ -168,9 +163,8 @@ Before your first pull request can be merged, you need to sign the [CLA](CLA.md). A bot comments on the pull request with a sentence to reply with; that is the whole process, and it is only needed once. -The CLA grants LabStack the right to relicense contributions. That is what -keeps future licensing decisions possible — without it, any change would -require permission from every past contributor individually. +The CLA grants LabStack the right to relicense contributions. Review the +agreement before contributing. ## License diff --git a/README.md b/README.md index 87cb58b10..0177bce62 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,8 @@ Fanout keeps OpenTelemetry traces, logs, and metrics in one binary and one data directory, with no -external services to operate. Fanout is pre-release and changes without migration paths; the browser -client, chat investigator, MCP tools, dashboards, and alerts are preview capabilities +external storage services to operate. Fanout is pre-release and changes without migration paths; the browser +client, built-in agent, MCP tools, dashboards, and alerts are preview capabilities ([status](https://fanout.run/status/capabilities)). Start with the [documentation](https://fanout.run) or run it below. @@ -101,7 +101,8 @@ See [AI settings](https://fanout.run/reference/settings/ai). Set `FANOUT_PUBLIC_URL` to your stable, externally reachable HTTPS origin, then point a remote MCP client at that origin's `/mcp` endpoint. The client discovers and registers through OAuth; you -authorize its scopes in the browser. See [connect over +authorize its scopes in the browser. The client must support MCP protocol `2026-07-28` over +stateless Streamable HTTP; older versions and the `initialize` handshake are unsupported. See [connect over MCP](https://fanout.run/guides/connect-over-mcp) for setup and permissions. ## How it compares @@ -207,7 +208,7 @@ generated assets, hooks, and project layout. ## Releases Versions are CalVer — `vYYYY.M.N[-alpha|-beta|-rc]`, numbered from 0 within each month across all -maturity suffixes. Fanout is currently alpha (for example, `v2026.10.1-alpha`); GA has no suffix. +maturity suffixes. Fanout is alpha (for example, `v2026.10.1-alpha`); GA has no suffix. Container tags omit the leading `v`, and every release moves `latest`. Tagged releases publish identical manifests to Docker Hub (`labstack/fanout`) and GHCR (`ghcr.io/labstack/fanout`); GHCR is canonical and also carries development images. diff --git a/SECURITY.md b/SECURITY.md index f952a29dc..93a4665e8 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -24,11 +24,12 @@ these areas are especially relevant: - Authentication and session handling — local email codes, OIDC, MCP OAuth - Authorization between roles, and between browser sessions and MCP clients - Ingest credential generation, storage, rotation, and enforcement -- Query paths that could read data outside the requesting namespace +- Query paths that bypass an explicit namespace filter or dashboard ownership - Anything that turns telemetry content into executable behavior -The credential classes above are deliberately separate and are never -interchangeable. A finding that crosses those boundaries is in scope. +Namespaces filter telemetry queries; they do not restrict account access to data. +Every telemetry reader can query every namespace. Credential substitution and +cross-owner dashboard access are authorization findings. ## Supported versions diff --git a/cmd/fanout-docgen/main.go b/cmd/fanout-docgen/main.go index df805d145..0850ae24e 100644 --- a/cmd/fanout-docgen/main.go +++ b/cmd/fanout-docgen/main.go @@ -486,10 +486,10 @@ var groups = map[string]groupPage{ }, "ai": { Title: "AI provider settings", - Description: "The provider, key, model and base URL backing the chat investigator.", + Description: "The provider, key, model and base URL backing the built-in agent.", Summary: "Chat is disabled unless a provider is selected; its API key is then required.", ReadWhen: []string{ - "The chat investigator is disabled and you want it on.", + "The built-in agent is disabled and you want it on.", "You are pointing Fanout at a self-hosted or proxied model endpoint.", }, }, diff --git a/cmd/fanout-docgen/mcptools.go b/cmd/fanout-docgen/mcptools.go index 2a7082df0..f4fc538e1 100644 --- a/cmd/fanout-docgen/mcptools.go +++ b/cmd/fanout-docgen/mcptools.go @@ -169,23 +169,7 @@ func renderMCPTools() ([]byte, error) { b.WriteString("\n") } b.WriteString("## Authentication\n\n") - b.WriteString("MCP uses OAuth, not a static key, and **not the ingest token** — an agent\n") - b.WriteString("presenting the ingest token is rejected. A client discovers the endpoints,\n") - b.WriteString("registers itself, and is issued a token bound to this instance's resource\n") - b.WriteString("URI. [Connect an agent](/guides/connect-over-mcp) covers the flow.\n\n") - - b.WriteString("The dashboard tools act on the authenticated user's **own** dashboards. The\n") - b.WriteString("capability boundary is `dashboards:manage-own`: an agent acts as the user\n") - b.WriteString("whose credential it holds and cannot reach anyone else's. A tool description\n") - b.WriteString("that tells a model when to call it is guidance to the model, not a\n") - b.WriteString("permission check — see [roles](/reference/roles).\n\n") - - b.WriteString("## What is not here\n\n") - b.WriteString("No tool writes telemetry, changes configuration, manages users, or edits\n") - b.WriteString("alert rules. Ingest is OTLP only and the rest is HTTP surface — see\n") - b.WriteString("[HTTP routes](/reference/http-routes). An agent connected over MCP can read\n") - b.WriteString("everything the instance knows and manage its own dashboards, and that is the\n") - b.WriteString("whole envelope.\n") + b.WriteString("MCP uses OAuth tokens bound to the instance’s resource URI.\n[Connect an agent](/guides/connect-over-mcp#scopes) documents protocol\nrequirements and delegated scopes. Dashboard tools operate on the authenticated\nuser’s own dashboards and require the account capability\n`dashboards:manage-own`; see [roles](/reference/roles).\n\n## Other interfaces\n\nUse OTLP to write telemetry. Configuration uses environment variables, and user\nand alert management use the [HTTP API](/reference/http-routes).\n") toolCount = tools return []byte(b.String()), nil @@ -206,7 +190,7 @@ func effect(tool mcp.ToolDoc) string { func effectProse(tool mcp.ToolDoc) string { switch { case tool.ReadOnly: - return "Read-only. Calling it changes nothing." + return "Read-only." case tool.Destructive && tool.Idempotent: return "**Replaces existing state.** Calling it twice with the same arguments " + "leaves the same result as calling it once, but the first call has already " + diff --git a/cmd/fanout-docgen/roles.go b/cmd/fanout-docgen/roles.go index af75b8729..b651c5d0e 100644 --- a/cmd/fanout-docgen/roles.go +++ b/cmd/fanout-docgen/roles.go @@ -20,7 +20,7 @@ var capabilityNotes = map[string]string{ "dashboards:manage-own": "Create and edit dashboards you own. Owner-scoped for every role, including admin.", "ingest:read-metadata": "See ingest settings, but not the token itself.", "alerts:manage": "Create, change and delete alert rules.", - "agent:run": "Run the chat investigator, which calls a model provider and acts on the instance's behalf.", + "agent:run": "Run the built-in agent, which calls a model provider and acts on the instance's behalf.", "ingest:manage": "Rotate the ingest token.", "users:manage": "Create, change and remove user accounts and their roles.", "operations:read": "Read the instance's own internals: Prometheus metrics and, when enabled, the profiling endpoints.", @@ -83,13 +83,7 @@ func renderRoles() ([]byte, error) { b.WriteString("{/* Generated by cmd/fanout-docgen from internal/api. Edit the generator, not this page. */}\n\n") - b.WriteString("Fanout has three roles. They are fixed — there is no custom role builder, and\n") - b.WriteString("a user holds exactly one.\n\n") - - b.WriteString("Every protected route names a capability rather than a role, and a role is a\n") - b.WriteString("set of capabilities. The table below is that set, read from the same map the\n") - b.WriteString("middleware consults, so it cannot describe a permission the server does not\n") - b.WriteString("grant.\n\n") + b.WriteString("Each user has one fixed role: `viewer`, `operator` or `admin`. The table is\ngenerated from the capability map enforced by the authorization middleware.\n\n") b.WriteString("| Capability |") for _, role := range roleOrder { diff --git a/cmd/fanout-docgen/routes.go b/cmd/fanout-docgen/routes.go index 87ab13b52..9e7ddfed0 100644 --- a/cmd/fanout-docgen/routes.go +++ b/cmd/fanout-docgen/routes.go @@ -249,14 +249,8 @@ func renderRoutes(routes []api.RouteDoc) []byte { b.WriteString("OTLP shares this listener but uses its own handlers and ingest credential; see\n") b.WriteString("[send your first telemetry](/start/send-telemetry).\n\n") - b.WriteString(":::note[What this table is, and what it is not]\n") - b.WriteString("Every route the binary registers, wherever it is registered — the application\n") - b.WriteString("handlers, the agent runtime, the operational and protocol endpoints, and the\n") - b.WriteString("SPA catch-all. A route the generator cannot get a classification for fails\n") - b.WriteString("the build, so a new route cannot quietly go undocumented.\n\n") - b.WriteString("It is the surface the binary *can* register, not the surface any particular\n") - b.WriteString("instance exposes. Some of it is conditional, so check the instance before\n") - b.WriteString("concluding a route is reachable — or that it is not:\n\n") + b.WriteString("## Conditional routes\n\nThe table includes every route the binary can register. These routes depend on\nconfiguration:\n\n") + b.WriteString("- `/debug/pprof/*` — only when `FANOUT_PPROF_ENABLED` is true, which is\n") b.WriteString(" **not** the default. Enabling it also turns on mutex and block sampling.\n") b.WriteString("- `/mcp`, `/api/mcp`, `/oauth/*` and `/.well-known/*` — only when\n") @@ -267,27 +261,13 @@ func renderRoutes(routes []api.RouteDoc) []byte { b.WriteString(" `FANOUT_AUTH_MODE=oidc`.\n\n") b.WriteString("Everything else is always registered. A path shown with `:name` or `*` is the\n") b.WriteString("pattern Echo matches on, not a literal URL.\n") - b.WriteString(":::\n\n") - - b.WriteString(":::caution[Most of this is not a public API]\n") - b.WriteString("The `/api/*` routes are the browser client's own backend. They are listed here\n") - b.WriteString("so an operator can see the whole surface and what guards it — not as an\n") - b.WriteString("interface to build against. They change with the client, without notice and\n") - b.WriteString("without migration paths.\n\n") - b.WriteString("The supported programmatic interface is **MCP**, at `/mcp` — see\n") - b.WriteString("[MCP tools](/reference/mcp-tools). The stable non-MCP surfaces are OTLP\n") - b.WriteString("ingest, and the operational endpoints in [endpoints](/reference/endpoints).\n\n") - b.WriteString("Alert rules (`/api/alerting/rules`, `/api/alerting/alerts`) currently have no browser\n") - b.WriteString("page. Ingest-token rotation uses `POST /api/settings/ingest/token/rotate`\n") - b.WriteString("and is also available to administrators on **Connect telemetry**.\n") - b.WriteString(":::\n\n") + b.WriteString("\n") + + b.WriteString("## Interface stability\n\nThe `/api/*` routes serve the browser client and can change without migration\npaths. [MCP](/guides/connect-over-mcp) is the agent interface. OTLP ingest and\n[operational endpoints](/reference/endpoints) have their own contracts.\n\nManage alert rules through the [HTTP API](/guides/set-up-alerts). Administrators\nrotate ingest tokens on **Connect telemetry** or with\n`POST /api/settings/ingest/token/rotate`.\n\n") b.WriteString("## Errors\n\nApplication API errors, including unknown routes and wrong methods, return objects shaped like\n`{\"code\":\"bad_request\",\"message\":\"Safe explanation\"}`. Codes are stable\nsnake_case identifiers; clients branch on `code` rather than message text.\nInvalid dashboard or panel specs also include `problems` with field paths,\nmessages and optional hints. Every error response uses `Cache-Control: no-store`;\nHEAD errors have no body. Server failures return a short, safe message; the\nunderlying error is logged and never returned.\n\nDefault codes by HTTP status:\n\n| Status | Code |\n|---|---|\n| 400 | `bad_request` |\n| 401 | `unauthorized` |\n| 403 | `forbidden` |\n| 404 | `not_found` |\n| 405 | `method_not_allowed` |\n| 409 | `conflict` |\n| 413 | `payload_too_large` |\n| 415 | `unsupported_media_type` |\n| 422 | `unprocessable` |\n| 429 | `rate_limited` |\n| 500 | `internal` |\n| 502 | `bad_gateway` |\n| 503 | `unavailable` |\n| 504 | `timeout` |\n\nOther 4xx statuses use `bad_request`; other 5xx statuses use `internal`.\nSpecific conditions use `already_current`, `dashboard_version_not_found`,\n`dashboard_version_conflict`, `invalid_spec` and `last_active_administrator`.\nTool failures carry `error: {code, message}` inside the tool result.\nPanel execution results keep their own status and error fields.\nOAuth, OTLP/gRPC, MCP JSON-RPC and AG-UI run errors keep their protocol spelling.\nOperational responses at `/healthz`, `/readyz` and `/metrics` keep their bodies.\n\n") - b.WriteString("The **Requires** column is not a description of the rule. It is the answer the\n") - b.WriteString("authorization middleware gives for that exact method and path, so a route\n") - b.WriteString("cannot be documented as public while the server treats it otherwise.\n") - b.WriteString("Capabilities map to roles in [roles](/reference/roles).\n\n") + b.WriteString("The **Requires** column comes from the authorization middleware for each method\nand path. [Roles](/reference/roles) maps capabilities to roles.\n\n") b.WriteString("| Method | Path | Requires |\n") b.WriteString("|---|---|---|\n") @@ -296,19 +276,15 @@ func renderRoutes(routes []api.RouteDoc) []byte { } b.WriteString("\n## What the requirements mean\n\n") - b.WriteString("- **none** — reachable without a credential. The health endpoints are\n") - b.WriteString(" deliberately here: a probe that needs a credential fails for the wrong\n") - b.WriteString(" reason during an outage.\n") + b.WriteString("- **none** — reachable without a credential.\n") + b.WriteString("- **any signed-in user** — a session, but no particular capability.\n") b.WriteString("- **protocol handshake** — the OAuth and MCP endpoints, which authenticate\n") b.WriteString(" as part of their own protocol rather than through the middleware.\n") b.WriteString("- **a named capability** — the caller's role must carry it.\n") b.WriteString("- **or a service credential** — additionally reachable without a browser\n") b.WriteString(" session, which is how a scraper reaches the metrics endpoint.\n\n") - b.WriteString("A method of `Any` means the route is registered for every verb, and the middleware\n") - b.WriteString("gives the same answer for all of them — where it would not, this page fails\n") - b.WriteString("to build rather than pick one. `GET /*` serves the single-page application\n") - b.WriteString("for browser paths. Unknown `/api/*` and OTLP paths return errors instead.\n") + b.WriteString("`Any` registers every HTTP method with the same authorization requirement.\n`GET /*` serves the single-page application for browser paths. Unknown `/api/*`\nand OTLP paths return errors.\n") return []byte(b.String()) } diff --git a/docs/authentication.md b/docs/authentication.md index 5d9770912..3f14b7e1d 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -20,7 +20,7 @@ stderr containing a **setup URL**: ============================================================ ``` -Properties worth knowing: +Setup credential behavior: - The credential carries 128 bits of entropy and lives only in memory. It is never written to the database. @@ -37,7 +37,7 @@ Properties worth knowing: > [!WARNING] > The setup URL is an administrator credential. Anywhere the process's stderr > is collected — container logs, a log shipper, a terminal recording, a shared -> screen — now holds it until the credential is consumed or expires. Treat a +> screen — can hold it until the credential is consumed or expires. Treat a > leaked banner as a compromised installation and rebuild the database. ### Before you complete setup @@ -57,7 +57,7 @@ login link remains available when delivery fails. Local accounts are invitation-only by default. To let any verified email address create an account, set `FANOUT_SELF_SIGNUP=true`. Fanout sends the -existing email code and creates an active `viewer` only after that code is +email code and creates an active `viewer` only after that code is successfully verified. The role is fixed: self-signup can never create an operator or administrator. The setting requires complete SMTP configuration and local auth mode. @@ -91,7 +91,7 @@ online is supported by the control database's WAL and busy-timeout settings. Fix SMTP after regaining access if email-code login is expected. OIDC-mode recovery remains at the identity provider or OIDC configuration layer; local -login links are deliberately unavailable in that mode. +login links are unavailable in that mode. ### User account API @@ -142,9 +142,9 @@ grants, and dashboards. ## Reverse proxies and client IP -Rate limiting and audit attribution both key on the client IP. Behind a proxy, -that address arrives in `X-Forwarded-For`, and trusting the header blindly lets -any client forge both. +Sign-in rate limiting and audit attribution use the client IP. MCP tool invocation +limits use the authenticated user and OAuth client. Behind a proxy, the client +address arrives in `X-Forwarded-For`; trust it only from configured proxies. - **Default (no configuration):** forwarded headers are ignored and the direct peer address is used. Safe when Fanout is exposed directly. @@ -176,13 +176,13 @@ export FANOUT_OIDC_ALLOWED_DOMAINS="*" export FANOUT_OIDC_DEFAULT_ROLE=viewer ``` -The wildcard is deliberately explicit and is rejected with +The wildcard is rejected with `FANOUT_OIDC_EMAIL_VERIFICATION=issuer`. Use a specific domain or group allowlist for a private installation. A wildcard makes the installation available to every identity accepted by the configured provider, so rate-limit public traffic and budget AI usage at the deployment edge. -Fanout's roles remain installation-wide rather than deployment-specific: +Fanout’s roles apply across the instance: - `viewer` reads telemetry, uses chat and MCP tools within viewer permissions, and manages its own dashboards. @@ -222,9 +222,7 @@ token entirely and emits `_claim_names`/`_claim_sources` pointing at the Graph API instead. An omitted claim does not mean the user belongs to no groups. When any group-based policy is configured and the token signals overage, Fanout -**denies the login** rather than reading the absence as an empty group set — -the alternative would demote or lock out every member of a large directory at -once. The denial names the group claim so the remediation is clear. +**denies the login** and names the group claim in the error. Fix it at the identity provider: configure the application registration to emit only **groups assigned to the application** rather than all group memberships. diff --git a/docs/operations.md b/docs/operations.md index 29419cb6d..fa3cbba4e 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -172,6 +172,9 @@ with `/mcp` appended. Fanout accepts public MCP transport requests only when their HTTP `Host` matches that origin, so the reverse proxy must preserve the original host. +MCP also validates `Origin` before authentication; see +[Connect an agent over MCP](https://fanout.run/guides/connect-over-mcp#protocol). + ## Health and monitoring `fanout healthcheck` derives `/healthz` from `FANOUT_ADDR` or its built-in diff --git a/docs/release.md b/docs/release.md index 27edeed59..c3b3ba62c 100644 --- a/docs/release.md +++ b/docs/release.md @@ -15,8 +15,8 @@ Fanout publishes one release from a verified commit on `main`. A release contain Tags use unpadded CalVer: `vYYYY.M.N[-alpha|-beta|-rc]`. The suffix states product maturity; GA has no suffix. The first release in a month is `.0`, and every -release increments `N` regardless of suffix. Fanout is currently alpha; after -`v2026.10.0`, the next release is `v2026.10.1-alpha`. +release increments `N` regardless of suffix. Fanout is alpha. For example, +`v2026.10.1-alpha` follows `v2026.10.0-alpha`. Container tags omit the leading `v`, so `v2026.10.1-alpha` publishes `ghcr.io/labstack/fanout:2026.10.1-alpha` and `labstack/fanout:2026.10.1-alpha`. Every release moves `latest`. GitHub Releases are not marked as prereleases: @@ -24,11 +24,8 @@ the tag carries maturity, and the installer's `/releases/latest` must resolve. Only release and `latest` tags are mirrored to Docker Hub; `main` and commit tags remain GHCR-only. -Onebox consumes that public container reference. Its deployment planner resolves -the tag to an immutable registry digest before release, so production manifests -can remain readable without making the running revision mutable. Live Onebox -manifests and secret files are deployment state and do not belong in this public -repository. +Deployments should resolve public tags to immutable registry digests. Keep live +manifests and secret profiles outside this public repository. ## Creating a release @@ -49,14 +46,8 @@ installer, and verifies provenance. Only after those checks pass does the workflow publish the release's `server.json` to the MCP Registry with GitHub OIDC; no long-lived registry credential is stored in the repository. -Fanout does not currently use GoReleaser. DuckDB requires CGO and the supported -targets are built on four native runners. GoReleaser's supported split-and-merge -pipeline for native CGO builds is a Pro-only feature, while maintaining four -cross-compilation toolchains would add risk without improving the artifact. The -custom workflow follows the same clean-tree, tag, archive, checksum, and -post-publish verification discipline without introducing a commercial release -dependency. Revisit this if the build becomes cross-compilable or a GoReleaser -Pro subscription is intentionally adopted. +The release workflow builds CGO targets on four native runners. It creates +archives, checksums and attestations, then verifies the published artifacts. ## Consumer verification @@ -78,12 +69,10 @@ docker buildx imagetools inspect docker.io/labstack/fanout:2026.10.1-alpha ## Supply-chain scope -The first public release provides SHA-pinned Actions, archive checksums, GitHub +The release workflow uses SHA-pinned Actions, archive checksums, GitHub build provenance, dependency and secret scanning, legal inventories, and post-publication verification. The container is consumed by immutable digest. -Standalone signatures and SBOM publication are deferred until Fanout has a -consumer that verifies them. Adding unconsumed artifacts would create a policy -claim without an operational control. This decision does not block adding either -later; provenance and the deterministic `THIRD_PARTY_NOTICES` inventory already -establish the release source and shipped dependency set. +Standalone signatures and SBOMs are outside the release artifact inventory. +GitHub build provenance identifies the source; `THIRD_PARTY_NOTICES` lists the +shipped dependencies. diff --git a/docs/testing.md b/docs/testing.md index 952424ca1..a06335524 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -60,22 +60,25 @@ timings and any calibrated CI ceiling must be reported separately. For individual panels, collect at least one hundred warm executions per query shape against the same snapshot and report p95 against **500 ms**. Cover the headline totals, grouped latency/error measures, time series and logs actually -used by the board. Retain failures and timeout counts alongside latency; do not +used by the dashboard. Retain failures and timeout counts alongside latency; do not make a slow or failed run disappear by retrying until it passes. These targets are acceptance criteria, not guarantees for arbitrary telemetry volumes. -The current executor compiles ordinary structured aggregates against raw +The executor compiles ordinary structured aggregates against raw telemetry. Its disposable read-cache version 4 stores completed-batch trace -candidates and parts, not general minute aggregates. Service map and health -panels use analytical rollups with their own watermark lag and approximate -latency semantics. Do not assume those rollups answer arbitrary raw counts, +candidates and parts, not general minute aggregates. Service maps combine +analytical rollups with a raw client-span query for external peers. That query +materializes the filtered client projection once for reuse by peer and edge +aggregates; its child-span and observed-service checks also read spans. Health +panels use analytical rollups. Rollup data has separate watermark lag and approximate latency +semantics. Do not assume those rollups answer arbitrary raw counts, rates or quantiles exactly, or report every dashboard query as cached. -The existing native tests exercise whole-window totals, bounded newest buckets +The native tests exercise whole-window totals, bounded newest buckets and width-aware 24-hour bucket selection: ```sh -rtk just test ./internal/panel -run '"TestGaugeTotalsMatchStat|TestBudgetKeepsCompleteNewestBuckets|TestWidthAwareCellBuckets"' +just test ./internal/panel -run 'TestGaugeTotalsMatchStat|TestBudgetKeepsCompleteNewestBuckets|TestWidthAwareCellBuckets' ``` Use the pinned engine wrapper through `just test`, with the workspace's offline @@ -88,11 +91,11 @@ measurements and limitations in the milestone's `docs/benchmarks/` document. Run the browser-free host tests and type checks from `ui/host`: ```sh -rtk bun run test -rtk bun run lint +bun run test +bun run lint ``` -The existing theme, chart-unit and row-formatting tests check semantic text and +The theme, chart-unit and row-formatting tests check semantic text and mark contrast in both schemes. Keyboard tests cover dashboard focus, chart navigation, range cancellation, full-screen and shortcut preferences. The exact palette-order test preserves six categorical colour slots; its name alone does @@ -106,6 +109,11 @@ single-key shortcut switch, typing/menu/dialog exceptions and error inspection in Data, including an error longer than its Chart preview. Review populated, empty, failed, stale and truncated states. +Check that accessible names contain the visible labels of trace links, service-map +nodes, filter chips, flame-graph spans and the account menu. Service-map node names +must also include health; full trace IDs and service details remain available in +titles. + Assess WCAG AA text contrast and chart marks against their actual surfaces. Check all six ordered categorical colours plus Other under colour-vision deficiency simulation. Browser accessibility scans cannot read canvas text, so @@ -122,9 +130,9 @@ an unrun or inconclusive check is not an accessibility pass. The evaluation runner tests scoring and transport offline without a provider: ```sh -rtk proxy bun test scripts/dashboard-eval -rtk proxy bun scripts/dashboard-eval/main.ts --mock --no-output -rtk just dashboard-eval-generate-check +bun test scripts/dashboard-eval +bun scripts/dashboard-eval/main.ts --mock --no-output +just dashboard-eval-generate-check ``` The mock exercises ten saves and five consecutive edits with synthetic usage. @@ -156,15 +164,17 @@ are generated from the server; change their generator sources when necessary, then regenerate and check: ```sh -rtk just docs-generate -rtk just docs-generate-check -rtk just test ./cmd/fanout-docgen +just docs-generate +just docs-generate-check +just test ./cmd/fanout-docgen ``` -With site dependencies already installed, run `rtk bun run build` from `site/` -to check the sidebar and compile pages, then run the table, social-card and -canonical guards included in that script. `just site-build` also installs site +With site dependencies installed, run `npm run build` from `site/` +to check the sidebar, compile pages and run its table, social-card, canonical +and benchmark guards. `just site-build` also installs site dependencies; use the installed build directly when dependency installation is outside the verification environment's scope. Neither command publishes the site. -Refresh the README's light and dark System overview captures with `just landing-captures` (real seeded server and local Chrome). To capture an existing instance such as the live demo, set `FANOUT_LANDING_BASE_URL` to its URL and `FANOUT_LANDING_SESSION_COOKIE` to a `name=value` session cookie before running the same command; no server starts and no data is seeded. The landing page's chat and dashboard clips are recorded the same way with `FANOUT_LANDING_RECORDINGS=1`; see `site/scripts/landing-recordings.md`. +Refresh the README's light and dark System overview captures with `just landing-captures` (real seeded server and local Chrome). To capture an existing instance such as the live demo, set `FANOUT_LANDING_BASE_URL` to its URL and `FANOUT_LANDING_SESSION_COOKIE` to a `name=value` session cookie before running the same command; no server starts and no data is seeded. + +To record chat and dashboard clips, set `FANOUT_LANDING_RECORDINGS=1` and the external-instance variables above, then run `bun run e2e landing-recordings.spec.ts --project=1440-light --project=1440-dark` from `ui/host`. Follow [landing-recordings.md](../site/scripts/landing-recordings.md) to encode and upload them. diff --git a/internal/config/config.go b/internal/config/config.go index f423e59fc..aaaf23bca 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -56,12 +56,9 @@ type Config struct { // IngestBatchSize sets the group-commit row target; valid values are 1–50000. // Individual requests remain atomic and can exceed this target. IngestBatchSize int `group:"ingest" env:"FANOUT_INGEST_BATCH_SIZE" default:"50000"` - // IngestMaxInFlightBytes caps the decoded telemetry the process will hold - // across concurrent requests. Concurrency is HTTP/2 streams times - // connections and each handler holds its batch until the commit is - // durable, so without a ceiling a burst is bounded only by memory. Zero is - // unbounded. A single request is admitted when no other request holds budget, - // even if it exceeds the limit. + // IngestMaxInFlightBytes caps decoded telemetry held across concurrent requests + // until durable publication. Zero is unbounded. A single request is admitted + // when no other request holds budget, even if it exceeds the limit. IngestMaxInFlightBytes int `group:"ingest" env:"FANOUT_INGEST_MAX_IN_FLIGHT_BYTES" default:"268435456"` // RollupInterval schedules analytical rollups; use a Go duration of at least 1s. RollupInterval time.Duration `group:"storage" env:"FANOUT_ROLLUP_INTERVAL" default:"1m"` @@ -99,21 +96,20 @@ type Config struct { // comment: cmd/fanout-docgen publishes each field's comment as that // setting's note, and this paragraph describes three of them. - // DuckDBMemory caps DuckDB's memory (e.g. "8GB"). Empty means Fanout sizes - // it from detected memory, reserving headroom for the Go runtime; see - // resolveSizing. DuckDB's own default is 80% of detected RAM, which is - // calculated as though DuckDB owned the machine and has been observed to - // get the process OOM-killed once the Go heap is added on top. + // DuckDBMemory caps DuckDB's memory (e.g. "8GB"). Empty selects 60% of detected + // available memory, reserving headroom for Go. If detection fails, DuckDB uses + // its default with a process headroom adjustment. Startup logs and /readyz + // report the resolved budget and detection status. Set an explicit cap when + // memory limit detection is incomplete. DuckDBMemory string `group:"storage" env:"FANOUT_DUCKDB_MEMORY"` // DuckDBThreads caps DuckDB's global query worker pool. Zero leaves // DuckDB's own default in place (one worker per core). Set it to leave // cores free for ingest on a query-heavy co-tenant host. DuckDBThreads int `group:"storage" env:"FANOUT_DUCKDB_THREADS" default:"0"` - // DuckDBMaxConns caps the DuckDB connection pool. Reads scan immutable Parquet - // concurrently; rollup-cache writes are serialized by the query write gate. - // Zero means "size it from the machine" — the same spelling DuckDBThreads - // uses for deferring to a default. Resolution happens in resolveSizing and - // is reported in the startup configuration log. + // DuckDBMaxConns caps the DuckDB read connection pool. Reads scan immutable + // Parquet concurrently; analytical and completed-batch writes use separate + // gates and connections. Zero selects available Go CPUs, bounded to 2–16. + // Startup logs and /readyz report the resolved pool size. DuckDBMaxConns int `group:"storage" env:"FANOUT_DUCKDB_MAX_CONNECTIONS" default:"0"` // AlertEnabled runs the alert evaluation engine. AlertEnabled bool `group:"alerts" env:"FANOUT_ALERTS_ENABLED" default:"true"` @@ -153,7 +149,8 @@ type Config struct { SMTPFrom string `group:"smtp" env:"FANOUT_SMTP_FROM"` // AuthMode selects local sign-in or oidc; each mode validates its prerequisites. AuthMode string `group:"auth" env:"FANOUT_AUTH_MODE" default:"local"` - // PublicURL sets the external browser origin. Required for OIDC; HTTPS is required with MCP. + // PublicURL sets the external browser origin, MCP token audience, and trusted MCP + // request origin. Required for OIDC; HTTPS is required with MCP. PublicURL string `group:"server" env:"FANOUT_PUBLIC_URL"` // AuthCodeSecret signs local sign-in codes; required in local mode with at least 32 characters. AuthCodeSecret string `group:"auth" env:"FANOUT_AUTH_CODE_SECRET" secret:"true"` diff --git a/internal/mcp/server.go b/internal/mcp/server.go index b3a4a24aa..2135b5ae1 100644 --- a/internal/mcp/server.go +++ b/internal/mcp/server.go @@ -349,7 +349,7 @@ func (s *Server) registerTools() { fragmentTool(s, &mcp.Tool{ Name: "get_service_performance", Title: "Service performance explorer", - Description: "Display separate latency, error rate and request rate panels plus slow operations (HTTP, gRPC and consumers) for one service or the system.", + Description: "Display separate latency, error rate and request rate panels plus a Slow operations table showing p95 duration grouped by operation over server and consumer spans, covering HTTP, gRPC and message consumers, for one service or the system.", Annotations: readOnly, Meta: appToolMeta(panelsAppURI), }, s.performance) diff --git a/site/scripts/landing-recordings.md b/site/scripts/landing-recordings.md index fac181104..09c4a7320 100644 --- a/site/scripts/landing-recordings.md +++ b/site/scripts/landing-recordings.md @@ -27,12 +27,15 @@ bun run e2e landing-recordings.spec.ts --project=1440-light --project=1440-dark ``` Recordings use a 1280 × 800 viewport and raw video at the same size; Playwright -video captures CSS pixels, so a higher device scale only pads the frame. This only uses the external instance. It types the brief's prompts, waits for -the real run to finish, and dwells for three seconds. The dashboard clip also +video captures CSS pixels, so a higher device scale only pads the frame. It types the configured prompts, waits for the real run to finish, and dwells +for four seconds on chat or five seconds on the dashboard. The dashboard clip also opens the dashboard from its successful `create_dashboard` result and waits for the saved panels to render. It creates real chats and dashboards; no data is mocked or intercepted. +Use a dedicated recording account: before each take, the spec deletes all of +that account’s chats and non-default dashboards. + Raw WebM files and matching JSON timelines go to `ui/host/test-results/landing-recordings/`, excluded from Git and Docker inputs. Keep a copy before another Playwright run clears `test-results`. Timelines use diff --git a/site/src/content/docs/explanation/authentication-modes.mdx b/site/src/content/docs/explanation/authentication-modes.mdx index 6e6dd94b6..b89f1d50c 100644 --- a/site/src/content/docs/explanation/authentication-modes.mdx +++ b/site/src/content/docs/explanation/authentication-modes.mdx @@ -8,118 +8,73 @@ read_when: status: preview --- -Fanout signs people in one of two ways, set by `FANOUT_AUTH_MODE`. The choice is -not only about convenience — it decides who owns a user's role. +Fanout supports local sign-in and OIDC, selected by `FANOUT_AUTH_MODE`. +Both use the same [roles and capabilities](/reference/roles), browser sessions +and account suspension rules. ## Local -There are no passwords. Active users receive short-lived codes by email, which -is why SMTP exists as a setting at all. - -SMTP is optional, and that has a consequence worth understanding rather than -discovering. Creating a user without it succeeds, and reports that it could not -deliver an invitation. The account is real; nobody can reach it until an -operator with shell access mints a link with `fanout login-link`. That is the -designed path, not a workaround — see -[troubleshooting](/guides/troubleshoot). - -In local mode, roles are managed inside Fanout. - -### Account profiles and suspension - -User responses from `GET /api/auth/me` and `GET /api/users` use `display_name` -and `status`. Status is `active` or `suspended`; roles remain `viewer`, -`operator`, and `admin`. - -Administrators provision users with `POST /api/users`, supplying `email`, -`display_name`, and `role`. New users have status `active`. Profile edits use -`PATCH /api/users/{id}` with only `email` and `display_name`. Change roles with -`PATCH /api/users/{id}/role` and a body such as `{"role":"viewer"}`; suspend an -account with `PATCH /api/users/{id}/status` and `{"status":"suspended"}`. -Use `{"status":"active"}` on that same status route to restore sign-in. -Unknown fields and invalid statuses return `400`. - -Email, role, and status changes revoke existing browser sessions. Suspension -blocks both local and OIDC sign-in, as well as OAuth token use. Restoring status -does not restore revoked sessions. The last active administrator cannot be -demoted, suspended, or deleted. These account rules apply in both auth modes. - -### Self-signup - -`FANOUT_SELF_SIGNUP` (default `false`) lets anyone who can receive an email code -provision themselves an account. It exists for public installations that want -per-user access without a shared credential or an identity provider. - -Two conditions guard it, and both matter: - -- **Only after email-code verification.** An account is created when the code is - verified, not when it is requested, so an address nobody controls cannot - become a user. -- **Never before admin setup.** Provisioning is refused while the instance has - no users, so the first account is always the administrator you create - deliberately — a race for the setup URL cannot hand someone else the instance. - -Self-provisioned users are `viewer`. Be clear about what that grants before -turning this on: a viewer can read **all** telemetry the instance holds, keep -their own dashboards, and **run the chat investigator** — which calls your model -provider and spends money. It can change its own dashboards, but cannot manage -alert rules, rotate the ingest token, or administer users. - -If that is more than you want to hand to anyone who can receive an email, leave -self-signup off and create accounts deliberately. The full matrix is in -[roles](/reference/roles), generated from the authorization table itself. +Active users sign in with an emailed code when SMTP is configured. Without +SMTP, an operator with access to the control database mints a single-use link +with `fanout login-link `. Administrators manage accounts and roles +inside Fanout. See [account profiles and suspension](#account-profiles-and-suspension) +for account APIs and [authentication operations](https://github.com/labstack/fanout/blob/main/docs/authentication.md) +for invitation delivery and recovery. + +`FANOUT_SELF_SIGNUP` allows verified email addresses to create viewer accounts. +It defaults to `false` and requires complete SMTP configuration. Self-signup is +available only after the first administrator completes setup. Viewers can read +all telemetry, manage their own dashboards and run the built-in agent. +The built-in agent sends requests to your configured model provider and can +incur charges. Enabling self-signup grants that access to anyone who can verify +an email address. ## OIDC -An identity provider handles sign-in. Two behaviours are worth knowing before -you rely on it. - -### Eligibility is checked on every login +An identity provider handles sign-in. Group and domain allowlists are evaluated +on every login, including for linked identities. Removing a user’s eligibility +blocks their next login; it does not revoke a browser session already issued. +Suspending the account in Fanout blocks access and revokes its sessions. -`FANOUT_OIDC_ALLOWED_GROUPS` and `FANOUT_OIDC_ALLOWED_DOMAINS` are evaluated at -every login, including by an identity that is already linked. Removing someone -from an allowed group at the provider blocks their next login. It does not wait -for a provisioning cycle, and there is no window in which a removed user -continues to be admitted. +If neither `FANOUT_OIDC_ALLOWED_GROUPS` nor `FANOUT_OIDC_ALLOWED_DOMAINS` is +configured, no eligibility allow policy is enforced; membership is managed locally. -If neither list is set there is no allow policy, and membership is managed -locally instead. +### Account provisioning -### Verified identities can be auto-provisioned as viewers +`FANOUT_OIDC_AUTO_PROVISION` creates eligible accounts on first sign-in after +administrator setup. It requires an allowed group or domain. The role comes +from the configured group mapping, falling back to `FANOUT_OIDC_DEFAULT_ROLE` +(`viewer`). -`FANOUT_OIDC_AUTO_PROVISION` creates an eligible identity's account on first -login, after administrator setup. Its role comes from the configured admin or -operator group mapping, falling back to `FANOUT_OIDC_DEFAULT_ROLE` (`viewer`). -With the default `FANOUT_OIDC_EMAIL_VERIFICATION=required`, the identity must -have a verified email. The `issuer` policy trusts the configured issuer instead -and requires an allowlist. Auto-provisioning always requires an allowed group -or domain. Chat, MCP tools and owned dashboards are available to viewers; -operator actions still require the corresponding capabilities. +`FANOUT_OIDC_EMAIL_VERIFICATION=required` requires a verified email. The `issuer` +policy trusts the configured issuer and requires an allowlist. See +[OIDC operations](https://github.com/labstack/fanout/blob/main/docs/authentication.md#oidc) +for public access and Microsoft Entra ID group-overage handling. -This is the OIDC counterpart to local self-signup above, and it obeys the same -allow policy: if `FANOUT_OIDC_ALLOWED_GROUPS` or `FANOUT_OIDC_ALLOWED_DOMAINS` -is set, an identity outside it is not admitted at all, provisioning or not. +### Role ownership -### The provider can own roles, or not +If `FANOUT_OIDC_ADMIN_GROUPS` or `FANOUT_OIDC_OPERATOR_GROUPS` is configured, the +provider reapplies the mapped role on every login. Users outside mapped groups +receive `FANOUT_OIDC_DEFAULT_ROLE`. A role change revokes browser sessions and +writes an audit event in the same transaction. -If `FANOUT_OIDC_ADMIN_GROUPS` or `FANOUT_OIDC_OPERATOR_GROUPS` is set, the -provider owns each linked user's role. The mapped role is applied on every -login; anyone in no mapped group falls back to `FANOUT_OIDC_DEFAULT_ROLE`. A -role change increments the user's auth version, revokes their browser sessions, -and writes a `role.changed` audit event — in one transaction, so a demotion -cannot half-apply and leave live sessions at the old level. +Without a role-group mapping, administrators manage roles inside Fanout and +OIDC sign-in preserves them. Reconciliation cannot demote the last active +administrator; promote a second administrator before applying that mapping. -If neither group list is set, roles are managed locally and logins never change -them. +## Account profiles and suspension -:::caution[The last administrator is never demoted] -Role reconciliation refuses to demote the last active administrator, because an -installation that cannot administer itself has no way back. If you expect the -mapping to apply to your first admin, promote a second one first. -::: +Administrators create active accounts with `POST /api/users`, supplying `email`, +`display_name` and `role`. Edit profiles with `PATCH /api/users/{id}`; change +roles with `PATCH /api/users/{id}/role` and `{"role":"viewer"}`. Suspend with +`PATCH /api/users/{id}/status` and `{"status":"suspended"}`; restore with +`{"status":"active"}`. Unknown fields and invalid statuses return `400`. +Email, role and status changes revoke browser sessions. Suspension blocks local +and OIDC sign-in and OAuth token use. Reactivation does not restore revoked +sessions. The last active administrator cannot be demoted, suspended or deleted. -## What neither mode is +## Access boundaries -Neither is a tenancy boundary. Namespaces scope telemetry queries, but anyone -who can query the instance can query every namespace in it. An instance is one -trust domain; separate trust domains want separate instances. +Every telemetry reader can query every namespace. Namespaces filter queries; +separate trust domains require separate instances. Dashboard access is scoped +to the owner for every role, including administrators. diff --git a/site/src/content/docs/explanation/storage-model.mdx b/site/src/content/docs/explanation/storage-model.mdx index 0c8ff3159..684708ad4 100644 --- a/site/src/content/docs/explanation/storage-model.mdx +++ b/site/src/content/docs/explanation/storage-model.mdx @@ -85,8 +85,8 @@ Attribute names such as `service.name` are literal keys. In SQL, use `attr(attributes, 'service.name')` and an explicit cast when a scalar type is needed, for example `TRY_CAST(attr(attributes, 'retry.count') AS BIGINT)`. General attribute extracts -through views retain their types, but this engine preview does not propagate -their extraction across view projections. Prefer the existing scalar service, +through views retain their types; extraction across view projections does not +reach the Parquet scan. Prefer the scalar service, namespace, version, environment, and messaging columns for those hot queries. The JSON SQL response converts nested values only when returning results. @@ -141,7 +141,7 @@ footer, including negative timestamps. Files without complete statistics remain eligible. Late-arriving telemetry is selected by its event time, independently of its ingestion timestamp. Arbitrary SQL retains access to all active files. -Endpoint panels and log counts scan footer-pruned Parquet for the exact +Operation panels and log counts scan footer-pruned Parquet for the exact requested window. Text searches match the redacted body. Notable-trace selection keeps one indexed candidate per trace, updated from new batches. A candidate records whether its namespace and service are unambiguous; @@ -160,7 +160,7 @@ is not yet cached, the output remains directly queryable until its own backfill. The private cache stores per-batch trace parts and one incremental candidate per trace. It does not copy every span or log timestamp -or maintain four global trace indexes. Complete cached compaction replacements +or maintain global scope indexes. Complete cached compaction replacements preserve candidate bounds without recomputation. Retention and incomplete replacements recompute only affected trace IDs from active contributions. A semantic version covers the cache schema and aggregation rules; a version @@ -168,8 +168,8 @@ change atomically discards all private read tables and rebuilds from authoritative format-4 Parquet. The background worker processes bounded groups; `fanout_read_cache_pending_batches` reports its trace backlog independently of the service and edge rollups' publication horizon. -Version history drains on its own worker, so an analytical-gate wait cannot -delay the completed-batch worker. +Service-version observations populate their analytical rollup on a separate +worker, so an analytical-gate wait cannot delay the completed-batch worker. Completed-batch and analytical writers use separate gates and two connections outside the read pool. They modify disjoint tables; maintenance holds both gates for checkpointing. Trace reads avoid materializing every retained candidate into diff --git a/site/src/content/docs/explanation/why-one-binary.mdx b/site/src/content/docs/explanation/why-one-binary.mdx index ab4f1f880..b8d81a012 100644 --- a/site/src/content/docs/explanation/why-one-binary.mdx +++ b/site/src/content/docs/explanation/why-one-binary.mdx @@ -8,57 +8,36 @@ read_when: status: shipped --- -A conventional self-hosted observability setup is a collector, a storage -backend, a query layer, a dashboard service and an alertmanager. Five processes, -five configurations, five upgrade cadences, and a set of failure modes that only -exist between them. +Fanout packages telemetry ingest, storage, queries, alerting and the browser +client in one process. The built-in agent and external MCP clients use the +same typed tools to investigate that telemetry and build dashboards. -Fanout is one process. That is the whole design decision, and everything else on -this page is a consequence of it. +## Operation -## What it buys +One binary pins the runtime version, and one data directory holds telemetry and +application state. [Back up the complete directory](/guides/back-up-and-restore) +and restore it with the matching binary version. -**One thing to operate.** One binary to pin, one data directory to back up, one -process to restart. The [backup guide](/guides/back-up-and-restore) is short -because the unit of backup is a directory. +Queries read local storage. The browser, agent and alert engine share query +implementations and analytical rollups. Configuration comes from environment +variables, documented in the generated [reference](/reference/configuration). -**No integration surface.** The query layer does not talk to storage over a -network. The alert engine reads the same rollups the browser does. The chat -investigator calls the same typed query tools the API exposes, which is why what -it tells you matches what the dashboards show — there is no second -implementation to disagree. +## Resource sharing -**Configuration in one place.** Settings use `FANOUT_` variables, with vendor -names for AI credentials and endpoints, [generated into one -reference](/reference/configuration) from the type the loader binds. +Ingest, queries and maintenance share CPU, memory bandwidth and disk. They have +separate coordination paths, but cannot scale onto separate machines. +Compaction prepares merges while reads continue, then briefly gates readers +while swapping files. [Tune retention](/guides/tune-retention) explains the +maintenance controls. -## What it costs +One process is one failure domain. Stopping it stops ingest, queries, alerts and +the UI. Monitor the instance from outside its host. -**The parts scale together.** Ingest, query and maintenance share a process and -a machine. There is no scaling the query layer without also scaling ingest, -because they are the same thing. +## Deployment scope -**They contend for one machine.** Parquet ingest, DuckDB reads, rollups, and -native compaction have separate coordination paths, but they consume the same -CPU, memory bandwidth, filesystem cache, and disk. Maintenance excludes readers -only for bounded namespace changes—compaction swaps and retention removals; the -merge itself runs outside that gate. -Compacting harder is still traded against ingest and query headroom. [Tuning -retention](/guides/tune-retention) is mostly about managing that trade. +Fanout serves one trust domain on one machine. Namespaces filter telemetry +queries; every telemetry reader can access all namespaces. Use separate +instances for mutually untrusted teams. -**One process is one failure domain.** Nothing degrades independently. A process -that dies takes ingest, query, alerting and the UI with it. - -## Where the line is - -Fanout is built for one instance holding one team's telemetry, on hardware that -team controls, at a volume a single machine can hold. The reference deployment -target is a small VM. - -It is not built to be a multi-tenant platform, and namespaces are not the -mechanism for pretending otherwise: they scope queries, not access. Separate -trust domains want separate instances. - -If your volume needs horizontal ingest, or your organisation needs one system -serving mutually distrustful tenants, the single-process design is working -against you rather than for you, and you want something else. +Workloads requiring horizontal ingest, replication or an object-storage tier +require a backend that provides those capabilities. diff --git a/site/src/content/docs/guides/back-up-and-restore.mdx b/site/src/content/docs/guides/back-up-and-restore.mdx index ef257adf2..76f2bd469 100644 --- a/site/src/content/docs/guides/back-up-and-restore.mdx +++ b/site/src/content/docs/guides/back-up-and-restore.mdx @@ -12,8 +12,7 @@ Fanout is one process and one persistent data directory. Back up the directory as a unit. The directory holds atomic telemetry Parquet batches, rebuildable query state, -and the control SQLite database. Copying one subdirectory produces something -that looks like a backup and does not restore. +and the control SQLite database. Preserve all three together. ## Take a cold backup @@ -25,8 +24,7 @@ that looks like a backup and does not restore. 3. Copy or snapshot the complete data directory, preserving ownership and permissions. 4. Start Fanout and confirm `/readyz`. -5. Periodically restore a backup into an isolated directory. An untested backup - is not a recovery plan. +5. Periodically restore a backup into an isolated directory. Verify sign-in and a known telemetry query after restoring. :::caution[Not while it is running] Do not take a recursive copy of a live data directory. A storage-level snapshot diff --git a/site/src/content/docs/guides/build-dashboards.mdx b/site/src/content/docs/guides/build-dashboards.mdx index c8a2f9592..e4c3735d7 100644 --- a/site/src/content/docs/guides/build-dashboards.mdx +++ b/site/src/content/docs/guides/build-dashboards.mdx @@ -33,7 +33,7 @@ panels. An incomplete save check means the panels were not all executed; it does not undo the save or establish that they work. A follow-up edit reads the dashboard and changes the named panels, preserving -the others. Ask explicitly for a redesign when you want the whole board replaced. +the others. Ask explicitly for a redesign when you want the whole dashboard replaced. You can also ask to add a variable, change the default time range or remove a panel. @@ -123,28 +123,21 @@ not a historical registry. Structured `query.from`, variables and unscoped arbitrary SQL cannot read it. The [SQL relation reference](/reference/mcp-tools#panel-sql-relations) lists column types and semantics. -### Update existing System overview panels deliberately - -New defaults use `resource_inventory` for **What changed?** (`versions`) and -the service-host input to **Is it reachable?** (`check_states`). Existing -saved dashboards keep their SQL. Deploy the supporting binary before editing -those saved definitions. - -1. Use `list_dashboards` and `get_dashboard` to select the owner's dashboard by - ID and capture its current `version` and spec. Do not identify a board by - title alone. Compare both panel SQL fields with the known shipped definitions - being upgraded; skip and report customized or missing definitions. -2. Build replacements from the new default SQL, changing only those SQL fields. - Run `preview_panels` with the saved time and variables and inspect the complete - frames, including first-seen times and reachability warnings. -3. Call `edit_dashboard` with the captured `base_version` and two - `update_panel` operations, each with its panel `id` and `set: {sql: ...}`. - Preserve every other field, layout and variable. If the base version is - stale, reread and review the diff before retrying. -4. Retain the prior SQL and version history. Before rolling back to a binary - without this relation, restore both prior SQL fields through reviewed edits - at the then-current base version. The disposable cache rebuilds independently; - the telemetry format remains unchanged. +### System overview defaults + +Each user receives an owned copy of **System overview**. Saved copies retain +their specification when the binary’s default changes. The default’s **What +changed?** panel (`versions`) and service-host input to **Is it reachable?** +(`check_states`) use `resource_inventory`. + +Deploy a binary supporting `resource_inventory` before editing saved panels. +Use `list_dashboards` and `get_dashboard` to select the owner’s dashboard by ID +and capture its version and spec. Compare `versions` and `check_states` with +the shipped definitions; skip customized or missing definitions. Preview +replacements with the saved time and variables, then submit two `update_panel` +operations changing only `sql`, using the captured `base_version`. On conflict, +reread and review before retrying. Retain the prior SQL; restore it through +reviewed edits before rolling back to a binary without `resource_inventory`. ## Choose metric measures by kind @@ -333,8 +326,11 @@ when the compact Chart preview cuts it short. On a narrow card, choose Data from the panel menu. **Spec** shows the authored panel definition. Text panels expose Content and Spec instead of Data. -Empty panels show their diagnosis in Chart. Check the time range, selected -variables and the panel's description before treating the absence as meaningful. +Empty panels show their diagnosis in Chart. When filters together match nothing, +the diagnosis names that combination. Chat keeps views whose results are all +empty collapsed on an “empty” summary. Expand an empty view to inspect its +diagnosis. Check the time range, selected variables and panel description before +interpreting missing results. Truncation and other result notes remain visible below the panel. If a refresh fails after data was loaded, the old data can remain on screen with a warning; it is not a fresh successful result. Use **Retry** for a request failure, or @@ -371,7 +367,7 @@ the same duration. Time series draw the previous series; stats display a previou value as a delta when available. Other panel types do not draw this comparison; a bar's deploy split is a separate before/since view. An individual panel can have its own range or time shift; its header labels that -override. Ask chat to set it when a panel needs a different window from the board. +override. Ask chat to set it when a panel needs a different window from the dashboard. ## Share the current view @@ -385,7 +381,7 @@ range moves with the time the link is opened. Links open the current saved dashboard and query its data; they do not freeze a historical version or result. The recipient needs an account and access to that dashboard. Dashboards are -currently owner-scoped: another account cannot open your dashboard just because +owner-scoped: another account cannot open your dashboard just because you copied its link. A view link grants no access and is not a public snapshot. ## Layout and saved versions @@ -396,7 +392,7 @@ from a corner. Choose **Save layout** to persist the grid as a new version; menus while editing. Those actions save immediately, including any pending layout changes. Narrow screens stack panels and do not allow layout editing. -Edits use the version that was read to detect competing saves. If the board +Edits use the version that was read to detect competing saves. If the dashboard changed meanwhile, use **Load latest**, then redo the change. An MCP client should likewise read the latest dashboard and supply `base_version` when editing or replacing it. diff --git a/site/src/content/docs/guides/connect-over-mcp.mdx b/site/src/content/docs/guides/connect-over-mcp.mdx index 3ec74293b..e2d91d921 100644 --- a/site/src/content/docs/guides/connect-over-mcp.mdx +++ b/site/src/content/docs/guides/connect-over-mcp.mdx @@ -8,10 +8,9 @@ read_when: status: preview --- -Fanout serves MCP at `/mcp`. It is the intended way for an agent to read an -instance: the [tools](/reference/mcp-tools) return the same typed results -the browser client and the HTTP API use, so what an agent tells you matches what -the dashboards show. +Fanout serves MCP at `/mcp` for external agents. Its [tools](/reference/mcp-tools) +query telemetry and manage the authenticated user’s dashboards. The browser +client and built-in agent use the same typed query results. [Build and refine dashboards](/guides/build-dashboards) covers schema discovery, panel previews, targeted edits and saved-version restore through chat or MCP. @@ -27,13 +26,8 @@ reachable origin that clients are issued tokens against. It must be HTTPS, and it must stay **stable across restarts**: tokens carry the derived resource as their audience, so changing it invalidates every one already issued. -Getting this wrong is the most common failure. A client discovers, registers and -receives a token, and then every call is rejected because the audience does not -match the resource it is calling. Set it before connecting anything. - -The resource is derived from `FANOUT_PUBLIC_URL`; there is no separate MCP -public-origin setting. An unrecognised `FANOUT_`-prefixed variable is a startup -error rather than something ignored. +The resource is derived from `FANOUT_PUBLIC_URL`; see +[server settings](/reference/settings/server#fanout_public_url). Set `FANOUT_MCP_ENABLED=false` to turn the endpoint off entirely; it defaults to `true`. @@ -70,31 +64,30 @@ HTTP. Every request carries `MCP-Protocol-Version: 2026-07-28`; a request without it, or with an earlier version, is rejected, and there are no sessions or `initialize` handshake. Use a client that supports this version. -A request that carries an `Origin` header must come from the origin of -`FANOUT_PUBLIC_URL`; any other origin receives `403` before authentication. -Clients that do not send `Origin`, such as command-line agents, are -unaffected. +On `/mcp` and `/api/mcp`, an `Origin` header must exactly match the RFC 6454 +serialization of `FANOUT_PUBLIC_URL`. Malformed or untrusted origins receive +`403` before authentication. Without a public URL, only same-authority loopback +origins are accepted. Requests without `Origin` pass this check. -Tool calls are limited to 20 per second for each user and client, with -bursts of up to 100. A client above the limit receives `429` with -`Retry-After`. +`tools/call` requests are limited to 20 per second per user–OAuth client pair, +with a burst of 100. Excess calls receive `429` with `Retry-After`. The in-process +agent is exempt. Client disconnects cancel in-flight tool calls, including DuckDB +queries. ## Scopes | Scope | Grants | |---|---| -| `telemetry:read` | The read-only observability tools | +| `telemetry:read` | Required for every remote MCP request. | | `dashboard:manage` | `list_dashboards`, `get_dashboard`, `create_dashboard`, `replace_dashboard`, `edit_dashboard`, `list_dashboard_versions`, and `restore_dashboard_version` | -An agent holding only `telemetry:read` can investigate but cannot manage -a dashboard. +Dashboard tools additionally require `dashboard:manage`. An `insufficient_scope` +challenge lists every scope required by the request, including scopes already +granted. -The MCP tool catalog provides `list_dashboards`, `get_dashboard`, -`create_dashboard`, `replace_dashboard`, `edit_dashboard`, -`list_dashboard_versions`, and `restore_dashboard_version`. Restore requires -an explicit user request and appends the selected historical spec as a new -saved version with a normal save receipt. Deletion is -available in Fanout's dashboard API; there is no MCP delete tool. +Restore requires an explicit user request and appends the selected historical +spec as a new saved version with a save receipt. Dashboard deletion uses the +HTTP API; there is no MCP delete tool. ## What the agent can and cannot do @@ -104,11 +97,11 @@ account capabilities still permit those scopes. Two consequences: - Dashboard tools are owner-scoped. An agent can manage your dashboards and cannot touch anyone else's. -- `agent:run` is not involved here. That capability gates Fanout's *own* chat - investigator; an external MCP client is a separate path. +- `agent:run` is not involved here. That capability gates Fanout's *own* built-in + agent; an external MCP client is a separate path. There is no tool that writes telemetry, edits configuration, manages users or -changes alert rules. That is the whole envelope, deliberately. +changes alert rules. ## Behind a proxy diff --git a/site/src/content/docs/guides/set-up-alerts.mdx b/site/src/content/docs/guides/set-up-alerts.mdx index 5020d848a..2e89fc07f 100644 --- a/site/src/content/docs/guides/set-up-alerts.mdx +++ b/site/src/content/docs/guides/set-up-alerts.mdx @@ -12,8 +12,8 @@ The alert engine runs inside the binary and is on by default. It evaluates persisted rules every `FANOUT_ALERTS_EVALUATION_INTERVAL` (30s) against service rollups, and delivers by webhook. -Rules are managed over HTTP. There is no browser page for them yet — see -[capabilities](/status/capabilities). +Manage rules through the HTTP API using an operator or administrator session. +The browser client has no alert-rule editor. | Endpoint | Does | |---|---| @@ -22,6 +22,8 @@ Rules are managed over HTTP. There is no browser page for them yet — see | `GET /api/alerting/rules` | List rules | | `POST /api/alerting/rules` | Create and compile a rule | | `PUT /api/alerting/rules/:id` | Replace a rule; recompile it when enabled | +| `POST /api/alerting/rules/:id/test` | Evaluate a saved expression against live data without changing alert state or delivering a webhook | +| `DELETE /api/alerting/rules/:id` | Delete the rule and its alerts | Reading takes `telemetry:read`; creating and replacing takes `alerts:manage`, which starts at the `operator` role. See [roles](/reference/roles). @@ -40,8 +42,8 @@ An expression, an optional service to scope it to, timing, and delivery: | `cooldown_s` | Minimum quiet period after resolving before firing again | | `repeat_interval_s` | How often to re-deliver while still firing | | `webhook_url` | Where to deliver | -| `webhook_headers` | Extra headers, for a shared secret or routing key | -| `webhook_template` | Custom payload body; omit for the default | +| `webhook_headers` | JSON-encoded object of extra headers, supplied as a string | +| `webhook_template` | Go text/template payload body; omit for the default | | `notify_on_resolve` | Also deliver when the alert clears | Nonempty expressions supplied when creating or replacing a rule are type-checked @@ -57,15 +59,14 @@ An expression reads one service's rollup for the current window. The full list itself](/reference/alert-expressions), so it cannot drift from what the evaluator actually binds. -So a rule body reads like the thing it means: +For example: ```text error_rate > 0.02 && throughput > 10 ``` -The throughput clause matters more than it looks. Here `throughput` is the -total span count in the current rollup window, not requests per second. Without -a traffic floor, a single failure on a quiet service can trigger the rule. +`throughput` is the total span count in the rollup window. A traffic floor +prevents a single failure on a quiet service from triggering this rule. ## The lifecycle @@ -81,23 +82,20 @@ An alert moves through three states: `cooldown_s` then holds the rule quiet for that long after resolving, which is what stops a metric hovering at the threshold from delivering repeatedly. -Each alert records its last delivery status and timestamp, so a webhook endpoint -that started rejecting is visible in `GET /api/alerting/alerts` rather than silent. +Each alert records its last delivery status and timestamp in `GET /api/alerting/alerts`. +Setting `repeat_interval_s` to zero disables repeat delivery. Disabling a rule +removes its pending and firing alerts. :::caution[The namespace field on a rule is not applied] -A rule carries a `namespace` selector and it is stored, but evaluation reads -instance-wide service rollups and does not filter on it. A rule you believe is -scoped to one namespace is evaluating across all of them. - -Scope with `service` instead, which is applied. This is a real gap rather than a -subtlety — it is marked here because the field's presence implies otherwise. +A rule stores `namespace`, but evaluation combines service rollups across +namespaces. Scope with `service`; services with the same name in different +namespaces are evaluated together. ::: ## Why alerts lag the raw data -Evaluation reads rollups, not raw telemetry, and rollups deliberately trail the -newest data by a safety margin because telemetry arrives out of order. An alert -therefore fires seconds after the condition is visible in a raw query. That is a -correctness choice — [how storage works](/explanation/storage-model) explains -the margin — and it means `for_seconds` should not be set below the rollup -interval expecting finer resolution than the data has. +Evaluation reads analytical rollups. The rollup pass follows durable telemetry +publication; the evaluation interval and `for_seconds` add further delay. +[How storage works](/explanation/storage-model#rollups-follow-durable-publication) +explains the publication horizon and watermark. A shorter evaluation interval +does not increase the rollups’ time resolution. diff --git a/site/src/content/docs/guides/terminate-tls.mdx b/site/src/content/docs/guides/terminate-tls.mdx index 1caaaa5b0..e6d79ff42 100644 --- a/site/src/content/docs/guides/terminate-tls.mdx +++ b/site/src/content/docs/guides/terminate-tls.mdx @@ -13,8 +13,7 @@ Use direct TLS or terminate TLS at a reverse proxy. ## Direct TLS -Set both files. Setting one without the other is a startup error rather than a -half-configured listener: +Set both files; supplying only one fails startup: ```sh export FANOUT_TLS_CERT_FILE=/etc/fanout/tls/cert.pem @@ -34,15 +33,16 @@ export FANOUT_PUBLIC_URL=https://fanout.example.com export FANOUT_TRUSTED_PROXY_CIDRS=10.0.1.0/24 ``` -`FANOUT_PUBLIC_URL` is the externally reachable HTTPS origin. Fanout uses it as -a trusted signal that TLS is terminated somewhere in front, which is what lets -it mark session cookies `Secure`. Without it, an instance behind a proxy issues -cookies that are not — and it warns about exactly that at startup. +`FANOUT_PUBLIC_URL` is the externally reachable HTTPS origin. Fanout uses it to +mark browser session cookies `Secure` when TLS terminates at the proxy. + +Without local TLS or an HTTPS `FANOUT_PUBLIC_URL`, browser session cookies lack +`Secure`, and Fanout warns at startup. `FANOUT_TRUSTED_PROXY_CIDRS` is the list of networks whose forwarded client addresses Fanout will believe. Set it to the proxy network and nothing wider. -Never `0.0.0.0/0`: audit records and rate limits both key on client address, and -trusting every source means any caller can claim to be any address. Fanout warns +Never `0.0.0.0/0`: audit attribution and sign-in rate limits use the client address. +Trusting every source lets any caller claim any address. Fanout warns when a public URL is set, TLS is not terminated locally, and this is empty. ### HTTP/2 to the backend @@ -75,3 +75,6 @@ from it, and that derived resource is what tokens are bound to as their audience. So it must be HTTPS and stable across restarts — changing it invalidates every token already issued. `FANOUT_PUBLIC_URL` is the only public-origin setting. + +MCP also validates `Origin` before authentication; see +[Connect an agent over MCP](/guides/connect-over-mcp#protocol). diff --git a/site/src/content/docs/guides/troubleshoot.mdx b/site/src/content/docs/guides/troubleshoot.mdx index d256abd35..67f886fbe 100644 --- a/site/src/content/docs/guides/troubleshoot.mdx +++ b/site/src/content/docs/guides/troubleshoot.mdx @@ -15,11 +15,8 @@ configuration refusal names the setting. Other startup errors can report storage, listener, or identity-provider failures; read the error before changing settings. -The one that surprises people is an unrecognised variable. Fanout rejects -unknown `FANOUT_`-prefixed setting names, except platform-injected service-discovery -names, so a typo stops the process instead of being ignored. That is deliberate; -see -[configuration](/reference/configuration). +Unknown `FANOUT_` setting names fail startup, except platform-injected service +discovery names. Check spelling against the [configuration reference](/reference/configuration). ## An unresolved compaction blocks startup @@ -27,22 +24,15 @@ One startup refusal is not about configuration. If a compaction was interrupted and Fanout can neither finish nor undo it, recovery fails closed and the error names `telemetry/COMPACTION.json`. -That is deliberate. The marker lists the batches the compaction retired, and -recovery must not guess whether the original batches or their replacement are -authoritative. A wrong guess could delete the only surviving copy of some rows, -so Fanout stops instead and leaves things where they are: the replacement is -either staged under `telemetry/compaction/` or already published as -`telemetry/parquet/batches/.batch`, and the retired inputs sit under -`telemetry/parquet/batches/`, named `.retired-`. +The marker identifies the authoritative batch set during a swap. The replacement +is staged under `telemetry/compaction/` or published as +`telemetry/parquet/batches/.batch`. Retired inputs are named +`.retired-` under `telemetry/parquet/batches/`. +A partial publish can remove some retired inputs; verify every input before +attempting a rollback. -A publish that failed partway through may already have removed some of those -retired inputs, so the rollback set is not guaranteed to be complete. That is -what step 2 below checks, and why it has to be checked before anything is -deleted. - -Usually the interruption was transient — a full disk, or the process killed -mid-swap. **Clear the underlying cause and start Fanout again.** Recovery -re-runs on its own and needs no manual step. +**Clear the underlying cause, such as a full disk, and start Fanout again.** +Recovery runs automatically at startup. If recovery keeps failing, roll the compaction back by hand. With the process stopped, use `telemetry/parquet/batches/` as the batch directory: @@ -64,17 +54,10 @@ stopped, use `telemetry/parquet/batches/` as the batch directory: 6. Delete `telemetry/COMPACTION.json`. 7. Start Fanout. -Deleting the whole `telemetry/` directory also clears the refusal, and discards -exactly the telemetry the refusal was protecting. Neither step above needs it. - -:::caution[Verify the set, then restore, then delete] -The order is load-bearing in both directions. Verifying first (step 2) is what -keeps you from deleting a replacement that holds the only surviving copy of an -input's rows. Restoring before deleting the marker (steps 3 and 6) matters -because the marker is what protects the retired directories from cleanup — with -it gone, the next successful startup treats every `*.retired-*` directory as -reclaimable and removes it. Deleting the marker on its own is not a rollback; -it discards the rows the compaction had retired. +:::caution[Verify inputs before deleting the replacement] +Restore the retired inputs before removing the compaction marker. The marker +protects those directories from startup cleanup. Keep the replacement until +every input is restored; it may hold the only surviving copy of some rows. ::: ## An unreadable telemetry batch blocks startup @@ -148,13 +131,13 @@ fanout login-link user@example.com The link expires after 15 minutes, works once, and is recorded in the authentication audit history. It is available in `local` auth mode only. -A configured SMTP relay that fails delivery is reported as an error rather than -silently claiming an invitation arrived — so "no error" and "not configured" are -distinguishable. +A configured SMTP relay that fails delivery returns an error. See +[authentication operations](https://github.com/labstack/fanout/blob/main/docs/authentication.md#adding-local-users-without-smtp) +for invitation responses and account recovery. -:::caution[Do not fix this in the database] +:::caution[Preserve the account] Deleting a user row cascades to sessions, OAuth grants and owned dashboards. -The login-link path exists so that nobody has to. +Use a login link for an active local account. ::: ## Telemetry arrives but queries look empty @@ -167,16 +150,11 @@ An unscoped query spans every namespace, so this is only a problem when something has scoped the query — a dashboard filter, or an MCP call passing `namespace`. Clear the scope before concluding the data is missing. -Rollups also lag ingest by design — the alert engine and the overview read -aggregates, so the newest few seconds of data are not immediately reflected in -them even though the raw telemetry is queryable. +The alert engine and overview read analytical rollups, which follow durable +publication. Raw queries can see committed rows before the next rollup pass. +See [rollup timing](/explanation/storage-model#rollups-follow-durable-publication). ## What to watch in production -- `/healthz` — liveness. -- `/readyz` — storage readiness and resolved runtime sizing. -- `/metrics` — Prometheus metrics. Keep it private or set - `FANOUT_METRICS_TOKEN`. Do not make it public merely to simplify scraping. - -Alert on repeated restarts, readiness failures, ingest authentication failures, -telemetry drops, sustained query latency, and free disk space. +The [endpoint reference](/reference/endpoints#what-to-alert-on) lists health +probes, scrape credentials and signals to monitor. diff --git a/site/src/content/docs/guides/tune-retention.mdx b/site/src/content/docs/guides/tune-retention.mdx index 5c6576d95..740fe06d1 100644 --- a/site/src/content/docs/guides/tune-retention.mdx +++ b/site/src/content/docs/guides/tune-retention.mdx @@ -8,8 +8,8 @@ read_when: status: preview --- -These settings govern what is on disk and how it is shaped. They do different -jobs and are worth separating before changing any of them. +Retention controls telemetry lifetime. Group commits and compaction control +file count and query cost. All configuration changes require a restart. ## How long data is kept @@ -19,7 +19,8 @@ export FANOUT_RETENTION_DAYS=30 Zero means keep everything. Changing it does not delete anything immediately — expired data goes when maintenance next runs, so disk use falls on the -maintenance cycle rather than at the moment you change the setting. +maintenance cycle after restart. Expiry uses ingestion time; see +[storage semantics](/explanation/storage-model#small-files-are-bounded-by-compaction). Observability API, MCP, and dashboard queries can span up to this retention period. With unlimited retention, each query remains capped at 30 days. Fanout @@ -31,8 +32,8 @@ automatically uses wider timeline buckets for windows longer than 24 hours. export FANOUT_MAINTENANCE_INTERVAL=1h ``` -This is the expensive pass: retention deletes plus full compaction. Lower it to -reclaim space sooner, at the cost of running the heavy work more often. +The maintenance pass removes expired batches, compacts eligible files and +checkpoints query state. Shorter intervals run this work more frequently. ## Group-commit target @@ -54,8 +55,7 @@ setting controls admission grouping, not the durability boundary. Maintenance prepares merges while reads continue, then briefly gates readers while it swaps or removes immutable files. New batches keep encoding and need only the short publication lock. Ingest, queries, and maintenance still share -CPU, memory bandwidth, and disk, so running maintenance much more often is not -free. Change one setting at a time and watch `/metrics`. +CPU, memory bandwidth and disk. Change one setting at a time and watch `/metrics`. The full list, with defaults and types, is in the [storage settings](/reference/settings/storage) reference. diff --git a/site/src/content/docs/reference/configuration.mdx b/site/src/content/docs/reference/configuration.mdx index afe5e887f..bcbbcf704 100644 --- a/site/src/content/docs/reference/configuration.mdx +++ b/site/src/content/docs/reference/configuration.mdx @@ -82,8 +82,8 @@ for examples. ## Validation The whole configuration is validated before data files or listeners open. A value the -binary cannot accept stops startup. [First boot](/start/first-boot) lists what -is checked. The healthcheck command derives its probe from the listener and +binary cannot accept stops startup. The generated settings pages list individual +constraints; [first boot](/start/first-boot) covers administrator setup. The healthcheck command derives its probe from the listener and TLS environment settings without validating unrelated settings or secrets. ## DuckDB sizing @@ -94,7 +94,7 @@ headroom for Go and sizes the DuckDB connection pool from available CPUs. The resolved values and whether Fanout chose them are available in the `runtime_sizing` block returned by `/readyz`. -These variables are escape hatches for measured, unusual workloads: +Override these values when measurements justify different resource limits: | Variable | Automatic behavior | When to override | |---|---|---| diff --git a/site/src/content/docs/reference/data-layout.mdx b/site/src/content/docs/reference/data-layout.mdx index 0a07111a6..4f2ade8c8 100644 --- a/site/src/content/docs/reference/data-layout.mdx +++ b/site/src/content/docs/reference/data-layout.mdx @@ -36,9 +36,8 @@ complete data directory is the supported and fastest restore path. holds the dashboards and alert rules that refer to the telemetry, and the accounts that own them. -So the unit of backup is the whole directory. [Back up and -restore](/guides/back-up-and-restore) covers doing that safely, which mostly -means doing it while the process is stopped. +[Back up and restore](/guides/back-up-and-restore) covers cold backups of the +complete directory. ## Two engines, on purpose @@ -52,7 +51,7 @@ works](/explanation/storage-model) covers the reasoning and the write path. DuckDB spills here when a query needs more memory than `FANOUT_DUCKDB_MEMORY` allows. It is regenerated as needed and holds nothing durable, but it does need space: a query against a wide time range can spill substantially, and a full -disk fails the query rather than degrading it. +disk causes the query to fail. ## Sizing diff --git a/site/src/content/docs/reference/endpoints.mdx b/site/src/content/docs/reference/endpoints.mdx index f953be9f8..248c2c12c 100644 --- a/site/src/content/docs/reference/endpoints.mdx +++ b/site/src/content/docs/reference/endpoints.mdx @@ -22,10 +22,7 @@ the middleware that enforces it — see [HTTP routes](/reference/http-routes). | `/healthz` | nothing | Liveness — the process is up | | `/readyz` | nothing | Readiness — storage is attached, plus resolved runtime sizing | -Both are deliberately unauthenticated: a probe that needs a credential is a -probe that fails for the wrong reason during an outage. Use `/healthz` for -restart decisions and `/readyz` for traffic decisions — an instance can be alive -while its storage is still coming up. +Use `/healthz` for restart decisions and `/readyz` for traffic decisions. ## Operations @@ -36,9 +33,11 @@ while its storage is still coming up. `/metrics` is Prometheus exposition. It accepts a service credential as well as an admin session, which is how a scraper reaches it without a browser login — -set `FANOUT_METRICS_TOKEN`. `FANOUT_METRICS_PUBLIC=true` removes the requirement -entirely, and Fanout logs a warning at startup when you do, because metrics -describe your traffic shape to anyone who asks. +set `FANOUT_METRICS_TOKEN`. `FANOUT_METRICS_PUBLIC=true` permits unauthenticated +scrapes and emits a startup warning. + +Metrics reveal traffic volumes, query activity and resource use. Keep `/metrics` +private or authenticate scrapes with `FANOUT_METRICS_TOKEN`. `/debug/pprof/*` is off unless `FANOUT_PPROF_ENABLED=true`, and is admin-only even then. Profiling output can contain memory contents, which is why it sits diff --git a/site/src/content/docs/reference/http-routes.mdx b/site/src/content/docs/reference/http-routes.mdx index 2c68cc366..143c3e34b 100644 --- a/site/src/content/docs/reference/http-routes.mdx +++ b/site/src/content/docs/reference/http-routes.mdx @@ -16,15 +16,10 @@ the image sets `:7520`). OTLP shares this listener but uses its own handlers and ingest credential; see [send your first telemetry](/start/send-telemetry). -:::note[What this table is, and what it is not] -Every route the binary registers, wherever it is registered — the application -handlers, the agent runtime, the operational and protocol endpoints, and the -SPA catch-all. A route the generator cannot get a classification for fails -the build, so a new route cannot quietly go undocumented. +## Conditional routes -It is the surface the binary *can* register, not the surface any particular -instance exposes. Some of it is conditional, so check the instance before -concluding a route is reachable — or that it is not: +The table includes every route the binary can register. These routes depend on +configuration: - `/debug/pprof/*` — only when `FANOUT_PPROF_ENABLED` is true, which is **not** the default. Enabling it also turns on mutex and block sampling. @@ -37,22 +32,16 @@ concluding a route is reachable — or that it is not: Everything else is always registered. A path shown with `:name` or `*` is the pattern Echo matches on, not a literal URL. -::: -:::caution[Most of this is not a public API] -The `/api/*` routes are the browser client's own backend. They are listed here -so an operator can see the whole surface and what guards it — not as an -interface to build against. They change with the client, without notice and -without migration paths. +## Interface stability -The supported programmatic interface is **MCP**, at `/mcp` — see -[MCP tools](/reference/mcp-tools). The stable non-MCP surfaces are OTLP -ingest, and the operational endpoints in [endpoints](/reference/endpoints). +The `/api/*` routes serve the browser client and can change without migration +paths. [MCP](/guides/connect-over-mcp) is the agent interface. OTLP ingest and +[operational endpoints](/reference/endpoints) have their own contracts. -Alert rules (`/api/alerting/rules`, `/api/alerting/alerts`) currently have no browser -page. Ingest-token rotation uses `POST /api/settings/ingest/token/rotate` -and is also available to administrators on **Connect telemetry**. -::: +Manage alert rules through the [HTTP API](/guides/set-up-alerts). Administrators +rotate ingest tokens on **Connect telemetry** or with +`POST /api/settings/ingest/token/rotate`. ## Errors @@ -91,10 +80,8 @@ Panel execution results keep their own status and error fields. OAuth, OTLP/gRPC, MCP JSON-RPC and AG-UI run errors keep their protocol spelling. Operational responses at `/healthz`, `/readyz` and `/metrics` keep their bodies. -The **Requires** column is not a description of the rule. It is the answer the -authorization middleware gives for that exact method and path, so a route -cannot be documented as public while the server treats it otherwise. -Capabilities map to roles in [roles](/reference/roles). +The **Requires** column comes from the authorization middleware for each method +and path. [Roles](/reference/roles) maps capabilities to roles. | Method | Path | Requires | |---|---|---| @@ -167,9 +154,7 @@ Capabilities map to roles in [roles](/reference/roles). ## What the requirements mean -- **none** — reachable without a credential. The health endpoints are - deliberately here: a probe that needs a credential fails for the wrong - reason during an outage. +- **none** — reachable without a credential. - **any signed-in user** — a session, but no particular capability. - **protocol handshake** — the OAuth and MCP endpoints, which authenticate as part of their own protocol rather than through the middleware. @@ -177,7 +162,6 @@ Capabilities map to roles in [roles](/reference/roles). - **or a service credential** — additionally reachable without a browser session, which is how a scraper reaches the metrics endpoint. -A method of `Any` means the route is registered for every verb, and the middleware -gives the same answer for all of them — where it would not, this page fails -to build rather than pick one. `GET /*` serves the single-page application -for browser paths. Unknown `/api/*` and OTLP paths return errors instead. +`Any` registers every HTTP method with the same authorization requirement. +`GET /*` serves the single-page application for browser paths. Unknown `/api/*` +and OTLP paths return errors. diff --git a/site/src/content/docs/reference/mcp-tools.mdx b/site/src/content/docs/reference/mcp-tools.mdx index 168c8bfda..73bb985ab 100644 --- a/site/src/content/docs/reference/mcp-tools.mdx +++ b/site/src/content/docs/reference/mcp-tools.mdx @@ -86,7 +86,7 @@ AG-UI `mcp-app` activity content uses exactly `resource_uri`, `tool_name`, **Get dashboard** — Read one dashboard's complete spec and version. Read it before editing so operations name real panel ids. See create_dashboard for the spec guide. -Read-only. Calling it changes nothing. +Read-only. | Input | Type | Required | Means | |---|---|---|---| @@ -96,7 +96,7 @@ Read-only. Calling it changes nothing. **Latest detected anomalies** — Return the latest precomputed health score, anomalies, insights, and recurring warning or error log patterns. -Read-only. Calling it changes nothing. +Read-only. Takes no arguments. @@ -104,7 +104,7 @@ Takes no arguments. **System health overview** — Summarize service health for a bounded telemetry window. Start here for incident triage. -Read-only. Calling it changes nothing. +Read-only. **View resource:** `ui://fanout/panels.html` (model and app visible). @@ -120,7 +120,7 @@ Read-only. Calling it changes nothing. **Service dependency traversal** — Find upstream or downstream dependencies of one service with minimum hop counts. Uses the full scoped edge rollup, handles cycles, and reports truncation from depth or node limits. -Read-only. Calling it changes nothing. +Read-only. | Input | Type | Required | Means | |---|---|---|---| @@ -133,9 +133,9 @@ Read-only. Calling it changes nothing. ## get_service_performance -**Service performance explorer** — Display separate latency, error rate and request rate panels plus slow operations (HTTP, gRPC and consumers) for one service or the system. +**Service performance explorer** — Display separate latency, error rate and request rate panels plus a Slow operations table showing p95 duration grouped by operation over server and consumer spans, covering HTTP, gRPC and message consumers, for one service or the system. -Read-only. Calling it changes nothing. +Read-only. **View resource:** `ui://fanout/panels.html` (model and app visible). @@ -152,7 +152,7 @@ Read-only. Calling it changes nothing. **Service dependency topology** — Return services and observed dependency edges with health, traffic, latency, and error data. -Read-only. Calling it changes nothing. +Read-only. **View resource:** `ui://fanout/panels.html` (model and app visible). @@ -168,7 +168,7 @@ Read-only. Calling it changes nothing. **Telemetry schema** — List the signals, columns with their common values, attribute keys seen per service, metric names, services, measure functions, units and SQL-only relations in sql_relations. Read this before drafting panels so filters use values that exist. See create_dashboard for the spec guide. -Read-only. Calling it changes nothing. +Read-only. | Input | Type | Required | Means | |---|---|---|---| @@ -179,7 +179,7 @@ Read-only. Calling it changes nothing. **Trace detail** — Inspect an exact trace, or select the most relevant recent error or slow trace, with spans, waterfall, flame graph, and correlated logs. -Read-only. Calling it changes nothing. +Read-only. **View resource:** `ui://fanout/panels.html` (model and app visible). @@ -197,7 +197,7 @@ Read-only. Calling it changes nothing. **List dashboard versions** — List the authenticated user's saved versions of one dashboard, newest first, with author and message. The historical version identifies a restore target; restore_dashboard_version saves it as a new version. -Read-only. Calling it changes nothing. +Read-only. | Input | Type | Required | Means | |---|---|---|---| @@ -207,7 +207,7 @@ Read-only. Calling it changes nothing. **List dashboards** — List the authenticated user's dashboards with panel counts and versions. See create_dashboard for the spec guide. -Read-only. Calling it changes nothing. +Read-only. Takes no arguments. @@ -215,7 +215,7 @@ Takes no arguments. **Panel exemplars** — Find bounded traces for a panel selection. -Read-only. Calling it changes nothing. +Read-only. **Visibility:** app only; no resource attachment. @@ -235,7 +235,7 @@ Read-only. Calling it changes nothing. **Preview panels** — Check and run panels without saving them. Each panel reports ok with rows and a sample, empty with the reason, error, or invalid with the exact field and a suggestion. The result includes total elapsed_ms and executed per-panel elapsed_ms; invalid and not_run panels omit elapsed_ms because they were not executed. Fix every invalid panel and replace or explain every empty one before saving. Spec guide: see create_dashboard. -Read-only. Calling it changes nothing. +Read-only. | Input | Type | Required | Means | |---|---|---|---| @@ -248,7 +248,7 @@ Read-only. Calling it changes nothing. **Refresh telemetry panels** — Run every panel in a dashboard fragment; panel subsets are forbidden. -Read-only. Calling it changes nothing. +Read-only. **Visibility:** app only; no resource attachment. @@ -264,7 +264,7 @@ Read-only. Calling it changes nothing. **Telemetry panel** — Display one v1 panel in chat as an executable dashboard fragment. Use get_telemetry_schema to discover fields; see create_dashboard for the spec guide. The authored spec plus vars must fit 128 KiB (131072 serialized JSON bytes); larger inputs are rejected with their actual size. -Read-only. Calling it changes nothing. +Read-only. **View resource:** `ui://fanout/panels.html` (model and app visible). @@ -292,7 +292,7 @@ Read-only. Calling it changes nothing. **Panel variable options** — Resolve variable options within a dashboard fragment window. -Read-only. Calling it changes nothing. +Read-only. **Visibility:** app only; no resource attachment. @@ -317,7 +317,7 @@ Read-only. Calling it changes nothing. **Log explorer** — Search and filter logs with a severity timeline and links back to correlated traces. -Read-only. Calling it changes nothing. +Read-only. **View resource:** `ui://fanout/panels.html` (model and app visible). @@ -349,21 +349,13 @@ Distinct full resource identities per signal, namespace and service observed ins ## Authentication -MCP uses OAuth, not a static key, and **not the ingest token** — an agent -presenting the ingest token is rejected. A client discovers the endpoints, -registers itself, and is issued a token bound to this instance's resource -URI. [Connect an agent](/guides/connect-over-mcp) covers the flow. +MCP uses OAuth tokens bound to the instance’s resource URI. +[Connect an agent](/guides/connect-over-mcp#scopes) documents protocol +requirements and delegated scopes. Dashboard tools operate on the authenticated +user’s own dashboards and require the account capability +`dashboards:manage-own`; see [roles](/reference/roles). -The dashboard tools act on the authenticated user's **own** dashboards. The -capability boundary is `dashboards:manage-own`: an agent acts as the user -whose credential it holds and cannot reach anyone else's. A tool description -that tells a model when to call it is guidance to the model, not a -permission check — see [roles](/reference/roles). +## Other interfaces -## What is not here - -No tool writes telemetry, changes configuration, manages users, or edits -alert rules. Ingest is OTLP only and the rest is HTTP surface — see -[HTTP routes](/reference/http-routes). An agent connected over MCP can read -everything the instance knows and manage its own dashboards, and that is the -whole envelope. +Use OTLP to write telemetry. Configuration uses environment variables, and user +and alert management use the [HTTP API](/reference/http-routes). diff --git a/site/src/content/docs/reference/roles.mdx b/site/src/content/docs/reference/roles.mdx index dd62d122d..b5e7baa6a 100644 --- a/site/src/content/docs/reference/roles.mdx +++ b/site/src/content/docs/reference/roles.mdx @@ -12,13 +12,8 @@ generated: true {/* Generated by cmd/fanout-docgen from internal/api. Edit the generator, not this page. */} -Fanout has three roles. They are fixed — there is no custom role builder, and -a user holds exactly one. - -Every protected route names a capability rather than a role, and a role is a -set of capabilities. The table below is that set, read from the same map the -middleware consults, so it cannot describe a permission the server does not -grant. +Each user has one fixed role: `viewer`, `operator` or `admin`. The table is +generated from the capability map enforced by the authorization middleware. | Capability | viewer | operator | admin | |---|---|---|---| @@ -33,7 +28,7 @@ grant. ## What each capability permits -- `agent:run` — Run the chat investigator, which calls a model provider and acts on the instance's behalf. +- `agent:run` — Run the built-in agent, which calls a model provider and acts on the instance's behalf. - `alerts:manage` — Create, change and delete alert rules. - `dashboards:manage-own` — Create and edit dashboards you own. Owner-scoped for every role, including admin. - `ingest:manage` — Rotate the ingest token. diff --git a/site/src/content/docs/reference/settings/ai.mdx b/site/src/content/docs/reference/settings/ai.mdx index 5ed983dea..78c1c5885 100644 --- a/site/src/content/docs/reference/settings/ai.mdx +++ b/site/src/content/docs/reference/settings/ai.mdx @@ -1,9 +1,9 @@ --- title: "AI provider settings" -description: "The provider, key, model and base URL backing the chat investigator." +description: "The provider, key, model and base URL backing the built-in agent." summary: "Chat is disabled unless a provider is selected; its API key is then required." read_when: - - "The chat investigator is disabled and you want it on." + - "The built-in agent is disabled and you want it on." - "You are pointing Fanout at a self-hosted or proxied model endpoint." status: preview generated: true diff --git a/site/src/content/docs/reference/settings/ingest.mdx b/site/src/content/docs/reference/settings/ingest.mdx index 53b8042bd..6822196f4 100644 --- a/site/src/content/docs/reference/settings/ingest.mdx +++ b/site/src/content/docs/reference/settings/ingest.mdx @@ -35,4 +35,4 @@ Sets the group-commit row target; valid values are 1–50000. Individual request ### `FANOUT_INGEST_MAX_IN_FLIGHT_BYTES` -Caps the decoded telemetry the process will hold across concurrent requests. Concurrency is HTTP/2 streams times connections and each handler holds its batch until the commit is durable, so without a ceiling a burst is bounded only by memory. Zero is unbounded. A single request is admitted when no other request holds budget, even if it exceeds the limit. +Caps decoded telemetry held across concurrent requests until durable publication. Zero is unbounded. A single request is admitted when no other request holds budget, even if it exceeds the limit. diff --git a/site/src/content/docs/reference/settings/server.mdx b/site/src/content/docs/reference/settings/server.mdx index eaf93934b..5389cbec6 100644 --- a/site/src/content/docs/reference/settings/server.mdx +++ b/site/src/content/docs/reference/settings/server.mdx @@ -38,7 +38,7 @@ Exposes Go's net/http/pprof handlers at /debug/pprof/* for CPU/heap/mutex/gorout ### `FANOUT_PUBLIC_URL` -Sets the external browser origin. Required for OIDC; HTTPS is required with MCP. +Sets the external browser origin, MCP token audience, and trusted MCP request origin. Required for OIDC; HTTPS is required with MCP. ### `FANOUT_TLS_CERT_FILE` diff --git a/site/src/content/docs/reference/settings/storage.mdx b/site/src/content/docs/reference/settings/storage.mdx index a79371581..23a6a658f 100644 --- a/site/src/content/docs/reference/settings/storage.mdx +++ b/site/src/content/docs/reference/settings/storage.mdx @@ -36,11 +36,11 @@ Stores telemetry, query state, and the control database. ### `FANOUT_DUCKDB_MAX_CONNECTIONS` -Caps the DuckDB connection pool. Reads scan immutable Parquet concurrently; rollup-cache writes are serialized by the query write gate. Zero means "size it from the machine" — the same spelling DuckDBThreads uses for deferring to a default. Resolution happens in resolveSizing and is reported in the startup configuration log. +Caps the DuckDB read connection pool. Reads scan immutable Parquet concurrently; analytical and completed-batch writes use separate gates and connections. Zero selects available Go CPUs, bounded to 2–16. Startup logs and /readyz report the resolved pool size. ### `FANOUT_DUCKDB_MEMORY` -Caps DuckDB's memory (e.g. "8GB"). Empty means Fanout sizes it from detected memory, reserving headroom for the Go runtime; see resolveSizing. DuckDB's own default is 80% of detected RAM, which is calculated as though DuckDB owned the machine and has been observed to get the process OOM-killed once the Go heap is added on top. +Caps DuckDB's memory (e.g. "8GB"). Empty selects 60% of detected available memory, reserving headroom for Go. If detection fails, DuckDB uses its default with a process headroom adjustment. Startup logs and /readyz report the resolved budget and detection status. Set an explicit cap when memory limit detection is incomplete. ### `FANOUT_DUCKDB_THREADS` diff --git a/site/src/content/docs/start/first-boot.mdx b/site/src/content/docs/start/first-boot.mdx index 8c16a2f73..74853edaa 100644 --- a/site/src/content/docs/start/first-boot.mdx +++ b/site/src/content/docs/start/first-boot.mdx @@ -8,32 +8,15 @@ read_when: status: preview --- -Fanout validates its entire configuration before it opens any listener. A -setting it will not accept stops the process at startup rather than failing -later under load, so a Fanout that is running is one whose configuration was -acceptable. +Fanout validates configuration before opening data files or listeners. Invalid +settings stop startup with an error naming the setting. See +[configuration](/reference/configuration) for precedence, secret files and validation. -## What it checks - -Timing, batch sizing and auth settings are checked together: - -- Addresses and the data directory must not be empty. -- `FANOUT_ROLLUP_INTERVAL` must be at least `1s`; -- `FANOUT_AUTH_MODE` must be `local` or `oidc`. -- `FANOUT_SESSION_IDLE_TTL` must be at least `5m`, and the absolute TTL must be - positive and no shorter than the idle one. -- `FANOUT_AUTH_CODE_SECRET` is **required** in the default `local` auth mode, - and must be at least 32 characters. It is the one setting a first-time - instance is most likely to be missing. -- SMTP is all-or-nothing: set `FANOUT_SMTP_HOST`, `FANOUT_SMTP_USERNAME`, - `FANOUT_SMTP_PASSWORD` and `FANOUT_SMTP_FROM` together, or none of them. -- In `oidc` mode the issuer URL and `FANOUT_PUBLIC_URL` must both be HTTPS, and - a client ID and secret are required. - -An unknown `FANOUT_` setting name is an error too, except platform-injected -service-discovery names. A typo in a setting -name is otherwise indistinguishable from a setting you never made, and the -failure surfaces months later as a default nobody chose. +Local sign-in requires `FANOUT_AUTH_CODE_SECRET` with at least 32 characters. +SMTP and an AI provider are optional; each validates its required settings when +enabled. OIDC requires an HTTPS issuer and public URL, a client ID and a client +secret. The generated [settings reference](/reference/settings/auth) lists the +available authentication settings. ## Claiming the first administrator @@ -65,10 +48,9 @@ show it again. The setup form sends `email`, `display_name`, and `setup_token` to `POST /api/auth/setup`. The first administrator starts with status `active`. -The warning in the banner is not boilerplate. The URL carries a credential that -creates an administrator, and container logs are routinely shipped somewhere -else. Treat a leaked setup URL as an unclaimed admin account and restart with a -fresh data directory if you cannot account for who has seen it. +The setup URL is an administrator credential. Restrict access to process logs +until it is consumed or expires. Treat a leaked setup URL as a compromised +installation and rebuild with a fresh data directory before repeating setup. ## Signing in afterwards @@ -79,5 +61,5 @@ link for an existing active user. OIDC deployments use the provider's flow inste ## Next -An instance with no data is a blank browser client. [Send your first -telemetry](/start/send-telemetry) points an exporter at it. +[Send your first telemetry](/start/send-telemetry), then investigate it with +[Fanout’s agent or an MCP client](/start/send-telemetry#investigate-the-data). diff --git a/site/src/content/docs/start/install.mdx b/site/src/content/docs/start/install.mdx index 1c29060a6..8b63e0b93 100644 --- a/site/src/content/docs/start/install.mdx +++ b/site/src/content/docs/start/install.mdx @@ -11,8 +11,7 @@ status: shipped import { Tabs, TabItem } from "@astrojs/starlight/components"; Fanout ships as a single binary and as a multi-architecture container image. -Neither needs anything else installed: there is no runtime, no database and no -collector to place first. +The release packages include the browser assets and embedded databases. @@ -29,18 +28,11 @@ Images are published to Docker Hub as `labstack/fanout` and mirrored to GitHub Container Registry as `ghcr.io/labstack/fanout`. The two carry the same digests; pick whichever registry your hosts already pull from. -`FANOUT_AUTH_CODE_SECRET` is required in the default `local` auth mode and must -be at least 32 characters — the container refuses to start without it. It is the -only setting the command above adds; the image ships listener and data-directory -defaults of its own. Select `FANOUT_AI_PROVIDER=anthropic` with `ANTHROPIC_API_KEY`, -or `FANOUT_AI_PROVIDER=openai` with `OPENAI_API_KEY`, to enable the chat -investigator. Chat is optional and disabled when no provider is selected, even -with inherited vendor credentials or endpoints. Selecting a provider requires -its key at startup and validates only its endpoint. -Without a selected provider, ingest, dashboards, traces, logs, metrics, and MCP -continue to work; only investigation chat and AI-assisted controls are hidden. - -:::caution[Use a named volume, or fix the ownership yourself] +`FANOUT_AUTH_CODE_SECRET` is required for local sign-in. After setup, +[enable the built-in agent](/reference/settings/ai) or +[connect an external agent over MCP](/guides/connect-over-mcp). + +:::caution[Volume ownership] The image is distroless and runs unprivileged as UID/GID 65532. A **named volume**, as above, is set up correctly for you. A bind-mounted host directory is not: `-v "$PWD/data:/var/lib/fanout/data"` fails to open its data directory @@ -64,18 +56,19 @@ writable or `~/.local/bin` otherwise. Set `FANOUT_PREFIX` to choose the directory, or `FANOUT_VERSION` to pin a tag instead of taking the latest. Versions are CalVer — `vYYYY.M.N[-alpha|-beta|-rc]`, numbered from 0 within each -month across all maturity suffixes. Fanout is currently alpha, so +month across all maturity suffixes. Fanout is alpha, so `v2026.10.1-alpha` is the second release of October 2026. GA has no suffix. Container tags omit the leading `v`, and every release moves `latest`. -Download the artifact for your platform from [GitHub -Releases](https://github.com/labstack/fanout/releases), make it executable, and -run it: +Download and extract the archive for your platform from [GitHub +Releases](https://github.com/labstack/fanout/releases). For example, with the +Linux amd64 archive: ```sh +tar -xzf fanout_v2026.10.1-alpha_linux_amd64.tar.gz chmod +x fanout export FANOUT_AUTH_CODE_SECRET=$(openssl rand -hex 32) ./fanout @@ -116,8 +109,8 @@ runner, because DuckDB needs cgo. Release and `latest` tags also exist under `ghcr.io/labstack/fanout`. Development tags are GHCR-only. -Standalone signatures and SBOMs are deliberately not published yet — the -reasoning is in the repository's release contract. +See the [release contract](https://github.com/labstack/fanout/blob/main/docs/release.md) +for the artifact inventory and verification workflow. ## What an instance opens @@ -126,24 +119,17 @@ reasoning is in the repository's release contract. | `7520` | Browser, API, chat, MCP, OTLP/gRPC and OTLP/HTTP | `127.0.0.1:7520`, loopback | | `./data` | Telemetry, query state, users, sessions, dashboards, alerts and agent history | `./data` | -Every OTLP export requires the ingest token, including on the shared port. -Ingest rejects requests before setup completes. Read [authenticate -exporters](/start/send-telemetry) before pointing a service at the instance. - -Exporters use the shared port `7520` or the public HTTPS origin. Every OTLP -export requires the ingest token. A private collector hostname can be entered -on **Connect telemetry** before copying its generated configuration. +Complete [first boot](/start/first-boot) to create the administrator and ingest +token, then [configure exporters](/start/send-telemetry). **Connect telemetry** +can generate configuration for a private Collector hostname. If the dashboard is public but ingest must remain LAN-only, keep Fanout's backend port private and deny `/v1`, `/v1/*`, and `/opentelemetry.proto.collector.*` on the public proxy. Allow collectors through the private network or a restricted proxy route, and verify that neither OTLP transport is reachable through the public origin. -One port simplifies deployment; it does not replace this access policy. ## Next -The process validates its whole configuration before it opens any listener, so a -setting it will not accept is a refusal to start rather than a failure later. -[First boot](/start/first-boot) covers what it checks, and what it prints once -it is running. +[First boot](/start/first-boot) covers configuration validation, administrator +setup and sign-in. diff --git a/site/src/content/docs/start/send-telemetry.mdx b/site/src/content/docs/start/send-telemetry.mdx index 5c633f406..88c15c277 100644 --- a/site/src/content/docs/start/send-telemetry.mdx +++ b/site/src/content/docs/start/send-telemetry.mdx @@ -24,15 +24,8 @@ Send it as a bearer token; this is the only accepted ingest credential form: Authorization: Bearer fo_ ``` -Two things are worth knowing before you debug a rejection: - -- **Browser sessions and MCP tokens are not ingest credentials.** They are - different credentials for different surfaces, and an exporter presenting one - is rejected like any other unauthenticated caller. -- **Before setup completes, ingest rejects everything.** With no administrator - there is no token to check against, so a collector started ahead of setup - fails until you have finished it. That is the intended order: the instance - does not accept telemetry it cannot attribute. +Ingest is available after administrator setup. Exporters require the ingest +token; browser sessions and MCP OAuth tokens cannot authorize exports. ## Configure an SDK @@ -80,12 +73,8 @@ service: exporters: [otlp/fanout] ``` -The scheme and the port both earn their place. `https://` puts the exporter on -TLS and keeps it there, whatever `tls.insecure` says below it. The port is not -optional: the gRPC exporter validates its endpoint before dialling and refuses -to start without one, with `address fanout.example.com: missing port in -address`. gRPC's own default of 443 belongs to a resolver path this exporter -never reaches. +The gRPC exporter requires an explicit port. Use `https://` for TLS and `:443` +for a proxy serving standard HTTPS. If nothing in front of Fanout terminates TLS — a local instance, or one on a private network — the endpoint is `http://fanout.example.com:7520` and the @@ -93,10 +82,8 @@ exporter needs `tls: { insecure: true }` under `otlp/fanout`, or it will fail to connect. **Connect telemetry** in the application generates this block with your own endpoint already in it, and includes that line when it applies. -A Collector is optional. Fanout speaks the same protocol your SDKs already -export, so it can sit directly behind them — but if you already run a Collector -for sampling, enrichment or fan-out to a second backend, Fanout is just another -exporter in the pipeline. +SDKs can export directly to Fanout. Use a Collector for sampling, enrichment +or forwarding to several backends. ## Watch hosts, containers and endpoints @@ -193,9 +180,9 @@ both in the bad state. A receiver that has never sent data shows an empty panel. If the machine running Fanout fails, Fanout cannot report that failure on its own page: monitor Fanout itself from outside that machine. -Existing users keep their saved copy of the default dashboard. New system -sections appear in newly created default dashboards; existing copies are not -automatically replaced. +Each user owns a saved copy of **System overview**. Changes to the default +specification apply when a copy is created; saved dashboards retain their spec. +See [dashboard defaults](/guides/build-dashboards#system-overview-defaults) for edits. ## Namespaces @@ -203,9 +190,8 @@ Fanout reads `service.namespace` from each OTLP resource, falling back to `FANOUT_DEFAULT_NAMESPACE` (`default`) when it is absent. Namespaces let one instance hold several services' telemetry without them running together. -A query with no namespace set now spans **all** of them. Scoping is opt-in: you -narrow to one namespace deliberately, rather than being silently confined to one -and wondering where the rest of your telemetry went. +A query with no namespace filter spans all namespaces. Add a namespace filter +to narrow the result. They are not an authorisation boundary. A namespace is not a user, an organisation or a tenant, and anyone who can query the instance can query every @@ -222,3 +208,13 @@ When using a reverse proxy, enable HTTP/2 to the backend for gRPC. Plaintext Fanout accepts prior-knowledge HTTP/2 (h2c); a TLS listener negotiates HTTP/2 through ALPN. HTTP/1.1 forwarding works for OTLP/HTTP, but cannot carry gRPC. See [terminate TLS](/guides/terminate-tls). + +## Investigate the data + +With an [AI provider configured](/reference/settings/ai), open chat and ask a +question such as “Why is checkout slower in the last hour?” The agent queries +telemetry and displays its evidence in interactive views. Ask it to +[build a dashboard](/guides/build-dashboards) to save a view for repeated use. + +To use your own agent, [connect over MCP](/guides/connect-over-mcp). MCP does not +require Fanout’s built-in AI provider. diff --git a/site/src/content/docs/start/what-fanout-is.mdx b/site/src/content/docs/start/what-fanout-is.mdx index b5112c601..4fdf7f423 100644 --- a/site/src/content/docs/start/what-fanout-is.mdx +++ b/site/src/content/docs/start/what-fanout-is.mdx @@ -1,17 +1,22 @@ --- title: What Fanout is -description: One Go process that ingests OpenTelemetry, publishes authoritative Parquet, and answers questions through indexed reads and embedded analytics. -summary: The scope of the product in one page — what the binary contains, what it deliberately does not, and who it is for. +description: Investigate OpenTelemetry with a built-in agent or your own MCP client, using one self-hosted binary. +summary: Agent investigations, dashboards and telemetry storage in one process, with one data directory. read_when: - You are deciding whether Fanout fits before installing anything. - You want to know what Fanout replaces in an existing observability stack. status: preview --- -Fanout is a single self-hosted binary for OpenTelemetry. One Go process accepts -OTLP over gRPC and HTTP, publishes atomic Parquet batches with persistent trace -indexes, runs DuckDB analytics and rollups, evaluates alert rules, serves a chat -investigator and MCP tools, and hosts the browser client. +Fanout is a self-hosted OpenTelemetry backend for agent investigations. Ask its +built-in agent a question about traces, logs or metrics, or connect your own +agent over MCP. Both use the same typed tools to inspect telemetry and build +dashboards. + +One Go process accepts OTLP over gRPC and HTTP, stores telemetry in local Parquet, +runs DuckDB analytics, evaluates alert rules and serves the browser client. +The built-in agent requires a configured AI provider; external MCP clients use +their own model provider.
@@ -25,11 +30,9 @@ investigator and MCP tools, and hosts the browser client.
One process owns the complete path from OTLP ingest to investigation.
-The point of that list is that it is one list. A conventional deployment of the -same capability is a collector, a storage backend, a query layer, a dashboard -service and an alertmanager, each with its own configuration, failure modes and -upgrade cadence. Fanout is one process with one configuration and one thing to -restart. +One binary and one data directory contain ingest, storage, queries and the +browser client. [Why one binary](/explanation/why-one-binary) explains the +operating tradeoffs. ## What it contains @@ -39,19 +42,17 @@ restart. | Storage | Atomically publishes indexed Parquet batches to a local data directory | | Query | Direct indexed trace reads plus in-process DuckDB SQL and rollups | | Alerts | Evaluates persisted rules on a fixed interval against rollups | -| Investigator | A chat agent working from the same typed query tools | +| Agent | A chat agent working from the same typed query tools | | MCP server | Exposes those tools to an external agent | | Browser client | Served by the same process, from the same binary | -## What it is not +## Deployment boundaries -Fanout is not a hosted service, and it is not a collector. It sits where the -backend sits: your SDKs or your existing Collector export to it. +SDKs and Collectors export to Fanout as their telemetry backend. Fanout runs on +one machine with local storage. It has no clustering, replication or object tier. -It is also not a multi-tenant platform. Namespaces scope telemetry queries so -one instance can hold several services' data without them running together, but -a namespace is not a user, an organisation or an authorisation boundary. An -instance is a trust domain. +Namespaces scope queries. Every account with telemetry access can read every +namespace; deploy separate instances for separate trust domains. ## Who it is for @@ -59,9 +60,7 @@ Teams that want their telemetry on their own hardware, with a small enough operational surface that observability does not become its own on-call rotation. The reference deployment target is a single small VM. -## Where it is in its life +## Stability -Fanout is pre-release. It changes without migration paths, and the shape of -things that already run may still move. The [capabilities -page](/status/capabilities) is the account of what is settled and what is not; -it is worth reading before building anything durable on top. +Fanout is alpha. User-facing contracts can change without migration paths. +The [capabilities page](/status/capabilities) lists each feature’s stability. diff --git a/site/src/content/docs/status/capabilities.mdx b/site/src/content/docs/status/capabilities.mdx index 192154d92..65ef39142 100644 --- a/site/src/content/docs/status/capabilities.mdx +++ b/site/src/content/docs/status/capabilities.mdx @@ -1,62 +1,44 @@ --- title: Shipped vs planned description: What the current Fanout binary does, what runs but may still change shape, and what is only designed. -summary: The honest account of where each capability stands, marked page by page across the documentation. +summary: Capability availability, contract stability and operating limits. read_when: - You are deciding whether to build something durable on a Fanout capability. - A page describes something and you want to know whether it executes today. status: preview --- -Fanout is pre-release. It is used in earnest, and it changes without migration -paths. This page is the account of what that means per capability, so a reader -does not have to infer it from how confidently a page is written. +Fanout is alpha. User-facing contracts and storage formats can change without +migration paths. Every documentation page states one of these statuses: -Every documentation page carries one of three markers in its frontmatter, and -the vocabulary is closed — a fourth value fails the build rather than quietly -introducing a fourth kind of claim: - -| Marker | What it means | +| Marker | Meaning | |---|---| -| `shipped` | The binary on the current tag does this, and the shape is settled. | -| `preview` | It runs today, and its shape may still change without a migration path. | -| `planned` | Designed and written down. Nothing executes it yet. | - -The marker reaches an agent too: `llms.txt` annotates every non-shipped page -inline, so something reading the index knows before it fetches the page. - -Every page states its status explicitly rather than relying on the default. -That is deliberate: `shipped` is the schema's default, so a page that says -nothing asserts stability by silence — which is the opposite of what a -pre-release product should do. Most pages here are `preview` because their -user-facing contracts are still being refined. The marker describes the -current stability of a capability; it does not imply an unlisted compatibility -surface. +| `shipped` | Available with a settled contract. | +| `preview` | Available; the contract can change without a migration path. | +| `planned` | Designed but unavailable. | -`shipped` is reserved for what has not moved and is not expected to: what -Fanout is, the release and install mechanics, and backing up the data -directory. +`llms.txt` includes the status of every non-shipped page. A page covering several +capabilities uses `preview` if any of its contracts remain unsettled. ## Where each capability stands | Capability | Status | Notes | |---|---|---| | OTLP ingest over gRPC and HTTP | shipped | Both transports, one port and one ingest token. | -| Parquet storage, trace indexes, and DuckDB analytics | shipped | Authoritative local Parquet; rebuildable DuckDB query state. | -| Browser client | preview | Ships in the binary; surfaces still moving. | -| Chat investigator | preview | Disabled unless `FANOUT_AI_PROVIDER` selects `anthropic` or `openai`; the selected provider's key is required at startup. | +| Parquet storage, trace indexes, and DuckDB analytics | preview | Authoritative local Parquet; rebuildable DuckDB query state. | +| Browser client | preview | Ships in the binary; preview contracts. | +| Built-in agent | preview | Disabled unless `FANOUT_AI_PROVIDER` selects `anthropic` or `openai`; the selected provider's key is required at startup. | | Agent-built dashboards | preview | [Build and refine from chat](/guides/build-dashboards): fifteen panel types, variables, comparison, saved grids and immutable versions with restore. View links retain filters and time; dashboard access remains owner-scoped. | | MCP tools | preview | Served at `/mcp`; the tool set is not frozen. | | Alerts | preview | Rules evaluate on an interval against rollups. | | Local email sign-in | shipped | Codes by email; no passwords. | | Local self-signup | preview | `FANOUT_SELF_SIGNUP`, off by default. Provisions viewers after code verification only. | -| OIDC viewer auto-provisioning | preview | Verified identities admitted as viewers without a shared credential. | +| OIDC account auto-provisioning | preview | Eligible identities receive the configured mapped or default role; the default is viewer. | | OIDC sign-in | shipped | Provider flow, with group and domain mapping. | | Generated settings reference | shipped | `cmd/fanout-docgen` writes it; `just check` fails when it drifts from the type. | | Release checksums and provenance | shipped | `SHA256SUMS` plus GitHub build attestations on every archive. | -| Published ingest benchmark | shipped | [Performance](/explanation/performance) reports v2026.10.7-alpha with three sweep repetitions and [raw evidence](https://github.com/labstack/fanout-bench/tree/main/published/2026-10-16-ccx33x2-v2026.10.7-alpha). | -| Signatures and SBOM | planned | Deliberately deferred until something consumes them. | -| Guides for every operational task | preview | Dashboard authoring and inspection are documented; operational coverage is still incomplete. | +| Published ingest benchmark | shipped | [Performance](/explanation/performance) reports v2026.10.8-alpha with three sweep repetitions and [raw evidence](https://github.com/labstack/fanout-bench/tree/main/published/2026-10-16-ccx33x2-v2026.10.8-alpha). | +| Signatures and SBOM | planned | Unavailable; see the [release contract](https://github.com/labstack/fanout/blob/main/docs/release.md#supply-chain-scope). | | Namespace scoping on alert rules | planned | The field is stored but evaluation ignores it; scope with `service`. | ## Operating limits