processore add_entries processore copy_values processore delete_entries processore move_keys appiattire il processore processore di ricerca processore geoip

Processori di trasformazione

I processori di trasformazione modificano la struttura degli eventi di registro aggiungendo, copiando, spostando o rimuovendo campi.

processore add_entries

Aggiunge coppie chiave-valore statiche agli eventi di registro. È possibile aggiungere al massimo 1 add_entries processore a una pipeline.

Configurazione

Configurate il processore add_entries con i seguenti parametri:


processor:
  - add_entries:
      entries:
        - key: "environment"
          value: "production"
          overwrite_if_key_exists: false

Parameters

entries(obbligatorio): Matrice di coppie chiave-valore da aggiungere a ciascun evento di registro.
entries[].key(obbligatorio): Il nome del campo da aggiungere all'evento di registro. Supporta i campi annidati utilizzando la notazione a punti.
entries[].value(obbligatorio): Il valore statico da assegnare alla chiave.
entries[].overwrite_if_key_exists (facoltativo): Flag booleano che determina il comportamento quando la chiave esiste già. Il valore predefinito è false (falso).
when (facoltativo): Processor-level espressione condizionale. Quando specificato, l'intero processore viene ignorato se l'espressione restituisce false. La lunghezza massima è 256 caratteri. Per informazioni, consulta Sintassi delle espressioni per l'elaborazione condizionale.
entries[].when (facoltativo): Entry-level espressione condizionale. Se specificata, solo questa voce viene ignorata se l'espressione restituisce false. La lunghezza massima è 256 caratteri. Per informazioni, consulta Sintassi delle espressioni per l'elaborazione condizionale.
entries[].when_else (facoltativo): Voce di riserva che viene eseguita solo quando nessuna delle altre when condizioni nello stesso processore corrisponde. Il valore dell'espressione identifica le when condizioni da considerare. La lunghezza massima è 256 caratteri. Per informazioni, consulta Sintassi delle espressioni per l'elaborazione condizionale.

processore copy_values

Copia i valori da un campo all'altro. È possibile aggiungere al massimo 1 copy_values processore a una pipeline.

Configurazione

Configurate il processore copy_values con i seguenti parametri:


processor:
  - copy_values:
      entries:
        - from_key: "user_id"
          to_key: "backup_user"
          overwrite_if_to_key_exists: false

Parameters

entries(obbligatorio): Matrice di operazioni di copia da eseguire su ogni evento di registro.
entries[].from_key(obbligatorio): Il nome del campo da cui copiare il valore. Utilizza la notazione a punti per i campi annidati.
entries[].to_key(obbligatorio): Il nome del campo in cui copiare il valore. Creerà strutture annidate se si utilizza la notazione a punti.
entries[].overwrite_if_to_key_exists (facoltativo): Flag booleano che controlla il comportamento quando il campo di destinazione esiste già. Il valore predefinito è false (falso).
when (facoltativo): Processor-level espressione condizionale. Quando specificato, l'intero processore viene ignorato se l'espressione restituisce false. La lunghezza massima è 256 caratteri. Per informazioni, consulta Sintassi delle espressioni per l'elaborazione condizionale.
entries[].when (facoltativo): Entry-level espressione condizionale. Se specificata, solo questa voce viene ignorata se l'espressione restituisce false. La lunghezza massima è 256 caratteri. Per informazioni, consulta Sintassi delle espressioni per l'elaborazione condizionale.
entries[].when_else (facoltativo): Voce di riserva che viene eseguita solo quando nessuna delle altre when condizioni nello stesso processore corrisponde. Il valore dell'espressione identifica le when condizioni da considerare. La lunghezza massima è 256 caratteri. Per informazioni, consulta Sintassi delle espressioni per l'elaborazione condizionale.

processore delete_entries

Rimuove i campi specificati dagli eventi del registro.

Configurazione

Configura il processore delete_entries con i seguenti parametri:


processor:
  - delete_entries:
      with_keys: ["temp_field", "debug_info"]

