Processador add_entries Processador copy_values Processador delete_entries Processador move_keys Processador flatten processador de pesquisa

Processadores de transformação

Os processadores de transformação modificam a estrutura dos eventos de log adicionando, copiando, movendo ou removendo campos.

Processador add_entries

Adiciona pares estáticos de chave-valor aos eventos de logs. No máximo 1 processador add_entries pode ser adicionado a um pipeline.

Configuração

Configure o processador add_entries com os seguintes parâmetros:


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

Parâmetros

entries (obrigatório): Uma matriz de pares de chave-valor a serem adicionados a cada evento de log.
entries[].key (obrigatório): O nome do campo a ser adicionado ao evento de log. Permite campos aninhados usando a notação de pontos.
entries[].value (obrigatório): O valor estático a ser atribuído à chave.
entries[].overwrite_if_key_exists (opcional): Sinalizador booleano que determina o comportamento quando a chave já existe. O padrão é falso.
when (opcional): Expressão condicional no nível de processador. Quando especificado, todo o processador será ignorado se a expressão for avaliada como false. O tamanho máximo é de 256 caracteres. Consulte Sintaxe da expressão para processamento condicional.
entries[].when (opcional): Expressão condicional no nível de entrada. Quando especificado, somente essa entrada será ignorada se a expressão for avaliada como false. O tamanho máximo é de 256 caracteres. Consulte Sintaxe da expressão para processamento condicional.
entries[].when_else (opcional): Entrada de fallback que é executada somente quando nenhuma das outras condições when no mesmo processador corresponde. O valor da expressão identifica quais condições when considerar. O tamanho máximo é de 256 caracteres. Consulte Sintaxe da expressão para processamento condicional.

Processador copy_values

Copia valores de um campo para outro. No máximo 1 processador copy_values pode ser adicionado a um pipeline.

Configuração

Configure o processador copy_values com os seguintes parâmetros:


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

Parâmetros

entries (obrigatório): Matriz de operações de cópia a serem executadas em cada evento de log.
entries[].from_key (obrigatório): O nome do campo do qual o valor será copiado. Usa notação de pontos para campos aninhados.
entries[].to_key (obrigatório): O nome do campo para o qual o valor será copiado. Criará estruturas aninhadas se a notação de pontos for usada.
entries[].overwrite_if_to_key_exists (opcional): Sinalizador booleano que controla o comportamento quando o campo de destino já existe. O padrão é falso.
when (opcional): Expressão condicional no nível de processador. Quando especificado, todo o processador será ignorado se a expressão for avaliada como false. O tamanho máximo é de 256 caracteres. Consulte Sintaxe da expressão para processamento condicional.
entries[].when (opcional): Expressão condicional no nível de entrada. Quando especificado, somente essa entrada será ignorada se a expressão for avaliada como false. O tamanho máximo é de 256 caracteres. Consulte Sintaxe da expressão para processamento condicional.
entries[].when_else (opcional): Entrada de fallback que é executada somente quando nenhuma das outras condições when no mesmo processador corresponde. O valor da expressão identifica quais condições when considerar. O tamanho máximo é de 256 caracteres. Consulte Sintaxe da expressão para processamento condicional.

Processador delete_entries

Remove campos especificados dos eventos de logs.

Configuração

Configure o processador de delete_entries com os seguintes parâmetros:


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

Parâmetros

with_keys (obrigatório): Matriz de nomes de campo a serem removidos de cada evento de log. Permite a exclusão de campos aninhados usando notação de pontos.
when (opcional): Expressão condicional que determina se esse processador é executado. O tamanho máximo é de 256 caracteres. Consulte Sintaxe da expressão para processamento condicional.

Processador move_keys

Move campos de um local para outro.

Configuração

Configure o processador move_keys com os seguintes parâmetros:


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

Parâmetros

entries (obrigatório): Matriz de operações de movimentação. Máximo de 5 entradas.
entries[].from_key (obrigatório): Nome do campo de origem. Máximo de 128 caracteres.
entries[].to_key (obrigatório): Nome de campo de destino. Máximo de 128 caracteres.
entries[].overwrite_if_to_key_exists (opcional): Se o campo de destino existente deve ou não ser substituído.
when (opcional): Expressão condicional no nível de processador. Quando especificado, todo o processador será ignorado se a expressão for avaliada como false. O tamanho máximo é de 256 caracteres. Consulte Sintaxe da expressão para processamento condicional.
entries[].when (opcional): Expressão condicional no nível de entrada. Quando especificado, somente essa entrada será ignorada se a expressão for avaliada como false. O tamanho máximo é de 256 caracteres. Consulte Sintaxe da expressão para processamento condicional.
entries[].when_else (opcional): Entrada de fallback que é executada somente quando nenhuma das outras condições when no mesmo processador corresponde. O valor da expressão identifica quais condições when considerar. O tamanho máximo é de 256 caracteres. Consulte Sintaxe da expressão para processamento condicional.

