Principle:Promptfoo Promptfoo Telemetry Collection
| Knowledge Sources | |
|---|---|
| Domains | Telemetry, Analytics |
| Last Updated | 2026-02-14 07:45 GMT |
Overview
Principle governing anonymous, opt-out usage telemetry collection to understand feature adoption and improve the product.
Description
Telemetry Collection defines how promptfoo collects anonymous usage events while respecting user privacy. The principle mandates that telemetry is (1) opt-out via PROMPTFOO_DISABLE_TELEMETRY environment variable, (2) anonymous (using a random user ID, no personal data beyond voluntary email), (3) non-blocking (events sent asynchronously with fire-and-forget semantics), and (4) clean-shutting-down (PostHog client is properly flushed before process exit). Events are dual-routed to PostHog (for analytics) and a custom endpoint (for operational metrics).
Usage
Apply this principle when adding new telemetry events. Use the typed event schema to ensure events are properly categorized and include relevant properties.
Theoretical Basis
The telemetry system implements the Observer Pattern with dual sinks:
- PostHog sink — product analytics with user identification
- Custom REST sink — lightweight operational metrics
The Singleton Pattern ensures a single telemetry instance per process, with symbol-based keys for cross-module-reload stability. The flushInterval: 0 configuration prevents the PostHog timer from keeping the Node.js event loop alive.