INTEGRITY Dokumentace

← Cloudflare Logs / logs / logpush / logpush-job

Konfigurace API

Endpointy

Následující tabulka shrnuje operace s úlohami dostupné jak pro úlohy Logpush, tak pro úlohy Edge Log Delivery. Ujistěte se, že datové sady na úrovni účtu používají /accounts/{account_id} a datové sady vázané na zónu používají /zone/{zone_id}. Další informace najdete v Datové sady stránce.

Můžete najít {zone_id} a {account_id} argumentů na základě Najděte ID zóny a účtu stránku. {job_id} je číselný argument, například 123456. {dataset_id} určuje kategorii logu (například http_requests nebo audit_logs).

Operace Popis API
POST Vytvoření úlohy Dokumentace
GET Načíst podrobnosti o úloze Dokumentace
GET Načíst všechny úlohy všech datových sad Dokumentace
GET Načíst všechny úlohy datové sady Dokumentace
GET Načíst všechna dostupná pole datové sady Dokumentace
PUT Aktualizace úlohy Dokumentace
DELETE Odstraňte úlohu Dokumentace
POST Ověřte, zda cíl existuje Dokumentace
POST Získání ověřovací výzvy vlastnictví Dokumentace
POST Ověření výzvy vlastnictví Dokumentace
POST Ověření možností protokolu Dokumentace

Konkrétní příklady najdete v návodech v Příklady Logpush.

Připojování

Logpush API vyžaduje přihlašovací údaje stejně jako jakékoli jiné API Cloudflare.

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:
Seznam úloh Logpush
curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/logpush/jobs" \
	--request GET \
	--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Vlastnictví

Před vytvořením nové úlohy je nutné prokázat vlastnictví cíle.

Chcete-li vydat token pro ověření vlastnictví do cílového umístění:

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:
Získání ověřovací výzvy vlastnictví
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"
	}'

Do cíle se zapíše challenge soubor a název souboru bude uveden v odpovědi (název souboru může být vyjádřen jako cesta, pokud je to pro váš cíl vhodné):

{
  "errors": [],
  "messages": [],
  "result": {
    "valid": true,
    "message": "",
    "filename": "<PATH_TO_CHALLENGE_FILE>.txt"
  },
  "success": true
}

Při vytváření úlohy budete muset zadat token obsažený v tomto souboru.

Cíl

Cíl u poskytovatele cloudových služeb zadáte pomocí povinného destination_conf .

destination_conf parametr musí mít následující formát:

<scheme>://<destination-address>

Níže jsou uvedena podporovaná schémata, z nichž je každé přizpůsobené konkrétním poskytovatelům, jako jsou R2, S3 atd. Navíc existují obecné případy použití, jako je https jsou také zahrnuty:

destination-address by měl obvykle poskytnout cílový poskytovatel. U některých poskytovatelů ale vyžadujeme destination-address dodržovat konkrétní formát:

Pro R2, S3, Google Cloud Storage, a Azure, můžete protokoly uspořádat do denních podadresářů tak, že zahrnete speciální zástupný symbol {DATE} v cestě URL. Tento zástupný symbol bude automaticky nahrazen datem ve formátu YYYYMMDD formát (například 20180523).

Například:

Tento přístup je užitečný, pokud chcete mít protokoly seskupené podle dne.

Další informace o hodnotě pro vašeho poskytovatele cloudového úložiště najdete v následujících konvencích:

Chcete-li zjistit, zda se cílové umístění již používá:

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:
Zkontrolujte, zda cíl existuje
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"
	}'

Odpověď

{
  "errors": [],
  "messages": [],
  "result": {
    "exists": false
  },
  "success": true
}

Název

Volitelný, člověku srozumitelný název úlohy, který nemusí být jedinečný. Doporučujeme zvolit smysluplný název, například název domény, aby bylo možné úlohu snadno identifikovat a spravovat. Název můžete kdykoli později upravit.

Typ

Parametr kind (volitelný) se používá k rozlišení mezi úlohami Logpush a Edge Log Delivery. U úloh Logpush lze tento parametr ponechat prázdný nebo zcela vynechat. U úloh Edge Log Delivery nastavte "kind": "edge". Edge Log Delivery je v současné době podporováno pouze pro http_requests datová sada.

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:
Vytvořit úlohu Logpush
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"
	}'

