From 29e8692c907c0bc15d78d93349099bdb024a79f0 Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Thu, 5 Nov 2026 20:10:27 -0800 Subject: [PATCH 1/2] docs: add an Explore guide and list Explore, FanQL and format 5 --- README.md | 1 + site/astro.config.mjs | 1 + .../docs/docs/get-started/overview.mdx | 2 + site/src/content/docs/docs/guides/explore.mdx | 100 ++++++++++++++++++ site/src/content/docs/docs/index.mdx | 1 + .../docs/docs/reference/capabilities.mdx | 3 + 6 files changed, 108 insertions(+) create mode 100644 site/src/content/docs/docs/guides/explore.mdx diff --git a/README.md b/README.md index 793e86f89..8faf687b8 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ client, built-in agent, MCP tools, dashboards, and alerts are preview capabiliti [documentation](https://fanout.run) or run it below. - OTLP ingest over gRPC and HTTP, with local Parquet storage and DuckDB analytics. +- Explore and FanQL for querying telemetry without an AI provider. - An investigation agent that answers questions about your telemetry in plain language. - An MCP server for external agents using the same typed query tools. - Dashboards across traces, logs, and metrics, and alerts on service error rate, latency, diff --git a/site/astro.config.mjs b/site/astro.config.mjs index 24531fc63..02fb9e5f1 100644 --- a/site/astro.config.mjs +++ b/site/astro.config.mjs @@ -90,6 +90,7 @@ export default defineConfig({ { label: "Terminate TLS", slug: "docs/guides/tls" }, { label: "Set up alerts", slug: "docs/guides/alerts" }, { label: "Connect an agent over MCP", slug: "docs/guides/mcp" }, + { label: "Query with Explore", slug: "docs/guides/explore" }, { label: "Build and refine dashboards", slug: "docs/guides/dashboards" }, { label: "Back up and restore", slug: "docs/guides/backup-and-restore" }, { label: "Tune retention", slug: "docs/guides/retention" }, diff --git a/site/src/content/docs/docs/get-started/overview.mdx b/site/src/content/docs/docs/get-started/overview.mdx index e28484043..068f2121d 100644 --- a/site/src/content/docs/docs/get-started/overview.mdx +++ b/site/src/content/docs/docs/get-started/overview.mdx @@ -18,6 +18,8 @@ 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. +[Explore and FanQL](/docs/guides/explore) let you query telemetry without an AI provider. +
=warn +``` + +Use service names present in your telemetry. See the +[FanQL reference](/docs/reference/fanql) for syntax, fields and functions. + +## Read diagnostics + +When a query has problems, the editor marks the affected text and lists messages +below it. Problems prevent execution. Use **Replace with** when a suggested fix +fits, or edit the text yourself, then run again. Notices provide guidance and +do not block execution. + +The result's **Ran as** line shows the canonical query. If you edit a query or a +run fails, the previous result can remain visible. Check its status before +reading it as the result of your current query. + +## Pick a visualization + +After parsing, the visualization picker offers types compatible with the query. +Choose one to rerun it. Options that need settings such as minimum and maximum +values or thresholds stay disabled until those settings are supplied in a +dashboard panel. + +Buttons with an ellipsis offer a query rewrite. Hover to inspect the proposed +text before selecting one. The rewritten query appears in the editor and runs. + +## Search Logs and Traces + +Open **Logs** or **Traces** in the sidebar. Their search bars accept FanQL filters +only. Leave out the source, `where` and aggregation clauses. + +On Logs, enter: + +```text +service:checkout severity>=warn +``` + +On Traces, enter: + +```text +status:error duration>500ms +``` + +Press Enter or select **Search**. The service, severity, error and duration +controls add filters to the typed search. Use the time picker and order control +to change the window and ordering. + +Trace results list traces with matching spans. The displayed root span can have +different values from the span that matched; see +[trace semantics](/docs/reference/fanql#visualization-and-trace-semantics). + +## Save to a dashboard + +After a successful run with data, select **Save to dashboard** in Explore, Logs +or Traces. If you changed the query or filters, run them again first. + +Choose an existing dashboard or **New dashboard**, enter a panel title and select +**Save**. A new dashboard also needs a name. Fanout opens the saved dashboard. +Existing dashboards keep their time settings; new ones use the selected window. +See [dashboard controls](/docs/guides/dashboards) for further changes. + +## Use HTTP or MCP + +The [HTTP API reference](/docs/reference/api) lists FanQL parse, format, +completion and reference routes, plus panel query and dashboard routes. +Over MCP, [query_telemetry](/docs/reference/mcp#query_telemetry) accepts FanQL +text with a panel. Use [create_dashboard](/docs/reference/mcp#create_dashboard) +or [edit_dashboard](/docs/reference/mcp#edit_dashboard) to save panels. diff --git a/site/src/content/docs/docs/index.mdx b/site/src/content/docs/docs/index.mdx index e5a891a4e..6c544216e 100644 --- a/site/src/content/docs/docs/index.mdx +++ b/site/src/content/docs/docs/index.mdx @@ -25,6 +25,7 @@ Send OpenTelemetry to one binary. Investigate with Fanout's built-in agent, or c - [Set up alerts](/docs/guides/alerts) +- [Query with Explore](/docs/guides/explore) - [Build and refine dashboards](/docs/guides/dashboards) - [Connect an agent over MCP](/docs/guides/mcp) - [Terminate TLS](/docs/guides/tls) diff --git a/site/src/content/docs/docs/reference/capabilities.mdx b/site/src/content/docs/docs/reference/capabilities.mdx index a9db55097..1c9c93804 100644 --- a/site/src/content/docs/docs/reference/capabilities.mdx +++ b/site/src/content/docs/docs/reference/capabilities.mdx @@ -26,7 +26,10 @@ capabilities uses `preview` if any of its contracts remain unsettled. |---|---|---| | OTLP ingest over gRPC and HTTP | shipped | Both transports, one port and one ingest token. | | Parquet storage, trace indexes, and DuckDB analytics | preview | Authoritative local Parquet; rebuildable DuckDB query state. | +| Batch format 5 storage | preview | [Typed Parquet attributes and dedicated columns](/docs/concepts/storage); unsupported batch formats prevent startup. | | Browser client | preview | Ships in the binary; preview contracts. | +| Explore | preview | [Run queries, choose visualizations and save dashboard panels](/docs/guides/explore) without an AI provider. | +| FanQL | preview | [Text queries](/docs/reference/fanql) with diagnostics and completion; filter-only search on Logs and Traces. | | 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](/docs/guides/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. | From 79429f288981643d0131a93e2e1c2a8c564b6212 Mon Sep 17 00:00:00 2001 From: Vishal Rana Date: Thu, 5 Nov 2026 20:47:56 -0800 Subject: [PATCH 2/2] docs: cover alerts, dashboard editing, upgrades, deployment and the CLI --- .dockerignore | 1 + .gitignore | 1 + README.md | 8 +- cmd/fanout-docgen/routes.go | 2 +- site/astro.config.mjs | 14 ++- .../docs/docs/concepts/authentication.mdx | 84 ++++++++++++++- .../content/docs/docs/concepts/comparison.mdx | 20 ++++ .../content/docs/docs/concepts/insights.mdx | 64 +++++++++++ .../docs/docs/get-started/first-boot.mdx | 13 ++- .../content/docs/docs/get-started/install.mdx | 8 +- .../docs/docs/get-started/send-telemetry.mdx | 24 +++++ site/src/content/docs/docs/guides/alerts.mdx | 99 ++++++++++++++--- .../docs/docs/guides/backup-and-restore.mdx | 10 +- site/src/content/docs/docs/guides/chat.mdx | 55 ++++++++++ .../content/docs/docs/guides/dashboards.mdx | 38 +++++-- site/src/content/docs/docs/guides/deploy.mdx | 101 ++++++++++++++++++ site/src/content/docs/docs/guides/explore.mdx | 26 +++++ .../content/docs/docs/guides/hardening.mdx | 60 +++++++++++ site/src/content/docs/docs/guides/mcp.mdx | 23 +++- .../docs/docs/guides/troubleshooting.mdx | 24 ++++- site/src/content/docs/docs/guides/upgrade.mdx | 44 ++++++++ site/src/content/docs/docs/help.mdx | 32 ++++++ site/src/content/docs/docs/index.mdx | 16 ++- site/src/content/docs/docs/reference/api.mdx | 4 +- .../docs/docs/reference/capabilities.mdx | 10 +- site/src/content/docs/docs/reference/cli.mdx | 72 +++++++++++++ .../docs/docs/reference/configuration.mdx | 2 +- .../content/docs/docs/reference/endpoints.mdx | 22 +++- site/src/pages/llms-full.txt.ts | 2 +- site/src/pages/llms.txt.ts | 3 +- 30 files changed, 819 insertions(+), 63 deletions(-) create mode 100644 site/src/content/docs/docs/concepts/comparison.mdx create mode 100644 site/src/content/docs/docs/concepts/insights.mdx create mode 100644 site/src/content/docs/docs/guides/chat.mdx create mode 100644 site/src/content/docs/docs/guides/deploy.mdx create mode 100644 site/src/content/docs/docs/guides/hardening.mdx create mode 100644 site/src/content/docs/docs/guides/upgrade.mdx create mode 100644 site/src/content/docs/docs/help.mdx create mode 100644 site/src/content/docs/docs/reference/cli.mdx diff --git a/.dockerignore b/.dockerignore index 486fe78e2..27012c3b3 100644 --- a/.dockerignore +++ b/.dockerignore @@ -61,3 +61,4 @@ docs/ # OS .DS_Store +.wrangler/ diff --git a/.gitignore b/.gitignore index 56fbf8e6e..4b7a88056 100644 --- a/.gitignore +++ b/.gitignore @@ -64,3 +64,4 @@ cover.out /bench /fanout /fanout-docgen +.wrangler/ diff --git a/README.md b/README.md index 8faf687b8..0bcf9cb32 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,7 @@ export FANOUT_AUTH_CODE_SECRET=$(openssl rand -hex 32) fanout ``` -Set `FANOUT_VERSION` to a [release tag](https://github.com/labstack/fanout/releases), such as `v2026.10.23-alpha`, to pin a release, and `FANOUT_PREFIX` to choose the installation +Set `FANOUT_VERSION` to a [release tag](https://github.com/labstack/fanout/releases), such as `v2026.11.0-alpha`, to pin a release, and `FANOUT_PREFIX` to choose the installation directory. Native installs bind `127.0.0.1:7520`; set `FANOUT_ADDR=:7520` for remote access, then follow the same first-boot setup. @@ -212,7 +212,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 alpha (for example, `v2026.10.23-alpha`); GA has no suffix. +maturity suffixes. Fanout is alpha (for example, `v2026.11.0-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. @@ -220,9 +220,9 @@ canonical and also carries development images. | Image tag | Points at | | --- | --- | | `labstack/fanout:latest` | the newest release, mirrored on Docker Hub | -| `labstack/fanout:2026.10.23-alpha` | that exact release, mirrored on Docker Hub | +| `labstack/fanout:2026.11.0-alpha` | that exact release, mirrored on Docker Hub | | `ghcr.io/labstack/fanout:latest` | the newest release | -| `ghcr.io/labstack/fanout:2026.10.23-alpha` | that exact release | +| `ghcr.io/labstack/fanout:2026.11.0-alpha` | that exact release | | `ghcr.io/labstack/fanout:main` | the tip of `main` | | `ghcr.io/labstack/fanout:sha-` | one specific commit | diff --git a/cmd/fanout-docgen/routes.go b/cmd/fanout-docgen/routes.go index 1a67f5672..b67e36eb8 100644 --- a/cmd/fanout-docgen/routes.go +++ b/cmd/fanout-docgen/routes.go @@ -263,7 +263,7 @@ func renderRoutes(routes []api.RouteDoc) []byte { b.WriteString("pattern Echo matches on, not a literal URL.\n") b.WriteString("\n") - b.WriteString("## Interface stability\n\nThe `/api/*` routes serve the browser client and can change without migration\npaths. [MCP](/docs/guides/mcp) is the agent interface. OTLP ingest and\n[operational endpoints](/docs/reference/endpoints) have their own contracts.\n\nManage alert rules through the [HTTP API](/docs/guides/alerts). Administrators\nrotate ingest tokens on **Connect telemetry** or with\n`POST /api/settings/ingest/token/rotate`.\n\n") + b.WriteString("## Interface stability\n\nThe `/api/*` routes serve the browser client and can change without migration\npaths. [MCP](/docs/guides/mcp) is the agent interface. OTLP ingest and\n[operational endpoints](/docs/reference/endpoints) have their own contracts.\n\nManage alert rules on the [Alerts page](/docs/guides/alerts) or through the HTTP API.\nAdministrators rotate 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`.\n`GET /api/telemetry/schema` returns 503 `schema_busy` with `Retry-After` when a\nnew window and namespace cannot start a discovery yet, or when the discovery is\nstill running after 15 seconds; it keeps running, so a retry finds it cached.\nCached ones are always served. An unknown window is 400 `bad_request`.\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") diff --git a/site/astro.config.mjs b/site/astro.config.mjs index 02fb9e5f1..7e3cff695 100644 --- a/site/astro.config.mjs +++ b/site/astro.config.mjs @@ -82,16 +82,21 @@ export default defineConfig({ { label: "Install", slug: "docs/get-started/install" }, { label: "First boot", slug: "docs/get-started/first-boot" }, { label: "Send your first telemetry", slug: "docs/get-started/send-telemetry" }, + { label: "Get help and contribute", slug: "docs/help" }, ], }, { label: "Guides", items: [ - { label: "Terminate TLS", slug: "docs/guides/tls" }, - { label: "Set up alerts", slug: "docs/guides/alerts" }, - { label: "Connect an agent over MCP", slug: "docs/guides/mcp" }, + { label: "Use the built-in agent", slug: "docs/guides/chat" }, { label: "Query with Explore", slug: "docs/guides/explore" }, { label: "Build and refine dashboards", slug: "docs/guides/dashboards" }, + { label: "Set up alerts", slug: "docs/guides/alerts" }, + { label: "Connect an agent over MCP", slug: "docs/guides/mcp" }, + { label: "Run with Compose or systemd", slug: "docs/guides/deploy" }, + { label: "Terminate TLS", slug: "docs/guides/tls" }, + { label: "Upgrade", slug: "docs/guides/upgrade" }, + { label: "Harden an instance", slug: "docs/guides/hardening" }, { label: "Back up and restore", slug: "docs/guides/backup-and-restore" }, { label: "Tune retention", slug: "docs/guides/retention" }, { label: "Troubleshoot", slug: "docs/guides/troubleshooting" }, @@ -111,6 +116,7 @@ export default defineConfig({ { autogenerate: { directory: "docs/reference/configuration" } }, ], }, + { label: "CLI", slug: "docs/reference/cli" }, { label: "HTTP routes", slug: "docs/reference/api" }, { label: "MCP tools", slug: "docs/reference/mcp" }, { label: "FanQL", slug: "docs/reference/fanql" }, @@ -127,6 +133,8 @@ export default defineConfig({ { label: "Why one binary", slug: "docs/concepts/architecture" }, { label: "How storage works", slug: "docs/concepts/storage" }, { label: "Authentication modes", slug: "docs/concepts/authentication" }, + { label: "Insights and anomalies", slug: "docs/concepts/insights" }, + { label: "How Fanout compares", slug: "docs/concepts/comparison" }, { label: "Performance", slug: "docs/concepts/performance" }, ], }, diff --git a/site/src/content/docs/docs/concepts/authentication.mdx b/site/src/content/docs/docs/concepts/authentication.mdx index a4758c99d..0d9517660 100644 --- a/site/src/content/docs/docs/concepts/authentication.mdx +++ b/site/src/content/docs/docs/concepts/authentication.mdx @@ -17,9 +17,10 @@ and account suspension rules. 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. +through the HTTP API. There is no user-management browser page. See +[account profiles and suspension](#account-profiles-and-suspension) +for account APIs and [local recovery](#recover-local-sign-in) 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 @@ -48,8 +49,8 @@ from the configured group mapping, falling back to `FANOUT_OIDC_DEFAULT_ROLE` `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. +[Microsoft Entra ID group overage](#microsoft-entra-id-group-overage) if group +claims are omitted. ### Role ownership @@ -62,6 +63,14 @@ 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. +### Microsoft Entra ID group overage + +Entra can omit the `groups` claim when an account has too many memberships. +If the token signals group overage and any group-based policy is configured, +Fanout denies login. It does not fetch group membership from Graph. +Configure the application registration to emit only groups assigned to the +application. Domain-only allow policies are unaffected. + ## Account profiles and suspension Administrators create active accounts with `POST /api/users`, supplying `email`, @@ -73,6 +82,71 @@ 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. +`GET /api/users` returns a `users` array. `DELETE /api/users/{id}` removes an +account and cascades to its sessions, OAuth grants and owned dashboards. Use +suspension when the account and its data should remain. + +`POST /api/users/{id}/access/revoke` revokes all browser sessions and OAuth +tokens for that user. It preserves the account. A user who remains eligible +can sign in again. + +### Call account APIs from a script + +These routes accept only a browser session with the admin role. Fanout has no +API key for user administration. Ingest tokens, metrics tokens and MCP OAuth +tokens cannot substitute for that session. + +Sign in as an administrator. In browser developer tools, find an authenticated +request and copy its session cookie into a temporary Netscape-format cookie +jar supported by curl. Keep it private and outside source control. A script +can use that jar while the session remains valid: + +```sh +curl --fail-with-body --cookie "$COOKIE_JAR" \ + https://fanout.example.com/api/users + +curl --fail-with-body --cookie "$COOKIE_JAR" \ + -H 'Fanout-Request: 1' -H 'Content-Type: application/json' \ + -X POST https://fanout.example.com/api/users \ + --data '{"email":"user@example.com","display_name":"New user","role":"viewer"}' +``` + +Replace the origin and set `COOKIE_JAR` to that private jar. Mutating requests +need `Fanout-Request: 1` or a matching Origin/Referer; cross-site browser requests +are rejected. Session expiry or revocation requires signing in again. Delete +the temporary jar when finished and sign out to revoke that session. + +## Recover local sign-in + +Run with the server's environment and data directory: + +```sh +fanout login-link admin@example.com +# For Docker: +docker exec fanout fanout login-link admin@example.com +``` + +The URL is printed to stderr, expires in 15 minutes and works once. Issuance +and redemption are audited. The command supports an online server but refuses +missing or suspended users, a missing control database and OIDC mode. + +Creating a local user without SMTP returns `201`, +`invite_delivery: "not_configured"` and `login_link_required: true`. Mint a link +for that active user and deliver it through a trusted channel. If configured +SMTP fails delivery, the API reports an error. Repair SMTP after regaining access. + +If the only administrator is suspended or has an unusable address, stop Fanout +and back up the control database. Repair that existing account's email or status +in SQLite, preserving its ID and owned data. Restart and mint a login link for +the active account. OIDC recovery belongs at the provider or configuration layer. + +## Review MCP connections + +Open **Connect telemetry → Connected agents** in the account menu to review and disconnect one OAuth client. +Disconnecting revokes that client's access and refresh tokens for your account. +Reconnect by authorizing it again. Other clients and browser sessions remain +connected. See [MCP connections](/docs/guides/mcp#disconnect-an-agent) for API routes. + ## Access boundaries See [namespace access limits](/docs/reference/capabilities#operating-limits). diff --git a/site/src/content/docs/docs/concepts/comparison.mdx b/site/src/content/docs/docs/concepts/comparison.mdx new file mode 100644 index 000000000..806a51233 --- /dev/null +++ b/site/src/content/docs/docs/concepts/comparison.mdx @@ -0,0 +1,20 @@ +--- +title: How Fanout compares +description: Compare the deployment shape and scope of Fanout with other telemetry systems. +summary: The comparison table from the project README. +read_when: + - You are deciding whether one Fanout instance fits your workload. +status: preview +--- + +| If you use | Where Fanout differs | +| --- | --- | +| **Grafana with Loki, Tempo, and Mimir** | That stack keeps a service and a query language per signal, plus object storage underneath. Fanout keeps one process, one data directory, and one typed contract across all three signals, at the cost of the horizontal scale those components are built for. | +| **SigNoz** | Both are OTLP-native and self-hosted. SigNoz composes a collector, ClickHouse, and query services; Fanout compiles ingest, authoritative Parquet storage, indexed trace reads, DuckDB analytics, alerting, and the browser client into one binary. | +| **Jaeger** | Jaeger covers traces and expects a storage backend you run separately. Fanout ingests traces, logs, and metrics into the same store, with nothing else to deploy. | +| **Prometheus with Grafana** | Prometheus pulls metrics and is excellent at them. Fanout accepts pushed OTLP for all three signals and is built around investigating a specific incident rather than maintaining long-range metric series. | +| **Datadog**, **Honeycomb**, **Grafana Cloud** | Those are managed services: someone else runs the storage, the scaling, and the upgrades, and your telemetry leaves your network to get there. Fanout is a binary you run, on data that stays on your disk. | +| **An OpenTelemetry Collector piped into ClickHouse** | The same shape, assembled by hand: collector, database, dashboards, and the glue between them. Fanout is that assembly as one program, with an agent and an MCP server already wired to the same query contract. | + +Fanout is a single node. It has no clustering, no replication, and no object tier; a deployment that +outgrows one machine's disk and CPU has outgrown Fanout. diff --git a/site/src/content/docs/docs/concepts/insights.mdx b/site/src/content/docs/docs/concepts/insights.mdx new file mode 100644 index 000000000..dccba32b3 --- /dev/null +++ b/site/src/content/docs/docs/concepts/insights.mdx @@ -0,0 +1,64 @@ +--- +title: Insights and anomalies +description: Understand detector snapshots and the values used by alert rules. +summary: Service changes, repeated log patterns, health scores and alert variables. +read_when: + - You need to interpret an insight or detector-based alert. +status: preview +--- + +## Read a snapshot + +`GET /api/insights` returns the latest completed detector snapshot and requires +`telemetry:read`. It returns 503 before a snapshot is ready. MCP clients use +`get_insights`. Neither path requires an AI provider. + +The detector runs once at startup and every 60 seconds. Its lookback is +15 minutes. These are built-in detector settings, not environment options. +Snapshots contain anomalies, repeated log patterns, derived insights, a summary, +`generated_at`, `timeframe` and `health_score`. + +## What detection measures + +The detector checks service error-rate changes, latency degradation and span +volume changes across all namespaces. Service checks use completed rollup +minutes, ending before the service watermark. The baseline is the preceding +window of equal length. Latency uses the span-weighted mean of minute p95 +values. See [rollup timing](/docs/concepts/storage#rollups-follow-durable-publication). + +Scores compare current values with the baseline and apply signal-specific +variance floors and change thresholds. The z-score thresholds are 2.0 for +error rate and latency, and 2.5 for volume. Treat a finding as a reason to +inspect its current value, baseline and service evidence. + +Log detection reads the current wall-clock lookback even when the rollup +watermark has not advanced. It groups `WARN`, `ERROR` and `FATAL` logs by body +template, severity and service. A pattern needs at least three occurrences; +the snapshot keeps at most 50, ordered by count. Repeated `ERROR` patterns +with at least 20 occurrences also produce warning insights. + +## Health score + +The score starts at 100 and has a floor of zero: + +| Finding | Deduction | +|---|---| +| Absolute anomaly z-score at least 3.0 | 15 | +| Absolute anomaly z-score at least 2.5 but below 3.0 | 10 | +| Absolute anomaly z-score at least 2.0 but below 2.5 | 5 | +| Each `ERROR` pattern with at least 10 occurrences | 5 | +| Each `WARN` pattern with at least 20 occurrences | 2 | + +This is a summary of detected findings, not an uptime percentage. + +## Alert variables + +Alert evaluation takes `health_score` from the latest detector snapshot and +uses the same score for every service. For each service, `z_score` is the +signed anomaly score with the largest absolute value across that service's +anomalies. It is zero when that service has no anomaly in the snapshot. +If no snapshot exists, both values default to zero. + +Use `z_score > 2.5 || z_score < -2.5` when either direction matters. Combine these values with +service measurements in [alert rules](/docs/guides/alerts). Detector timing +is separate from the alert evaluation interval. diff --git a/site/src/content/docs/docs/get-started/first-boot.mdx b/site/src/content/docs/docs/get-started/first-boot.mdx index 71a622abf..9a0c21b4b 100644 --- a/site/src/content/docs/docs/get-started/first-boot.mdx +++ b/site/src/content/docs/docs/get-started/first-boot.mdx @@ -45,6 +45,11 @@ Open the URL, create the administrator, and **save the ingest token shown after setup**. The raw token is displayed once; Fanout stores only its hash and cannot show it again. +An administrator can issue a replacement in **Connect telemetry → Ingest token** in the account menu, or +with `POST /api/settings/ingest/token/rotate`. Save the new token when it is +shown. Rotation invalidates the old token immediately and cuts off existing +exporters until you update their credentials. + The setup form sends `email`, `display_name`, and `setup_token` to `POST /api/auth/setup`. The first administrator starts with status `active`. @@ -57,7 +62,13 @@ installation and rebuild with a fresh data directory before repeating setup. Local mode has no passwords. Once SMTP is configured, active users receive short-lived codes by email. Without SMTP, run `fanout login-link ` with the server's environment and data directory to mint a 15-minute, single-use -link for an existing active user. OIDC deployments use the provider's flow instead. +link for an existing active user. For Docker, use: + +```sh +docker exec fanout fanout login-link admin@example.com +``` + +OIDC deployments use the provider's flow instead. ## Next diff --git a/site/src/content/docs/docs/get-started/install.mdx b/site/src/content/docs/docs/get-started/install.mdx index 90e9ce325..686272ec0 100644 --- a/site/src/content/docs/docs/get-started/install.mdx +++ b/site/src/content/docs/docs/get-started/install.mdx @@ -57,7 +57,7 @@ directory, or `FANOUT_VERSION` to pin a tag instead of taking the latest. Versions use CalVer format `vYYYY.M.N[-alpha|-beta|-rc]`, numbered from 0 within each month across all maturity suffixes. Fanout is alpha, so -`v2026.10.1-alpha` is the second release of October 2026. GA has no suffix. +`v2026.11.0-alpha` is the first release of November 2026. GA has no suffix. Container tags omit the leading `v`, and every release moves `latest`. @@ -68,7 +68,7 @@ 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 +tar -xzf fanout_v2026.11.0-alpha_linux_amd64.tar.gz chmod +x fanout export FANOUT_AUTH_CODE_SECRET=$(openssl rand -hex 32) ./fanout @@ -84,7 +84,7 @@ page by hand, check both the checksum and the build provenance: ```sh sha256sum -c SHA256SUMS -gh attestation verify fanout_v2026.10.1-alpha_linux_amd64.tar.gz \ +gh attestation verify fanout_v2026.11.0-alpha_linux_amd64.tar.gz \ --repo labstack/fanout ``` @@ -92,7 +92,7 @@ For containers, record or pin the digest the registry returns rather than trusting a moving tag: ```sh -docker buildx imagetools inspect labstack/fanout:2026.10.1-alpha +docker buildx imagetools inspect labstack/fanout:2026.11.0-alpha ``` Release images are multi-architecture for `linux/amd64` and `linux/arm64`, and diff --git a/site/src/content/docs/docs/get-started/send-telemetry.mdx b/site/src/content/docs/docs/get-started/send-telemetry.mdx index ed06e5690..67a237458 100644 --- a/site/src/content/docs/docs/get-started/send-telemetry.mdx +++ b/site/src/content/docs/docs/get-started/send-telemetry.mdx @@ -18,6 +18,11 @@ same port as the application: `7520` by default. Both require the ingest token. The raw ingest token is shown once, immediately after you create the first administrator. It is `fo_`-prefixed, and Fanout stores only its hash. +An administrator can issue a replacement in **Connect telemetry → Ingest token** in the account menu, or +with `POST /api/settings/ingest/token/rotate`. Save the new token when it is +shown. Rotation invalidates the old token immediately and cuts off existing +exporters until you update their credentials. + Send it as a bearer token; this is the only accepted ingest credential form: ```text @@ -43,6 +48,25 @@ proxy terminates TLS. A general OTLP endpoint is a base URL; signal-specific variables such as `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` must include their path (`/v1/traces`, `/v1/metrics` or `/v1/logs`). +OTLP/HTTP requires `Content-Type: application/x-protobuf`. JSON payloads return +HTTP 415 after authentication. The JavaScript `*-otlp-http` exporter packages +send JSON. Choose `@opentelemetry/exporter-trace-otlp-proto` for traces and the +matching `*-otlp-proto` packages for metrics and logs. Setting a protocol variable +does not change an explicitly constructed JSON exporter. + +## Common SDKs + +Use the endpoint and bearer header above for each SDK. Select the transport +supported by the exporter you install. + +| SDK | Protocol and environment notes | +|---|---| +| [JavaScript](https://opentelemetry.io/docs/languages/js/exporters/) | Use the `*-otlp-proto` packages for HTTP protobuf, or `*-otlp-grpc` in Node.js. For SDK-managed exporter selection, set `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`. | +| [Python](https://opentelemetry.io/docs/languages/python/exporters/) | Install the HTTP protobuf or gRPC exporter. For automatic instrumentation, select `http/protobuf` or `grpc` with `OTEL_EXPORTER_OTLP_PROTOCOL`. | +| [Go](https://opentelemetry.io/docs/languages/go/exporters/) | Import `otlptracehttp` for protobuf HTTP or `otlptracegrpc` for gRPC, and the matching metric/log packages. These read endpoint and header environment variables; the imported package selects the transport. | +| [Java](https://opentelemetry.io/docs/languages/java/configuration/) | With SDK autoconfiguration or the Java agent, set `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf` or `grpc`, plus endpoint and headers. | +| [.NET](https://opentelemetry.io/docs/languages/dotnet/exporters/) | Use the OTLP exporter with `HttpProtobuf` or `Grpc`. Configure endpoint and headers through exporter options or supported OTLP environment variables. | + ## Configure a Collector ```yaml diff --git a/site/src/content/docs/docs/guides/alerts.mdx b/site/src/content/docs/docs/guides/alerts.mdx index 543f1f797..d12b8828f 100644 --- a/site/src/content/docs/docs/guides/alerts.mdx +++ b/site/src/content/docs/docs/guides/alerts.mdx @@ -12,21 +12,33 @@ 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. -Manage rules through the HTTP API using an operator or administrator session. -The browser client has no alert-rule editor. +## Create and manage a rule -| Endpoint | Does | -|---|---| -| `GET /api/alerting/alerts` | Current alert state | -| `GET /api/alerting/summary` | Counts by state | -| `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 | +Open **Alerts** in the sidebar, then choose **New rule**. Enter a name and +expression, plus an optional description and webhook URL. Without a webhook +URL, the rule records alerts but delivers nothing. Leave **Service** empty to +evaluate every service, or select one service. Choose **Start from a template** +for an example expression, then set the timers and save. + +The new-rule form starts enabled, with **Hold for (s)** 60, **Cooldown (s)** +300 and **Repeat every (s)** 3600. **Notify when resolved** starts off. The name, +description, service, expression and webhook fields start empty. + +Use the **Enabled** toggle to pause or resume a rule. The rule's actions menu +has **Edit**, **Test against current data** and **Delete**. Testing evaluates +the saved expression without changing alert state or sending a webhook. +Deleting removes the rule and its alert history. -Reading takes `telemetry:read`; creating and replacing takes `alerts:manage`, -which starts at the `operator` role. See [roles](/docs/reference/roles). +Choose **Open in Explore** to chart a watched measure from raw telemetry. +Its values can differ from the rule's rollups. Explore shows error rate as a +percent: `0.05` in a rule is `5` there. + +Read current states and delivery results under **History**. +`FANOUT_ALERTS_HISTORY_DAYS` sets resolved-history retention in days (default 7). + +Viewers can read rules and history. Creating, editing, toggling, testing and +deleting require an operator or administrator session; see +[roles](/docs/reference/roles). ## What a rule contains @@ -35,7 +47,8 @@ An expression, an optional service to scope it to, timing, and delivery: | Field | Means | |---|---| | `name` | Required rule name | -| `enabled` | Set `true` to evaluate the rule; omitted means disabled | +| `description` | Optional text explaining the rule | +| `enabled` | Whether to evaluate the rule | | `expression` | The condition, in [CEL](https://cel.dev) | | `service` | Evaluate only for this service; omit for all | | `for_seconds` | How long the condition must hold before firing | @@ -82,7 +95,8 @@ what stops a metric hovering at the threshold from delivering repeatedly. 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. +removes pending alerts and resolves firing alerts, sending a resolve webhook +when `notify_on_resolve` is set. :::caution[The namespace field on a rule is not applied] A rule stores `namespace`, but evaluation combines service rollups across @@ -97,3 +111,58 @@ publication; the evaluation interval and `for_seconds` add further delay. [How storage works](/docs/concepts/storage#rollups-follow-durable-publication) explains the publication horizon and watermark. A shorter evaluation interval does not increase the rollups' time resolution. + +## Webhook payload + +Leave `webhook_template` empty to send this body: + +```text +{"rule":"{{.Rule.Name}}","service":"{{.Alert.Service}}","state":"{{.Alert.State}}","event":"{{.Event}}","value":{{.Alert.Value}}} +``` + +Templates use Go `text/template` and exported field names, with this context: + +| Value | Fields | +|---|---| +| `.Rule` | `ID`, `Name`, `Description`, `Enabled`, `Service`, `Namespace`, `Expression`, `ForSeconds`, `CooldownS`, `RepeatIntervalS`, `WebhookURL`, `WebhookHeaders`, `WebhookTemplate`, `NotifyOnResolve`, `CreatedAt`, `UpdatedAt` | +| `.Alert` | `ID`, `RuleID`, `Service`, `State`, `Value`, `FiredAt`, `ResolvedAt`, `RepeatedAt`, `LastEvaluatedAt`, `LastDeliveryStatus`, `LastDeliveryAt`, `CreatedAt` | +| `.Event` | `firing`, `reminder` or `resolved` | +| `.Env` | `ErrorRate`, `P50`, `P95`, `Throughput`, `LogCount`, `ZScore`, `HealthScore`, `ErrorRateDelta`, `P95Delta`, `ThroughputDelta`, `Service` | +| `.Time` | Delivery context time as a Go `time.Time` | + +`.Alert.Value` is the first variable the expression reads, at the last +evaluation. Timestamp fields on `.Rule` and `.Alert` are strings. + +For a Slack incoming webhook, set its URL and use this template: + +```text +{"text":{{printf "%q" (printf "%s: %s on %s (value %g)" .Event .Rule.Name .Alert.Service .Alert.Value)}}} +``` + +This uses the built-in `printf` function; no JSON template helper is registered. +`text/template` does not automatically escape values for JSON. With this example, +use names without control characters other than tabs and line breaks. + +Fanout sends a POST with `Content-Type: application/json` unless custom headers +override it. Each attempt has a 10-second total timeout and a 5-second response +header timeout. Delivery makes up to three attempts, waiting 2 then 4 seconds +before retries; 4xx responses are not retried. + +## Use the HTTP API + +The browser uses these routes. Reads require `telemetry:read`; mutations and +tests require `alerts:manage`. + +| Endpoint | Does | +|---|---| +| `GET /api/alerting/alerts` | Current alert state | +| `GET /api/alerting/summary` | Counts by state | +| `GET /api/alerting/rules` | List rules | +| `POST /api/alerting/rules` | Create and compile a rule | +| `PUT /api/alerting/rules/:id` | Replace a rule and check any nonempty expression | +| `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 | + +When creating through HTTP, omitted booleans are false, timers are zero and +optional strings are empty. In particular, omitted `enabled` means disabled. +These API defaults differ from the new-rule form above. diff --git a/site/src/content/docs/docs/guides/backup-and-restore.mdx b/site/src/content/docs/docs/guides/backup-and-restore.mdx index b5160c089..1b2a94969 100644 --- a/site/src/content/docs/docs/guides/backup-and-restore.mdx +++ b/site/src/content/docs/docs/guides/backup-and-restore.mdx @@ -44,15 +44,7 @@ capture related files from different moments. ## Upgrading -1. Read the release notes and pin the target tag. -2. Take a backup, and verify it. -3. Stop Fanout, replace only the binary or image, keep the data directory. -4. Start, then check `/readyz`, sign-in, both OTLP transports, and a few - representative queries. - -Migrations run forward at startup. A rollback to the previous binary after they -have run is not assumed safe. Restore the pre-upgrade backup with the previous -version instead. +Follow [Upgrade](/docs/guides/upgrade) for release checks, format changes and rollback. ## Never delete an account from the control database diff --git a/site/src/content/docs/docs/guides/chat.mdx b/site/src/content/docs/docs/guides/chat.mdx new file mode 100644 index 000000000..cd79329e9 --- /dev/null +++ b/site/src/content/docs/docs/guides/chat.mdx @@ -0,0 +1,55 @@ +--- +title: Use the built-in agent +description: Configure a model provider and investigate telemetry in chat. +summary: Provider setup, saved threads, search and panel explanations. +read_when: + - You want to investigate telemetry with the built-in agent. +status: preview +--- + +## Enable a provider + +Select one provider and supply its key before starting Fanout: + +```sh +export FANOUT_AI_PROVIDER=anthropic +export ANTHROPIC_API_KEY_FILE=/run/secrets/anthropic_api_key +``` + +For OpenAI, use `FANOUT_AI_PROVIDER=openai` and `OPENAI_API_KEY_FILE` instead. +The selected provider requires its key. An empty provider disables chat. +Restart after changing settings. + +The default models are `claude-sonnet-5-5` for Anthropic and `gpt-6.1-sol` for +OpenAI. Override with `FANOUT_AI_MODEL`. `ANTHROPIC_BASE_URL` and +`OPENAI_BASE_URL` select a gateway or alternate endpoint. See +[AI settings](/docs/reference/configuration/ai) for endpoint and model requirements. + +Requests send conversation and query evidence to the configured provider and +can incur provider charges. Set usage budgets with that provider or your gateway. +Every built-in role has `agent:run`, including viewers. This permission gates +agent runs and thread APIs. See [roles](/docs/reference/roles). + +## Investigate in a thread + +Choose **New chat** in the navigation rail. Include a service, time window and +symptom, for example: "Why did checkout latency rise in the last hour?" +Continue in that thread to keep the conversation context. The agent can query +telemetry and build [dashboards](/docs/guides/dashboards). + +Threads belong to the signed-in user. Select a saved chat in the rail to reopen +it. Use **Search** at the bottom of the rail, or press **⌘K** (**Ctrl+K** on +other keyboards), to find chats, dashboards and services. A service result +starts an investigation for that service. + +Open a chat's menu to **Rename** it or **Delete** it. Confirm deletion in the +dialog. Renaming accepts a nonempty title of up to 120 characters. + +## Explain a panel + +Open a dashboard panel's menu and choose **Explain in chat**. Fanout opens chat +with the panel context. Explanation requests are answer-only; the agent can +read evidence and suggest corrections, but cannot save changes during that run. + +Review the evidence before acting. Narrow the service or time window if a run +hits its step limit or five-minute time limit. diff --git a/site/src/content/docs/docs/guides/dashboards.mdx b/site/src/content/docs/docs/guides/dashboards.mdx index fc653bc6d..6204bebe6 100644 --- a/site/src/content/docs/docs/guides/dashboards.mdx +++ b/site/src/content/docs/docs/guides/dashboards.mdx @@ -1,13 +1,37 @@ --- title: Build and refine dashboards -description: Build a telemetry dashboard from chat, refine its panels, and share the current view. -summary: Chat authoring, fifteen panel types, variables, comparison, view links, saved versions and keyboard controls. +description: Build dashboards with the panel editor or chat, refine panels, and share the current view. +summary: Panel editing, chat authoring, fifteen panel types, variables, comparison, view links and saved versions. read_when: - - You want to build or change a dashboard from chat. + - You want to build or change a dashboard with or without chat. - You want to inspect a failed panel, share a view or restore a saved version. status: preview --- +## Build without chat + +Choose **New dashboard** in the sidebar or on the empty dashboards page. +Enter a dashboard name, then use the panel editor's **Query**, **Builder** or +**SQL** tab. Run the query and select **Create dashboard** to save it with its +first panel. Query and Builder offer compatible visualizations; SQL starts +with a table. + +On an existing dashboard, choose **Edit layout**, then **Add panel**. To change +a panel, open its menu and choose **Edit panel**. The editor uses the dashboard's +current time window and variables. Set the panel title, run the query and select +**Add panel** or **Save panel**. A new panel needs data before saving; an edited +panel can save after a successful empty result. + +These controls work without an AI provider. See +[Explore](/docs/guides/explore) for the query tabs. + +Delete an owned dashboard through `DELETE /api/dashboards/:id` with the +`Fanout-Confirm-Delete` header set to its ID. A script also needs the request +headers in [Call account APIs from a script](/docs/concepts/authentication#call-account-apis-from-a-script). +The browser has no dashboard delete control. + +## Build from chat + Open chat and describe the system view you need. For example: "Build a dashboard of checkout latency and errors by service." Fanout reads the telemetry schema, previews the panels and saves a dashboard. The save receipt records the saved @@ -18,7 +42,7 @@ To refine the result, name the panel and the change: "On the checkout latency panel, add a warning threshold at 500 ms." Use the receipt's changes and version history to inspect what changed. -## Build, check and refine +### Check and refine Chat needs a configured AI provider. When it is available, you can start in chat or use **Create with AI** on the empty dashboards page. Describe the question, @@ -88,6 +112,8 @@ panel can apply a variable filter when clicked, or open matching logs or exempla traces. Deploy markers and anomaly bands provide context; they do not establish the cause of a change. +## Use guarded SQL + For queries that need it, a panel can use guarded SQL: one read-only `SELECT` over approved telemetry relations, with a required time-window filter. It cannot call edit distances such as `levenshtein` or the Jaro similarities, @@ -113,8 +139,8 @@ another type, so `"200"` reads as the number 200, and they need no cast. A subquery or CTE that projects only the map, such as `WITH s AS (SELECT attributes FROM spans)`, reads values as sent there. Other keys read as sent, and `SELECT *` returns the `attributes` and `resource` maps. -SQL is an authoring escape hatch. **Spec** is a read-only inspection view; -there is no SQL or chart-style editor there. +**Spec** is a read-only inspection view. Use the panel menu's **Edit panel** +to change its query or SQL and choose a compatible visualization. ### Discover resources observed in the window diff --git a/site/src/content/docs/docs/guides/deploy.mdx b/site/src/content/docs/docs/guides/deploy.mdx new file mode 100644 index 000000000..f3ab22b7e --- /dev/null +++ b/site/src/content/docs/docs/guides/deploy.mdx @@ -0,0 +1,101 @@ +--- +title: Run with Compose or systemd +description: Run a persistent Fanout instance under a process supervisor. +summary: A Compose service and a systemd unit with mounted secrets and persistent data. +read_when: + - You need Fanout to restart after an exit or host reboot. +status: preview +--- + +## Run with Compose + +Save this as `docker-compose.yml`. Provision an auth code secret of at least +32 characters through your secret manager. Set `AUTH_SECRET_PATH` to its mounted +source file, readable by UID/GID 65532. + +```yaml +services: + fanout: + image: ghcr.io/labstack/fanout:2026.11.0-alpha + container_name: fanout + restart: unless-stopped + ports: + - "127.0.0.1:7520:7520" + volumes: + - fanout-data:/var/lib/fanout/data + environment: + FANOUT_AUTH_CODE_SECRET_FILE: /run/secrets/auth_code + secrets: + - auth_code + healthcheck: + test: ["CMD", "fanout", "healthcheck"] + interval: 30s + timeout: 3s + start_period: 40s + retries: 3 +secrets: + auth_code: + file: ${AUTH_SECRET_PATH} +volumes: + fanout-data: +``` + +Start with `docker compose up -d`. Read the setup URL with +`docker compose logs fanout`, then complete [first boot](/docs/get-started/first-boot). +The image listens on `:7520` and keeps data in `/var/lib/fanout/data`. +The port mapping above exposes it only on the host's loopback interface. +Use [TLS](/docs/guides/tls) and a restricted network route for remote clients. + +The ingest token is issued during administrator setup and stored in control +state. There is no ingest-token environment setting or `_FILE` form. Give the +issued token to your exporters through their secret delivery mechanism; see +[send telemetry](/docs/get-started/send-telemetry). + +A named volume preserves data across container replacement. Do not remove it +when upgrading. The healthcheck marks an unhealthy container; Docker does not +restart it solely because that check fails. + +## Run with systemd + +Install the binary as `/usr/local/bin/fanout`. Create a dedicated system user +and group named `fanout`, with no interactive login. Store the auth secret +at `/etc/fanout/auth_code`, readable only by root. systemd passes it to the +service as a credential. + +Save this as `/etc/systemd/system/fanout.service`: + +```ini +[Unit] +Description=Fanout +After=network.target + +[Service] +Type=simple +User=fanout +Group=fanout +StateDirectory=fanout +WorkingDirectory=/var/lib/fanout +Environment=FANOUT_ADDR=127.0.0.1:7520 +Environment=FANOUT_DATA_DIR=/var/lib/fanout/data +LoadCredential=fanout_auth_code:/etc/fanout/auth_code +Environment=FANOUT_AUTH_CODE_SECRET_FILE=%d/fanout_auth_code +ExecStart=/usr/local/bin/fanout +Restart=on-failure +RestartSec=5s + +[Install] +WantedBy=multi-user.target +``` + +`StateDirectory` creates `/var/lib/fanout` for the service user. Fanout creates +its data subdirectory. Load and start the unit: + +```sh +sudo systemctl daemon-reload +sudo systemctl enable --now fanout +sudo journalctl -u fanout +``` + +Use the setup URL from the journal. Restrict journal access because that URL +is an administrator credential. Check `http://127.0.0.1:7520/readyz` after startup. +See [hardening](/docs/guides/hardening) before exposing the listener. diff --git a/site/src/content/docs/docs/guides/explore.mdx b/site/src/content/docs/docs/guides/explore.mdx index 09ab4b0e1..12bafa572 100644 --- a/site/src/content/docs/docs/guides/explore.mdx +++ b/site/src/content/docs/docs/guides/explore.mdx @@ -35,6 +35,32 @@ logs where service:checkout severity>=warn Use service names present in your telemetry. See the [FanQL reference](/docs/reference/fanql) for syntax, fields and functions. +## Use the Builder tab + +Select **Builder** to choose a source, measures, filters, grouping fields, +time buckets and a row limit. **Query** and **Builder** edit the same FanQL +query. Builder changes appear under **As FanQL**. Select **Run** to execute. +Complex filters and measures remain as chips; edit them in **Query**. +If the Query tab says the text is read-only, keep editing in Builder. + +## Use the SQL tab + +Select **SQL** to write a separate statement. Switching tabs does not convert +FanQL to SQL. Run one read-only `SELECT` with a time filter, for example: + +```sql +SELECT service, count(*) AS spans +FROM spans +WHERE $__window(start_time) +GROUP BY service +``` + +Explore shows SQL results as a table. See the +[guarded SQL rules](/docs/guides/dashboards#use-guarded-sql) and +[rollup relations](/docs/reference/mcp#panel-sql-relations) for limits and +rollup columns. The `get_telemetry_schema` MCP tool lists the columns of +`spans`, `logs` and `metrics`. + ## Read diagnostics When a query has problems, the editor marks the affected text and lists messages diff --git a/site/src/content/docs/docs/guides/hardening.mdx b/site/src/content/docs/docs/guides/hardening.mdx new file mode 100644 index 000000000..c556f69e1 --- /dev/null +++ b/site/src/content/docs/docs/guides/hardening.mdx @@ -0,0 +1,60 @@ +--- +title: Harden an instance +description: Restrict network access and protect credentials on a Fanout instance. +summary: TLS, operations access, account policy and secret delivery. +read_when: + - You are preparing an instance for shared or remote access. +status: preview +--- + +## Protect the listener + +Fanout serves plaintext by default. Configure `FANOUT_TLS_CERT_FILE` and +`FANOUT_TLS_KEY_FILE` together, or terminate TLS at a reverse proxy. Direct TLS +uses TLS 1.3. Set `FANOUT_PUBLIC_URL` to the stable external HTTPS origin. +See [TLS](/docs/guides/tls) for HTTP/2 and proxy setup. + +Native installs bind `127.0.0.1:7520`; the image binds `:7520`. Restrict host +port publishing and firewall rules. Browser, API, MCP and both OTLP transports +share that listener. Follow the [network surface](/docs/reference/endpoints#restrict-the-network-surface) +notes to keep ingest private and route public SDKs through a gateway. + +Trust forwarded client addresses only from your proxy networks with +`FANOUT_TRUSTED_PROXY_CIDRS`. Never use `0.0.0.0/0`. + +## Restrict operations access + +Keep `/metrics` private or set `FANOUT_METRICS_TOKEN` for authenticated scrapes. +An administrator browser session can also read it. Leave +`FANOUT_METRICS_PUBLIC=false`; enabling it permits unauthenticated scrapes. + +Leave `FANOUT_PPROF_ENABLED=false` unless profiling is needed. When enabled, +`/debug/pprof/*` still requires `operations:read`, available only to admins. +Profiles can contain memory contents. Health and readiness probes require no +credential. See [endpoints](/docs/reference/endpoints). + +## Choose an account policy + +Keep local self-signup off unless any verified email address should receive a +viewer account. `FANOUT_SELF_SIGNUP=true` requires SMTP. Viewers can query all +telemetry and run the built-in agent, which can incur provider charges. + +Each instance is one trust domain. Namespaces filter queries and do not isolate +access. Run separate instances for mutually untrusted teams. Dashboards and +chat threads belong to their owners. See [authentication](/docs/concepts/authentication) +for OIDC eligibility, suspension and access revocation. + +## Deliver secrets + +Supply secret settings through runtime injection or managed mounts with their +`_FILE` variables. Set only one nonempty form. Restrict mount access at the +platform layer; Fanout does not check file modes. See +[secret settings](/docs/reference/configuration#secrets). + +Keep the setup URL, login links, session cookies and ingest token out of public +logs and tickets. Restrict access to startup logs until setup is complete. +Use the [ingest rotation procedure](/docs/get-started/send-telemetry#the-ingest-token) +if the ingest token is lost or exposed. + +Report vulnerabilities privately through +[SECURITY.md](https://github.com/labstack/fanout/blob/main/SECURITY.md). diff --git a/site/src/content/docs/docs/guides/mcp.mdx b/site/src/content/docs/docs/guides/mcp.mdx index ad226c324..1a0960e76 100644 --- a/site/src/content/docs/docs/guides/mcp.mdx +++ b/site/src/content/docs/docs/guides/mcp.mdx @@ -62,14 +62,31 @@ claude mcp add --transport http fanout https://fanout.example.com/mcp Use your instance's public URL, then authorize the connection in your browser. +### Codex + +Codex is a verified client. Add the Streamable HTTP server, then sign in: + +```sh +codex mcp add fanout --url https://fanout.example.com/mcp +codex mcp login fanout +``` + +Complete authorization in your browser. Use `codex mcp list` to check the +registration. See the [official Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=cli). + +Other MCP clients are untested. They need Streamable HTTP and Fanout's OAuth +flow; use their own setup instructions. + ### Disconnect an agent -Open **Settings → Connected agents**, find the agent, and choose **Disconnect**. +Open **Connect telemetry → Connected agents** in the account menu, find the agent, and choose **Disconnect**. Confirm to revoke its access immediately. Your other agents and browser session stay connected. To reconnect, authorize that agent again in your browser. -Administrators can still revoke all of a user's access, including browser -sessions and OAuth tokens. +The API equivalents are `GET /api/auth/oauth/connections` and +`POST /api/auth/oauth/connections/{id}/revoke`. Both require a browser session. +Administrators can revoke all of a user's browser sessions and OAuth tokens +with `POST /api/users/{id}/access/revoke`. ## Protocol diff --git a/site/src/content/docs/docs/guides/troubleshooting.mdx b/site/src/content/docs/docs/guides/troubleshooting.mdx index dd2266c58..3e265d792 100644 --- a/site/src/content/docs/docs/guides/troubleshooting.mdx +++ b/site/src/content/docs/docs/guides/troubleshooting.mdx @@ -119,6 +119,26 @@ For OTLP/HTTP, set the exporter protocol to `http/protobuf` and give it the base endpoint, `http://fanout:7520`. Exporters derive `/v1/traces`, `/v1/metrics` and `/v1/logs` from it themselves. +The raw token is shown once after setup or rotation. If it is lost, an +administrator can issue a replacement in **Connect telemetry → Ingest token** in the account menu, or +with `POST /api/settings/ingest/token/rotate`. Save the new token when it is +shown. Rotation invalidates the old token immediately and cuts off existing +exporters until you update their credentials. + +### HTTP 415: unsupported media type + +OTLP/HTTP requires `Content-Type: application/x-protobuf`; JSON returns 415. +JavaScript `*-otlp-http` packages send JSON. Use the `*-otlp-proto` packages, +such as `@opentelemetry/exporter-trace-otlp-proto`, or a gRPC exporter in Node.js. +See [Common SDKs](/docs/get-started/send-telemetry#common-sdks) for language setup. + +### HTTP 429 or gRPC RESOURCE_EXHAUSTED + +Fanout throttles whole exports under ingest pressure. Enable exporter retries +and honor HTTP `Retry-After` or gRPC `RetryInfo`. Check disk space, compaction +backlog and query pressure. See [ingest admission](/docs/concepts/storage#rollups-follow-durable-publication) +for thresholds and metrics. + ## Someone cannot sign in and SMTP is not configured SMTP is optional. Creating a local user without it succeeds and reports @@ -128,13 +148,15 @@ mints a link directly: ```sh fanout login-link user@example.com +# For Docker: +docker exec fanout 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 returns an error. See -[authentication operations](https://github.com/labstack/fanout/blob/main/docs/authentication.md#adding-local-users-without-smtp) +[account recovery](/docs/concepts/authentication#recover-local-sign-in) for invitation responses and account recovery. :::caution[Preserve the account] diff --git a/site/src/content/docs/docs/guides/upgrade.mdx b/site/src/content/docs/docs/guides/upgrade.mdx new file mode 100644 index 000000000..d12d01b2e --- /dev/null +++ b/site/src/content/docs/docs/guides/upgrade.mdx @@ -0,0 +1,44 @@ +--- +title: Upgrade +description: Replace a Fanout release and handle storage format changes. +summary: Back up first, retain control state, and follow the target release notes. +read_when: + - You are upgrading an existing instance. +status: preview +--- + +## Upgrade an instance + +1. Read the target [GitHub Release](https://github.com/labstack/fanout/releases) + and pin its binary or image tag. Check for batch-format and API changes. +2. Take and verify a [cold backup](/docs/guides/backup-and-restore). +3. Stop Fanout and wait for it to exit. +4. Replace the binary or image. Keep the data directory unless the release + requires the format-change procedure below. +5. Start Fanout. Check `/readyz`, sign-in, configured OTLP transports and + representative queries. + +Pending control SQLite migrations run forward at startup. A rollback after +migration is not assumed safe. Restore the complete pre-upgrade backup with +the previous binary when rollback is required. + +## When a release changes the batch format + +[v2026.11.0-alpha](https://github.com/labstack/fanout/releases/tag/v2026.11.0-alpha) +requires batch format 5 and cannot read format 4. For that upgrade: + +1. Stop Fanout and take a complete cold backup. +2. Move `telemetry/` and `query/` out of the data directory. Keep them together + for recovery with the previous version. +3. Keep `control/` in place. It preserves users, dashboards, alert rules and + the ingest token. +4. Install the target binary or image and start Fanout with the same data + directory setting. +5. Verify readiness and sign-in, then send new telemetry and check a query. + +Old telemetry is unavailable in the upgraded instance. Query state rebuilds +from the new telemetry. Do not copy unsupported batches back into it. +See [storage](/docs/concepts/storage) for the current format contract. + +This release also renames API and MCP contracts without aliases. Update scripts +and clients using the release notes and [HTTP routes](/docs/reference/api). diff --git a/site/src/content/docs/docs/help.mdx b/site/src/content/docs/docs/help.mdx new file mode 100644 index 000000000..225c21c6f --- /dev/null +++ b/site/src/content/docs/docs/help.mdx @@ -0,0 +1,32 @@ +--- +title: Get help and contribute +description: Find setup help, report a defect or contribute a change. +summary: Support channels, contribution steps and private security reporting. +read_when: + - You need help or want to contribute. +status: shipped +--- + +## Get help + +Use [GitHub Discussions](https://github.com/labstack/fanout/discussions) for setup +questions and deployment advice. Open an [issue](https://github.com/labstack/fanout/issues) +for a reproducible defect or feature request. Fanout is community-supported; +see [SUPPORT.md](https://github.com/labstack/fanout/blob/main/SUPPORT.md). + +Include the version or image digest, operating system or container runtime, +configuration with secrets removed, and a small relevant log excerpt. Exclude +credentials, login links, session cookies, private telemetry and production +host details. + +## Contribute + +Follow [CONTRIBUTING.md](https://github.com/labstack/fanout/blob/main/CONTRIBUTING.md) +for tools, setup, repository conventions and checks. Run `just check` and +`just test-race` before opening a pull request. First-time contributors must +sign the contributor license agreement before a change can merge. + +## Report a vulnerability + +Follow [SECURITY.md](https://github.com/labstack/fanout/blob/main/SECURITY.md) +for private reporting. Do not open a public issue for a vulnerability. diff --git a/site/src/content/docs/docs/index.mdx b/site/src/content/docs/docs/index.mdx index 6c544216e..8f573d67f 100644 --- a/site/src/content/docs/docs/index.mdx +++ b/site/src/content/docs/docs/index.mdx @@ -20,27 +20,37 @@ Send OpenTelemetry to one binary. Investigate with Fanout's built-in agent, or c - [Install](/docs/get-started/install) - [First boot](/docs/get-started/first-boot) - [Send your first telemetry](/docs/get-started/send-telemetry) +- [Get help and contribute](/docs/help) -- [Set up alerts](/docs/guides/alerts) +- [Use the built-in agent](/docs/guides/chat) - [Query with Explore](/docs/guides/explore) - [Build and refine dashboards](/docs/guides/dashboards) +- [Set up alerts](/docs/guides/alerts) - [Connect an agent over MCP](/docs/guides/mcp) +- [Run with Compose or systemd](/docs/guides/deploy) - [Terminate TLS](/docs/guides/tls) -- [Tune retention](/docs/guides/retention) +- [Upgrade](/docs/guides/upgrade) +- [Harden an instance](/docs/guides/hardening) - [Back up and restore](/docs/guides/backup-and-restore) +- [Tune retention](/docs/guides/retention) - [Troubleshoot](/docs/guides/troubleshooting) - [Configuration](/docs/reference/configuration) +- [CLI](/docs/reference/cli) - [HTTP routes](/docs/reference/api) - [MCP tools](/docs/reference/mcp) +- [FanQL](/docs/reference/fanql) +- [Alert expressions](/docs/reference/alert-expressions) - [Roles](/docs/reference/roles) - [Endpoints](/docs/reference/endpoints) +- [Data layout](/docs/reference/data-layout) +- [Shipped vs planned](/docs/reference/capabilities) @@ -48,6 +58,8 @@ Send OpenTelemetry to one binary. Investigate with Fanout's built-in agent, or c - [Why one binary](/docs/concepts/architecture) - [How storage works](/docs/concepts/storage) - [Authentication modes](/docs/concepts/authentication) +- [Insights and anomalies](/docs/concepts/insights) +- [How Fanout compares](/docs/concepts/comparison) - [Performance](/docs/concepts/performance) diff --git a/site/src/content/docs/docs/reference/api.mdx b/site/src/content/docs/docs/reference/api.mdx index 386e96644..dce248f61 100644 --- a/site/src/content/docs/docs/reference/api.mdx +++ b/site/src/content/docs/docs/reference/api.mdx @@ -39,8 +39,8 @@ The `/api/*` routes serve the browser client and can change without migration paths. [MCP](/docs/guides/mcp) is the agent interface. OTLP ingest and [operational endpoints](/docs/reference/endpoints) have their own contracts. -Manage alert rules through the [HTTP API](/docs/guides/alerts). Administrators -rotate ingest tokens on **Connect telemetry** or with +Manage alert rules on the [Alerts page](/docs/guides/alerts) or through the HTTP API. +Administrators rotate ingest tokens on **Connect telemetry** or with `POST /api/settings/ingest/token/rotate`. ## Errors diff --git a/site/src/content/docs/docs/reference/capabilities.mdx b/site/src/content/docs/docs/reference/capabilities.mdx index 1c9c93804..9fbe602ff 100644 --- a/site/src/content/docs/docs/reference/capabilities.mdx +++ b/site/src/content/docs/docs/reference/capabilities.mdx @@ -28,12 +28,16 @@ capabilities uses `preview` if any of its contracts remain unsettled. | Parquet storage, trace indexes, and DuckDB analytics | preview | Authoritative local Parquet; rebuildable DuckDB query state. | | Batch format 5 storage | preview | [Typed Parquet attributes and dedicated columns](/docs/concepts/storage); unsupported batch formats prevent startup. | | Browser client | preview | Ships in the binary; preview contracts. | -| Explore | preview | [Run queries, choose visualizations and save dashboard panels](/docs/guides/explore) without an AI provider. | +| Explore | preview | [Query, Builder and SQL tabs](/docs/guides/explore) run queries and save dashboard panels without an AI provider. | +| Logs and Traces search | preview | [Search with FanQL filters](/docs/guides/explore#search-logs-and-traces), inspect results and save panels. | | FanQL | preview | [Text queries](/docs/reference/fanql) with diagnostics and completion; filter-only search on Logs and Traces. | | 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](/docs/guides/dashboards): fifteen panel types, variables, comparison, saved grids and immutable versions with restore. View links retain filters and time; dashboard access remains owner-scoped. | +| Dashboards | preview | [Build with the panel editor or chat](/docs/guides/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. | +| Alerts page | preview | [Create, edit, test, enable and delete rules](/docs/guides/alerts) without chat; rules evaluate on an interval against rollups. | +| Connected agents | preview | List and disconnect your authorized MCP agents on **Connect telemetry**. | +| Ingest token rotation | preview | Administrators rotate the token on **Connect telemetry** or through HTTP; the old token stops working. | +| Insights and anomaly detection | preview | Detect error, latency and volume changes against rollup baselines; report insights, log patterns and a health score. | | 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 account auto-provisioning | preview | Eligible identities receive the configured mapped or default role; the default is viewer. | diff --git a/site/src/content/docs/docs/reference/cli.mdx b/site/src/content/docs/docs/reference/cli.mdx new file mode 100644 index 000000000..7db7fc092 --- /dev/null +++ b/site/src/content/docs/docs/reference/cli.mdx @@ -0,0 +1,72 @@ +--- +title: CLI +description: Commands and flags accepted by the Fanout binary. +summary: Server startup, version output, login links, health probes and offline repair. +read_when: + - You need to run or script a Fanout command. +status: preview +--- + +## Commands and flags + +| Invocation | Behavior | +|---|---| +| `fanout` | Validate environment settings and start the server. | +| `fanout version` | Print the build version to stdout and exit. | +| `fanout --version`, `fanout -v` | Print the build version to stdout and exit. | +| `fanout -h`, `fanout --help` | Print usage to stderr and exit successfully. | +| `fanout login-link ` | Mint a login URL for an existing active local user. | +| `fanout healthcheck [url]` | Probe an explicit URL, or derive `/healthz` from listener settings. | +| `fanout repair verify` | Validate every authoritative telemetry batch without changing it. | +| `fanout repair quarantine --batch ` | Move one confirmed corrupt batch aside. `--batch` is required. | + +These are the complete subcommands and flags. Configuration comes from the +environment, not CLI configuration flags. See [configuration](/docs/reference/configuration). +Version output uses the release version embedded at build time, or `dev` when +no version was embedded. + +## Login links + +Run with the server's environment and data directory: + +```sh +fanout login-link admin@example.com +# For Docker: +docker exec fanout fanout login-link admin@example.com +``` + +The command requires local auth mode, an existing control database and an +active user. It prints one URL to stderr. The URL expires in 15 minutes and +works once. It can run while the server is online. See +[account recovery](/docs/concepts/authentication#recover-local-sign-in). + +## Health probes + +With no URL, `healthcheck` reads only `FANOUT_ADDR` and +`FANOUT_TLS_CERT_FILE`. Unspecified bind hosts become `127.0.0.1`. +A certificate selects HTTPS. Derived probes bypass environment proxies; +HTTPS IP probes trust the configured certificate and verify its first DNS or +IP SAN. Hostname probes use normal verification. + +An explicit URL uses normal proxy and certificate verification. Each probe has +a three-second timeout and succeeds only on HTTP 200. No auth secret is needed. + +## Offline repair + +Stop Fanout and back up telemetry before running repair. Both commands load and +validate the normal environment configuration. Verification reports each +confirmed unreadable batch on stdout. An unsupported format or operational +failure stops verification and does not authorize quarantine. + +Quarantine renames one corrupt batch beside the authoritative set. It refuses +a healthy batch or a batch protected by a compaction marker. Its rows become +unavailable to queries. Preserve the reported destination for recovery, verify +again, then restart. See [batch recovery](/docs/guides/troubleshooting#an-unreadable-telemetry-batch-blocks-startup). + +## Exit status + +| Status | Meaning | +|---|---| +| `0` | Command completed successfully, including help and version. | +| `1` | Configuration or runtime failure, failed login-link creation, failed health probe, or repair failure. Verification finding corrupt batches also exits 1. | +| `2` | Invalid arguments or failure to derive the healthcheck address. | diff --git a/site/src/content/docs/docs/reference/configuration.mdx b/site/src/content/docs/docs/reference/configuration.mdx index 62aaa0559..49cbf2abd 100644 --- a/site/src/content/docs/docs/reference/configuration.mdx +++ b/site/src/content/docs/docs/reference/configuration.mdx @@ -113,7 +113,7 @@ set `FANOUT_DUCKDB_MEMORY` for a guaranteed bound. See | Image tag | Points at | |---|---| | `labstack/fanout:latest` | the newest release | -| `labstack/fanout:2026.10.1-alpha` | that exact release | +| `labstack/fanout:2026.11.0-alpha` | that exact release | | `ghcr.io/labstack/fanout:main` | the tip of `main` | | `ghcr.io/labstack/fanout:sha-` | one specific commit | diff --git a/site/src/content/docs/docs/reference/endpoints.mdx b/site/src/content/docs/docs/reference/endpoints.mdx index fae869ab0..b0ef29b09 100644 --- a/site/src/content/docs/docs/reference/endpoints.mdx +++ b/site/src/content/docs/docs/reference/endpoints.mdx @@ -56,7 +56,9 @@ behind `operations:read` rather than `telemetry:read`. | Path | Purpose | |---|---| -| `/mcp` | The MCP endpoint external agents connect to | +| `/mcp` | External MCP clients; OAuth access token | +| `/api/mcp` | Browser MCP; browser session and `telemetry:read` | +| `/api/auth/oauth/*` | Browser authorization and connected-agent management; browser session | | `/.well-known/*` | OAuth discovery for MCP clients | | `/oauth/register`, `/oauth/token` | OAuth client registration and token issue | @@ -79,6 +81,24 @@ protobuf and gzip, with a 64 MiB decompressed body limit. See [send your first telemetry](/docs/get-started/send-telemetry). +## Restrict the network surface + +Keep the backend listener private when a proxy serves the browser publicly. +To keep ingest private, deny `/v1`, `/v1/*` and +`/opentelemetry.proto.collector.*` at the public proxy. Verify both OTLP +transports from outside the private network. + +Never ship the shared ingest token in browser or mobile code. Send public-client +telemetry through a Collector or gateway you control. That gateway handles +client authentication, rate limits and privacy controls, then forwards to +private Fanout. Propagate `traceparent` and `tracestate` to correlate backend +requests. + +For gRPC, forward HTTP/2 to the backend: h2c for plaintext or HTTP/2 over TLS. +Set `FANOUT_PUBLIC_URL` to the public HTTPS origin. Preserve the public Host +header for MCP and trust forwarded client IPs only from configured proxy CIDRs. +See [TLS](/docs/guides/tls) and [hardening](/docs/guides/hardening). + ## What to alert on The endpoints tell you the instance is up; the metrics tell you whether it is diff --git a/site/src/pages/llms-full.txt.ts b/site/src/pages/llms-full.txt.ts index 4467ed9fc..41836f8e8 100644 --- a/site/src/pages/llms-full.txt.ts +++ b/site/src/pages/llms-full.txt.ts @@ -10,7 +10,7 @@ import { toPlainMarkdown } from "../lib/markdown"; // The landing page and docs home share the "index" group, listed explicitly // so neither is dropped from a document headed "complete documentation". const ROOT = "index"; -const ORDER = [ROOT, "get-started", "guides", "reference", "concepts", "privacy"]; +const ORDER = [ROOT, "get-started", "guides", "reference", "concepts", "help", "privacy"]; function groupOf(id: string): string { if (id === "docs") return ROOT; diff --git a/site/src/pages/llms.txt.ts b/site/src/pages/llms.txt.ts index 2fd3d9586..d428ebc7e 100644 --- a/site/src/pages/llms.txt.ts +++ b/site/src/pages/llms.txt.ts @@ -12,7 +12,7 @@ import { getCollection } from "astro:content"; // The landing page and docs home share the "index" group, listed explicitly // so neither is dropped from an index whose heading promises every one. const ROOT = "index"; -const ORDER = [ROOT, "get-started", "guides", "reference", "concepts", "privacy"]; +const ORDER = [ROOT, "get-started", "guides", "reference", "concepts", "help", "privacy"]; function groupOf(id: string): string { if (id === "docs") return ROOT; @@ -25,6 +25,7 @@ const GROUP_TITLES: Record = { guides: "Guides", reference: "Reference", concepts: "Concepts", + help: "Help and contributions", privacy: "Site terms", };