← Cloudflare Logs / logs / logpush / logpush-job / enable-destinations

Включите Google BigQuery

Cloudflare Logpush поддерживает отправку журналов напрямую в Google BigQuery (с использованием Legacy Streaming API) через панель управления Cloudflare или API.

Cloudflare использует Google Application Credentials, указанные в задании Logpush destination_conf чтобы получить доступ на запись к таблице. Указанному сервисному аккаунту нужны права на запись в таблицу.

Чтобы включить Logpush для BigQuery:

1. Перейдите в Google Cloud Console для своей учётной записи.
2. Перейдите в IAM & Admin > Сервисные аккаунты, и создайте новую служебную учётную запись.
3. Добавить BigQuery Data Editor роль в разделе Permissions. Как минимум для этого требуется bigquery.tables.updateData разрешение.
4. Добавьте ключ в разделе Keys.
   1. Нажмите Добавить ключ.
   2. Нажмите Создать новый ключ.
   3. Выберите Key type JSON.
   4. Нажмите Создание.
   5. Сохраните файл Application Credentials JSON. Он понадобится вам при настройке нового задания Logpush.
5. Создайте набор данных и таблицу в BigQuery. См. инструкции от BigQuery ↗. Например, если использовать schema.json и bq команда:

gcloud auth activate-service-account --key-file=${KEY_FILE}

PROJECT_ID=<PROJECT_ID>
DATASET_ID=<DATASET_ID>
TABLE_ID=<TABLE_ID>

bq mk --table "${PROJECT_ID}:${DATASET_ID}.${TABLE_ID}" schema.json

1. На панели управления Cloudflare перейдите к разделу Logpush на уровне аккаунта или домена (также называемого зоной).

   Для аккаунта: Перейдите в Logpush ↗

   Для домена (также называемого зоной): Перейдите в Logpush ↗

2. В зависимости от выбора вам доступны наборы данных уровня аккаунта и наборы данных, привязанные к зоне, соответственно.

3. Выберите Создание задания Logpush.

4. В Выберите пункт назначения, выберите Google BigQuery.

5. Введите следующие данные о получателе:

   • Project ID - ID вашего проекта Google Cloud
   • ID набора данных - набор данных BigQuery, содержащий вашу таблицу
   • ID таблицы - таблица BigQuery, в которую передаются журналы
   • Service Account Credentials - вставьте JSON-ключ сервисного аккаунта Google. Эти учётные данные хранятся в зашифрованном виде и больше не отображаются.

Когда вы закончите вводить данные получателя, выберите Продолжение.

6. Выберите набор данных для отправки в хранилище.

7. На следующем шаге настройте задание Logpush:

   • Введите Название задания.
   • В разделе Если журналы соответствуют, вы можете выбрать, какие события включить в журналы или исключить из них. См. Фильтры с дополнительной информацией. Эта опция доступна не для всех наборов данных.
   • В Отправьте следующие поля, вы можете либо отправлять в хранилище назначения все журналы, либо выбирать, какие журналы отправлять.

