Menu
Logs do Amazon CloudWatch
Guia do usuário

Sintaxe do padrão e do filtro

Você usa filtros de métrica para procurar e relacionar termos, frases ou valores em seus eventos de log. Quando um filtro de métrica encontra um dos termos, frases ou valores nos seus eventos de log, você pode incrementar o valor de uma métrica do CloudWatch. Por exemplo, você pode criar um filtro de métrica para procurar e contar a ocorrência da palavra ERRO em seus eventos de log.

Os filtros de métrica também podem extrair valores numéricos dos eventos de log limitados por espaço, como a latência das solicitações da web. Nesses exemplos, você pode aumentar o seu valor de métrica pelo valor numérico real extraído do log.

Você também pode usar operadores condicionais e curingas para criar correspondências exatas. Antes de criar um filtro de métrica, você pode testar seus padrões de pesquisa no console do CloudWatch. As seções a seguir explicam a sintaxe do filtro da métrica em mais detalhes.

Correspondência de termos em eventos de log

Para procurar um termo nos seus eventos de log, use o termo como seu padrão de filtro de métrica. Você pode especificar vários termos em um filtro de métrica padrão, mas todos os termos devem aparecer em um evento de log para haver uma correspondência. Os filtros de métrica fazem distinção de maiúsculas e minúsculas.

Os termos de filtro de métrica que incluem caracteres que não sejam alfanuméricos ou sublinhado devem ser colocados entre aspas duplas ("").

Para excluir um termo, use um sinal de menos (-) antes dele.

Exemplo 1: Termo único

O padrão de filtro "ERRO" faz a correspondência das mensagens de eventos de log que contêm esse termo da seguinte forma:

  • [ERRO] Ocorreu uma exceção fatal

  • Saindo com ERRORCODE: -1

Exemplo 2: Incluir um termo e excluir um termo

No exemplo anterior, se você alterar o padrão de filtro para "ERRO" – "Saindo", a mensagem de evento de log "Saindo com ERRORCODE: -1" será excluída.

Exemplo 3: Vários termos

O padrão de filtro "ERRO Exceção" faz a correspondência de mensagens de eventos de log que contêm os dois termos, como o seguinte:

  • [ERRO] IllegalArgumentException captada

  • [ERRO] Exceção não tratada

O padrão de filtro "Falha ao processar a solicitação" faz a correspondência de mensagens de eventos de log que contêm todos os termos, como o seguinte:

  • [AVISO] Falha ao processar a solicitação

  • [ERRO] Não foi possível continuar: falha ao processar a solicitação

Correspondência de padrão OU

Você pode corresponder termos em filtros com base em texto usando a correspondência de padrão OU. Para os padrões de exemplo abaixo, ERRO (corresponde a ERRO) no padrão 1 e 2. ?ERROR WARN (corresponde a linhas que contêm ERRO ou AVISO) em padrões 1, 2 e 3. ERRO AVISO (corresponde a linhas que contêm ERRO e AVISO) no padrão 1. ERRO -AVISO (corresponde a linhas que contêm ERRO e não contêm AVISO) no padrão 2.:

  1. Mensagem de AVISO DE ERRO

  2. Mensagem de ERRO

  3. Mensagem de AVISO

Você pode corresponder termos usando a correspondência de padrão OU em filtros delimitados por espaços. Para os padrões do exemplo a seguir, [w1=ERROR, w2] corresponde a ERRO (padrão 2), [w1=ERROR || WARN, w2] corresponde a linhas que contêm ERRO ou AVISO (padrões 2 e 3), [w1=!ERROR&&!WARN, w2] corresponde a linhas que contêm ERRO E AVISO (padrão 1).

  1. Mensagem de AVISO DE ERRO

  2. Mensagem de ERRO

  3. Mensagem de AVISO

Você pode corresponder termos usando a correspondência de padrão OU em filtros JSON. Para os padrões de exemplo a seguir, {$.foo = bar} corresponde ao padrão 1, {$.foo = baz } corresponde ao padrão 2 e {$.foo = bar || $.foo = baz } corresponde aos padrões 1 e 2.

  1. {"foo": "bar"}

  2. {"foo": "baz"}

Correspondência de termos em eventos de log JSON

