Index of every page on this site: llms.txt
All skills
n8n-io avatar

/telemetry

@273d130 official
by n8n - Workflow Automationn8n-io/n8n211k stars
61,599
Run it yourself

Guides adding, changing, and reviewing telemetry through the `@n8n/telemetry` event registry. Use when working on telemetry, analytics, tracking, product events, `track()` calls, or RudderStack/PostHog product events, in frontend or backend code — and whenever you need to find which registered telemetry events exist, what an event means, or what properties it carries.

  • 1 file
  • 5.4 KB
  • Updated 3 weeks ago
  • GitHub
Use this Skill: https://skilld.dev/gh/n8n-io/n8n/telemetry

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈96 tokens for metadata: the name and description. ≈1.3k when used: this file.

Description uses 4.8% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈386 characters, or 4.8%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Telemetry

The registry

Events migrated to the registry live in packages/@n8n/telemetry as one entry per event — its exact emitted name, a description, and a zod schema typing its properties — organized per product domain in src/events/ and composed into TELEMETRY_EVENT.<DOMAIN>.<EVENT>. The package defines registered events and never depends on transport SDKs.

To find which events are registered, what they mean, or what properties they carry, run the catalog first:

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.

Pass the entry itself to track() — it resolves the emitted name internally:

import { TELEMETRY_EVENT } from '@n8n/telemetry';

telemetry.track(TELEMETRY_EVENT.PLATFORM.USER_IS_PART_OF_EXPERIMENT, {
	name: experimentName,
	variant,
});

Both track() implementations accept registry entries and plain strings. Plain strings remain supported for events that have not yet migrated:

  • Frontend: packages/frontend/editor-ui/src/app/plugins/telemetry/index.ts
  • Backend: packages/cli/src/telemetry/index.ts

Entries get property autocomplete and compile-time checks — typo'd, missing, or wrongly typed properties fail typecheck. When the telemetry transport is initialized, track() additionally validates registered-event payloads via getEventValidationError (shared from @n8n/telemetry) and logs a warning on mismatch, including unrecognized properties that slipped past structural typing. A validation warning does not stop the event from being emitted.

Adding an event

  1. Check the catalog first (pnpm --filter @n8n/telemetry catalog). If an existing event covers the same user action from another surface, augment it with a property instead of adding a near-duplicate event.
  2. Pick the domain by the event's subject — what the event is about, never the surface that triggered it. User opened Credential modal is CREDENTIALS whether opened from the NDV, template setup, or chat. The trigger context goes into a source property.
  3. Name it with the house grammar: sentence case, actor first, past-tense verb, specific object (User pinned node data). No template interpolation in names — variability goes into properties. The name must snake_case cleanly into a BigQuery table name: no punctuation beyond spaces, no casing that collides after snake_casing.
  4. Write the entry description stating what the event means and when it fires — a registry test rejects blank descriptions. Document individual properties with .describe() where the key alone is not obvious.
  5. Type the properties with zod (import { z } from 'zod/v4'): snake_case keys, explicit .optional() where a call site may omit a value, z.looseObject()/.catchall() for genuinely dynamic remainders. Schemas must stay JSON-Schema-representable — no transforms, refinements, or z.date() (a registry test enforces this via z.toJSONSchema()).
  6. Place the emission: frontend via useTelemetry().track(...); backend either through a RelayEventMap handler in packages/cli/src/events/relays/telemetry.event-relay.ts (event-bus-driven) or a direct Telemetry.track(...) call — both reference the same registry entry.

Hard rules

  • Never rename an emitted event. BigQuery materializes one table per event name; a rename orphans downstream history. A rename is delete + create, names are never reused, and removals must be coordinated with the data team before deleting the registry entry.
  • Never duplicate an event name — one entry per event across all domains, referenced by every call site (even FE + BE). CI fails on collision.
  • Properties evolve additively only. Changing a property's type forks warehouse columns even under a stable name. Mark deprecations on the schema (.meta({ deprecated: true })) instead of removing.
  • Breaking changes need a data-team heads-up in Slack plus a Notion note before they ship.

Testing

Do not retype event-name literals in tests:

  • In call-site tests, mock useTelemetry().track or the backend Telemetry.track service and expect the registry entry itself with the payload.
  • In frontend transport tests, expect window.rudderanalytics.track to receive entry.name and the augmented payload.
  • In backend transport tests, expect the RudderStack payload's event field to equal entry.name and its properties to include the event payload.

To check by hand that an event arrives, run pnpm telemetry:sink (add --grep <event name> to filter) and start the backend with pnpm dev:be:telemetry. Backend and editor events appear on screen and in .output/telemetry.ndjson, one per line.

Related

Experiment exposure and metric events follow n8n:experiments (.agents/skills/experiments/SKILL.md).

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 273d130. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago

README badge

README badge for n8n-io/n8n/telemetry