← Cloudflare Logs / logs / logpush / logpush-job

Настройка API

В таблице ниже перечислены операции с заданиями, доступные как для заданий Logpush, так и для заданий Edge Log Delivery. Убедитесь, что для наборов данных на уровне аккаунта используется /accounts/{account_id} а наборы данных уровня зоны используют /zone/{zone_id}. Дополнительную информацию см. в Наборы данных страницу.

Найти {zone_id} и {account_id} аргументов на основе Найдите ID зоны и аккаунта страницу. {job_id} является числовым аргументом, например 123456. {dataset_id} указывает категорию лога (например, http_requests или audit_logs).

Конкретные примеры можно найти в руководствах в Примеры Logpush.

Для Logpush API, как и для любого другого API Cloudflare, требуются учётные данные.

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

Перед созданием нового задания необходимо подтвердить владение пунктом назначения.

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

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

В место назначения будет записан challenge-файл, а имя файла будет указано в ответе (имя файла может быть представлено в виде пути, если это уместно для вашего места назначения):

{
  "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): путь к bucket + ID аккаунта + R2 access key ID + R2 secret access key; например: r2://<BUCKET_PATH>?account-id=<ACCOUNT_ID>&access-key-id=<R2_ACCESS_KEY_ID>&secret-access-key=<R2_SECRET_ACCESS_KEY>
• AWS S3 (схема s3): bucket + необязательный каталог + регион + необязательный параметр шифрования (если это требуется вашей политикой); например: s3://bucket/[dir]?region=<REGION>[&sse=AES256]
• Datadog (схема datadog): URL-адрес конечной точки Datadog + API-ключ Datadog + необязательные параметры; например: datadog://<DATADOG_ENDPOINT_URL>?header_DD-API-KEY=<DATADOG_API_KEY>&ddsource=cloudflare&service=<SERVICE>&host=<HOST>&ddtags=<TAGS>
• Google Cloud Storage (схема gs): bucket + необязательный каталог; например: gs://bucket/[dir]
• Microsoft Azure (схема azure): SAS URL уровня сервиса с https заменено на azure + необязательный каталог, добавленный перед query string, например: azure://<BLOB_CONTAINER_PATH>/[dir]?<QUERY_STRING>
• New Relic (используйте схему https): URL-адрес конечной точки New Relic, который представляет собой https://log-api.newrelic.com/log/v1 для США или https://log-api.eu.newrelic.com/log/v1 для EU + ключ лицензии + формат; например, для US "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): URL-адрес конечной точки Splunk + ID канала Splunk + флаг insecure-skip-verify + sourcetype 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): URL-адрес источника HTTP с https заменено на sumo; например: sumo://<SUMO_ENDPOINT_URL>/receiver/v1/http/<UNIQUE_HTTP_COLLECTOR_CODE>
• SentinelOne (схема sentinelone): URL-адрес конечной точки SentinelOne + sourcetype SentinelOne + токен авторизации SentinelOne; например: sentinelone://<SENTINELONE_ENDPOINT_URL>?sourcetype=<SOURCE_TYPE>&header_Authorization=<SENTINELONE_AUTH_TOKEN>

Для R2, S3, Google Cloud Storage, а также Azure, вы можете упорядочить журналы по ежедневным подкаталогам, включив специальный заполнитель {DATE} в пути URL. Этот заполнитель будет автоматически заменен датой в YYYYMMDD в формате (например, 20180523).

Например:

• s3://mybucket/logs/{DATE}?region=us-east-1&sse=AES256
• azure://myblobcontainer/logs/{DATE}?[QueryString]

Такой подход удобен, если вы хотите группировать журналы по дням.

Дополнительную информацию о значении для вашего поставщика облачного хранилища см. в следующих соглашениях:

• AWS S3 CLI ↗ (тип аргумента пути S3Uri)
• Google Cloud Storage CLI ↗ (синтаксис для доступа к ресурсам)
• Microsoft Azure Shared Access Signature ↗
• Sumo Logic HTTP Source ↗

Чтобы проверить, используется ли уже место назначения:

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 набор данных.

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 функции Custom Log Formatting. Подробнее см. в Параметры вывода журнала документацию, где приведены инструкции по настройке этих параметров и обновлению существующих заданий для их использования.

Если вы всё ещё используете logpull_options, вот параметры, которые можно настроить:

1. Поля (необязательно): См. Наборы данных для доступных на данный момент полей. Список полей также доступен напрямую через 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.
2. Формат временной метки (необязательно): Формат, в котором будут возвращаться поля временной метки. Возможные значения: unixnano (единица измерения наносекунды, по умолчанию), unix (единица измерения секунды), rfc3339 (единица измерения секунды).
3. Маскирование данных для CVE-2021-44228 (необязательно): Эта опция заменит каждое вхождение ${ с x{. Чтобы включить эту функцию, задайте "CVE-2021-44228": true.

Чтобы проверить, что выбранный logpull_options допустимы:

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&timestamps=rfc3339&CVE-2021-44228=true",
		"dataset": "http_requests"
	}'

Ответ

{
  "errors": [],
  "messages": [],
  "result": {
    "valid": true,
    "message": ""
  },
  "success": true
}

Когда вы изменяете конфигурацию задания Logpush, изменения не вступают в силу сразу.

Если вы перенастраиваете задание на новую цель, в течение переходного периода журналы могут ещё около 10-15 минут отправляться на старую цель. Эта задержка позволяет системе завершить текущие загрузки и распространить новую конфигурацию по всей сети Cloudflare.

Когда вы добавляете новые поля в существующее задание Logpush, они появляются в ваших журналах примерно через 10-15 минут. Это время приблизительное и может меняться в зависимости от нагрузки на систему.

С помощью фильтров выберите события, которые нужно включить в журналы или исключить из них. Подробнее см. в Фильтры.

Значение может составлять от 0.0 (не включая) до 1.0 (включительно). sample=0.1 означает возврат 10% (1 из 10) всех записей. Значение по умолчанию: 1, это означает, что логи не будут проходить сэмплирование.

sample_rate параметр и SampleInterval являются независимыми механизмами, работающими на разных этапах конвейера логирования:

• sample_rate: Параметр конфигурации, который вы задаете в задании Logpush, чтобы управлять тем, какой процент логов доставляется в место назначения (0.0-1.0). Например, если задать значение sample_rate: 0.1 доставляет примерно 10% логов.

• SampleInterval: Поле данных, которое присутствует в некоторых наборах данных (в частности Журналы сетевой аналитики) указывающий на то, что при сборе данных применялось сэмплирование на стороне источника. Значение SampleInterval равное 1000 означает, что запись журнала представляет 1 из 1000 пакетов.

sample_rate который вы настраиваете, применяется поверх уже имеющегося сэмплирования. Если в ваших данных уже есть SampleInterval: 1000 и вы задаёте sample_rate: 0.1, вы получаете примерно 1 из 10,000 исходных событий (1000 × 10).

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

• Сократите max_upload_records если ваше место назначения плохо справляется с большими полезными нагрузками или ему не хватает памяти при обработке крупных пакетов.
• Увеличьте max_upload_records если вам нужно меньше файлов большего размера (например, при отправке в объектное хранилище, такое как R2 или S3).
• Для таких получателей, как Datadog, с жёсткими ограничениями на объём полезной нагрузки, Logpush автоматически использует пакеты меньшего размера (например, 1,000 строк).

Вы можете добавить в записи журнала HTTP-запросов пользовательские поля в виде заголовков HTTP-запросов, заголовков HTTP-ответов и cookies. Настройка пользовательских полей применяется ко всем заданиям Logpush в зоне, использующим набор данных HTTP requests. Подробнее см. Пользовательские поля.

Следующие действия Logpush регистрируются в Cloudflare Audit Logs: создание, обновление и удаление задания.