Parameters

with_keys(obbligatorio): Matrice di nomi di campo da rimuovere da ogni evento di registro. Supporta l'eliminazione dei campi annidati utilizzando la notazione a punti.
when (facoltativo): Espressione condizionale che determina se questo processore è in esecuzione. La lunghezza massima è 256 caratteri. Per informazioni, consulta Sintassi delle espressioni per l'elaborazione condizionale.

processore move_keys

Sposta i campi da una posizione all'altra.

Configurazione

Configura il processore move_keys con i seguenti parametri:


processor:
  - move_keys:
      entries:
        - from_key: "old_field"
          to_key: "new_field"
          overwrite_if_to_key_exists: true

Parameters

entries(obbligatorio): Serie di operazioni di spostamento. Massimo 5 voci.
entries[].from_key(obbligatorio): Nome del campo di origine. Massimo 128 caratteri.
entries[].to_key(obbligatorio): Nome del campo di destinazione. Massimo 128 caratteri.
entries[].overwrite_if_to_key_exists (facoltativo): Se sovrascrivere il campo di destinazione esistente.
when (facoltativo): Processor-level espressione condizionale. Quando specificato, l'intero processore viene ignorato se l'espressione restituisce false. La lunghezza massima è 256 caratteri. Per informazioni, consulta Sintassi delle espressioni per l'elaborazione condizionale.
entries[].when (facoltativo): Entry-level espressione condizionale. Se specificata, solo questa voce viene ignorata se l'espressione restituisce false. La lunghezza massima è 256 caratteri. Per informazioni, consulta Sintassi delle espressioni per l'elaborazione condizionale.
entries[].when_else (facoltativo): Voce di riserva che viene eseguita solo quando nessuna delle altre when condizioni nello stesso processore corrisponde. Il valore dell'espressione identifica le when condizioni da considerare. La lunghezza massima è 256 caratteri. Per informazioni, consulta Sintassi delle espressioni per l'elaborazione condizionale.

appiattire il processore

Appiattisce le strutture degli oggetti annidati.

Configurazione

Configura il processore di appiattimento con i seguenti parametri:


processor:
  - flatten:
      source: "metadata"
      target: "flattened"
      remove_processed_fields: true
      exclude_keys: ["sensitive_data"]

Parameters

source(obbligatorio): Campo contenente un oggetto annidato da appiattire.
target(obbligatorio): Prefisso del campo di destinazione per le chiavi appiattite.
remove_processed_fields (facoltativo): Se rimuovere il campo annidato originale dopo l'appiattimento.
exclude_keys (facoltativo): Matrice di chiavi da escludere dall'appiattimento. Massimo 20 tasti, ciascuno con un massimo di 128 caratteri.
when (facoltativo): Espressione condizionale che determina se questo processore è in esecuzione. La lunghezza massima è 256 caratteri. Per informazioni, consulta Sintassi delle espressioni per l'elaborazione condizionale.

processore di ricerca

Arricchisce gli eventi di registro con i dati di una tabella di CloudWatch ricerca Logs. Il processore confronta i campi degli eventi di registro con i campi della tabella di ricerca e aggiunge i campi specificati agli eventi di registro. Utilizzate questo processore per scenari di arricchimento dei dati, ad esempio mappando gli ID utente ai dettagli utente, i codici di prodotto alle informazioni sul prodotto o i codici di errore alle descrizioni degli errori. È possibile aggiungere al massimo 1 lookup processore a una pipeline.

Nota

Se una tabella di ricerca viene utilizzata in una pipeline, è necessario fornire un ruolo di esecuzione con logs:GetLookupTable autorizzazioni sulla tabella. Per ulteriori informazioni, consulta CloudWatch pipeline, politiche e autorizzazioni IAM.

Configurazione

Configura il processore di ricerca con i seguenti parametri:


processor:
  - lookup:
      lookup_table: "arn:aws:logs:us-east-1:123456789012:lookup-table:my_lookup_table"
      match_keys:
        - log_key: "src_ip"
          lookup_key: "ip_address"
      entries:
        - source: "hostname"
          target: "src_hostname"
          overwrite_if_exists: true

