Implementation:Promptfoo Promptfoo Telemetry

Knowledge Sources	Promptfoo_Promptfoo
Domains	Telemetry, Analytics
Last Updated	2026-02-14 07:45 GMT

Overview

Concrete tool for managing anonymous usage telemetry collection via PostHog and a custom analytics endpoint, with opt-out support.

Description

The Telemetry module (telemetry.ts) implements the Telemetry class that tracks anonymous usage events (commands used, evaluations run, red team operations, web UI actions). Events are sent to both PostHog (via posthog-node) and a custom endpoint (r.promptfoo.app). The module supports opt-out via PROMPTFOO_DISABLE_TELEMETRY environment variable, handles user identification, and includes a saveConsent() method for the harmful red team data consent flow. A singleton instance is exported as the default.

Usage

Import the default telemetry instance to record events. It is used throughout the codebase to track feature usage and command invocations.

Code Reference

Source Location

• Repository: Promptfoo_Promptfoo
• File: src/telemetry.ts
• Lines: 1-240

Signature

export class Telemetry {
  get disabled(): boolean
  record(eventName: TelemetryEventTypes, properties: EventProperties): void
  async saveConsent(email: string, metadata?: Record<string, string>): Promise<void>
  async shutdown(): Promise<void>
}

declare const telemetry: Telemetry;
export default telemetry;

Import

import telemetry from './telemetry';

I/O Contract

Inputs

Name	Type	Required	Description
eventName	TelemetryEventTypes	Yes	Event type (e.g., 'eval_ran', 'command_used')
properties	EventProperties	Yes	Key-value properties for the event

Outputs

Name	Type	Description
(void)	void	Events sent asynchronously in the background

Usage Examples

import telemetry from './telemetry';

// Record a command usage event
telemetry.record('command_used', { command: 'eval' });

// Record evaluation completion
telemetry.record('eval_ran', {
  numTests: 50,
  numProviders: 3,
  duration: 120,
});

// Check if telemetry is disabled
if (!telemetry.disabled) {
  // Additional tracking
}

Related Pages

• Environment:Promptfoo_Promptfoo_Node_Runtime