n8n:telemetry

テレメトリー

レジストリ

レジストリに移行済みのイベントは、packages/@n8n/telemetry にイベントごとに1つのエントリーとして格納されます。各エントリーには、実際に出力される名前、説明、プロパティの型を定義する zod スキーマが含まれています。エントリーは src/events/ 内で製品ドメインごとに整理され、TELEMETRY_EVENT.<DOMAIN>.<EVENT> にまとめられています。このパッケージは登録済みイベントを定義し、トランスポート SDK には依存しません。

登録済みのイベント、その意味、またはプロパティを確認するには、まずカタログを実行してください。

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

レジストリへの移行は段階的に進められています。まだ登録されていないイベントはカタログに表示されないため、カタログで該当するイベントが見つからない場合は track() の呼び出し箇所を検索してください。

エントリー自体を track() に渡してください。出力される名前は内部で解決されます。

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

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

どちらの track() 実装も、レジストリーエントリーと通常の文字列を受け付けます。まだ移行されていないイベントには、引き続き通常の文字列を使用できます。

• フロントエンド：packages/frontend/editor-ui/src/app/plugins/telemetry/index.ts
• バックエンド：packages/cli/src/telemetry/index.ts

エントリーを使うと、プロパティの入力補完とコンパイル時チェックが有効になります。誤記、必須プロパティの欠落、型の不一致があると、型チェックに失敗します。テレメトリーのトランスポートが初期化されている場合、track() はさらに @n8n/telemetry から共有される getEventValidationError を使って登録済みイベントのペイロードを検証し、構造的な型付けをすり抜けた未認識のプロパティも含め、不一致があると警告をログに記録します。検証の警告が出ても、イベントの出力は停止されません。

イベントの追加

1. まずカタログを確認します（pnpm --filter @n8n/telemetry catalog）。別の画面から発生する同じユーザーアクションを既存のイベントで扱える場合は、よく似たイベントを追加するのではなく、プロパティを追加してください。
2. イベントの対象に基づいてドメインを選びます。イベントが何についてのものかで判断し、きっかけとなった画面では決めません。User opened Credential modal は、NDV、テンプレートのセットアップ、チャットのどこから開かれた場合も CREDENTIALS です。きっかけとなった状況は source プロパティに入れます。
3. プロジェクトの命名規則に従います。 文頭のみ大文字の文形式にし、主体を先に、動詞を過去形にし、対象を具体的にします（User pinned node data）。名前にテンプレート補間は使用せず、変動する値はプロパティに入れます。名前は BigQuery のテーブル名に snake_case で変換しても問題ない形式にしてください。句読点はスペース以外使わず、snake_case への変換後に大文字小文字の違いが衝突するような名前も避けます。
4. エントリーの description を記述します。 イベントの意味と発生するタイミングを説明してください。レジストリのテストでは、説明が空だとエラーになります。キーだけでは意味が明らかでないプロパティには、.describe() を使って個別に説明を追加してください。
5. zod でプロパティの型を定義します（import { z } from 'zod/v4'）。 キーは snake_case にし、呼び出し元で値を省略できる場合は明示的に .optional() を指定します。本当に動的な残余プロパティには z.looseObject()／.catchall() を使います。スキーマは JSON Schema で表現可能な状態にしてください。トランスフォーム、リファインメント、z.date() は使用できません（z.toJSONSchema() によってレジストリのテストで検証されます）。
6. イベントの出力方法を選びます。 フロントエンドでは useTelemetry().track(...) を使います。バックエンドでは、packages/cli/src/events/relays/telemetry.event-relay.ts 内の RelayEventMap ハンドラー（イベントバス駆動）か、直接の Telemetry.track(...) 呼び出しを使います。どちらの場合も、同じレジストリーエントリーを参照します。

厳守事項

• 出力済みイベントの名前は絶対に変更しないでください。 BigQuery はイベント名ごとに1つのテーブルを作成するため、名前を変更すると下流の履歴が孤立します。名前の変更は削除と新規作成を意味し、名前を再利用することはできません。レジストリーエントリーを削除する前に、データチームと調整してください。
• イベント名を重複させないでください。 すべてのドメインを通じて1イベントにつき1つのエントリーを作り、すべての呼び出し元（フロントエンドとバックエンドを含む）から参照してください。名前が重複すると CI に失敗します。
• プロパティは追加によってのみ変更します。 プロパティの型を変更すると、イベント名を維持していても、データウェアハウスの列が分岐します。プロパティを削除する代わりに、スキーマで .meta({ deprecated: true }) を設定して非推奨にしてください。
• 破壊的変更をリリースする前に、Slack でデータチームに知らせ、Notion に記録してください。

テスト

テストでイベント名のリテラルを再入力しないでください。

• 呼び出し箇所のテストでは、useTelemetry().track またはバックエンドの Telemetry.track サービスをモックし、ペイロードとともにレジストリエントリーそのものが渡されることを検証します。
• フロントエンドのトランスポートのテストでは、window.rudderanalytics.track に entry.name と追加されたペイロードが渡されることを検証します。
• バックエンドのトランスポートのテストでは、RudderStack のペイロードの event フィールドが entry.name と一致し、properties にイベントのペイロードが含まれることを検証します。

イベントが届くことを手動で確認するには、pnpm telemetry:sink を実行し（絞り込むには --grep <event name> を追加）、バックエンドを pnpm dev:be:telemetry で起動します。バックエンドとエディターのイベントは、画面上と .output/telemetry.ndjson に1行ずつ表示されます。

関連項目

実験の露出イベントとメトリクスイベントは n8n:experiments（.agents/skills/experiments/SKILL.md）に従います。