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 793e86f89..0bcf9cb32 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, @@ -59,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. @@ -211,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. @@ -219,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 24531fc63..7e3cff695 100644 --- a/site/astro.config.mjs +++ b/site/astro.config.mjs @@ -82,15 +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: "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: "Build and refine dashboards", slug: "docs/guides/dashboards" }, + { 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" }, @@ -110,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" }, @@ -126,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/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. + +## 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 +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/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 e5a891a4e..8f573d67f 100644 --- a/site/src/content/docs/docs/index.mdx +++ b/site/src/content/docs/docs/index.mdx @@ -20,26 +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) @@ -47,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 a9db55097..9fbe602ff 100644 --- a/site/src/content/docs/docs/reference/capabilities.mdx +++ b/site/src/content/docs/docs/reference/capabilities.mdx @@ -26,11 +26,18 @@ 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 | [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", };