Transformers 允许你在 Logpush 将每批记录投递到目标之前对其运行 SQL 查询。你可以用它们过滤不想存储的记录、将字段重塑为下游 schema、脱敏敏感值、计算新字段或添加静态元数据。
你将逻辑写成一条 SQL 查询,将其附加到 Logpush 作业,然后由 Cloudflare 在每批数据上运行。FROM 子句指定 Logpush 数据集(例如 http_requests 或 audit_logs_v2),字段名来自该数据集的 schema。
Transformers 适用于受支持 Logpush 数据集的 Free、Pro、Business 和 Enterprise 计划。每个 Cloudflare 账户每月包含 1 GB 转换输入。额外输入按每 GB $0.04 计费。更多信息请参阅 Logpush 定价。
- 基于 SQL 的转换 - 每个 Logpush 作业一条单语句 SQL 查询。
- 按记录执行 - 在 Cloudflare 投递批次之前,对每条 NDJSON 记录运行。
- 高级筛选与重塑 - 删除、重命名、脱敏、计算或标记字段。
- 无需重新部署即可附加和分离 - 从 Cloudflare 仪表板或 API 管理 transformers。
- 版本历史 - 每次保存都会创建新版本;旧版本仍可查看。
开始之前,你需要:
- 使用
ndjson输出格式的 Logpush 作业。Transformers 仅适用于 NDJSON 作业,并同时支持账户作用域和 zone 作用域的数据集。 - 如果使用 API,需要具有该账户
Logs Write权限的 API 令牌。 - 熟悉计划转换的记录所属 数据集。你的 SQL 会直接引用其字段名。
你可以通过 Cloudflare 仪表板或 API 创建、预览、附加和管理 transformers。
每个 Logpush 作业可以有 transformer 或 筛选器,但不能同时拥有两者。当你在 Cloudflare 仪表板中将 transformer 附加到已有筛选器的作业时,Transformer Studio 会将现有筛选器转换为等效的 SQL 谓词。
将谓词复制到 transformer 的 WHERE 子句中以保留筛选行为。确认附加后,Transformer Studio 会移除作业筛选器并附加 transformer。
API 不会将 Logpush 筛选器转换为 SQL。要通过 API 迁移带筛选器的作业,请将筛选器转换为等效 SQL 谓词并添加到 transformer 的 WHERE 子句。然后在同一 Logpush 作业更新请求中清空 filter 并设置 transformer_id:
{
"filter": "",
"transformer_id": 42
}如果设置 transformer_id 而未清空现有筛选器,API 会返回 400 响应。
Transformer Studio 是包含 SQL 编辑器的工作区,用于编写、预览和管理 Transformers。可从 Cloudflare 仪表板的 Logpush 页面打开。
前往 Logpush ↗在 Studio 中你可以:
- 通过对 Logpush 数据集编写 SQL 查询来创建新 transformer。
- 在保存前,针对目标数据集的预置示例记录预览 transformer。
- 将 transformer 附加到账户或 zone 上任何符合条件的 Logpush 作业。只有与 transformer 数据集匹配的 NDJSON 作业会显示为可附加目标。不会显示 CSV 作业。
- 从作业中分离 transformer。
- 每次编辑并保存 SQL 时保存新版本。旧版本仍可查看。
- 重命名 transformer 或更新其描述。
- 删除 transformer。只要仍有 Logpush 作业引用它,就不能删除。
所有 transformer 操作都可通过 Cloudflare API 使用。要完成身份验证,请使用具有 Logs Write 权限的 API 令牌。
| 操作 | 方法 | 端点 |
|---|---|---|
| 列出 transformers | GET |
accounts/:account_id/logpush/transformers |
| 创建 transformer | POST |
accounts/:account_id/logpush/transformers |
| 预览 transformer | POST |
accounts/:account_id/logpush/transformers/preview |
| 获取 transformer | GET |
accounts/:account_id/logpush/transformers/:id |
| 下载 SQL | GET |
accounts/:account_id/logpush/transformers/:id/content |
| 列出版本 | GET |
accounts/:account_id/logpush/transformers/:id/versions |
| 更新 transformer | PUT |
accounts/:account_id/logpush/transformers/:id |
| 删除 transformer | DELETE |
accounts/:account_id/logpush/transformers/:id |
以下请求创建一个 transformer,从 zone 作用域的 dns_logs 数据集中选择三个字段:
Required API token permissions
At least one of the following token permissions is required:Logs Write
curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/logpush/transformers" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"name": "dns-query-fields",
"description": "Selects key fields from DNS query logs.",
"code": "SELECT QueryName, QueryType, ResponseCode FROM dns_logs"
}'要从作业附加或分离 transformer,请在 Logpush 作业上设置 transformer_id。作业端点请参阅 Logpush 作业设置。
transformer 是一条 SQL 查询。Logpush 数据集是源表;查询输出成为投递记录。
SELECT ClientIP, RayID, EdgeResponseStatus
FROM http_requests
WHERE EdgeResponseStatus >= 400FROM 表名必须与 transformer 所附加 Logpush 作业的数据集匹配。如果不匹配,附加会失败。
不匹配 WHERE 子句的记录会从输出中丢弃。
Transformers 使用与 Basin Pipelines 相同的 SQL 方言。支持以下操作:
- 投影 -
SELECT特定字段,使用AS重命名,使用表达式计算新字段。 - 筛选 - 带有标准比较、布尔和空值检查运算符的
WHERE子句。 - CTE -
WITH ... AS (...)公用表表达式。 UNNEST- 将数组或列表字段展开为行。- JSON 访问 -
->运算符返回 JSON 对象;->>返回字符串。例如,RequestHeaders ->> 'Host'。 - 嵌套输出 -
named_struct('key', value, ...)构建嵌套 JSON 对象。 - 数组输出 -
[value1, value2]构建 JSON 数组。 - 标量函数 - 标准 SQL 函数,包括
UPPER、LOWER、COALESCE、CAST、extract和to_timestamp。
- Joins
- 子查询
- 聚合(
GROUP BY、HAVING、COUNT、SUM) - 窗口函数
ORDER BY- 多条语句 - 每个 transformer 一条查询
每条 SQL 查询在保存前都会对照目标数据集的 schema 进行验证。未知字段、错误类型、无效语法、未知数据集以及不支持的操作会在上传时被拒绝。
在仪表板中,验证错误会以内联方式显示在编辑器中,并带有行号和列号。通过 API 时,它们会返回在响应的 errors 数组中。
| 限制 | 值 |
|---|---|
| SQL 查询大小 | 250 KB |
| Transformer 名称长度 | 255 bytes |
| Transformer 描述长度 | 4,096 bytes |
| 查询对文件系统的访问 | 无 |
| 查询对网络的访问 | 无 |
| 批次分块大小 | 1,000 行 |
以下示例在单条查询中应用 主要功能 中的各项能力。每条查询都会保留一部分记录、重塑剩余记录,并丢弃下游管道不需要的字段。
此 transformer 仅保留审计跟踪中的 update 操作,并重塑剩余记录以便下游投递。具体而言,它会:
- 排除所有
ActionType不是update的记录。 - 将
ActionTimestamp从 RFC3339 转换为 Unix epoch 整数,并重命名为unix_ts。 - 将
ActionType转为大写并重命名为action_type。 - 添加值为
Cloudflare的硬编码provider字段。 - 将
ActorType、ActorEmail和ActorIPAddress分组到嵌套的actor对象中。 - 根据
ResourceType = 'zone'派生布尔标志is_zone。 - 从
ResourceType和ResourceID构建resource_meta数组。 - 通过在
SELECT中省略来丢弃ActorID、AccountID和ActorContext。
来自 audit_logs_v2 数据集的输入记录:
{
"ActionType": "update",
"ActorEmail": "[email protected]",
"ActorID": "a1b2c3d4",
"ActorIPAddress": "203.0.113.42",
"ActorType": "user",
"ActionTimestamp": "2026-05-21T15:00:00Z",
"AccountID": "90796717",
"ResourceID": "r1s2t3u4",
"ResourceType": "zone",
"ActorContext": "dashboard"
}Transformer:
SELECT
extract(epoch FROM to_timestamp(ActionTimestamp)) AS unix_ts,
UPPER(ActionType) AS action_type,
'Cloudflare' AS provider,
named_struct(
'type', ActorType,
'email', ActorEmail,
'ip', ActorIPAddress
) AS actor,
ResourceType = 'zone' AS is_zone,
[ResourceType, ResourceID] AS resource_meta
FROM audit_logs_v2
WHERE ActionType = 'update'投递记录:
{
"action_type": "UPDATE",
"actor": {
"email": "[email protected]",
"ip": "203.0.113.42",
"type": "user"
},
"is_zone": true,
"provider": "Cloudflare",
"resource_meta": ["zone", "r1s2t3u4"],
"unix_ts": 1779375600
}此 transformer 保留所有 HTTP 流量,但排除 健康检查、指标抓取器和面向内部的主机名。这是希望保留完整日志流、同时去掉可预期噪声的常见模式。具体而言,它会:
- 排除发往
internal.example.com和health.example.com的所有请求。 - 排除路径以
/healthz或/metrics开头的所有请求。 - 将
EdgeStartTimestamp从 RFC3339 转换为 Unix epoch 整数,并重命名为unix_ts。 - 将
ClientRequestMethod转为大写并重命名为method。 - 添加值为
Cloudflare的硬编码provider字段。 - 将
ClientRequestHost、ClientRequestPath和ClientRequestMethod分组到嵌套的request对象中。 - 根据
EdgeResponseStatus >= 500派生布尔标志is_server_error。 - 从
ClientRequestHost和ClientRequestPath构建request_meta数组。 - 通过在
SELECT中省略来丢弃ClientIP、ClientRequestUserAgent、RayID、OriginResponseTime和WAFAction。
来自 http_requests 数据集的输入记录:
{
"ClientIP": "203.0.113.42",
"ClientRequestHost": "example.com",
"ClientRequestMethod": "POST",
"ClientRequestPath": "/api/checkout",
"ClientRequestUserAgent": "curl/7.85.0",
"EdgeResponseStatus": 502,
"EdgeStartTimestamp": "2026-05-21T15:00:00Z",
"RayID": "8e2a1c60ef9e1c9a",
"OriginResponseTime": 3200000000,
"WAFAction": "unknown"
}此示例假设 EdgeStartTimestamp 以 RFC3339 字符串形式投递。如果你的作业以 Unix 纳秒投递时间戳,请去掉 to_timestamp() 包装,改为除以 1e9。
Transformer:
SELECT
extract(epoch FROM to_timestamp(EdgeStartTimestamp)) AS unix_ts,
UPPER(ClientRequestMethod) AS method,
'Cloudflare' AS provider,
named_struct(
'host', ClientRequestHost,
'path', ClientRequestPath,
'method', ClientRequestMethod
) AS request,
EdgeResponseStatus >= 500 AS is_server_error,
[ClientRequestHost, ClientRequestPath] AS request_meta
FROM http_requests
WHERE ClientRequestHost NOT IN ('internal.example.com', 'health.example.com')
AND ClientRequestPath NOT LIKE '/healthz%'
AND ClientRequestPath NOT LIKE '/metrics%'投递记录:
{
"is_server_error": true,
"method": "POST",
"provider": "Cloudflare",
"request": {
"host": "example.com",
"method": "POST",
"path": "/api/checkout"
},
"request_meta": ["example.com", "/api/checkout"],
"unix_ts": 1779375600
}| HTTP | 消息 | 原因 |
|---|---|---|
403 |
transformer feature is not available for this account |
你的账户无权使用 Transformers。 |
400 |
missing required field: name |
在请求正文中添加 name 字段。 |
400 |
missing required field: code |
添加包含 SQL 查询的非空 code 字段。 |
400 |
Schema validation error (unknown column, invalid syntax) | SQL 引用了不存在的字段、使用了不支持的语法,或存在类型不匹配。请修复查询后重试。 |
413 |
(request entity too large) | SQL 查询超过 250 KB。请缩短查询。 |
400 |
transformer N not found for this account |
transformer ID 不存在,或属于其他账户。 |
400 |
transformer N dataset "X" does not match job dataset "Y" |
transformer 的 FROM 表与作业数据集不匹配。 |
400 |
a job cannot have both a filter and a transformer configured; use one or the other |
在设置 transformer_id 的同一请求中清空作业的 filter。 |
如果 transformer 在处理某批次时失败,该批次会失败:不会为其投递任何内容,错误会记录在 Logpush 作业上,然后 Logpush 按正常计划重试该批次。没有自动回退到原始日志。
如果失败持续发生,受影响批次中的记录最终会被丢弃且无法恢复。
最近一次错误会出现在作业的 last_error 字段中。常见原因:
- 输出超过大小限制。 降低每条记录的输出,或使用
WHERE丢弃更多记录。 - 发生了 Cloudflare 内部错误。 请携带作业 ID 和时间戳联系 Cloudflare 支持。
要调试,请在 Transformer Studio 中打开 transformer,并使用 Run 按钮针对示例记录进行预览。验证和执行逻辑相同,因此生产中可见的问题通常也能在预览中复现。
- Logpush 数据集 - 你的 SQL 查询所引用的字段
- Logpush 作业设置 - 创建和管理 Logpush 作业
- 日志字段参考 - 各数据集的完整字段说明
- 筛选器 - 无需 SQL 的更简单筛选