Možnosti

Logpull_options bylo nahrazeno parametrem output_options funkce Custom Log Formatting. Další informace najdete v Možnosti výstupu protokolu dokumentaci, kde najdete pokyny ke konfiguraci těchto možností a k aktualizaci stávajících úloh tak, aby tyto možnosti využívaly.

Pokud stále používáte logpull_options, zde jsou možnosti, které si můžete přizpůsobit:

  1. Pole (volitelné): Viz Datové sady pro aktuálně dostupná pole. Seznam polí je také dostupný přímo z API: https://api.cloudflare.com/client/v4/zones/{zone_id}/logpush/datasets/{dataset_id}/fields. Výchozí pole: https://api.cloudflare.com/client/v4/zones/{zone_id}/logpush/datasets/{dataset_id}/fields/default.
  2. Formát časového razítka (volitelné): Formát, ve kterém se budou vracet pole s časovým razítkem. Možné hodnoty: unixnano (jednotka nanosekundy, výchozí), unix (jednotka sekundy), rfc3339 (jednotka sekundy).
  3. Redakce pro CVE-2021-44228 (volitelné): Tato možnost nahradí každý výskyt ${ hodnotou x{. Chcete-li ji povolit, nastavte "CVE-2021-44228": true.

Chcete-li zkontrolovat, zda vybraný logpull_options jsou platné:

Požadovaná oprávnění API tokenu

Alespoň jeden z následujících oprávnění tokenu je povinné:
Ověření originu
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"
	}'

Odpověď

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

Časování změn konfigurace

Když upravíte konfiguraci úlohy Logpush, změny se neprojeví okamžitě.

Změny cíle

Pokud úlohu překonfigurujete na nový cíl, protokoly se mohou během přechodného období ještě přibližně 10-15 minut nadále odesílat na starý cíl. Toto zpoždění umožňuje systému dokončit rozpracovaná nahrání a rozšířit novou konfiguraci po celé síti Cloudflare.

Změny polí

Když do stávající úlohy Logpush přidáte nová pole, objeví se ve vašich protokolech přibližně do 10 až 15 minut. Tento údaj je pouze orientační a může se lišit podle zatížení systému.

Filtr

Pomocí filtrů vyberte události, které chcete do protokolů zahrnout nebo z nich odstranit. Další informace najdete v Filtry.

Vzorkovací frekvence

Hodnota se může pohybovat od 0.0 (nezahrnující) do 1.0 (včetně). sample=0.1 znamená vrátit 10 % (1 z 10) všech záznamů. Výchozí hodnota je 1, což znamená, že protokoly nebudou vzorkovány.

Pochopení sample_rate a SampleInterval

sample_rate parametr a SampleInterval jsou nezávislé mechanismy, které fungují v různých fázích procesu logování:

sample_rate které nastavíte, se uplatní nad rámec případného již existujícího vzorkování. Pokud vaše data již obsahují SampleInterval: 1000 a nastavíte sample_rate: 0.1, obdržíte přibližně 1 z 10,000 původních událostí (1000 × 10).

Maximální parametry nahrávání

Tyto parametry určují velikost jednotlivé dávky nahrávání, nikoli rychlost doručování dat. Použijte je, abyste zabránili přetížení cílového umístění nahráváním dávek, které jsou příliš velké nebo příliš malé.

Parametr Popis Výchozí
max_upload_bytes Maximální nekomprimovaná velikost souboru dávky protokolů. Liší se podle cíle
max_upload_records Maximální počet řádků protokolu na dávku. 100,000
max_upload_interval_seconds Maximální časové rozpětí dat protokolu na dávku (používá se ve scénářích dohánění zpoždění). Liší se podle cíle

Kdy tyto parametry upravit

Vlastní pole

Do záznamů protokolu HTTP požadavků můžete přidat vlastní pole ve formě hlaviček HTTP požadavků, hlaviček HTTP odpovědí a cookies. Konfigurace vlastních polí platí pro všechny úlohy Logpush v zóně, které používají datovou sadu HTTP requests. Další informace najdete v Vlastní pole.

Audit

Následující akce Logpush jsou zaznamenány v Cloudflare Audit Logs: vytvoření, aktualizace a odstranění úlohy.