下表汇总了 Logpush 和 Edge Log Delivery 作业可用的作业操作。账户范围数据集使用 /accounts/{account_id},zone 范围数据集使用 /zones/{zone_id}。有关详细信息,请参阅数据集。
HTTP 请求和防火墙事件数据集支持两种范围。要收集账户中每个 zone 的日志,请通过 /accounts/{account_id}/logpush/jobs 端点为数据集创建账户范围作业。使用 ZoneName 字段识别每条日志记录的来源 zone。
你可以根据查找 zone 和账户 ID 页面找到 {zone_id} 和 {account_id} 参数。
{job_id} 参数是数字,例如 123456。
{dataset_id} 参数表示日志类别(例如 http_requests 或 audit_logs)。
| 操作 | 说明 | API |
|---|---|---|
POST |
创建作业 | 文档 |
GET |
检索作业详细信息 | 文档 |
GET |
检索所有数据集的所有作业 | 文档 |
GET |
检索数据集的所有作业 | 文档 |
GET |
检索数据集的所有可用字段 | 文档 |
PUT |
更新作业 | 文档 |
DELETE |
删除作业 | 文档 |
POST |
检查目标是否存在 | 文档 |
POST |
获取所有权质询 | 文档 |
POST |
验证所有权质询 | 文档 |
POST |
验证日志选项 | 文档 |
有关具体示例,请参阅 Logpush 示例中的教程。
与任何其他 Cloudflare API 一样,Logpush API 需要凭据。
Required API token permissions
At least one of the following token permissions is required:Logs Write
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/jobs" \
--request GET \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"创建新作业前,必须证明目标的所有权。
要向目标发出所有权质询令牌:
Required API token permissions
At least one of the following token permissions is required:Logs Write
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/ownership" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"destination_conf": "s3://<BUCKET_PATH>?region=us-west-2"
}'系统会将质询文件写入目标,响应中会包含文件名(如果适合你的目标,文件名可能表示为路径):
{
"errors": [],
"messages": [],
"result": {
"valid": true,
"message": "",
"filename": "<PATH_TO_CHALLENGE_FILE>.txt"
},
"success": true
}创建作业时,需要提供文件中包含的令牌。
你可以通过必需的 destination_conf 参数指定云服务提供商目标。
destination_conf 参数必须采用以下格式:
<scheme>://<destination-address>下面列出了支持的方案,每种方案针对 R2、S3 等特定提供商。此外,还涵盖了 https 等通用用例:
r2,gs,s3,sumo,https,azure,splunk,sentinelone,datadog.
destination-address 通常应由目标提供商提供。但是,对于某些提供商,我们要求 destination-address 遵循特定格式:
- Cloudflare R2(方案
r2):存储桶路径 + 账户 ID + R2 访问密钥 ID + R2 机密访问密钥;例如:r2://<BUCKET_PATH>?account-id=<ACCOUNT_ID>&access-key-id=<R2_ACCESS_KEY_ID>&secret-access-key=<R2_SECRET_ACCESS_KEY> - AWS S3(方案
s3):存储桶 + 可选目录 + 区域 + 可选加密参数(如果策略要求);例如:s3://bucket/[dir]?region=<REGION>[&sse=AES256] - Datadog(方案
datadog):Datadog 端点 URL + Datadog API 密钥 + 可选参数;例如:datadog://<DATADOG_ENDPOINT_URL>?header_DD-API-KEY=<DATADOG_API_KEY>&ddsource=cloudflare&service=<SERVICE>&host=<HOST>&ddtags=<TAGS> - Google Cloud Storage(方案
gs):存储桶 + 可选目录;例如:gs://bucket/[dir] - Microsoft Azure(方案
azure):将https替换为azure的服务级 SAS URL + 在查询字符串前添加的可选目录;例如:azure://<BLOB_CONTAINER_PATH>/[dir]?<QUERY_STRING> - New Relic(使用方案
https):New Relic 端点 URL(美国为https://log-api.newrelic.com/log/v1,欧盟为https://log-api.eu.newrelic.com/log/v1)+ 许可证密钥 + 格式;例如,美国为"https://log-api.newrelic.com/log/v1?Api-Key=<NR_LICENSE_KEY>&format=cloudflare",欧盟为"https://log-api.eu.newrelic.com/log/v1?Api-Key=<NR_LICENSE_KEY>&format=cloudflare" - Splunk(方案
splunk):Splunk 端点 URL + Splunk 通道 ID + 跳过不安全验证标志 + Splunk 源类型 + Splunk 授权令牌;例如:splunk://<SPLUNK_ENDPOINT_URL>?channel=<SPLUNK_CHANNEL_ID>&insecure-skip-verify=<INSECURE_SKIP_VERIFY>&sourcetype=<SOURCE_TYPE>&header_Authorization=<SPLUNK_AUTH_TOKEN> - Sumo Logic(方案
sumo):将https替换为sumo的 HTTP 源地址 URL;例如:sumo://<SUMO_ENDPOINT_URL>/receiver/v1/http/<UNIQUE_HTTP_COLLECTOR_CODE> - SentinelOne(方案
sentinelone):SentinelOne 端点 URL + SentinelOne 源类型 + SentinelOne 授权令牌;例如:sentinelone://<SENTINELONE_ENDPOINT_URL>?sourcetype=<SOURCE_TYPE>&header_Authorization=<SENTINELONE_AUTH_TOKEN>
对于 R2、S3、Google Cloud Storage 和 Azure,可以在 URL 路径中包含特殊占位符 {DATE},将日志整理到每日子目录中。此占位符会自动替换为 YYYYMMDD 格式的日期(例如 20180523)。
例如:
s3://mybucket/logs/{DATE}?region=us-east-1&sse=AES256azure://myblobcontainer/logs/{DATE}?[QueryString]
当你希望按天对日志进行分组时,此方法很有用。
有关云存储提供商的值的详细信息,请参阅以下约定:
- AWS S3 CLI ↗(S3Uri 路径参数类型)
- Google Cloud Storage CLI ↗(访问资源的语法)
- Microsoft Azure 共享访问签名 ↗
- Sumo Logic HTTP 源 ↗
要检查目标是否已在使用:
Required API token permissions
At least one of the following token permissions is required:Logs Write
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/validate/destination/exists" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"destination_conf": "s3://foo"
}'响应
{
"errors": [],
"messages": [],
"result": {
"exists": false
},
"success": true
}人类可读的可选作业名称,无需唯一。建议选择有意义的名称(例如域名),以便轻松识别和管理作业。以后可根据需要更新名称。
可选的 kind 参数用于区分 Logpush 和 Edge Log Delivery 作业。对于 Logpush 作业,可以将此参数留空或省略。对于 Edge Log Delivery 作业,请设置 "kind": "edge"。目前,Edge Log Delivery 仅支持 http_requests 数据集。
Required API token permissions
At least one of the following token permissions is required:Logs Write
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/jobs" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"name": "<DOMAIN_NAME>",
"destination_conf": "s3://<BUCKET_PATH>?region=us-west-2",
"dataset": "http_requests",
"output_options": {
"field_names": [
"ClientIP",
"ClientRequestHost",
"ClientRequestMethod",
" ClientRequestURI",
"EdgeEndTimestamp",
"EdgeResponseBytes",
"EdgeResponseStatus",
"EdgeStartTimestamp",
"RayID"
],
"timestamp_format": "rfc3339"
},
"kind": "edge"
}'Logpull_options 已替换为自定义日志格式化 output_options。有关配置这些选项以及更新现有作业以使用这些选项的说明,请参阅日志输出选项文档。
如果仍在使用 logpull_options,可以自定义以下选项:
- 字段(可选):有关当前可用字段,请参阅数据集。也可以直接从 API 访问字段列表:
https://api.cloudflare.com/client/v4/zones/{zone_id}/logpush/datasets/{dataset_id}/fields。默认字段:https://api.cloudflare.com/client/v4/zones/{zone_id}/logpush/datasets/{dataset_id}/fields/default。 - 时间戳格式(可选):返回时间戳字段的格式。值选项:
unixnano(纳秒单位,默认)、unix(秒单位)、rfc3339(秒单位)。 - 针对 CVE-2021-44228 的编辑(可选):此选项会将每次出现的
${替换为x{。要启用,请设置"CVE-2021-44228": true。
要检查所选 logpull_options 是否有效:
Required API token permissions
At least one of the following token permissions is required:Logs Write
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/validate/origin" \
--request POST \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--json '{
"logpull_options": "fields=RayID,ClientIP,EdgeStartTimestamp×tamps=rfc3339&CVE-2021-44228=true",
"dataset": "http_requests"
}'响应
{
"errors": [],
"messages": [],
"result": {
"valid": true,
"message": ""
},
"success": true
}修改 Logpush 作业配置时,更改不会立即生效。
如果重新配置作业以使用新目标,在过渡期间,日志可能会继续发送到旧目标约 10-15 分钟。此延迟让系统能够完成正在进行的上传,并在 Cloudflare 网络中传播新配置。
向现有 Logpush 作业添加新字段时,新字段会在大约 10-15 分钟内出现在日志中。此时间为估计值,可能因系统负载而异。
使用过滤器选择要包含在日志中的事件和/或从中移除的事件。有关详细信息,请参阅过滤器。
在仪表板中,选择 Advanced Options 下的 Exclude DDoS attack traffic。对于 API,将 filter_attack_traffic 设置为 true。默认值为 false。
此设置支持以下数据集:
- HTTP 请求 (
http_requests) - 防火墙事件 (
firewall_events) - Network Analytics Logs (
network_analytics_logs)
然后,Logpush 会从日志中排除已识别的 DDoS 攻击流量。
取值范围为 0.0(不含)到 1.0(含)。sample=0.1 表示返回全部记录的 10%(每 10 条取 1 条)。默认值为 1,表示日志不进行采样。
sample_rate 参数和 SampleInterval 字段是相互独立的机制,分别作用于日志管道的不同阶段:
-
sample_rate:你在 Logpush 作业中设置的配置参数,用于控制发送到目标位置的日志比例(0.0–1.0)。例如,设置sample_rate: 0.1会发送约 10% 的日志。 -
SampleInterval:某些数据集(尤其是 Network Analytics Logs)中包含的数据字段,表示数据收集期间上游应用的采样。SampleInterval为 1000 表示每条日志代表 1000 个数据包中的 1 个。
你配置的 sample_rate 会叠加在任何已有采样之上。如果数据已具有 SampleInterval: 1000,而你又设置 sample_rate: 0.1,那么收到的数据约为原始事件的万分之一(1000 × 10)。
这些参数用于控制每个上传批次的大小,而非数据的传输速度。你可以使用这些参数,避免因上传批次过大或过小而使目标位置过载。
| 参数 | 说明 | 默认值 |
|---|---|---|
max_upload_bytes |
每批日志的最大未压缩文件大小。 | 因目标位置而异 |
max_upload_records |
每批日志行的最大数量。 | 100,000 |
max_upload_interval_seconds |
每批日志数据的最大时间跨度(用于追赶处理场景)。 | 因目标位置而异 |
- 如果目标位置难以处理大型负载,或处理大批次时内存不足,请降低
max_upload_records。 - 如果你希望减少文件数量并增大文件尺寸(例如推送到 R2 或 S3 等对象存储),请提高
max_upload_records。 - 对于 Datadog 等有严格负载限制的目标位置,Logpush 会自动采用较小的批次(例如 1,000 行)。
你可以在 HTTP 请求日志条目中添加自定义字段,包括 HTTP 请求标头、HTTP 响应标头和 Cookie。自定义字段配置适用于 zone 中所有使用 HTTP requests 数据集的 Logpush 作业。更多信息请参阅自定义字段。
以下 Logpush 操作会记录在 Cloudflare Audit Logs 中:创建、更新和删除作业。