Você pode extrair valores de eventos de log JSON. Para extrair valores de eventos de log JSON, você precisa criar um filtro de métrica com base em string. Strings que contêm notação científica não têm suporte. Os itens nos dados de eventos de log JSON devem corresponder exatamente ao filtro de métrica. É possível criar filtros de métrica em eventos de log JSON para indicar o seguinte:

  • Ocorre um determinado evento. Por exemplo, eventName é "UpdateTrail".

  • O IP está fora de uma sub-rede conhecida. Por exemplo, sourceIPAddress não está no intervalo de alguma sub-rede conhecida.

  • Uma combinação de duas ou mais condições são verdadeiras. Por exemplo, o eventName é "UpdateTrail" e o recipientAccountId é 123456789012.

Uso de filtros de métrica para extrair valores de eventos de log JSON

Você pode usar filtros de métrica para extrair valores de eventos de log JSON. Um filtro de métrica verifica os logs de entrada e modifica um valor numérico quando encontra uma correspondência nos dados de log. Quando você cria um filtro de métrica, pode simplesmente incrementar uma contagem cada vez que o texto correspondente é encontrado em um log ou pode extrair valores numéricos do log e usá-los para incrementar o valor da métrica.

Correspondência de termos JSON com filtros de métricas

A sintaxe do filtro de métrica para eventos de log JSON usa o seguinte formato:

{ SELECTOR EQUALITY_OPERATOR STRING }

O filtro de métrica deve estar entre chaves { }, para indicar que essa é uma expressão JSON. O filtro de métrica contém as seguintes partes:

SELETOR

Especifica o que a propriedade JSON deve verificar. Os seletores de propriedade sempre começam com o sinal de cifrão ($), o que significa a raiz do JSON. Os seletores de propriedade são strings alfanuméricas que também dão suporte aos caracteres "-" e "_". Os elementos de matriz são indicados com a sintaxe [NUMBER] e devem seguir a uma propriedade. São exemplos: $.eventId, $.users[0], $.users[0].id, $.requestParameters.instanceId.

EQUALITY_OPERATOR

Pode ser = ou !=.

STRING

Uma string com ou sem aspas. Você pode usar o caractere curinga asterisco '*" para fazer a correspondência com qualquer texto em, antes ou depois de um termo de pesquisa. Por exemplo, *Event corresponderá a PutEvent e GetEvent. Event* corresponderá a EventId e EventName. Ev*ent corresponderá apenas à string real Ev*ent. Strings que consistem inteiramente em caracteres alfanuméricos não precisam de aspas. Strings que têm unicode e outros caracteres como "@", "$", "\", etc. devem estar entre aspas duplas para serem válidas.

Exemplos de filtro de métrica JSON

Veja um exemplo de JSON a seguir:

{ "eventType": "UpdateTrail", "sourceIPAddress": "111.111.111.111", "arrayKey": [ "value", "another value" ], "objectList": [ { "name": "a", "id": 1 }, { "name": "b", "id": 2 } ], "SomeObject": null, "ThisFlag": true }

Os seguintes filtros corresponderiam a:

{ $.eventType = "UpdateTrail" }

Filtrar com base no tipo de evento UpdateTrail.

{ $.sourceIPAddress != 123.123.* }

Filtrar com base no endereço IP fora do prefixo 123.123 da sub-rede.

{ $.arrayKey[0] = "value" }

Filtrar com base na primeira entrada no arrayKey "valor". Se não for uma matriz, arrayKey será falso.

{ $.objectList[1].id = 2 }

Filtrar com base na segunda entrada em objectList tendo uma propriedade chamada id = 2. Se não for uma matriz, objectList será falso. Se os itens em objectList não forem objetos ou não tiverem uma propriedade id, será falso.

{ $.SomeObject IS NULL }

Filtrar com base em SomeObject definido como nulo. Isso só será verdadeiro se o objeto especificado for definido como nulo.

{ $.SomeOtherObject NOT EXISTS }

Filtrar com base em SomeOtherObject sendo não existente. Isso só será verdadeiro se o objeto especificado não existir nos dados de log.

{ $.ThisFlag IS TRUE }

Filtrar com base em ThisFlag sendo TRUE. Isso também funciona para filtros boolianos que verificariam o valor FALSE.

Condições compostas JSON

Você pode combinar várias condições em uma expressão composta usando OR (||) e AND (&&). Parênteses são permitidos e a sintaxe segue a ordem padrão das operações () > && > ||.

