← Cloudflare Logs / logs / logpush

Transformers

Transformers umožňují spustit dotaz SQL nad každou dávkou záznamů předtím, než je Logpush doručí do vaší cílové destinace. Použijte je k filtrování záznamů, které nechcete ukládat, k úpravě polí podle cílového schématu, k redakci citlivých hodnot, k výpočtu nových polí nebo k přidání statických metadat.

Logiku napíšete jako jediný SQL dotaz, přiřadíte ji k úloze Logpush a Cloudflare ji spustí u každé dávky. Následující FROM určuje datovou sadu Logpush (například http_requests nebo audit_logs_v2) a názvy polí pocházejí ze schématu tohoto datasetu.

• Transformace založené na SQL - jeden SQL dotaz s jedním příkazem na úlohu Logpush.
• Provedení na jeden záznam - spouští se na každém záznamu NDJSON předtím, než Cloudflare doručí dávku.
• Pokročilé filtrování a přetváření dat - zahazování, přejmenování, redakce, výpočet nebo označování polí.
• Připojení a odpojení bez nutnosti nového nasazení - správa transformerů prostřednictvím dashboardu Cloudflare nebo API.
• Historie verzí - každé uložení vytvoří novou verzi; starší verze zůstávají viditelné.

Než začnete, budete potřebovat:

• Úloha Logpush, která používá ndjson výstupní formát. Transformery jsou dostupné pouze pro úlohy NDJSON a jsou podporovány jak pro datové sady na úrovni účtu, tak pro datové sady na úrovni zóny.
• API token s oprávněním Logs Write oprávnění pro účet.
• Znalost dataset jejíž záznamy plánujete transformovat. Váš SQL dotaz odkazuje přímo na názvy jejích polí.

Transformery můžete vytvářet, zobrazovat jejich náhled, přiřazovat a spravovat prostřednictvím řídicího panelu Cloudflare nebo přes API.

Transformer Studio je pracovní prostor s editorem SQL, ve kterém Transformers píšete, prohlížíte a spravujete. Otevřete jej ze stránky Logpush v Cloudflare dashboardu.

Ve Studiu můžete:

• Vytvořte nový transformer napsáním dotazu SQL nad datovou sadou Logpush.
• Před uložením zobrazte náhled transformátoru na předpřipraveném ukázkovém záznamu pro cílovou datovou sadu.
• Připojte transformer k libovolné vhodné úloze Logpush na účtu nebo zóně. Jako dostupné cíle pro připojení se zobrazují pouze úlohy NDJSON odpovídající datové sadě transformeru. Úlohy CSV se nezobrazují.
• Odpojte transformátor od úlohy.
• Nová verze se uloží při každé úpravě a uložení SQL. Starší verze zůstávají k dispozici k zobrazení.
• Přejmenujte transformátor nebo aktualizujte jeho popis.
• Odstraňte transformátor. Transformátor nelze odstranit, dokud na něj odkazuje nějaká úloha Logpush.

Každá akce transformátoru je dostupná přes Cloudflare API. Pro ověření použijte API token hodnotou Logs Write oprávnění.

Chcete-li k úloze připojit nebo od ní odpojit transformátor, nastavte transformer_id u úlohy Logpush. Viz Nastavení úlohy Logpush pro koncové body úloh.

Transformer je jeden SQL dotaz. Zdrojovou tabulkou je datová sada Logpush, výstup dotazu se stává doručeným záznamem.

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

FROM název tabulky musí odpovídat datové sadě úlohy Logpush, ke které je transformátor připojen. Pokud neodpovídá, připojení selže.

Záznamy, které neodpovídají WHERE se z výstupu vynechají.

Transformers používají stejný dialekt SQL jako Cloudflare Pipelines. Podporovány jsou tyto operace:

• Projekce - SELECT konkrétní pole přejmenujte pomocí AS, vypočítejte nová pole pomocí výrazů.
• Filtrování - WHERE pomocí standardních porovnávacích a booleovských operátorů a operátorů pro kontrolu hodnoty null.
• CTEs - WITH ... AS (...) společných tabulkových výrazů (CTE).
• UNNEST - rozbalení polí typu array nebo list do řádků.
• Přístup JSON - -> operátor vrací objekt JSON; ->> vrátí řetězec. Například RequestHeaders ->> 'Host'.
• Vnořený výstup - named_struct('key', value, ...) vytváří vnořený objekt JSON.
• Výstup ve formě pole - [value1, value2] vytváří pole JSON.
• Skalární funkce - standardní funkce SQL, včetně UPPER, LOWER, COALESCE, CAST, extract, a to_timestamp.