Parameters

lookup_table(obbligatorio): L'ARN della tabella di ricerca dei CloudWatch log da utilizzare per l'arricchimento. La lunghezza massima è 2048 caratteri.
match_keys(obbligatorio): Matrice di coppie di chiavi che definiscono come abbinare i campi degli eventi di log ai campi della tabella di ricerca. Minimo 1, massimo 5 chiavi di corrispondenza. Quando vengono specificate più chiavi di corrispondenza, una riga della tabella di ricerca deve corrispondere a tutte le chiavi per produrre un risultato (logica AND).
match_keys[].log_key(obbligatorio): Il nome del campo nell'evento di registro con cui confrontare. Massimo 128 caratteri.
match_keys[].lookup_key(obbligatorio): Il nome della colonna nella tabella di ricerca con cui confrontare. Massimo 128 caratteri.
entries(obbligatorio): Matrice di campi da aggiungere all'evento di log dalla riga corrispondente della tabella di ricerca. Minimo 1, massimo 10 voci.
entries[].source(obbligatorio): Il nome della colonna nella tabella di ricerca da cui recuperare il valore. Massimo 128 caratteri.
entries[].target (facoltativo): Il nome del campo da aggiungere all'evento di log. Se non specificato, il nome della source colonna viene utilizzato come nome del campo. Massimo 128 caratteri.
entries[].overwrite_if_exists (facoltativo): Flag booleano che determina il comportamento quando il campo di destinazione esiste già nell'evento di log. Il valore predefinito è false (falso).
when (facoltativo): Espressione condizionale che determina se questo processore è in esecuzione. La lunghezza massima è 256 caratteri. Per informazioni, consulta Sintassi delle espressioni per l'elaborazione condizionale.

Esempio

Considerate una tabella di ricerca denominata network_assets con le seguenti righe:

ip_address	hostname	owner	location
10.0.1.12	server web-01	squadra-alfa	us-east-1
10.0.2.45	server db 03	squadra beta	us-west-2
10.0.3.78	nodo cache-07	squadra-alfa	eu-west-1

Dato il seguente evento di registro:


{
  "timestamp": "2026-05-04T12:00:00Z",
  "src_ip": "10.0.2.45",
  "action": "connection_opened",
  "bytes": 2048
}

E la seguente configurazione del processore:


processor:
  - lookup:
      lookup_table: "arn:aws:logs:us-east-1:123456789012:lookup-table:network_assets"
      match_keys:
        - log_key: "src_ip"
          lookup_key: "ip_address"
      entries:
        - source: "hostname"
          target: "src_hostname"
        - source: "owner"
        - source: "location"
          target: "src_region"
          overwrite_if_exists: false

Il processore produce il seguente evento di registro arricchito:


{
  "timestamp": "2026-05-04T12:00:00Z",
  "src_ip": "10.0.2.45",
  "action": "connection_opened",
  "bytes": 2048,
  "src_hostname": "db-server-03",
  "owner": "team-beta",
  "src_region": "us-west-2"
}

autorizzazioni IAM

Quando una pipeline utilizza il processore di ricerca, il ruolo di esecuzione della pipeline deve includere l'logs:GetLookupTableautorizzazione per la tabella di riferimento. La seguente dichiarazione politica di esempio concede questa autorizzazione:


{
  "Effect": "Allow",
  "Action": "logs:GetLookupTable",
  "Resource": "arn:aws:logs:<region>:<account-id>:lookup-table:<table-name>"
}

processore geoip

Il processore geoip arricchisce gli eventi di registro con dati di posizione geografica basati sugli indirizzi IP. Il processore utilizza MaxMind i database per convertire gli indirizzi IP in informazioni geografiche quali città, paese, continente, coordinate e dati ASN (Autonomous System Number). Utilizza questo processore per l'analisi del traffico di rete, l'arricchimento della posizione degli utenti e gli scenari di indagine sulla sicurezza.

