← Cloudflare Logs / logs / logpush / logpush-job

Пользовательские поля

Набор данных HTTP-запросов по умолчанию включает большинство стандартной информации журнала. Однако если вам нужно фиксировать дополнительные заголовки или файлы cookie запроса либо ответа, вы можете использовать настраиваемые поля, чтобы адаптировать журналы под свои задачи

Пользовательские поля настраиваются для каждой зоны отдельно. После настройки они включаются для всех заданий Logpush в этой зоне, которые используют набор данных HTTP requests и содержат поля заголовков запроса, заголовков ответа или cookie. Эти поля можно записывать в исходном виде или в виде преобразованных значений.

Это поведение по умолчанию можно изменить. Вы можете настроить регистрацию заголовков запроса или ответа в исходном или преобразованном виде, в зависимости от ваших потребностей, но не в обоих видах одновременно для одного и того же заголовка.

Пользовательские поля можно включить через API или в панели управления Cloudflare.

Используйте Rulesets API чтобы создать правило, которое настраивает пользовательские поля. Подробнее о таких концепциях, как фазы, наборы правил и правила, а также о доступных операциях API см. Ruleset Engine документация.

Чтобы настроить пользовательские поля:

1. Создайте правило для настройки списка пользовательских полей.
2. Включите Cookies, RequestHeaders, и/или ResponseHeaders в вашем задании Logpush.

Создайте правило, которое настраивает список пользовательских полей в http_log_custom_fields фазы на уровне зоны. Задайте для действия правила значение log_custom_field и выражение правила на true.

action_parameters объект, который нужно включить в правило, настраивающее список пользовательских полей, должен иметь следующую структуру:

"action_parameters": {
//select raw (default) or transformed request header
  "request_fields": [
    { "name": "<http_request_header_raw>" }
  ],
  "transformed_request_fields": [
    { "name": "<http_request_header_transformed>" }
  ],
//select raw or transformed (default) response header
  "response_fields": [
    { "name": "<http_response_header_transformed>" }
  ],
  "raw_response_fields": [
    { "name": "<http_response_header_raw>" }
  ],
  "cookie_fields": [
    { "name": "<cookie_name>" }
  ]
}

Убедитесь, что определение вашего правила соответствует следующим требованиям:

• Необходимо включить хотя бы один из следующих массивов в action_parameters объект: request_fields, transformed_request_fields, response_fields, raw_response_fields, а также cookie_fields.
• Имена заголовков HTTP-запроса и HTTP-ответа необходимо указывать в нижнем регистре.
• В названиях cookie учитывается регистр: указывайте их точно так же, как они записаны в HTTP-запросе.
• Выражение правила необходимо задать как true.
• Для одного и того же заголовка запроса или ответа можно регистрировать либо исходные, либо преобразованные значения, но не оба варианта одновременно.

Чтобы создать правило, выполните следующие действия:

1. Используйте Список наборов правил зоны операцию, чтобы проверить, существует ли уже ruleset точки входа для http_log_custom_fields фазы на уровне зоны (на каждую фазу может быть только один входной набор правил):

   Список наборов правил зоны

   curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets" \
   	--request GET \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

   Если существует входной ruleset для http_log_custom_fields фазу (то есть набор правил с "kind": "zone" и "phase": "http_log_custom_fields"), запишите идентификатор ruleset.

2. (Необязательно) Если в ответе не было ruleset с "kind": "zone" и "phase": "http_log_custom_fields", создайте ruleset точки входа фазы с помощью Создание набора правил зоны операцию:

   Создание набора правил зоны

   curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets" \
   	--request POST \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
   	--json '{
   		"name": "Zone-level phase entry point",
   		"kind": "zone",
   		"description": "This ruleset configures custom log fields.",
   		"phase": "http_log_custom_fields"
   	}'

   Обратите внимание на ID набора правил, указанный в ответе.

