日志输出选项

Logpush 中的作业现在有一个新键 output_options，它取代了 logpull_options，并允许更灵活的格式设置。你可以通过 API 修改 output_options。

替换 logpull_options

以前，可以通过在 logpull_options 中以 URL 编码参数指定字段列表、采样率和时间戳格式来自定义 Logpush 作业。例如：

{
  "id": <JOB_ID>,
  "dataset": "http_requests",
  "enabled": false,
  "name": "<DOMAIN_NAME>",
  "logpull_options": "fields=ClientIP,EdgeStartTimestamp,RayID&sample=0.1&timestamps=rfc3339",
  "destination_conf": "s3://<BUCKET_PATH>?region=us-west-2"
}

我们已将其替换为 output_options，因为它同时用于 Logpull 和 Logpush。

{
  "id": <JOB_ID>,
  "dataset": "http_requests",
  "enabled": false,
  "name": "<DOMAIN_NAME>",
  "output_options": {
    "field_names": ["ClientIP", "EdgeStartTimestamp", "RayID"],
    "sample_rate": 0.1,
    "timestamp_format": "rfc3339"
  },
  "destination_conf": "s3://<BUCKET_PATH>?region=us-west-2"
}

:::caution[更新会完整替换 output_options]

当你通过 PUT /accounts/{account_id}/logpush/jobs/{job_id} 或 PUT /zones/{zone_id}/logpush/jobs/{job_id} 更新 Logpush 作业时，output_options 对象会被完整替换。任何先前已设置但从更新载荷中省略的字段将重置为默认值。例如，如果现有作业设置了 timestamp_format: "rfc3339"，而你的更新仅包含 field_names，则作业将恢复为默认 timestamp_format（对于通过 API 创建的作业为 unixnano）。更新作业时，请始终包含你希望应用的完整 output_options 对象。

输出类型

默认情况下，Logpush 将每条记录输出为单行 JSON（也称为 ndjson）。

使用 output_options，你可以切换为 CSV 或单个 JSON 对象，进一步自定义前缀、后缀、分隔符，或提供自己的记录模板（采用精简版 Go text/template ↗ 语法）。

output_options 对象具有以下设置：