Configurazione

Configura il processore geoip con i seguenti parametri:


processor:
  - geoip:
      entries:
        - source: "client_ip"
          target: "client_geo"
          include_fields:
            - "city_name"
            - "country_name"
            - "country_iso_code"
            - "continent_name"
            - "latitude"
            - "longitude"
          when: '.client_ip != "127.0.0.1"'

Parameters

entries(richiesto)

Matrice di oggetti di ingresso che definiscono quali campi IP arricchire con dati geografici. Minimo 1, massimo 10 voci.

entries[].source(obbligatorio)

Il nome del campo nell'evento di log che contiene l'indirizzo IP da cercare. Deve fare riferimento a un indirizzo IPv4 o IPv6 valido. Massimo 128 caratteri.

entries[].target(obbligatorio)

Il nome del campo in cui il processore scrive i dati di arricchimento geografico nell'evento di registro. Massimo 128 caratteri.

entries[].include_fields(obbligatorio)

Matrice di campi geografici da includere nel risultato dell'arricchimento. Minimo 1, massimo 12 campi. Sono disponibili i seguenti campi:

continent_code— codice Two-letter continentale (ad esempio, «NA»).
continent_name— Nome del continente (ad esempio, «Nord America»).
country_name— Nome del Paese (ad esempio, «Stati Uniti»).
country_iso_code— Codice paese ISO 3166-1 alpha-2 (ad esempio, «USA»).
city_name— Nome della città (ad esempio, «Seattle»).
postal_code— Codice postale associato alla posizione dell'indirizzo IP.
time_zone— Nome del fuso orario IANA (ad esempio, "America/Los_Angeles»).
latitude— Coordinata di latitudine della posizione dell'indirizzo IP.
longitude— Coordinata longitudinale della posizione dell'indirizzo IP.
network— Notazione CIDR della rete associata all'indirizzo IP.
asn— Numero di sistema autonomo associato all'indirizzo IP.
asn_organization— Nome dell'organizzazione associato al numero di sistema autonomo.

entries[].when (facoltativo)

Espressione condizionale che determina se questa voce viene eseguita. La lunghezza massima è 256 caratteri. Per informazioni, consulta Sintassi delle espressioni per l'elaborazione condizionale.

when (facoltativo)

Top-level espressione condizionale che determina se questo processore viene eseguito. La lunghezza massima è 256 caratteri. Per informazioni, consulta Sintassi delle espressioni per l'elaborazione condizionale.

Esempio

L'esempio seguente mostra un esempio di evento di registro con campi relativi all'indirizzo IP:


{
  "timestamp": "2026-05-04T12:00:00Z",
  "src_ip": "203.0.113.50",
  "dst_ip": "198.51.100.25",
  "action": "ALLOW",
  "bytes": 4096
}

La seguente configurazione del processore associa i campi IP di origine e di destinazione agli obiettivi di arricchimento geografico:


processor:
  - geoip:
      entries:
        - source: "src_ip"
          target: "src_geo"
          include_fields:
            - "city_name"
            - "country_name"
            - "country_iso_code"
            - "latitude"
            - "longitude"
            - "asn"
            - "asn_organization"
        - source: "dst_ip"
          target: "dst_geo"
          include_fields:
            - "country_name"
            - "country_iso_code"

Il processore produce il seguente evento di registro arricchito:


{
  "timestamp": "2026-05-04T12:00:00Z",
  "src_ip": "203.0.113.50",
  "dst_ip": "198.51.100.25",
  "action": "ALLOW",
  "bytes": 4096,
  "src_geo": {
    "city_name": "Seattle",
    "country_name": "United States",
    "country_iso_code": "US",
    "latitude": 47.6062,
    "longitude": -122.3321,
    "asn": 16509,
    "asn_organization": "Amazon.com, Inc."
  },
  "dst_geo": {
    "country_name": "Germany",
    "country_iso_code": "DE"
  }
}

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Processori parser

Processori di manipolazione delle stringhe