• Joins
• Poddotazy
• Agregace (GROUP BY, HAVING, COUNT, SUM)
• Okenní funkce
• ORDER BY
• Více příkazů: jeden dotaz na transformer

Každý dotaz SQL je před uložením ověřen proti schématu cílové datové sady. Neznámá pole, nesprávné typy, neplatná syntaxe, neznámé datové sady a nepodporované operace jsou při nahrávání odmítnuty.

V dashboardu se chyby ověření zobrazují přímo v editoru s čísly řádků a sloupců. Přes API se vracejí v errors pole odpovědi.

Následující příklady uplatňují všechny funkce z Klíčové funkce v jediném dotazu. Každý z nich ponechá jen podmnožinu záznamů, přetvaruje zbývající a odstraní pole, která následná část kanálu nepotřebuje.

Tento transformátor ponechává pouze update akce z auditní stopy a přetváří zbývající záznamy pro následné doručení. Konkrétně:

• Vylučuje každý záznam, jehož ActionType není update.
• Převádí ActionTimestamp z formátu RFC3339 na celé číslo Unix epoch, přejmenované na unix_ts.
• Převede na velká písmena ActionType a přejmenuje jej na action_type.
• Přidá pevně zadanou provider s hodnotou Cloudflare.
• Skupiny ActorType, ActorEmail, a ActorIPAddress do vnořeného actor objekt.
• Odvozuje booleovskou hodnotu is_zone příznak z ResourceType = 'zone'.
• Vytváří resource_meta pole z ResourceType a ResourceID.
• Zahozené ActorID, AccountID, a ActorContext vynecháním z SELECT.

Vstupní záznam z audit_logs_v2 datová sada:

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

Doručený záznam:

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

Tento transformátor ponechává veškerý provoz HTTP kromě health checky, nástroje pro sběr metrik (scrapery) a interní hostname. Jde o běžný postup pro týmy, které chtějí kompletní tok protokolů bez předvídatelného šumu. Konkrétně:

• Vylučuje každý požadavek na internal.example.com a health.example.com.
• Vylučuje každý požadavek na cesty začínající /healthz nebo /metrics.
• Převádí EdgeStartTimestamp z formátu RFC3339 na celé číslo Unix epoch, přejmenované na unix_ts.
• Převede na velká písmena ClientRequestMethod a přejmenuje jej na method.
• Přidá pevně zadanou provider s hodnotou Cloudflare.
• Skupiny ClientRequestHost, ClientRequestPath, a ClientRequestMethod do vnořeného request objekt.
• Odvozuje booleovskou hodnotu is_server_error příznak z EdgeResponseStatus >= 500.
• Vytváří request_meta pole z ClientRequestHost a ClientRequestPath.
• Zahozené ClientIP, ClientRequestUserAgent, RayID, OriginResponseTime, a WAFAction vynecháním z SELECT.

Vstupní záznam z http_requests datová sada:

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

Tento příklad předpokládá EdgeStartTimestamp je doručováno jako řetězec ve formátu RFC3339. Pokud vaše úloha doručuje časová razítka jako Unix nanosekundy, vynechte to_timestamp() obal a místo toho hodnotu vydělte 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%'

Doručený záznam:

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

Pokud transformátor při zpracování dávky selže, celá dávka selže: nic se pro ni nedoručí, u úlohy Logpush se zaznamená chyba a Logpush dávku podle svého běžného plánu zopakuje. Automatický návrat k nezpracovaným (raw) protokolům není k dispozici.

Pokud selhání přetrvává, záznamy v postižených dávkách se nakonec zahodí a nelze je obnovit.

Poslední chyba se zobrazuje na last_error . Časté příčiny:

• Výstup překročil limit velikosti. Omezte výstup na záznam nebo zahoďte více záznamů pomocí WHERE.
• Došlo k interní chybě Cloudflare. Kontaktujte Cloudflare Support s ID úlohy a časovým razítkem.

Chcete-li ladit, otevřete transformátor v Transformer Studio a použijte Spustit tlačítko a zobrazte náhled na ukázkovém záznamu. Logika ověřování a spouštění je stejná, takže problémy viditelné v produkčním prostředí se obvykle projeví i v náhledu.

• Datové sady Logpush - pole, na která odkazují vaše SQL dotazy
• Nastavení úlohy Logpush - vytváření a správa úloh Logpush
• Referenční přehled polí protokolu - úplné popisy polí napříč datovými sadami
• Filtry - jednodušší filtrování bez SQL