n8n/packages/@n8n/telemetry

@n8n/telemetry

Registry definitions for telemetry events: event names, descriptions, their zod property schemas, and telemetry constants (e.g. the PostHog events blacklist). Reference entries as TELEMETRY_EVENT.<DOMAIN>.<EVENT> and pass them to track() for property autocomplete and compile-time checks.

Definitions only — this package never depends on PostHog, RudderStack, or any other transport; zod is the only runtime dependency. Transports live in the editor-ui telemetry plugin and the cli telemetry service.

To find which events are registered, what they mean, and what properties they carry, use the catalog:

pnpm --filter @n8n/telemetry catalog          # human-readable, grouped by domain
pnpm --filter @n8n/telemetry catalog --json   # structured, for programmatic use

The registry is being adopted incrementally. Events not yet registered do not appear in the catalog, so search track() call sites when the catalog has no match.

Define an event in its domain file under src/events/:

import { z } from 'zod/v4';

import { defineTelemetryEvents } from '../define';

export const WORKFLOWS_TELEMETRY = defineTelemetryEvents({
	USER_PINNED_NODE_DATA: {
		name: 'User pinned node data',
		description: 'Fires when the user pins run data on a node.',
		properties: z.object({ workflow_id: z.string(), source: z.enum(['canvas', 'ndv']) }),
	},
});

Then add the domain to src/telemetry-events.ts so it is exported and included in the catalog:

import type { TelemetryEventRegistry } from './define';
import { PLATFORM_TELEMETRY } from './events/platform';
import { WORKFLOWS_TELEMETRY } from './events/workflows';

export const TELEMETRY_EVENT = {
	PLATFORM: PLATFORM_TELEMETRY,
	WORKFLOWS: WORKFLOWS_TELEMETRY,
} satisfies TelemetryEventRegistry;