ログ出力オプション

Logpush のジョブには、logpull_options に代わる新しいキー output_options があり、より柔軟に形式を指定できます。output_options は API から変更できます。

logpull_options を置き換える

これまでは、Logpush ジョブのカスタマイズは、フィールド一覧、サンプリングレート、タイムスタンプ形式を logpull_options に URL エンコードしたパラメーターとして指定して行っていました。例:

{
  "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"
}

Logpull と Logpush の両方で使うため、これを output_options に置き換えました。

{
  "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"
}

出力タイプ

デフォルトでは、Logpush は各レコードを 1 行の 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 形式で指定します。テンプレートは、次の 3 種類のトークンだけで構成できます。
- アクション: {{ .Field }} または {{ "constant text" }} です。
- テキスト: {{ actions }} の間にある単なる定数テキストです。
- コメント: {{/* 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

ndjson のデフォルト output_options

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

output_options の例

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

出力例

{"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:

output_options の例

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

出力例

{"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

CSV のデフォルト output_options

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

output_options の例

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

出力例

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

csv / json のバリエーション

上記を基に、csv や json に近い他の形式もサポートしています。

ヘッダー付き csv:

output_options の例

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

出力例

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

ヘッダー付き tsv:

output_options の例

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

出力例

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

ネストしたオブジェクトの json:

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": ","
}

出力例

{
	"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
}