# Pitot

One self-hosted binary for OpenTelemetry. The same Go process accepts OTLP
over gRPC and HTTP, publishes authoritative Parquet batches with persistent
trace indexes, runs embedded DuckDB analytics and rollups, evaluates alert
rules, serves a chat investigator and MCP tools, and hosts the browser client.

> Use this file as a map of the Pitot documentation. Fetch any page as
> Markdown by appending `.md` to its URL. Pitot is pre-release: entries
> marked PREVIEW run today but may change shape without a migration path,
> and entries marked PLANNED do not execute yet. Trust the marker over the
> confidence of the prose.

## Agent Resources

- [Markdown page export](https://pitot.dev/docs/get-started/install.md): Append `.md` to any docs page URL for clean Markdown.
- [Full documentation text](https://pitot.dev/llms-full.txt): Every page concatenated, for one-shot ingestion.
- [Sitemap](https://pitot.dev/sitemap-index.xml): Crawler URL index.

## Operating Pitot from an agent

- Pitot reads built-in defaults and process environment. Native installs listen on 127.0.0.1:7520; the image supplies PITOT_ADDR=:7520. Secret variables accept _FILE paths. Commands: `pitot [flags]`, `pitot version`, `pitot login-link <email>` (local recovery with host access), `pitot healthcheck [url]`, `pitot repair verify`, and `pitot repair quarantine --batch <id>`. Product operations use HTTP or MCP.
- MCP is the intended agent interface. The server exposes its tools at `/mcp`.
- External MCP clients authenticate with resource-bound OAuth tokens. The browser API uses browser sessions; `/api/mcp` uses the same session. These credentials do not authorize OTLP ingest.
- Telemetry goes in over OTLP only: gRPC and HTTP on the same port as the application (7520 by default). There is no bespoke ingest API to script against.
- Ingest always requires the ingest token, and rejects everything until the first administrator exists — a collector started before setup will fail until setup completes.
- Configuration is environment-only: built-in defaults followed by nonempty process environment values. Custom settings use PITOT_; AI credentials and endpoints use ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, OPENAI_API_KEY and OPENAI_BASE_URL. Unknown PITOT_ setting names fail startup, except platform-injected service-discovery names. Chat is off unless PITOT_AI_PROVIDER selects anthropic or openai and its required key is supplied; OPENAI_BASE_URL includes /v1.

## Overview

- [Documentation](https://pitot.dev/docs.md): Install Pitot, send OpenTelemetry, and configure investigations, dashboards and alerts.
- [Observability your agents can operate.](https://pitot.dev/index.md): Investigate with Pitot's built-in agent, or use the same typed tools from your own agent over MCP.

## Get started

- [First boot](https://pitot.dev/docs/get-started/first-boot.md): Configuration validation, the one-time setup URL, and the ingest token you are shown once. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: The process refuses to start and you want to know what it validated.
  - Read when: You have a running instance and need to create the first administrator.
- [Install](https://pitot.dev/docs/get-started/install.md): The three ways to get the binary onto a machine, and the ports and paths each one opens.
  - Read when: You are putting Pitot on a machine for the first time.
  - Read when: You need to know which ports and paths an instance uses.
- [What Pitot is](https://pitot.dev/docs/get-started/overview.md): Agent investigations, dashboards and telemetry storage in one process, with one data directory. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are deciding whether Pitot fits before installing anything.
  - Read when: You want to know what Pitot replaces in an existing observability stack.
- [Send your first telemetry](https://pitot.dev/docs/get-started/send-telemetry.md): The ingest token, one shared OTLP address, and a working SDK and Collector configuration. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You have a running instance and nothing in it yet.
  - Read when: An exporter is being rejected and you need to know which credential it wants.

## Guides

- [Set up alerts](https://pitot.dev/docs/guides/alerts.md): The rule model, the variables available to an expression, the pending/firing/resolved lifecycle, and webhook and email delivery. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You want to be told when a service degrades.
  - Read when: A rule is not firing when you expect it to.
- [Back up and restore](https://pitot.dev/docs/guides/backup-and-restore.md): The whole data directory is the unit of backup. Copying part of it does not produce a recoverable instance.
  - Read when: You are putting an instance into production.
  - Read when: You are restoring after a host loss, or moving an instance between machines.
- [Use the built-in agent](https://pitot.dev/docs/guides/chat.md): Provider setup, saved threads, search and panel explanations. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You want to investigate telemetry with the built-in agent.
- [Build and refine dashboards](https://pitot.dev/docs/guides/dashboards.md): Panel editing, chat authoring, fifteen panel types, variables, comparison, view links and saved versions. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You want to build or change a dashboard with or without chat.
  - Read when: You want to inspect a failed panel, share a view or restore a saved version.
- [Run with Compose or systemd](https://pitot.dev/docs/guides/deploy.md): A Compose service and a systemd unit with mounted secrets and persistent data. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You need Pitot to restart after an exit or host reboot.
- [Query with Explore](https://pitot.dev/docs/guides/explore.md): FanQL queries, diagnostics, visualization choices and dashboard saving without an AI provider. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You want to query telemetry without chat.
  - Read when: You want to save an Explore result or a log or trace search to a dashboard.
- [Harden an instance](https://pitot.dev/docs/guides/hardening.md): TLS, operations access, account policy and secret delivery. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are preparing an instance for shared or remote access.
- [Connect an agent over MCP](https://pitot.dev/docs/guides/mcp.md): The OAuth flow an MCP client uses, the two scopes, and the one setting that has to be right before any of it works. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are connecting Claude Code or another MCP client to an instance.
  - Read when: A client registers but its tokens are rejected.
- [Tune retention](https://pitot.dev/docs/guides/retention.md): Retention, atomic batch sizing, and the maintenance pass that keeps query latency bounded. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: Disk use is growing faster than expected.
  - Read when: Query or rollup latency is climbing on an instance that was fine.
- [Terminate TLS](https://pitot.dev/docs/guides/tls.md): The two supported TLS patterns, and the proxy-trust setting that has to accompany the second one. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are exposing an instance beyond a trusted network.
  - Read when: Browser session cookies are not coming back Secure.
- [Troubleshoot](https://pitot.dev/docs/guides/troubleshooting.md): Startup refusals, rejected exporters, locked-out users, and where to look when telemetry is not arriving. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: The process will not start, or an exporter is being rejected.
  - Read when: Someone cannot sign in and SMTP is not configured.
- [Upgrade](https://pitot.dev/docs/guides/upgrade.md): Pin a version, read every release's upgrade notes, back up first, and restore only with the version that made the backup. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are upgrading an existing instance.
  - Read when: You are choosing which releases to run in production.
  - Read when: You maintain scripts or clients against Pitot's HTTP routes, MCP tools or settings.

## Reference

- [Alert expression variables](https://pitot.dev/docs/reference/alert-expressions.md): The variables available to a CEL alert rule. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are writing an alert rule and need the variable names.
  - Read when: A rule compiles but never fires, and you want to check what it is reading.
- [HTTP routes](https://pitot.dev/docs/reference/api.md): Application, operational and protocol routes and the SPA catch-all, with the authorization requirement for each. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are auditing what an instance exposes and what guards each route.
  - Read when: A request came back 401 or 403 and you want to know which capability it wanted.
- [Shipped vs planned](https://pitot.dev/docs/reference/capabilities.md): Capability availability, contract stability and operating limits. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are deciding whether to build something durable on a Pitot capability.
  - Read when: A page describes something and you want to know whether it executes today.
- [CLI](https://pitot.dev/docs/reference/cli.md): Server startup, version output, login links, health probes and offline repair. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You need to run or script a Pitot command.
- [Configuration](https://pitot.dev/docs/reference/configuration.md): Setting precedence, naming, secret files, and validation. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are configuring an instance and want the rules before the list.
  - Read when: A setting you set appears to have been ignored.
- [AI provider settings](https://pitot.dev/docs/reference/configuration/ai.md): Chat is disabled unless a provider is selected; its API key is then required. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: The built-in agent is disabled and you want it on.
  - Read when: You are pointing Pitot at a self-hosted or proxied model endpoint.
- [Alert settings](https://pitot.dev/docs/reference/configuration/alerts.md): Settings for the alert evaluation loop and alert email. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: Alerts are evaluating too slowly, or not at all.
  - Read when: You are setting a default alert email destination or changing the per-address limit.
- [Authentication settings](https://pitot.dev/docs/reference/configuration/auth.md): Settings for how people sign in and how long their sessions last. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are moving an instance from local sign-in to an identity provider.
  - Read when: You need to map provider groups onto Pitot roles.
- [Ingest settings](https://pitot.dev/docs/reference/configuration/ingest.md): Settings for how telemetry arrives and how it is batched before it is written. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: Exporters cannot reach the instance.
  - Read when: You are tuning write throughput or flush latency.
- [MCP settings](https://pitot.dev/docs/reference/configuration/mcp.md): Settings for the MCP endpoint external agents connect to. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are connecting an external agent to a Pitot instance.
- [Metrics settings](https://pitot.dev/docs/reference/configuration/metrics.md): Settings for the Prometheus scrape endpoint at /metrics. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are scraping Pitot's own metrics.
- [Server settings](https://pitot.dev/docs/reference/configuration/server.md): Settings for the listener that serves the browser, API, chat, MCP and both OTLP transports. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are putting Pitot behind a reverse proxy.
  - Read when: Browser sessions are not getting Secure cookies.
- [SMTP settings](https://pitot.dev/docs/reference/configuration/smtp.md): Settings for outbound email, which local sign-in uses to deliver codes. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: Sign-in codes are not arriving.
- [Storage settings](https://pitot.dev/docs/reference/configuration/storage.md): Settings for where telemetry lives, how long it is kept, and how DuckDB is sized. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are sizing an instance for a host.
  - Read when: Disk use or query latency is growing and you need the maintenance knobs.
- [Data layout](https://pitot.dev/docs/reference/data-layout.md): The exact contents of PITOT_DATA_DIR, and why the directory is one unit. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are sizing disk or deciding what to back up.
  - Read when: You are inspecting an instance's files and want to know what you are looking at.
- [Endpoints](https://pitot.dev/docs/reference/endpoints.md): Health, readiness, metrics, profiling and the protocol endpoints, with the credential each expects. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are configuring a load balancer, a probe or a Prometheus scrape.
  - Read when: You need to know which endpoints are reachable without authentication.
- [FanQL](https://pitot.dev/docs/reference/fanql.md): FanQL syntax, fields, functions, variables, null semantics and examples, generated from query registries. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are writing a FanQL query and need syntax or field names.
- [MCP tools](https://pitot.dev/docs/reference/mcp.md): 20 tools served at /mcp, each with its inputs and mutation semantics. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are connecting an agent and want to know what it can call.
  - Read when: You need to know which tools mutate state and which cannot.
- [Roles](https://pitot.dev/docs/reference/roles.md): viewer, operator and admin, and what each is permitted to do. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are deciding which role to give someone.
  - Read when: You are mapping identity-provider groups onto Pitot roles.
  - Read when: A request came back 403 and you want to know which capability it needed.

## Concepts

- [Why one binary](https://pitot.dev/docs/concepts/architecture.md): What collapsing an observability stack into one process buys, and what it costs.
  - Read when: You are evaluating Pitot against an assembled stack.
  - Read when: You want to know where the single-process design stops being an advantage.
- [Authentication modes](https://pitot.dev/docs/concepts/authentication.md): Local codes versus an identity provider, who owns roles in each, and what happens on every login. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are choosing between local sign-in and OIDC.
  - Read when: You expect a provider group change to take effect and want to know when it does.
- [How Pitot compares](https://pitot.dev/docs/concepts/comparison.md): The comparison table from the project README. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are deciding whether one Pitot instance fits your workload.
- [Insights and anomalies](https://pitot.dev/docs/concepts/insights.md): Service changes, repeated log patterns, health scores and alert variables. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You need to interpret an insight or detector-based alert.
- [Performance](https://pitot.dev/docs/concepts/performance.md): Sustained mixed ingest at 507,311 items/s on a Hetzner ccx33.
  - Read when: You want to understand the performance figure on the landing page.
  - Read when: You need to measure an instance for your own load.
- [How storage works](https://pitot.dev/docs/concepts/storage.md): Atomic Parquet ingestion, indexed trace reads, DuckDB analytics, and SQLite control state. [PREVIEW: this runs, but its shape may still change without a migration path]
  - Read when: You are sizing disk, or deciding what to back up.
  - Read when: You want to understand ingest durability or query performance.

## Help and contributions

- [Get help and contribute](https://pitot.dev/docs/help.md): Support channels, contribution steps and private security reporting.
  - Read when: You need help or want to contribute.

## Site terms

- [Privacy](https://pitot.dev/privacy.md): Website analytics, consent controls, browser storage and hosting; separate from a self-hosted Pitot instance.
  - Read when: You want to know what this website records about your visit.
  - Read when: You allowed or declined analytics and want to change that answer.