Processador flatten

Nivela estruturas de objetos aninhados.

Configuração

Configure o processador flatten com os seguintes parâmetros:


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

Parâmetros

source (obrigatório): Campo contendo objeto aninhado a ser nivelado.
target (obrigatório): Prefixo do campo de destino para chaves niveladas.
remove_processed_fields (opcional): Se o campo aninhado original deve ou não ser removido após o nivelamento.
exclude_keys (opcional): Matriz de chaves a serem excluídas do nivelamento. Máximo de 20 chaves, cada uma com até 128 caracteres.
when (opcional): Expressão condicional que determina se esse processador é executado. O tamanho máximo é de 256 caracteres. Consulte Sintaxe da expressão para processamento condicional.

processador de pesquisa

Enriquece os eventos de logs com dados de uma tabela de pesquisa do CloudWatch Logs. O processador combina campos em seus eventos de logs com campos na tabela de pesquisa e anexa campos especificados aos seus eventos de logs. Use esse processador para cenários de enriquecimento de dados, como mapear IDs de usuário para detalhes do usuário, códigos de produto para informações do produto ou códigos de erro para descrições de erros. No máximo 1 processador lookup pode ser adicionado a um pipeline.

nota

Se uma tabela de pesquisa for usada em um pipeline, você deverá fornecer uma função de execução com permissões logs:GetLookupTable na tabela. Para obter mais informações, consulte Políticas e permissões do IAM para pipelines do CloudWatch.

Configuração

Configure o processador de pesquisa com os seguintes parâmetros:


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

Parâmetros

lookup_table (obrigatório): O ARN da tabela de pesquisa do CloudWatch Logs a ser usada para enriquecimento. O tamanho máximo é 2048 caracteres.
match_keys (obrigatório): Matriz de pares de chaves que definem como combinar campos de eventos de logs com campos de tabela de pesquisa. Mínimo de 1, máximo de 5 chaves de correspondência. Quando várias chaves de correspondência são especificadas, uma linha da tabela de pesquisa deve corresponder a todas as chaves para produzir um resultado (lógica AND).
match_keys[].log_key (obrigatório): O nome do campo no evento de logs a ser comparado. Máximo de 128 caracteres.
match_keys[].lookup_key (obrigatório): O nome da coluna na tabela de pesquisa a ser comparada. Máximo de 128 caracteres.
entries (obrigatório): Matriz de campos a serem adicionados ao evento de logs a partir da linha correspondente da tabela de pesquisa. Mínimo 1, máximo 10 entradas.
entries[].source (obrigatório): O nome da coluna na tabela de pesquisa da qual recuperar o valor. Máximo de 128 caracteres.
entries[].target (opcional): O nome do campo a ser adicionado ao evento de log. Se não for especificado, o nome da coluna source será usado como nome do campo. Máximo de 128 caracteres.
entries[].overwrite_if_exists (opcional): Sinalizador booleano que determina o comportamento quando o campo de destino já existe no evento de logs. O padrão é falso.
when (opcional): Expressão condicional que determina se esse processador é executado. O tamanho máximo é de 256 caracteres. Consulte Sintaxe da expressão para processamento condicional.

Exemplo

Considere uma tabela de pesquisa denominada network_assets com as seguintes linhas:

tabela network_assets lookup
ip_address	hostname	proprietário	location
10.0.1.12	web-server-01	team-alpha	us-east-1
10.0.2.45	db-server-03	team-beta	us-west-2
10.0.3.78	cache-node-07	team-alpha	eu-west-1

Considerando o seguinte evento de logs:


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

E a seguinte configuração de processador:


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

O processador produz o seguinte evento de logs aprimorado:


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

Permissões do IAM

Quando um pipeline usa o processador de pesquisa, a função de execução do pipeline deve incluir a permissão logs:GetLookupTable para a tabela referenciada. O exemplo de declaração de política a seguir concede essa permissão:


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

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Processadores de análise

Processadores de manipulação de strings