Skip to content
Back to search

fanout

Single-binary observability platform. Ingest OTLP, store as Parquet, query with DuckDB.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/labstack/pitot with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/labstack/pitot'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/labstack--fanout/badge.svg)](/listings/labstack--fanout)

HTML

<a href="/listings/labstack--fanout"><img src="/api/listings/labstack--fanout/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Docker

docker run --name fanout -p 7520:7520 \
  -v fanout-data:/var/lib/fanout/data \
  -e FANOUT_AUTH_CODE_SECRET=$(openssl rand -hex 32) \
  labstack/fanout:latest

Open the one-time setup URL printed by the container and create the first administrator. Fanout displays the ingest token exactly once; save it with your collector secrets. For later sign-in without SMTP, mint a 15-minute, single-use link against the running container's control database:

docker exec fanout fanout login-link admin@example.com

The UI, API, MCP, and both OTLP transports share port `7520`. See [installation](https://fanout.run/start/install) for image defaults and bind-mount ownership, and [first boot](https://fanout.run/start/first-boot) for setup and SMTP login.

Native binary

Install a checksum-verified release for Linux or macOS, amd64 or arm64:

curl -fsSL https://raw.githubusercontent.com/labstack/fanout/main/scripts/install.sh | sh
export FANOUT_AUTH_CODE_SECRET=$(openssl rand -hex 32)
fanout

Set `FANOUT_VERSION=v2026.10.1-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.

Send telemetry

A standard OTLP/HTTP exporter can use the saved ingest token:

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:7520
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer%20$INGEST_TOKEN"

For a Collector on the same private container network, the forwarding side is:

exporters:
  otlp_http/fanout:
    endpoint: http://fanout:7520
    headers:
      Authorization: "Bearer ${env:INGEST_TOKEN}"

service:
  pipelines:
    traces:  { receivers: [otlp], exporters: [otlp_http/fanout] }
    metrics: { receivers: [otlp], exporters: [otlp_http/fanout] }
    logs:    { receivers: [otlp], exporters: [otlp_http/fanout] }

Use an existing `otlp` receiver, set `INGEST_TOKEN`, and replace `fanout` with the Collector's reachable private hostname. OTLP/gRPC uses `localhost:7520` locally; see [send telemetry](https://fanout.run/start/send-telemetry) for TLS and HTTP/2 setup.

Enable chat

Select `FANOUT_AI_PROVIDER=anthropic` and inject `ANTHROPIC_API_KEY`, or select `FANOUT_AI_PROVIDER=openai` and inject `OPENAI_API_KEY`, then restart Fanout; the selected provider requires its key at startup. With no provider, chat is disabled and the other features still work. See [AI settings](https://fanout.run/reference/settings/ai).

Connect an MCP client

Set `FANOUT_PUBLIC_URL` to your stable, externally reachable HTTPS origin, then point a remote MCP client at that origin's `/mcp` endpoint. The client discovers and registers through OAuth; you authorize its scopes in the browser. The client must support MCP protocol `2026-07-28` over stateless Streamable HTTP; older versions and the `initialize` handshake are unsupported. See [connect over MCP](https://fanout.run/guides/connect-over-mcp) for setup and permissions.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 252 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Pitot
  2. Pitot (pronounced **PEE-toh**).
  3. **Observability your agents can operate.** Send OpenTelemetry to one binary, then investigate with
  4. Pitot's built-in agent or connect your own over MCP.
  5. [![CI](https://github.com/labstack/pitot/actions/workflows/ci.yml/badge.svg)](https://github.com/labstack/pitot/actions/workflows/ci.yml)
  6. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  7. [![Go Reference](https://pkg.go.dev/badge/github.com/labstack/pitot.svg)](https://pkg.go.dev/github.com/labstack/pitot)
  8. <a href="https://pitot.dev">
  9. <picture>
  10. <source media="(prefers-color-scheme: dark)" srcset="site/src/assets/landing/overview-dark.png">
  11. <img src="site/src/assets/landing/overview-light.png" alt="Pitot Store overview - last hour: request rate, error rate, p95 latency and error logs, with request rate, error rate and p95 latency by service.">
  12. </picture>
  13. </a>
  14. *Current Pitot interface with deterministic offline sample telemetry.*
  15. Pitot keeps OpenTelemetry traces, logs, and metrics in one binary and one data directory, with no
  16. external storage services to operate. Pitot is pre-release and changes without migration paths; the browser
  17. client, built-in agent, MCP tools, dashboards, and alerts are preview capabilities
  18. ([status](https://pitot.dev/docs/reference/capabilities)). Start with the
  19. [documentation](https://pitot.dev) or run it below.
  20. - OTLP ingest over gRPC and HTTP, with local Parquet storage and DuckDB analytics.
  21. - Explore and PitotQL for querying telemetry without an AI provider.
  22. - An investigation agent that answers questions about your telemetry in plain language.
  23. - An MCP server for external agents using the same typed query tools.
  24. - Dashboards across traces, logs, and metrics, and alerts on service error rate, latency,
  25. throughput, and log volume.
  26. ## Quick start
  27. ### Docker
  28. ```sh
  29. docker run --name pitot --restart unless-stopped -p 7520:7520 \
  30. -v pitot-data:/var/lib/pitot/data \
  31. -e PITOT_AUTH_CODE_SECRET=$(openssl rand -hex 32) \
  32. labstack/pitot:latest
  33. ```
  34. Open the one-time setup URL printed by the container and create the first administrator. Pitot
  35. displays the ingest token exactly once, unless `PITOT_INGEST_TOKEN` already set it; save it with your collector secrets. For later sign-in
  36. without SMTP, mint a 15-minute, single-use link against the running container's control database:
  37. ```sh
  38. docker exec pitot pitot login-link admin@example.com
  39. ```
  40. The UI, API, MCP, and both OTLP transports share port `7520`. See
  41. [installation](https://pitot.dev/docs/get-started/install) for image defaults and bind-mount ownership, and
  42. [first boot](https://pitot.dev/docs/get-started/first-boot) for setup and SMTP login.
  43. ### Native binary
  44. Install a checksum-verified release for Linux or macOS, amd64 or arm64:
  45. ```sh
  46. curl -fsSL https://raw.githubusercontent.com/labstack/pitot/main/scripts/install.sh | sh
  47. export PITOT_AUTH_CODE_SECRET=$(openssl rand -hex 32)
  48. pitot
  49. ```
  50. Set `PITOT_VERSION` to a [release tag](https://github.com/labstack/pitot/releases), such as `v2026.11.0-alpha`, to pin a release, and `PITOT_PREFIX` to choose the installation
  51. directory. Native installs bind `127.0.0.1:7520`; set `PITOT_ADDR=:7520` for remote access, then
  52. follow the same first-boot setup.
  53. ### Send telemetry
  54. A standard OTLP/HTTP exporter can use the saved ingest token:
  55. ```sh
  56. export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
  57. export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:7520
  58. export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer%20$INGEST_TOKEN"
  59. ```
  60. For a Collector on the same private container network, the forwarding side is:
  61. ```yaml
  62. exporters:
  63. otlp_http/pitot:
  64. endpoint: http://pitot:7520
  65. headers:
  66. Authorization: "Bearer ${env:INGEST_TOKEN}"
  67. service:
  68. pipelines:
  69. traces: { receivers: [otlp], exporters: [otlp_http/pitot] }
  70. metrics: { receivers: [otlp], exporters: [otlp_http/pitot] }
  71. logs: { receivers: [otlp], exporters: [otlp_http/pitot] }
  72. ```
  73. Use an existing `otlp` receiver, set `INGEST_TOKEN`, and replace `pitot` with the Collector's
  74. reachable private hostname. OTLP/gRPC uses `localhost:7520` locally; see [send
  75. telemetry](https://pitot.dev/docs/get-started/send-telemetry) for TLS and HTTP/2 setup.
  76. ### Enable chat
  77. Select `PITOT_AI_PROVIDER=anthropic` and inject `ANTHROPIC_API_KEY`, or select
  78. `PITOT_AI_PROVIDER=openai` and inject `OPENAI_API_KEY`, then restart Pitot; the selected provider
  79. requires its key at startup. With no provider, chat is disabled and the other features still work.
  80. See [AI settings](https://pitot.dev/docs/reference/configuration/ai).
  81. ### Connect an MCP client
  82. Set `PITOT_PUBLIC_URL` to your stable, externally reachable HTTPS origin, then point a remote MCP
  83. client at that origin's `/mcp` endpoint. The client discovers and registers through OAuth; you
  84. authorize its scopes in the browser. Pitot serves MCP `2026-07-28` and, through the `initialize`
  85. handshake, `2025-11-25` and `2025-06-18` over Streamable HTTP. See [connect over
  86. MCP](https://pitot.dev/docs/guides/mcp) for setup and permissions.
  87. ## How it compares
  88. | If you use | Where Pitot differs |
  89. | --- | --- |
  90. | **Grafana with Loki, Tempo, and Mimir** | That stack keeps a service and a query language per signal, plus object storage underneath. Pitot 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. |
  91. | **SigNoz** | Both are OTLP-native and self-hosted. SigNoz composes a collector, ClickHouse, and query services; Pitot compiles ingest, authoritative Parquet storage, indexed trace reads, DuckDB analytics, alerting, and the browser client into one binary. |
  92. | **Jaeger** | Jaeger covers traces and expects a storage backend you run separately. Pitot ingests traces, logs, and metrics into the same store, with nothing else to deploy. |
  93. | **Prometheus with Grafana** | Prometheus pulls metrics and is excellent at them. Pitot accepts pushed OTLP for all three signals and is built around investigating a specific incident rather than maintaining long-range metric series. |
  94. | **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. Pitot is a binary you run, on data that stays on your disk. |
  95. | **An OpenTelemetry Collector piped into ClickHouse** | The same shape, assembled by hand: collector, database, dashboards, and the glue between them. Pitot is that assembly as one program, with an agent and an MCP server already wired to the same query contract. |
  96. Pitot is a single node. It has no clustering, no replication, and no object tier; a deployment that
  97. outgrows one machine's disk and CPU has outgrown Pitot.
  98. ## Architecture
  99. One process contains ingest, storage, query, alerts, the agent, MCP, and the React client. Browser
  100. and agent clients share a typed observability contract.
  101. ![Pitot runtime architecture: OTLP ingest and commit workers publish Parquet; the browser API, agent runtime, and MCP server share queries and dashboards, with DuckDB query state, SQLite control state, anomaly detection, and webhook alerts.](docs/diagrams/architecture.svg)
  102. Parquet holds telemetry, DuckDB query state is rebuildable, and SQLite holds transactional product
  103. state. See [how storage works](https://pitot.dev/docs/concepts/storage) for durable ingest,
  104. indexed reads, and compaction while reads continue.
  105. ![Telemetry durability and query flow: authenticated OTLP rows pass through group admission, parallel commit workers, and durable publication into immutable Parquet batches; indexed trace reads, DuckDB SQL, retention, and compaction use those batches, while service and edge rollups populate rebuildable query state.](docs/diagrams/persistence.svg)
  106. ## Configuration
  107. Configuration is environment-only: built-in defaults followed by nonempty process environment
  108. values, validated before data files or listeners open. Settings are read once at startup; every
  109. change requires a restart.
  110. | Environment variable | Default | Purpose |
  111. | --- | --- | --- |
  112. | `PITOT_ADDR` | `127.0.0.1:7520` | UI, API, MCP, and both OTLP transports |
  113. | `PITOT_DATA_DIR` | `./data` | Parquet, query state, and control SQLite |
  114. | `PITOT_AUTH_MODE` | `local` | Login link or SMTP, or `oidc` |
  115. | `PITOT_AUTH_CODE_SECRET` | — | Required in local mode and for OIDC break-glass links, 32+ characters |
  116. | `PITOT_AI_PROVIDER` | — | Empty disables chat; `anthropic` or `openai` enables it |
  117. | `ANTHROPIC_API_KEY` | — | Required for Anthropic chat |
  118. | `OPENAI_API_KEY` | — | Required for OpenAI chat |
  119. | `PITOT_RETENTION_DAYS` | `30` | Telemetry retention window |
  120. | `PITOT_MCP_ENABLED` | `true` | Serve the MCP endpoint at `/mcp` |
  121. Every secret accepts `<NAME>_FILE` instead of its value; see the [settings
  122. reference](https://pitot.dev/docs/reference/configuration) for validation and [runtime secret
  123. delivery](docs/operations.md#runtime-secret-delivery) for deployment examples.
  124. ### Advanced DuckDB sizing
  125. Pitot sizes DuckDB automatically; measured workloads can override memory, connections, and threads
  126. as described in [DuckDB sizing](https://pitot.dev/docs/reference/configuration#duckdb-sizing).
  127. For TLS, health checks, backups, upgrades, retention, and recovery, see the [operator
  128. runbook](docs/operations.md).
  129. ## Performance
  130. Pitot v2026.11.0-alpha accepted **507,311 mixed OpenTelemetry items/s**
  131. over 306.8 seconds on a Hetzner Cloud ccx33 (8 dedicated vCPUs, 32 GB RAM), with
  132. telemetrygen on a separate ccx33. The ingest run on 6 November 2026 passed every
  133. quality gate. See the [performance methodology](https://pitot.dev/docs/concepts/performance).
  134. [Pitot Bench](https://github.com/labstack/pitot-bench) reproduces the measurement on your hardware.
  135. ## Build from source
  136. - **Go 1.27.3 and a C/C++ toolchain** on native Linux or macOS, amd64 or arm64.
  137. Build with `just build` or `bash scripts/with-duckdb.sh go build ./cmd/pitot`;
  138. the wrapper supplies DuckDB's pinned headers, static libraries, and CGO flags.
  139. The first build needs network access to download the checksum-verified engine.
  140. - **[Bun](https://bun.sh)** — compiles the browser assets
  141. - **Node.js 24.19.0** — runs development helpers and builds the documentation site
  142. - **[just](https://just.systems)** — task runner
  143. - A 32-character **authentication code secret**
  144. ```sh
  145. git clone https://github.com/labstack/pitot.git
  146. cd pitot
  147. just install # browser dependencies and git hooks
  148. just build # browser assets, then the binary
  149. ```
  150. Run it with the minimum configuration:
  151. ```sh
  152. export PITOT_AUTH_CODE_SECRET=$(openssl rand -hex 32) # must be 32+ characters
  153. ./bin/pitot
  154. ```
  155. Open <http://localhost:7520> and follow first-boot setup. SMTP and chat are optional; without SMTP,
  156. run `./bin/pitot login-link admin@example.com` with the same configuration and data directory.
  157. ## Development
  158. Run `just` to list recipes, `just check` for the full gate, `just test` for Go tests, and `just ui`
  159. to rebuild embedded browser assets. See [CONTRIBUTING.md](CONTRIBUTING.md) for environment setup,
  160. generated assets, hooks, and project layout.
  161. ## Releases
  162. Versions are CalVer — `vYYYY.M.N[-alpha|-beta|-rc]`, numbered from 0 within each month across all
  163. maturity suffixes. Pitot is alpha (for example, `v2026.11.0-alpha`); GA has no suffix.
  164. Container tags omit the leading `v`, and every release moves `latest`. Tagged releases publish
  165. identical manifests to Docker Hub (`labstack/pitot`) and GHCR (`ghcr.io/labstack/pitot`); GHCR is
  166. canonical and also carries development images.
  167. | Image tag | Points at |
  168. | --- | --- |
  169. | `labstack/pitot:latest` | the newest release, mirrored on Docker Hub |
  170. | `labstack/pitot:2026.11.0-alpha` | that exact release, mirrored on Docker Hub |
  171. | `ghcr.io/labstack/pitot:latest` | the newest release |
  172. | `ghcr.io/labstack/pitot:2026.11.0-alpha` | that exact release |
  173. | `ghcr.io/labstack/pitot:main` | the tip of `main` |
  174. | `ghcr.io/labstack/pitot:sha-<commit>` | one specific commit |
  175. See [docs/release.md](docs/release.md) for platforms, checksums, provenance, and verification.
  176. ## Contributing
  177. Issues and pull requests are welcome; follow [CONTRIBUTING.md](CONTRIBUTING.md) and run `just check`
  178. and `just test-race` before opening a pull request. Report security issues through
  179. [SECURITY.md](SECURITY.md).
  180. ## Scope
  181. This repository builds Pitot without another repository; LabStack's deployment configuration,
  182. uptime monitoring, and public demo instance are not included. The documentation site in
  183. [`site/`](site) is included, with settings pages generated from the same `internal/config` type the
  184. loader binds and checked by `just check`.
  185. ## License
  186. [Apache-2.0](LICENSE) © LabStack LLC. See [NOTICE](NOTICE) and
  187. [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES) for attribution, and
  188. [TRADEMARK](TRADEMARK.md) for use of the Pitot name and logo.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.