← Cloudflare Logs / logs / logpush

Transformers

Transformers позволяют выполнить SQL-запрос над каждым пакетом записей до того, как Logpush доставит их получателю. Используйте их, чтобы отфильтровать ненужные записи, привести поля в соответствие с целевой схемой, скрыть конфиденциальные значения, вычислить новые поля или добавить статические метаданные.

Логика записывается в виде одного SQL-запроса, который прикрепляется к заданию Logpush, и Cloudflare выполняет его для каждого пакета данных. Запрос FROM указывает набор данных Logpush (например, http_requests или audit_logs_v2) и имена полей берутся из схемы этого набора данных.

• Преобразования на основе SQL - один SQL-запрос с одним оператором на задание Logpush.
• Выполнение на одну запись - выполняется для каждой записи NDJSON перед тем, как Cloudflare доставит пакет.
• Расширенная фильтрация и изменение структуры - удаление, переименование, скрытие, вычисление или маркировка полей.
• Подключение и отключение без повторного развёртывания - управление трансформерами через дашборд Cloudflare или API.
• История версий - каждое сохранение создаёт новую версию; более старые версии остаются доступными для просмотра.

Прежде чем начать, вам потребуется:

• Задание Logpush, которое использует ndjson формата вывода. Преобразователи доступны только для заданий NDJSON и поддерживаются как для наборов данных уровня аккаунта, так и для наборов данных уровня зоны.
• API-токен с разрешением Logs Write разрешение для аккаунта.
• Знакомство с dataset записи которой вы планируете преобразовать. Ваш SQL обращается напрямую к именам её полей.

Трансформеры можно создавать, просматривать, подключать и настраивать через панель управления Cloudflare или API.

Transformer Studio представляет собой рабочую область с редактором SQL, где вы пишете, просматриваете и создаёте Transformers, а также управляете ими. Откройте её со страницы Logpush в дашборде Cloudflare.

В Studio вы можете:

• Создайте новый трансформер, написав SQL-запрос к набору данных Logpush.
• Перед сохранением проверьте работу трансформера на заранее подготовленной образцовой записи целевого набора данных.
• Подключите transformer к любому подходящему заданию Logpush в аккаунте или зоне. В качестве доступных целей для подключения отображаются только задания NDJSON, соответствующие набору данных transformer. Задания CSV не отображаются.
• Отключите трансформер от задания.
• При каждом редактировании и сохранении SQL-запроса создаётся новая версия. Более старые версии остаются доступными для просмотра.
• Переименуйте трансформер или обновите его описание.
• Удалите трансформер. Трансформер нельзя удалить, пока на него ссылается хотя бы одно задание Logpush.

Все действия трансформера доступны через Cloudflare API. Для аутентификации используйте API-токен на Logs Write разрешение.

Чтобы подключить или отключить трансформатор от задания, задайте transformer_id для задания Logpush. См. Настройка задания Logpush для конечных точек заданий.

Трансформер представляет собой один SQL-запрос. Исходной таблицей служит набор данных Logpush, а результат запроса становится доставляемой записью.

SELECT ClientIP, RayID, EdgeResponseStatus
FROM http_requests
WHERE EdgeResponseStatus >= 400

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

Записи, которые не соответствуют WHERE исключаются из вывода.

Transformers используют тот же диалект SQL, что и Cloudflare Pipelines. Поддерживаются следующие операции:

• Проекция - SELECT определённые поля, переименуйте их с помощью AS, вычисляйте новые поля с помощью выражений.
• Фильтрация - WHERE с помощью стандартных операторов сравнения, логических операторов и операторов проверки на null.
• CTEs - WITH ... AS (...) общих табличных выражений (CTE).
• UNNEST - разворачивание полей типа array или list в строки.
• Доступ JSON - -> оператор возвращает объект JSON; ->> возвращает строку. Например, RequestHeaders ->> 'Host'.
• Вложенный вывод - named_struct('key', value, ...) формирует вложенный объект JSON.
• Вывод в виде массива - [value1, value2] формирует массив JSON.
• Скалярные функции - стандартные функции SQL, включая UPPER, LOWER, COALESCE, CAST, extract, а также to_timestamp.

• Joins
• Подзапросы
• Агрегация (GROUP BY, HAVING, COUNT, SUM)
• Оконные функции
• ORDER BY
• Несколько операторов: один запрос на трансформер

Каждый SQL-запрос перед сохранением проверяется на соответствие схеме целевого набора данных. Неизвестные поля, неверные типы, синтаксические ошибки, неизвестные наборы данных и неподдерживаемые операции отклоняются уже на этапе загрузки.

В панели управления ошибки проверки отображаются прямо в редакторе с указанием номера строки и столбца. Через API они возвращаются в errors массив ответа.

Приведённые ниже примеры используют все возможности из Ключевые функции в одном запросе. Каждый оставляет подмножество записей, преобразует оставшиеся и отбрасывает поля, которые не нужны последующей части конвейера.

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

• Исключает все записи, у которых ActionType не update.
• Преобразует ActionTimestamp из формата RFC3339 в целое число Unix epoch, переименованное в unix_ts.
• Переводит в верхний регистр ActionType и переименовывает его в action_type.
• Добавляет жёстко заданный provider со значением Cloudflare.
• Группы ActorType, ActorEmail, а также ActorIPAddress во вложенный actor объект.
• Вычисляет логическое значение is_zone флаг из ResourceType = 'zone'.
• Создаёт resource_meta массив из ResourceType и ResourceID.
• Отброшено ActorID, AccountID, а также ActorContext путём исключения из SELECT.