field_names：字符串数组。目前没有一次添加所有字段的选项，你需要指定字段名称。
output_type：指定输出类型的字符串，例如 ndjson 或 csv（默认为 ndjson）。这会根据所选输出类型为其余设置设置默认值。某些格式规则（如字符串引号）在不同输出类型之间有所不同。
batch_prefix：在每个批次前添加的字符串。
batch_suffix：在每个批次后添加的字符串。
record_prefix：在每条记录前添加的字符串。
record_suffix：在每条记录后添加的字符串。
record_template：用作每条记录模板的字符串，而不是默认的逗号分隔列表。模板中使用的所有字段也必须出现在 field_names 中，否则它们将变为 null。格式为不包含任何标准函数（如条件、循环、子模板等）的 Go text/template。模板只能由以下三种类型的令牌组成：
- Action：这是 {{ .Field }} 或 {{ "constant text" }}。
- Text：这只是 {{ actions }} 之间的常量文本。
- Comment：{{/* comments */}} 会被静默丢弃。
record_delimiter：在记录之间作为分隔符插入的字符串。
field_delimiter：用于连接字段的字符串。设置 record_template 时将被忽略。
timestamp_format：指定时间戳格式的字符串。支持的值有：
- unixnano — 纳秒单位
- unix — 秒单位
- rfc3339 — 秒单位，例如：2024-02-17T23:52:01Z
- rfc3339ms — 毫秒单位，例如：2024-02-17T23:52:01.123Z
- rfc3339ns — 纳秒单位，例如：2024-02-17T23:52:01.123456789Z
除非显式设置，否则将应用默认时间戳格式。仪表板默认为 rfc3339，API 默认为 unixnano。
sample_rate：指定采样率的浮点数（默认 1.0：不采样）。采样在过滤之上应用，且与数据当前的 sample_interval 无关。
CVE-2021-44228：bool，默认为 false。如果设置为 true，将导致生成文件中所有 ${ 的出现被替换为 x{。

示例

指定 field_names 和 output_type 将导致其余选项按以下方式为指定的 output_type 配置：

ndjson

Default output_options for ndjson

{
	"record_prefix": "{",
	"record_suffix": "}\n",
	"field_delimiter": ","
}

Example output_options

"output_options": {
  "field_names": ["ClientIP", "EdgeStartTimestamp", "RayID"],
  "output_type": "ndjson"
}

Example output

{"ClientIP":"89.163.242.206","EdgeStartTimestamp":1506702504433000200,"RayID":"3a6050bcbe121a87"}
{"ClientIP":"89.163.242.207","EdgeStartTimestamp":1506702504433000300,"RayID":"3a6050bcbe121a88"}
{"ClientIP":"89.163.242.208","EdgeStartTimestamp":1506702504433000400,"RayID":"3a6050bcbe121a89"}

使用不同字段名称的 ndjson：

Example output_options

"output_options": {
  "field_names": ["ClientIP", "EdgeStartTimestamp", "RayID"],
  "output_type": "ndjson",
  "record_template": "\"client-ip\":{{.ClientIP}},\"timestamp\":{{.EdgeStartTimestamp}},\"ray-id\":{{.RayID}}"
}

Example output

{"client-ip":"89.163.242.206","timestamp":1506702504433000200,"ray-id":"3a6050bcbe121a87"}
{"client-ip":"89.163.242.207","timestamp":1506702504433000300,"ray-id":"3a6050bcbe121a88"}
{"client-ip":"89.163.242.208","timestamp":1506702504433000400,"ray-id":"3a6050bcbe121a89"}

带有双花括号 ({{}}) 的字面量，即 "double{{curly}}braces"，可以按照 go text/template 约定插入，即 "{{doublecurlybraces}}"。

csv

Default output_options for CSV

{
	"record_suffix": "\n",
	"field_delimiter": ","
}

Example output_options

"output_options": {
  "field_names": ["ClientIP", "EdgeStartTimestamp", "RayID"],
  "output_type": "csv"
}

Example output

"89.163.242.206",1506702504433000200,"3a6050bcbe121a87"
"89.163.242.207",1506702504433000300,"3a6050bcbe121a88"
"89.163.242.208",1506702504433000400,"3a6050bcbe121a89"

csv/json 变体

基于上述内容，还支持类似于 csv 或 json 的其他格式：

带表头的 csv：

Example output_options

"output_options": {
  "field_names": ["ClientIP", "EdgeStartTimestamp", "RayID"],
  "output_type": "csv",
  "batch_prefix": "ClientIP,EdgeStartTimestamp,RayID\n"
}

Example output

ClientIP,EdgeStartTimestamp,RayID
"89.163.242.206",1506702504433000200,"3a6050bcbe121a87"
"89.163.242.207",1506702504433000300,"3a6050bcbe121a88"
"89.163.242.208",1506702504433000400,"3a6050bcbe121a89"

带表头的 tsv：

Example output_options

"output_options": {
  "field_names": ["ClientIP", "EdgeStartTimestamp", "RayID"],
  "output_type": "csv",
  "batch_prefix": "ClientIP\tEdgeStartTimestamp\tRayID\n",
  "field_delimiter": "\t"
}

Example output

ClientIP EdgeStartTimestamp  RayID
"89.163.242.206"    1506702504433000200 "3a6050bcbe121a87"
"89.163.242.207"    1506702504433000300 "3a6050bcbe121a88"
"89.163.242.208"    1506702504433000400 "3a6050bcbe121a89"

带嵌套对象的 json：

Example output_options

"output_options": {
  "field_names": ["ClientIP", "EdgeStartTimestamp", "RayID"],
  "output_type": "ndjson",
  "batch_prefix": "{\"events\":[",
  "batch_suffix": "\n]}\n",
  "record_prefix": "\n  {\"info\":{",
  "record_suffix": "}}",
  "record_delimiter": ","
}

Example output

{
	"events": [
		{
			"info": {
				"ClientIP": "89.163.242.206",
				"EdgeStartTimestamp": 1506702504433000200,
				"RayID": "3a6050bcbe121a87"
			}
		},
		{
			"info": {
				"ClientIP": "89.163.242.207",
				"EdgeStartTimestamp": 1506702504433000300,
				"RayID": "3a6050bcbe121a88"
			}
		},
		{
			"info": {
				"ClientIP": "89.163.242.208",
				"EdgeStartTimestamp": 1506702504433000400,
				"RayID": "3a6050bcbe121a89"
			}
		}
	]
}

如何迁移

要将作业从使用 logpull_options 迁移到新的 output_options，请执行以下步骤：

将 &fields=ClientIP,EdgeStartTimestamp,RayID 参数更改为 output_options.field_names 中的数组。
将 &sample=0.1 参数更改为 output_options.sample_rate。
将 &timestamps=rfc3339 参数更改为 output_options.timestamp_format。
将 &CVE-2021-44228=true 参数更改为 output_options.CVE-2021-44228。

例如，如果 logpull_options 为 fields=ClientIP,EdgeStartTimestamp,RayID&sample=0.1&timestamps=rfc3339&CVE-2021-44228=true，则 output_options 将为：

"output_options": {
  "field_names": ["ClientIP", "EdgeStartTimestamp", "RayID"],
  "sample_rate": 0.1,
  "timestamp_format": "rfc3339",
  "CVE-2021-44228": true
}