n8n:telemetry

遥测

注册表

已迁移到注册表的事件位于 packages/@n8n/telemetry 中，每个事件各有一个条目，包含其实际发出的名称、描述以及用于定义其属性类型的 zod schema；这些条目按产品领域组织在 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() 还会通过 getEventValidationError（由 @n8n/telemetry 共享）验证已注册事件的负载，并在不匹配时记录警告，其中也包括因结构化类型检查而未被拦截的未识别属性。验证警告不会阻止事件发出。

添加事件

1. 先检查目录（pnpm --filter @n8n/telemetry catalog）。如果已有事件涵盖了来自其他界面的同一用户操作，应为其添加属性，而不是新增一个近似重复的事件。
2. 根据事件主体选择领域——也就是事件所描述的内容，而不是触发事件的界面。从 NDV、模板设置或聊天窗口打开的 User opened Credential modal 都属于 CREDENTIALS。触发场景应写入 source 属性。
3. 按照项目命名规范命名： 使用句首字母大写的句式、以行为主体开头、使用过去时动词和具体对象（User pinned node data）。名称中不要插入模板变量——变化部分应放入属性。名称必须能顺利转换为 BigQuery 表名：除空格外不得包含标点，且转换为 snake_case 后不得发生冲突。
4. 编写条目 description，说明事件含义及其触发时机——注册表测试会拒绝空描述。若仅凭属性键名无法明确理解其含义，请使用 .describe() 为各属性添加说明。
5. 使用 zod 定义属性类型（import { z } from 'zod/v4'）： 键名使用 snake_case；若调用位置可能省略某个值，应明确使用 .optional()；对于确实动态的剩余属性，使用 z.looseObject()/.catchall()。Schema 必须能够表示为 JSON Schema——不得使用 transforms、refinements 或 z.date()（注册表测试会通过 z.toJSONSchema() 强制执行此要求）。
6. 放置事件发送代码： 前端使用 useTelemetry().track(...)；后端可通过 packages/cli/src/events/relays/telemetry.event-relay.ts 中的 RelayEventMap 处理程序发送（由事件总线驱动），也可直接调用 Telemetry.track(...)——两者都引用同一个注册表条目。

硬性规则

• 绝不重命名已发出的事件。 BigQuery 会为每个事件名称创建一个表；重命名会导致下游历史数据失去关联。重命名等同于删除并新建，名称不得重复使用；删除注册表条目前，必须与数据团队协调。
• 绝不重复使用事件名称——所有领域中的每个事件只能有一个条目，所有调用位置（包括 FE + BE）都必须引用该条目。CI 会在名称冲突时失败。
• 属性只能以兼容方式演进。 即使名称稳定，更改属性类型也会在数据仓库中拆分列。应在 schema 上标记弃用（.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。

相关内容

实验曝光事件和指标事件遵循 n8n:experiments（.agents/skills/experiments/SKILL.md）。