Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,8 @@
An empty provider disables chat; exactly `anthropic` or `openai` requires
that provider's key. Ignore AI credentials and endpoints when chat is disabled;
validate only the selected provider's endpoint.
- For the first Pitot alpha, `internal/config/loader.go` resolves legacy
`FANOUT_*` only when the equivalent primary name is unset. Preserve explicit
empty primaries and emit one names-only warning. See `CHANGELOG.md` for the
removal window and storage compatibility names.
- Only the current `PITOT_*` custom environment names are read; the
pre-rename environment variable prefix is no longer supported.
- Every `secret:"true"` field accepts `<ENV>_FILE`. Both forms nonempty fail;
secret files lose exactly one trailing LF or CRLF and must remain nonempty.
Unselected AI providers' value and file forms are ignored.
Expand Down
54 changes: 34 additions & 20 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Unreleased — Pitot rename (2026-11-11)

The product is now **Pitot** (pronounced **PEE-toh**), formerly Fanout, at
The product is now **Pitot** (pronounced **PEE-toh**) at
[pitot.dev](https://pitot.dev). The owner approved this rename on 2026-11-11 to avoid a
conflict with a third party's registered US trademark in cloud services.

Expand All @@ -11,25 +11,39 @@ conflict with a third party's registered US trademark in cloud services.
- Container images are `ghcr.io/labstack/pitot` and `docker.io/labstack/pitot`.
Update deployment manifests, service names, install URLs and MCP client entries.
The MCP Registry identity is `io.github.labstack/pitot`.
- Use `PITOT_*` settings. For the first Pitot alpha only, an unset primary
variable falls back to its `FANOUT_*` equivalent, including secret `_FILE`
forms and installer version/prefix overrides. A primary variable explicitly
set to empty blocks its legacy equivalent and uses the ordinary default.
Startup emits one deprecation warning listing used old names, never values.
Mixed value/file forms still fail when both are nonempty. Replace old names
before upgrading to the following alpha, when this bridge is due for removal.
- Keep the complete existing data directory. Native default `./data`, the
`control/fanout.sqlite` filename, all other storage filenames, telemetry format,
marker files, Parquet `fanout.spill.*` footer keys, stored
`_fanout_diagnostic_context` metadata and published migrations are unchanged; there is no data migration.
The new image defaults to `/var/lib/pitot/data`: mount the **existing** volume
there, or explicitly set `PITOT_DATA_DIR` to its existing mount location.
Do not accidentally create a fresh named volume when changing deployment names.
- Existing sessions keep their cookie names and keyboard preferences keep their
storage key. Saved chat activities resolve their old MCP App resource URI to
the new URI in memory, without rewriting history. Existing ingest and OAuth secrets
remain valid; token prefixes (`foi_`, `foa_`, `for_`, `foc_`) are unchanged for
both existing and new tokens because there is no central token-prefix registry.
- The server and installer refuse to start if any variable with the exact,
case-sensitive pre-rename prefix is set, including empty assignments,
installer overrides and secret-file settings. The error lists names only.
Rename those variables to `PITOT_*` before upgrading; they no longer silently
use defaults.
- The query language is now **PitotQL**. Existing structured dashboard queries,
MCP `query_telemetry` arguments (`text`, `panel.query`, `panel.sql`), query
keywords, Explore URL parameters and browser storage keys are unchanged.
Previous query HTTP paths and the MCP reference URI remain read aliases;
responses and new clients use canonical PitotQL names. See
[rename compatibility](site/src/content/docs/docs/reference/rename-compatibility.mdx) for the exact aliases.
- Before upgrading, stop the service and take a cold backup of the complete
data directory. On startup, Pitot automatically renames the previous control
database and its SQLite WAL, shared-memory and rollback-journal sidecars in
`control/` to `pitot.sqlite` and matching sidecar names, then syncs the directory.
No manual filename change is needed, including for unattended agent upgrades.
If both database names or an incomplete sidecar move exist, startup refuses
before opening SQLite; stop the instance and recover a consistent file set
from the cold backup before retrying. Never delete a database just to bypass
this refusal or create a fresh volume by accident. For rollback to the previous
binary, restore its complete cold backup before starting it; older binaries
do not move the database name back.
- Telemetry spill footer keys retain their persisted format-5 spelling so
existing Parquet files remain valid and byte compatibility stays unchanged.
- Sessions use the `pitot_session` cookie (with the `__Host-` prefix over HTTPS),
so users must sign in again. Keyboard shortcut preferences reset. Saved chat
activities using the previous MCP App URI no longer render; begin a new chat.
Reserved diagnostic context metadata now uses `_pitot_diagnostic_context`;
discard pre-rename chat history before resuming chat.
- Published SQL migrations remain unchanged. Existing ingest and OAuth secrets
and their token prefixes remain valid. The image defaults to
`/var/lib/pitot/data`: mount the existing volume there, or set `PITOT_DATA_DIR`
to its existing mount location.
- HTTP request headers and metrics use the Pitot name. Update custom clients
using the product request header to `Pitot-Request` (and dashboard deletion confirmation to
`Pitot-Confirm-Delete`), and update Prometheus
Expand Down
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Pitot

Pitot (pronounced **PEE-toh**), formerly Fanout.
Pitot (pronounced **PEE-toh**).

**Observability your agents can operate.** Send OpenTelemetry to one binary, then investigate with
Pitot's built-in agent or connect your own over MCP.
Expand All @@ -12,11 +12,11 @@ Pitot's built-in agent or connect your own over MCP.
<a href="https://pitot.dev">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="site/src/assets/landing/overview-dark.png">
<img src="site/src/assets/landing/overview-light.png" alt="A Pitot dashboard the built-in agent built from one request: store request rate, error rate, p95 latency and error logs, with request and error rates by service.">
<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.">
</picture>
</a>

*Preview capture from the pre-rename alpha.*
*Current Pitot interface with deterministic offline sample telemetry.*

Pitot keeps OpenTelemetry traces, logs, and metrics in one binary and one data directory, with no
external storage services to operate. Pitot is pre-release and changes without migration paths; the browser
Expand All @@ -25,7 +25,7 @@ client, built-in agent, MCP tools, dashboards, and alerts are preview capabiliti
[documentation](https://pitot.dev) 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.
- Explore and PitotQL 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,
Expand Down
6 changes: 3 additions & 3 deletions cmd/pitot-docgen/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ import (

"github.com/labstack/pitot/internal/alert"
"github.com/labstack/pitot/internal/config"
"github.com/labstack/pitot/internal/fanql"
"github.com/labstack/pitot/internal/pitotql"
)

func main() {
Expand Down Expand Up @@ -117,7 +117,7 @@ func run(source, alertSource, routeDirs, outDir, envExample string, check bool)
return err
}
pages["mcp.mdx"] = toolsPage
pages["fanql.md"] = []byte("---\ntitle: \"FanQL\"\ndescription: \"The preview text syntax for structured telemetry queries.\"\nsummary: \"FanQL syntax, fields, functions, variables, null semantics and examples, generated from query registries.\"\nread_when:\n - \"You are writing a FanQL query and need syntax or field names.\"\nstatus: preview\ngenerated: true\n---\n\n" + fanql.Reference())
pages["pitotql.md"] = []byte("---\ntitle: \"PitotQL\"\ndescription: \"The preview text syntax for structured telemetry queries.\"\nsummary: \"PitotQL syntax, fields, functions, variables, null semantics and examples, generated from query registries.\"\nread_when:\n - \"You are writing a PitotQL query and need syntax or field names.\"\nstatus: preview\ngenerated: true\n---\n\n" + pitotql.Reference())

outputs := map[string][]byte{envExample: renderEnvironment(fields)}
for name, body := range pages {
Expand Down Expand Up @@ -555,7 +555,7 @@ func renderPage(name string, page groupPage, fields []field) []byte {

b.WriteString("Every setting below is read once at startup and requires a restart to change.\n")
b.WriteString("Built-in defaults are overridden by nonempty environment values.\n")
b.WriteString("For the first Pitot alpha, unset `PITOT_` variables accept `FANOUT_` equivalents with a names-only deprecation warning. Explicitly empty primary variables block fallback.\n")
b.WriteString("The pre-rename environment variable prefix is no longer read. Use `PITOT_` settings.\n")
b.WriteString("Unknown `PITOT_` names fail startup; platform-injected service names are tolerated.\n")
b.WriteString("Vendor credentials and endpoints keep the vendor's documented names.\n\n")
if name == "ai" {
Expand Down
8 changes: 4 additions & 4 deletions cmd/pitot-docgen/main_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,18 @@ import (
"testing"

"github.com/labstack/pitot/internal/config"
"github.com/labstack/pitot/internal/fanql"
"github.com/labstack/pitot/internal/pitotql"
)

const configSource = "../../internal/config/config.go"

func TestDocgenWritesFanQLReference(t *testing.T) {
func TestDocgenWritesPitotQLReference(t *testing.T) {
dir := t.TempDir()
out := filepath.Join(dir, "reference")
if err := run(configSource, "../../internal/alert/types.go", strings.Join(routeDirs, ","), out, filepath.Join(dir, ".env.example"), false); err != nil {
t.Fatal(err)
}
raw, err := os.ReadFile(filepath.Join(out, "fanql.md"))
raw, err := os.ReadFile(filepath.Join(out, "pitotql.md"))
if err != nil {
t.Fatal(err)
}
Expand All @@ -27,7 +27,7 @@ func TestDocgenWritesFanQLReference(t *testing.T) {
t.Fatal("missing site front matter")
}
_, content, ok := strings.Cut(page, "\n---\n\n")
if !ok || content != fanql.Reference() {
if !ok || content != pitotql.Reference() {
t.Fatalf("page content differs from the API/MCP reference: %q", page)
}
}
Expand Down
12 changes: 10 additions & 2 deletions cmd/pitot/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,11 @@ type loginLinkCommand struct {
}

func main() {
if err := store.RejectPreviousEnvironment(os.Environ()); err != nil {
fmt.Fprintln(os.Stderr, err)
os.Exit(1)
}

showVersion, loginLink, healthURL, derivedProbe, repair, err := parseCommandLine(os.Args[1:], os.Stderr)
if errors.Is(err, flag.ErrHelp) {
return
Expand All @@ -78,7 +83,7 @@ func main() {
var healthEnvironment map[string]string
if healthURL != "" || derivedProbe {
healthEnvironment = make(map[string]string)
for _, assignment := range config.ResolveEnvironment(os.Environ()) {
for _, assignment := range os.Environ() {
name, value, _ := strings.Cut(assignment, "=")
healthEnvironment[name] = value
}
Expand Down Expand Up @@ -316,7 +321,7 @@ func main() {
panels.SetRollupReader(queries)
panels.SetCacheTTL(cfg.QueryCacheTTL)
api.RegisterQueryRoutes(e, panels)
api.RegisterFanQLRoutes(e, q, panels)
api.RegisterPitotQLRoutes(e, q, panels)
api.RegisterAnnotationRoutes(e, annotations.New(q))
api.RegisterTraceRoutes(e, panels.CachedTraces(queries), cfg.RetentionDays)
api.RegisterIntelligenceRoutes(e, detector)
Expand Down Expand Up @@ -711,6 +716,9 @@ func createLoginLink(cfg config.Config, rawEmail string, breakGlass bool, output
if err != nil {
return err
}
if err := store.MigrateControlDatabase(cfg.ControlSQLitePath()); err != nil {
return err
}
if _, err := os.Stat(cfg.ControlSQLitePath()); err != nil {
if errors.Is(err, os.ErrNotExist) {
return fmt.Errorf("control database does not exist at %s", cfg.ControlSQLitePath())
Expand Down
68 changes: 68 additions & 0 deletions cmd/pitot/main_test.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package main

import (
"bufio"
"bytes"
"context"
"crypto/ecdsa"
Expand Down Expand Up @@ -824,3 +825,70 @@ func TestApplyConfiguredIngestTokenLogsWithoutToken(t *testing.T) {
t.Fatalf("logs must report both outcomes by setting name: %s", output)
}
}

func TestStartupRefusesRetiredEnvironmentBeforeStores(t *testing.T) {
if os.Getenv("TEST_STARTUP_CHILD") == "1" {
os.Args = []string{"pitot"}
main()
return
}
for _, retired := range []bool{true, false} {
t.Run(map[bool]string{true: "retired", false: "current"}[retired], func(t *testing.T) {
root := filepath.Join(t.TempDir(), "data")
ctx, cancel := context.WithTimeout(t.Context(), 30*time.Second)
defer cancel()
command := exec.CommandContext(ctx, os.Args[0], "-test.run=^TestStartupRefusesRetiredEnvironmentBeforeStores$")
command.Env = []string{"TEST_STARTUP_CHILD=1", "PATH=" + os.Getenv("PATH"), "PITOT_DATA_DIR=" + root, "PITOT_ADDR=127.0.0.1:0", "PITOT_MCP_ENABLED=false", "PITOT_AUTH_CODE_SECRET=" + strings.Repeat("x", 32)}
// Test fixture for the exact retired prefix; production spelling is isolated.
const previous = "FANOUT_"
if retired {
command.Env = append(command.Env, previous+"DATA_DIR=private-value", previous+"TOKEN=")
output, err := command.CombinedOutput()
if err == nil || !strings.Contains(string(output), previous+"DATA_DIR") || !strings.Contains(string(output), previous+"TOKEN") || !strings.Contains(string(output), "rename them to PITOT_") || strings.Contains(string(output), "private-value") {
t.Fatalf("refusal: %s, %v", output, err)
}
if _, err := os.Stat(root); !os.IsNotExist(err) {
t.Fatalf("data directory touched before refusal: %v", err)
}
return
}
pipe, err := command.StderrPipe()
if err != nil {
t.Fatal(err)
}
if err := command.Start(); err != nil {
t.Fatal(err)
}
ready := make(chan bool, 1)
go func() {
scanner := bufio.NewScanner(pipe)
for scanner.Scan() {
if strings.Contains(scanner.Text(), "HTTP and OTLP listening") {
ready <- true
return
}
}
ready <- false
}()
select {
case started := <-ready:
if !started {
_ = command.Wait()
t.Fatal("current environment did not start")
}
if err := command.Process.Signal(os.Interrupt); err != nil {
t.Fatal(err)
}
if err := command.Wait(); err != nil {
t.Fatal(err)
}
if _, err := os.Stat(filepath.Join(root, "control", "pitot.sqlite")); err != nil {
t.Fatal(err)
}
case <-ctx.Done():
_ = command.Wait()
t.Fatal("startup timed out")
}
})
}
}
6 changes: 3 additions & 3 deletions docs/adr/0006-one-structured-query-path.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,22 @@ Date: 2026-10-30

## Context

Telemetry is queried from dashboards, FanQL text, MCP tools and the agent, and
Telemetry is queried from dashboards, PitotQL text, MCP tools and the agent, and
a visual builder is planned. Separate query paths would each need their own validation,
limits and SQL generation, and could diverge.

## Decision

Every surface produces the same validated structured query (`from`, `where`,
`measures`, `by`, `bucket`, `histogram`, `sort`, `limit`), which one engine path
validates, budgets and turns into SQL. FanQL is the text form of that query and
validates, budgets and turns into SQL. PitotQL is the text form of that query and
compiles to it; its filters become predicates inside the query, checked by the
same validation, and it never runs SQL of its own. Arbitrary read-only SQL remains a
separate, locked-down gate for what the structured query cannot express.

## Consequences

- One place enforces relations, functions and budgets.
- A FanQL query executes through the same engine path as the equivalent
- A PitotQL query executes through the same engine path as the equivalent
dashboard panel.
- New query features are added once and become available everywhere.
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
# 0007. A hand-written FanQL parser
# 0007. A hand-written PitotQL parser

Status: Accepted
Date: 2026-10-30

## Context

FanQL needs precise, recovering diagnostics with source spans and suggested
PitotQL needs precise, recovering diagnostics with source spans and suggested
fixes, position-aware completion, and canonical printing, all fast enough to
run on every keystroke.

## Decision

FanQL uses a hand-written lexer and recursive-descent parser in Go, with no
PitotQL uses a hand-written lexer and recursive-descent parser in Go, with no
parser-generator or grammar library. It recovers after errors so it can report
every independent problem in one pass.

Expand Down
2 changes: 1 addition & 1 deletion docs/adr/0008-batch-format-5.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ Format 5 replaces format 4 and supersedes the format half of ADR 0003.
service and time. Metrics sort by namespace, service, name, hour, series
and time.
- Reads rewrite `attributes['k']` and `resource['k']` for a standard key to
its column on the parsed SQL, so FanQL, structured panels and SQL share one
its column on the parsed SQL, so PitotQL, structured panels and SQL share one
rule and read the converted value. Users never name the columns, and
result stars leave them out.
- SQL rejects `GROUP BY ALL`, because the pinned engine groups its keys
Expand Down
2 changes: 1 addition & 1 deletion docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,6 @@ Date: YYYY-MM-DD
| 0004 | [No legacy paths](0004-no-legacy-paths.md) | Accepted |
| 0005 | [CalVer releases](0005-calver-releases.md) | Accepted |
| 0006 | [One structured query path](0006-one-structured-query-path.md) | Accepted |
| 0007 | [A hand-written FanQL parser](0007-hand-written-fanql-parser.md) | Accepted |
| 0007 | [A hand-written PitotQL parser](0007-hand-written-pitotql-parser.md) | Accepted |
| 0008 | [Batch format 5](0008-batch-format-5.md) | Accepted |
| 0009 | [Ingest admission at saturation](0009-ingest-admission-at-saturation.md) | Accepted |
Loading
Loading