View a markdown version of this page

Sintaxe da expressão para processamento condicional - Amazon CloudWatch
Condições no nível de processador e no nível de entradaCompatibilidade com o processamento condicionalOperadoresFunçõesExemplos de expressõesLimitações

Sintaxe da expressão para processamento condicional

Os processadores de pipelines do CloudWatch compatíveis com o processamento condicional aceitam um parâmetro when que contém uma expressão. Quando a expressão for avaliada como true, o processador ou a entrada será executada. As expressões usam notação de pontos (.) para acesso a campos aninhados. Por exemplo, user.role acessa o campo role dentro do objeto user. Para obter mais detalhes sobre processadores compatíveis com o processamento condicional e seus parâmetros específicos, consulte Processadores de pipelines do CloudWatch. Para exemplos de configuração da , consulte Casos de uso comuns de processador.

Condições no nível de processador e no nível de entrada

Há dois níveis em que você pode aplicar uma condição when, dependendo do processador.

Nível de processador when (nível externo)

Um when inserido no nível superior da configuração do processador. Se a expressão for avaliada como false, todo o processador será ignorado e nenhuma operação dentro dele será executada. Todos os processadores compatíveis com o processamento condicional são compatíveis com esse nível.

exemplo Condição no nível de processador: ignorar todo o processador

O processador delete_entries a seguir é executado somente quando o ambiente está em produção ou em teste. Se a condição for false, nenhuma das chaves será excluída.

processor:
  - delete_entries:
      with_keys: ["password", "api_key", "ssn"]
      when: "environment in {'prod', 'staging'}"
Nível de entrada when (dentro de cada entrada)

Um when inserido dentro de uma entrada individual na matriz entries. Cada entrada é avaliada de forma independente. Se a expressão for false, somente essa entrada específica será ignorada enquanto as outras entradas no mesmo processador continuarão a ser executadas. Somente processadores com uma matriz entries são compatíveis com esse nível (como add_entries, copy_values, rename_keys, move_keys, extract_value e substitute_string).

exemplo Condição no nível de entrada: ignorar entradas individuais

O processador add_entries a seguir adiciona chaves diferentes, dependendo da condição de cada entrada. A primeira entrada adiciona severity somente quando o nível de log é ERROR. A segunda entrada sempre adiciona processed porque não tem nenhuma condição.

processor:
  - add_entries:
      entries:
        - key: "severity"
          value: "high"
          when: "log.level == 'ERROR'"
        - key: "processed"
          value: "true"

Os processadores compatíveis com os dois níveis podem usá-los juntos. Quando ambos são especificados, a condição no nível do processador é avaliada primeiro. Se for false, todo o processador será ignorado e nenhuma condição no nível de entrada será avaliada.

exemplo Ambos os níveis combinados

O nível de processador when garante que todo o processador seja executado somente para tráfego de produção. Nesse nível, cada entrada tem sua própria condição para controlar qual chave é adicionada.

processor:
  - add_entries:
      when: "environment == 'prod'"
      entries:
        - key: "alert_level"
          value: "critical"
          when: "log.level == 'ERROR'"
        - key: "alert_level"
          value: "warning"
          when: "log.level == 'WARN'"

Para ver uma tabela que mostra quais processadores são compatíveis com qual nível, consulte a seção Compatibilidade com o processamento condicional abaixo.

Fallback com when_else

Os processadores compatíveis com condições no nível de entrada também são compatíveis com when_else. Uma entrada com when_else atua como um fallback. Ela é executada somente quando nenhuma das outras condições when no mesmo processador corresponde. O valor da expressão fornecido para when_else identifica qual conjunto de condições when considerar, mas a entrada em si é executada com base apenas no fato de todas essas condições serem avaliadas como false. Não há verificação de negação explícita. A entrada simplesmente é executada quando nenhum outro when corresponde.

exemplo Entrada de fallback com when_else

A primeira entrada é executada quando o nível de log é ERROR. A segunda entrada usa when_else e é executada somente quando a primeira condição when da entrada não corresponde (ou seja, o nível do log é diferente de ERROR).

processor:
  - add_entries:
      entries:
        - key: "alert_level"
          value: "critical"
          when: "log.level == 'ERROR'"
        - key: "alert_level"
          value: "info"
          when_else: "log.level == 'ERROR'"

Compatibilidade com o processamento condicional

A tabela a seguir mostra quais processadores são compatíveis com o processamento condicional e em que nível.

Compatibilidade com o processador condicional
Processor Compatibilidade com condicional Nível
add_entriesSimProcessador e entrada
copy_valuesSimProcessador e entrada
delete_entriesSimProcessor
move_keysSimProcessador e entrada
nivelamentoSimProcessor
lowercase_stringSimProcessor
uppercase_stringSimProcessor
trim_stringSimProcessor
substitute_stringSimProcessador e entrada
truncateSimProcessor
extract_valueSimProcessador e entrada
convert_entry_typeSimProcessor
dateSimProcessor
dissectSimProcessor
list_to_mapSimProcessor
rename_keysSimProcessador e entrada
select_entriesSimProcessor
translateSimProcessor
grokSimProcessor
drop_eventsSimProcessador (obrigatório)
OCSF, CSV, JSON, KeyValue, WAF, Postgres, CloudFront, VPC, Route53Não—

Operadores

Operadores compatíveis
Categoria Operadores Exemplo
Relacional <, <=, >, >= status_code >= 200 and status_code < 300
Igualdade ==, != log.level == "ERROR"
Condicional and, or, not log.level == "ERROR" or log.level == "FATAL"
Aritmética +, -, *, / response_time * 1000 > 5000
Associação a conjuntos in, not in environment in {"prod", "staging", "preprod"}
Correspondência a Regex =~, !~ message =~ "^ERROR.*timeout"

Funções

length(value)

Retorna o tamanho de uma string ou matriz. Exemplo: length(message) > 100

contains(value, search)

Verifica se uma string contém uma substring ou se uma matriz contém um elemento. Exemplo: contains(message, "error")

startsWith(field, prefix)

Verifica se uma string começa com um prefixo especificado. Exemplo: startsWith(message, "ERROR")

Exemplos de expressões

log.level == "ERROR"
status_code >= 200 and status_code < 300
environment in {"prod", "staging", "preprod"}
message =~ "^ERROR.*timeout"
user.role == "admin" and user.permissions.write == true
length(message) > 100 and contains(message, "error")
(log.level == "ERROR" or log.level == "FATAL") and environment == "prod"

Limitações

  • O tamanho máximo de expressões é de 256 caracteres.

  • Os processadores analisadores (exceto o Grok) não são compatíveis com o processamento condicional. Isso inclui os analisadores JSON, CSV, KeyValue, WAF, Postgres, CloudFront, VPC, Route53 e OCSF.

  • Se o processador Grok for usado como analisador (primeiro processador) em um pipeline e sua condição when for avaliada como false, todo o pipeline não será executado para esse evento de logs.