8. В Advanced Options, вы можете:

   • Выберите формат полей отметки времени в своих журналах (RFC3339 (по умолчанию), Unix, или UnixNano).
   • Выберите частота сэмплирования для ваших журналов или отправлять случайно выбранный процент журналов.
   • Включите скрытие данных для CVE-2021-44228. Эта опция заменит каждое вхождение ${ с x{.

9. Выберите Отправить после того как настройка задания Logpush завершена.

Чтобы настроить задание Logpush для BigQuery:

1. Создайте задание, указав соответствующий URL конечной точки и параметры аутентификации.
2. Включите задание, чтобы оно начало отправлять журналы.

Убедитесь Log Share разрешения включены, прежде чем пытаться читать или настраивать задание Logpush. Дополнительные сведения см. в Раздел Roles.

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

• имя (необязательно) - Используйте имя своего домена в качестве имени задания.
• destination_conf - Получатель журналов, состоящий из ссылки на таблицу BigQuery и учётных данных в формате строки ниже.
  • <PROJECT_ID>, <DATASET_ID>, <TABLE_ID>: ID проекта, ID набора данных и ID таблицы указанной таблицы BigQuery.
  • <ENCODED_VALUE>: Закодированное значение файла Application Credentials JSON в виде credentials, либо в кодировке base64 с base64: префикса или в кодировке URL с url: префикс.

"bq://projects/<PROJECT_ID>/datasets/<DATASET_ID>/tables/<TABLE_ID>?credentials=<ENCODED_VALUE>"

• dataset - Категория журналов, которые вы хотите получать. См. Наборы данных для полного списка поддерживаемых наборов данных.
• output_options (необязательно) - Чтобы настроить поля, частоту выборки и формат временной метки, см. Параметры вывода журнала. Для временной метки Cloudflare рекомендует использовать timestamps=rfc3339.
  • При использовании пользовательских параметров форматирования, таких как output_type, либо любые параметры префикса, суффикса, разделителя или шаблона, обязательно задайте stringify_object также true, иначе поля с object типа может не сериализоваться в формате, совместимом с BigQuery Legacy Streaming API.

Пример запроса с использованием cURL:

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": "bq://projects/<PROJECT_ID>/datasets/<DATASET_ID>/tables/<TABLE_ID>?credentials=<ENCODED_VALUE>",
		"output_options": {
				"field_names": [
						"ClientIP",
						"ClientRequestHost",
						"ClientRequestMethod",
						"ClientRequestURI",
						"EdgeEndTimestamp",
						"EdgeResponseBytes",
						"EdgeResponseStatus",
						"EdgeStartTimestamp",
						"RayID"
				],
				"timestamp_format": "rfc3339"
		},
		"max_upload_bytes": 5000000,
		"max_upload_records": 50000,
		"dataset": "http_requests",
		"enabled": true
	}'

Ответ:

{
  "errors": [],
  "messages": [],
  "result": {
    "id": <JOB_ID>,
    "dataset": "http_requests",
    "kind": "",
    "max_upload_bytes": 5000000,
    "max_upload_records": 50000,
    "enabled": true,
    "name": "<DOMAIN_NAME>",
    "output_options": {
      "field_names": ["ClientIP", "ClientRequestHost", "ClientRequestMethod", "ClientRequestURI", "EdgeEndTimestamp", "EdgeResponseBytes", "EdgeResponseStatus" ,"EdgeStartTimestamp", "RayID"],
      "timestamp_format": "rfc3339"
    },
    "destination_conf": "bq://projects/<PROJECT_ID>/datasets/<DATASET_ID>/tables/<TABLE_ID>?credentials=<ENCODED_VALUE>",
    "last_complete": null,
    "last_error": null,
    "error_message": null
  },
  "success": true
}

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

См. Управлять Logpush с помощью cURL чтобы обновить задание (включая включение и отключение).

Учитывайте следующие квоту и лимиты по умолчанию, описанные в документация BigQuery ↗.

Для потоковой вставки в BigQuery действуют следующие ограничения:

• Максимальный размер HTTP-запроса (без сжатия, может включать заголовки): 10 MB
• Максимальный размер строки: 10 MB
• Максимальное количество строк на размер запроса: 50,000 строк.

Указаны квота и лимит по умолчанию. Настройте задания Logpush в соответствии с этим лимитом и, если необходимо, запросите у Google его увеличение.

Cloudflare Logpush поддерживает отправку журналов в Google Cloud Storage.

BigQuery поддерживает до 1,500 заданий загрузки на таблицу в сутки (включая неудачные), при этом каждая загрузка может содержать до 10 миллионов файлов. Это значит, что загружать данные в BigQuery можно раз в минуту, включая в каждую загрузку до 10 миллионов файлов. Подробнее см. в квотах BigQuery на задания загрузки.

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

Пример настройки запланированной загрузки задания в BigQuery, подготовленный сообществом, приведён в Cloudflare + Google Cloud | Репозиторий интеграций ↗. Обратите внимание, что этот репозиторий поддерживается по мере возможности и не обновляется на регулярной основе.