3. Используйте Обновление набора правил зоны операцию, чтобы задать правила найденного (или созданного на предыдущем шаге) входного набора правил, добавив правило с конфигурацией пользовательских полей. Правила, включённые в запрос, заменят все правила в наборе правил.

   Следующий пример настраивает пользовательские поля с именами заголовков HTTP-запроса, заголовков HTTP-ответа и cookie-файлов, которые нужно включить в журналы Logpush:

   Обновление набора правил зоны

   curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID" \
   	--request PUT \
   	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
   	--json '{
   		"rules": [
   				{
   						"action": "log_custom_field",
   						"expression": "true",
   						"description": "Set Logpush custom fields for HTTP requests",
   						"action_parameters": {
   								"request_fields": [
   										{
   												"name": "content-type"
   										},
   										{
   												"name": "x-forwarded-for"
   										}
   								],
   								"transformed_request_fields": [
   										{
   												"name": "host"
   										}
   								],
   								"response_fields": [
   										{
   												"name": "server"
   										},
   										{
   												"name": "content-type"
   										}
   								],
   								"raw_response_fields": [
   										{
   												"name": "allow"
   										}
   								],
   								"cookie_fields": [
   										{
   												"name": "__ga"
   										},
   										{
   												"name": "accountNumber"
   										},
   										{
   												"name": "__cfruid"
   										}
   								]
   						}
   				}
   		]
   	}'

   {
   	"result": {
   		"id": "<RULESET_ID>",
   		"name": "Zone-level phase entry point",
   		"description": "This ruleset configures custom log fields.",
   		"kind": "zone",
   		"version": "2",
   		"rules": [
   			{
   				"id": "<RULE_ID_1>",
   				"version": "1",
   				"action": "log_custom_field",
   				"action_parameters": {
   					"request_fields": [
   						{ "name": "content-type" },
   						{ "name": "x-forwarded-for" }
   					],
   					"transformed_request_fields": [{ "name": "host" }],
   					"response_fields": [
   						{ "name": "server" },
   						{ "name": "content-type" }
   					],
   					"raw_response_fields": [{ "name": "allow" }],
   					"cookie_fields": [
   						{ "name": "__ga" },
   						{ "name": "accountNumber" },
   						{ "name": "__cfruid" }
   					]
   				},
   				"expression": "true",
   				"description": "Set Logpush custom fields for HTTP requests",
   				"last_updated": "2021-11-21T11:02:08.769537Z",
   				"ref": "<RULE_REF_1>",
   				"enabled": true
   			}
   		],
   		"last_updated": "2021-11-21T11:02:08.769537Z",
   		"phase": "http_log_custom_fields"
   	},
   	"success": true,
   	"errors": [],
   	"messages": []
   }

Некоторые заголовки, отправленные origin-сервером, например set-cookie : могут содержать несколько значений, которые вы хотите зафиксировать. Вы можете использовать Rulesets API, чтобы указать, для каких заголовков нужно логировать все значения.

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/rulesets/$RULESET_ID" \
	--request PUT \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
	--json '{
		"rules": [
				{
						"action": "log_custom_field",
						"expression": "true",
						"description": "Set Logpush custom fields for HTTP requests",
						"action_parameters": {
								"response_fields": [
										{
												"name": "set-cookie",
												"preserve_duplicates": true
										}
								]
						}
				}
		]
	}'

Обратите внимание, что preserve_duplicates применяется как к response_fields и raw_response_fields. Если ни одно правило Transform Rules не затрагивает заголовок, включая preserve_duplicates в любом из response_fields или raw_response_fields должно дать тот же результат.

В этом примере все значения set-cookie заголовки будут регистрироваться. Они будут отображаться как массив строковых значений в ResponseFields, например:

{
  // ...
  "ResponseFields": {
    "set-cookie": ["name1=val1", "name2=val2", ...]
  }
}

Извлечь эти значения можно с помощью Worker или собственной логики на стороне получателя Logpush.

Далее включите Cookies, RequestHeaders, ResponseHeaders, и/или ResponseFields, в зависимости от настройки пользовательских полей, в списке полей output_options параметр задания при создании или обновлении задания. Журналы будут содержать настроенные пользовательские поля и их значения в запросе и ответе.

Например, рассмотрим следующий запрос, который создаёт задание с пользовательскими полями:

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": [
						"RayID",
						"EdgeStartTimestamp",
						"Cookies",
						"RequestHeaders",
						"ResponseHeaders"
				],
				"timestamp_format": "rfc3339"
		},
		"ownership_challenge": "<OWNERSHIP_CHALLENGE_TOKEN>"
	}'

1. На панели управления Cloudflare перейдите к разделу Logpush страницу.

   Перейдите в Logpush ↗

2. В Пользовательские поля журнала разделе выберите Редактировать пользовательские поля.

3. Выберите Настроить новое пользовательское поле.

4. Из раздела Тип поля раскрывающемся списке выберите Заголовок запроса, Заголовок ответа или Cookies и введите Имя поля.

5. Когда закончите, выберите Save.

Чтобы регистрировать в журнале данные сертификата mTLS (например, cf-cert-subject-dn или cf-cert-issuer-dn) в Logpush необходимо выполнить следующее:

1. Включить Добавление заголовков TLS-аутентификации клиента Managed Transform для добавления заголовков сертификата.
2. Настройте пользовательские поля Logpush с помощью transformed_request_fields (не request_fields) чтобы захватывать эти заголовки, добавленные Cloudflare.
3. Убедитесь, что ваше задание Logpush включает RequestHeaders поле.

Заголовки mTLS Cloudflare добавляет после получения запроса клиента, поэтому их нужно перехватывать с помощью transformed_request_fields вместо request_fields.

Дополнительную информацию о настройке клиентских сертификатов см. в аутентификация mTLS.

• Пользовательские поля позволяют указать до 100 заголовков на тип поля: это ограничение действует отдельно для request_fields, transformed_request_fields, response_fields, raw_response_fields, а также cookie_fields.
• Заголовок запроса Range в настоящее время не поддерживается функцией Custom Fields.
• Преобразованные и необработанные значения заголовков запроса и ответа доступны только через API. Задать их через интерфейс нельзя.