# 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](pipeline-processors.md). Para exemplos de configuração da , consulte [Casos de uso comuns de processador](processor-examples.md).
## 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.
**Example 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`).
**Example 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.
**Example 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](#conditional-support) 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.
**Example Entrada de fallback com when\$1else**
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\$1entries | Sim | Processador e entrada |
| copy\$1values | Sim | Processador e entrada |
| delete\$1entries | Sim | Processor |
| move\$1keys | Sim | Processador e entrada |
| nivelamento | Sim | Processor |
| lowercase\$1string | Sim | Processor |
| uppercase\$1string | Sim | Processor |
| trim\$1string | Sim | Processor |
| substitute\$1string | Sim | Processador e entrada |
| truncate | Sim | Processor |
| extract\$1value | Sim | Processador e entrada |
| convert\$1entry\$1type | Sim | Processor |
| date | Sim | Processor |
| dissect | Sim | Processor |
| list\$1to\$1map | Sim | Processor |
| rename\$1keys | Sim | Processador e entrada |
| select\$1entries | Sim | Processor |
| translate | Sim | Processor |
| grok | Sim | Processor |
| drop\$1events | Sim | Processador (obrigatório) |
| OCSF, CSV, JSON, KeyValue, WAF, Postgres, CloudFront, VPC, Route53 | Não | — |
## Operadores
**Operadores compatíveis**
| Categoria | Operadores | Exemplo |
| --- | --- | --- |
| Relacional | <, <=, >, >= | status\$1code >= 200 and status\$1code < 300 |
| Igualdade | ==, \$1= | log.level == "ERROR" |
| Condicional | and, or, not | log.level == "ERROR" or log.level == "FATAL" |
| Aritmética | \$1, -, \$1, / | response\$1time \$1 1000 > 5000 |
| Associação a conjuntos | in, not in | environment in \$1"prod", "staging", "preprod"\$1 |
| Correspondência a Regex | =\$1, \$1\$1 | message =\$1 "^ERROR.\$1timeout" |
## 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.