Входная запись из audit_logs_v2 набор данных:

{
  "ActionType": "update",
  "ActorEmail": "[email protected]",
  "ActorID": "a1b2c3d4",
  "ActorIPAddress": "203.0.113.42",
  "ActorType": "user",
  "ActionTimestamp": "2026-05-21T15:00:00Z",
  "AccountID": "90796717",
  "ResourceID": "r1s2t3u4",
  "ResourceType": "zone",
  "ActorContext": "dashboard"
}

Transformer:

SELECT
  extract(epoch FROM to_timestamp(ActionTimestamp)) AS unix_ts,
  UPPER(ActionType) AS action_type,
  'Cloudflare' AS provider,
  named_struct(
    'type', ActorType,
    'email', ActorEmail,
    'ip', ActorIPAddress
  ) AS actor,
  ResourceType = 'zone' AS is_zone,
  [ResourceType, ResourceID] AS resource_meta
FROM audit_logs_v2
WHERE ActionType = 'update'

Доставленная запись:

{
  "action_type": "UPDATE",
  "actor": {
    "email": "[email protected]",
    "ip": "203.0.113.42",
    "type": "user"
  },
  "is_zone": true,
  "provider": "Cloudflare",
  "resource_meta": ["zone", "r1s2t3u4"],
  "unix_ts": 1779375600
}

Этот трансформатор сохраняет весь HTTP-трафик кроме проверки работоспособности, сборщики метрик и внутренние имена хостов. Это распространенный подход для команд, которым нужен полный поток журналов без предсказуемого шума. А именно, он:

• Исключает все запросы к internal.example.com и health.example.com.
• Исключает все запросы к путям, начинающимся с /healthz или /metrics.
• Преобразует EdgeStartTimestamp из формата RFC3339 в целое число Unix epoch, переименованное в unix_ts.
• Переводит в верхний регистр ClientRequestMethod и переименовывает его в method.
• Добавляет жёстко заданный provider со значением Cloudflare.
• Группы ClientRequestHost, ClientRequestPath, а также ClientRequestMethod во вложенный request объект.
• Вычисляет логическое значение is_server_error флаг из EdgeResponseStatus >= 500.
• Создаёт request_meta массив из ClientRequestHost и ClientRequestPath.
• Отброшено ClientIP, ClientRequestUserAgent, RayID, OriginResponseTime, а также WAFAction путём исключения из SELECT.

Входная запись из http_requests набор данных:

{
  "ClientIP": "203.0.113.42",
  "ClientRequestHost": "example.com",
  "ClientRequestMethod": "POST",
  "ClientRequestPath": "/api/checkout",
  "ClientRequestUserAgent": "curl/7.85.0",
  "EdgeResponseStatus": 502,
  "EdgeStartTimestamp": "2026-05-21T15:00:00Z",
  "RayID": "8e2a1c60ef9e1c9a",
  "OriginResponseTime": 3200000000,
  "WAFAction": "unknown"
}

Этот пример предполагает EdgeStartTimestamp передается в виде строки формата RFC3339. Если ваше задание передает временные метки в виде наносекунд Unix, уберите to_timestamp() обёртку и вместо этого делите на 1e9.

Transformer:

SELECT
  extract(epoch FROM to_timestamp(EdgeStartTimestamp)) AS unix_ts,
  UPPER(ClientRequestMethod) AS method,
  'Cloudflare' AS provider,
  named_struct(
    'host', ClientRequestHost,
    'path', ClientRequestPath,
    'method', ClientRequestMethod
  ) AS request,
  EdgeResponseStatus >= 500 AS is_server_error,
  [ClientRequestHost, ClientRequestPath] AS request_meta
FROM http_requests
WHERE ClientRequestHost NOT IN ('internal.example.com', 'health.example.com')
  AND ClientRequestPath NOT LIKE '/healthz%'
  AND ClientRequestPath NOT LIKE '/metrics%'

Доставленная запись:

{
  "is_server_error": true,
  "method": "POST",
  "provider": "Cloudflare",
  "request": {
    "host": "example.com",
    "method": "POST",
    "path": "/api/checkout"
  },
  "request_meta": ["example.com", "/api/checkout"],
  "unix_ts": 1779375600
}

Если при обработке пакета трансформер завершается с ошибкой, весь пакет считается не обработанным: он не доставляется, в задании Logpush фиксируется ошибка, и Logpush повторяет попытку по обычному расписанию. Автоматического отката к необработанным (raw) журналам не предусмотрено.

Если сбои продолжаются, записи в затронутых пакетах в итоге отбрасываются и не подлежат восстановлению.

Последняя ошибка отображается на last_error . Частые причины:

• Объём вывода превысил лимит размера. Уменьшите объём вывода на запись или отбросьте больше записей с помощью WHERE.
• Произошла внутренняя ошибка Cloudflare. Обратитесь в Cloudflare Support, указав ID задания и метку времени.

Для отладки откройте трансформатор в Transformer Studio и используйте Запуск кнопку, чтобы просмотреть результат на примере записи. Логика проверки и выполнения та же самая, поэтому проблемы, заметные в продакшене, обычно воспроизводятся и в предпросмотре.

• наборы данных Logpush - поля, на которые ссылаются ваши SQL-запросы
• Настройка задания Logpush - создание заданий Logpush и управление ими
• Справочник полей журнала - полные описания полей по всем наборам данных
• Фильтры - более простая фильтрация без SQL