{ "user": { "id": 1, "email": "John.Stiles@example.com" }, "users": [ { "id": 2, "email": "John.Doe@example.com" }, { "id": 3, "email": "Jane.Doe@example.com" } ], "actions": [ "GET", "PUT", "DELETE" ], "coordinates": [ [0, 1, 2], [4, 5, 6], [7, 8, 9] ] }
Exemplos
{ ($.user.id = 1) && ($.users[0].email = "John.Doe@example.com") }

Corresponde ao JSON acima.

{ ($.user.id = 2 && $.users[0].email = "nonmatch") || $.actions[2] = "GET" }

Não corresponde ao JSON acima.

{ $.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = nonmatch && $.actions[2] = nomatch }

Corresponde ao JSON acima.

{ ($.user.email = "John.Stiles@example.com" || $.coordinates[0][1] = nonmatch) && $.actions[2] = nomatch }

Não corresponde ao JSON acima.

Considerações especiais JSON

O SELETOR deve apontar para um nó de valor (string ou número) no JSON. Se apontar para uma matriz ou objeto, o filtro não será aplicado porque o formato do log não corresponderá ao filtro. Por exemplo, {$.users = 1} e {$.users != 1} não corresponderá a um evento de log no qual users for uma matriz:

{ "users": [1, 2, 3] }
Comparações numéricas

A sintaxe do filtro de métrica oferece suporte à correspondência precisa em comparações numéricas. As seguintes comparações numéricas têm suporte: <, >, >=, <=, =, !=

Os filtros numéricos têm uma sintaxe de

{ SELECTOR NUMERIC_OPERATOR NUMBER }

O filtro de métrica deve estar entre chaves { }, para indicar que essa é uma expressão JSON. O filtro de métrica contém as seguintes partes:

SELETOR

Especifica o que a propriedade JSON deve verificar. Os seletores de propriedade sempre começam com o sinal de cifrão ($), o que significa a raiz do JSON. Os seletores de propriedade são strings alfanuméricas que também dão suporte aos caracteres "-" e "_". Os elementos de matriz são indicados com a sintaxe [NUMBER] e devem seguir a uma propriedade. São exemplos: $.latency, $.numbers[0], $.errorCode, $.processes[4].averageRuntime.

NUMERIC_OPERATOR

É possível fazer o seguinte: =, !=, <, >, <=, ou >=.

NUMBER

Um valor inteiro com um sinal opcional +ou –, um valor decimal com um sinal opcional + ou – ou um número em uma notação específica, que é um número inteiro ou decimal com um sinal opcional + ou –, seguido por "e", por um valor inteiro com um sinal opcional + ou –.

Exemplos:

{ $.latency >= 500 } { $.numbers[0] < 10e3 } { $.numbers[0] < 10e-3 } { $.processes[4].averageRuntime <= 55.5 } { $.errorCode = 400 } { $.errorCode != 500 } { $.latency > +1000 }

Uso de filtros de métrica para extrair valores de eventos de log delimitados por espaço

Você pode usar filtros de métrica para extrair valores de eventos de log delimitados por espaço. Os caracteres entre um par de colchetes [] ou duas aspas duplas ("") são tratados como um único campo. Por exemplo:

127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] "GET /apache_pb.gif HTTP/1.0" 200 1534 127.0.0.1 - frank [10/Oct/2000:13:35:22 -0700] "GET /apache_pb.gif HTTP/1.0" 500 5324 127.0.0.1 - frank [10/Oct/2000:13:50:35 -0700] "GET /apache_pb.gif HTTP/1.0" 200 4355

Para especificar um padrão de filtro de métrica que analise eventos delimitados por espaço, o padrão de filtro de métrica precisa especificar os campos com um nome, separados por vírgulas, com todo o padrão entre colchetes. Por exemplo: [ip, user, username, timestamp, request, status_code, bytes].

Quando você não souber o número de campos, use uma notificação abreviada com reticências (...). Por exemplo:

[..., status_code, bytes] [ip, user, ..., status_code, bytes] [ip, user, ...]

Você também pode adicionar condições aos seus campos, para que apenas os eventos de log correspondentes a todas as condições coincidam com os filtros. Por exemplo:

[ip, user, username, timestamp, request, status_code, bytes > 1000] [ip, user, username, timestamp, request, status_code = 200, bytes] [ip, user, username, timestamp, request, status_code = 4*, bytes] [ip, user, username, timestamp, request = *html*, status_code = 4*, bytes]

Você pode usar && como um operador AND, como nos exemplos a seguir:

[ip, user, username, timestamp, request, status_code = 4* && status_code = 5*, bytes] [ip, user, username, timestamp, request, status_code = 4* && status_code != 403, bytes]

O CloudWatch Logs oferece suporte a campos de string e numéricos condicionais. Para campos de string, você pode usar os operadores = ou != com um asterisco (*).

Para campos numéricos, você pode usar os operadores >, <, >=, <=, = e !=.

Se você estiver usando um filtro delimitado por espaço, os campos extraídos mapeados para os nomes dos campos delimitados por espaço (conforme expressos no filtro) terão o valor de cada um desses campos. Se você não estiver usando um filtro delimitado por espaço, ficará vazio.

Exemplo de filtro:

[..., request=*.html*, status_code=4*,]

Exemplo de evento de log para o filtro:

127.0.0.1 - frank [10/Oct/2000:13:25:15 -0700] \"GET /index.html HTTP/1.0\" 404 1534

Campos extraídos para o evento de log e padrão de filtro:

{ "$status_code": "404", "$request": "GET /products/index.html HTTP/1.0", "$7": "1534", "$4": "10/Oct/2000:13:25:15 -0700", "$3": "frank", "$2": "-", "$1": "127.0.0.1" }

Definir como os valores de métrica mudam quando são encontradas correspondências

Quando um filtro de métrica encontra um dos termos, frases ou valores correspondentes nos seus eventos de log, ele incrementa a contagem na métrica do CloudWatch pela quantidade que você especificar para o valor de métrica. O valor da métrica é agregado e relatado a cada minuto.

Se forem ingeridos logs durante um período de um minuto, mas nenhuma correspondência for encontrada, o valor especificado para Valor Padrão (se houver) será relatado. No entanto, se nenhum evento de log for ingerido durante um período de um minuto, nenhum valor será relatado.

Especificar um valor padrão, mesmo se esse valor for 0, ajuda a garantir que os dados serão relatadas com mais frequência, ajudando a evitar métricas irregulares quando não são encontradas correspondências.

Por exemplo, suponha que há um grupo de logs que publica dois registros a cada minuto, o valor de métrica é 1 e o valor padrão é 0. Se as correspondências forem encontradas nos dois registros de log no primeiro minuto, o valor de métrica para aquele minuto será 2. Se não houver correspondências nos registros de log publicados no segundo minuto, o valor padrão de 0 será usado para os dois registros de log e o valor de métrica para aquele minuto será 0.

Se você não especificar um valor padrão, nenhum dado será relatado para qualquer período em que não haja correspondências de padrão.

Valores numéricos de publicação encontrados em entradas de log

Em vez de apenas contar o número de itens correspondentes encontrados em logs, você também pode usar o filtro de métrica para publicar valores com base nos valores numéricos encontrados nos logs. O procedimento a seguir mostra como publicar uma métrica com a latência encontrada na solicitação JSON metricFilter: { $.latency = * } metricValue: $.latency.

Para publicar uma métrica com a latência em uma solicitação JSON

  1. Abra o console do CloudWatch em https://console.aws.amazon.com/cloudwatch/.

  2. No painel de navegação, selecione Logs.

  3. No painel de conteúdo, selecione um grupo de logs e escolha Criar filtro de métrica.

  4. Na tela Definir filtro de métrica de logs, em Padrão de filtro, digite { $.latency = * } e, em seguida, escolha Atribuir métrica.

  5. Na tela Criar filtro de métrica e atribuir métrica, escolha Mostrar configurações avançadas de métrica.

  6. Em Nome da métrica, digite myMetric.

  7. Em Valor de métrica, digite $.latency.

  8. Em Valor padrão digite 0 e escolha Criar filtro. Especificar um valor padrão garante que os dados são relatados mesmo durante períodos em que não ocorrem eventos de log. Isso evita métricas irregulares nas quais os dados, às vezes, não existem.

O evento de log a seguir publicaria um valor de 50 para a métrica myMetric após a criação do filtro.

{ "latency": 50, "requestType": "GET" }