Sintaxe de padrões de filtros para filtros de métricas

nota

Como os filtros de métricas diferem nas consultas do CloudWatch Logs Insights

Os filtros de métrica diferem das consultas do CloudWatch Logs Insights porque um valor numérico especificado é adicionado a um filtro de métrica sempre que um registro correspondente é encontrado. Para ter mais informações, consulte Configurando valores métricos para um filtro de métrica.

Para obter informações sobre como consultar seus grupos de CloudWatch logs com a linguagem de consulta Amazon Logs Insights, consulteCloudWatch Sintaxe de consulta do Logs Insights.

Exemplos genéricos de padrões de filtros

Para obter mais informações sobre a sintaxe de padrões de filtros genéricos aplicável a filtros de métricas, bem como filtros de assinatura e filtros de eventos de log, consulte Sintaxe de padrões de filtros para filtros de métricas, filtros de assinatura e filtros de eventos de log, que inclui os seguintes exemplos:

• Sintaxe de expressões regulares (regex) compatíveis

• Como fazer a correspondência de termos em eventos de log não estruturados

• Correspondência de termos em eventos de log JSON

• Como fazer a correspondência de termos em eventos de log delimitados por espaços

Os filtros de métricas permitem pesquisar e filtrar dados de registro que chegam aos CloudWatch registros, extrair observações métricas dos dados de registro filtrados e transformar os pontos de dados em uma métrica de CloudWatch registros. Você define os termos e padrões a serem procurados nos dados de registro à medida que eles são enviados para o CloudWatch Logs. Filtros de métrica são atribuídos a grupos de logs, e todos os filtros atribuídas a um grupo de logs são aplicados a seus streams de log.

Quando um filtro de métrica corresponde a um termo, ele incrementa a contagem da métrica em um valor numérico especificado. Por exemplo, você pode criar um filtro de métrica que conte a ocorrência da palavra ERRO em seus eventos de log.

É possível atribuir unidades de medida e dimensões a métricas. Por exemplo, se você criar um filtro de métrica que conte as vezes que a palavra ERROR ocorre em seus eventos de log, poderá especificar uma dimensão chamada ErrorCode para mostrar o número total de eventos de log que contenham a palavra ERROR (ERRO) e filtrar os dados por códigos de erro relatados.

dica

Ao atribuir uma unidade de medida a uma métrica, certifique-se de especificar a correta. Se você alterar a unidade depois, sua alteração pode não entrar em vigor. Para obter a lista completa das unidades que oferecem CloudWatch suporte, consulte MetricDatuma Amazon CloudWatch API Reference.

Configurando valores métricos para um filtro de métrica

Ao criar um filtro de métrica, você define seu padrão de filtro e especifica o valor da métrica e o valor padrão. Você pode definir valores de métrica para números, identificadores nomeados ou identificadores numéricos. Se você não especificar um valor padrão, CloudWatch não reportará dados quando seu filtro de métricas não encontrar uma correspondência. Recomendamos que você especifique um valor padrão, mesmo que o valor seja 0. Definir um valor padrão ajuda a CloudWatch relatar dados com mais precisão e CloudWatch evita a agregação de métricas irregulares. CloudWatch agrega e relata valores métricos a cada minuto.

Quando o filtro de métrica encontra uma correspondência em seus eventos de log, ele incrementa a contagem da métrica de acordo com o valor da métrica. Se seu filtro de métricas não encontrar uma correspondência, CloudWatch informa o valor padrão da métrica. Por exemplo, seu grupo de logs publica dois registros a cada minuto, o valor de métrica é 1 e o valor padrão é 0. Se o filtro de métrica encontrar correspondências nos dois registros de log no primeiro minuto, o valor de métrica para aquele minuto será 2. Se o filtro de métrica não encontrar correspondências em nenhum dos dois registros durante o segundo minuto, o valor padrão para aquele minuto será 0. Se você atribuir dimensões a métricas geradas por filtros de métrica, não será possível especificar valores padrão para essas métricas.

Você também pode configurar um filtro de métrica para incrementar uma métrica com um valor extraído de um evento de log, em vez de um valor estático. Para obter mais informações, consulte Usando valores em eventos de log para incrementar o valor de uma métrica.

Publicar dimensões com métricas de valores em eventos de log JSON ou delimitados por espaços

Você pode usar o CloudWatch console ou a AWS CLI para criar filtros métricos que publicam dimensões com métricas geradas por JSON e eventos de log delimitados por espaço. As dimensões são pares de valor nome/valor e só estão disponíveis para padrões de filtro JSON e delimitados por espaço. Você pode criar filtros de métrica JSON e delimitados por espaço com até três dimensões. Para obter mais informações sobre dimensões e informações sobre como atribuir dimensões a métricas, consulte as seguintes seções:

• Dimensões no guia do CloudWatch usuário da Amazon

• Exemplo: extraia campos de um log do Apache e atribua dimensões no Guia do usuário do Amazon CloudWatch Logs

Importante

As dimensões contêm valores que coletam cobranças iguais às métricas personalizadas. Para evitar cobranças inesperadas, não especifique campos de alta cardinalidade, por exemplo, IPAddress ou requestID, como dimensões.

Se você extrair métricas de eventos de log, você será cobrado por métricas personalizadas. Para evitar cobranças elevadas acidentais, a Amazon pode desabilitar seu filtro de métrica se este gerar 1.000 pares de nome/valor diferentes para as dimensões especificadas em um período de tempo específico.

Você pode criar alarmes de faturamento que o notificam sobre suas cobranças estimadas. Para obter mais informações, consulte Criação de um alarme de cobrança para monitorar suas AWS cobranças estimadas.

Publicar dimensões com métricas de eventos de log JSON

Os exemplos a seguir contêm trechos de código que descrevem como especificar dimensões em um filtro de métrica JSON.

Example: JSON log event

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

nota

Se você testar o filtro de métrica de exemplo com o exemplo de evento de log JSON, deverá inserir o exemplo de log JSON em uma única linha.

Example: Metric filter

O filtro de métrica incrementa a métrica sempre que um evento de log JSON contiver as propriedades eventType e "sourceIPAddress".

{ $.eventType = "*" && $.sourceIPAddress != 123.123.* }
                            

Ao criar um filtro de métrica JSON, é possível especificar qualquer uma das propriedades no filtro de métrica como dimensão. Por exemplo, para definir eventType como uma dimensão, use o seguinte:

"eventType" : $.eventType
                            

A métrica de exemplo contém uma dimensão nomeada "eventType", e o valor da dimensão no evento de log de exemplo é "UpdateTrail".

Publicar dimensões com métricas de eventos de log delimitados por espaços

Os exemplos a seguir contêm trechos de código que descrevem como especificar dimensões em um filtro de métrica delimitado por espaço.

Example: Space-delimited log event

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

                            

Example: Metric filter

                                
[ip, server, username, timestamp, request, status_code, bytes > 1000]
                           
                            

O filtro de métrica incrementa a métrica quando um evento de log delimitado por espaço inclui qualquer um dos campos especificados no filtro. Por exemplo, o filtro de métrica encontra os seguintes campos e valores no exemplo de evento de log delimitado por espaço.

{
   "$bytes": "1534", 
   "$status_code": "404", 

   "$request": "GET /index.html HTTP/1.0", 
   "$timestamp": "10/Oct/2000:13:25:15 -0700", 
   "$username": "frank",
   "$server": "Prod", 
   "$ip": "127.0.0.1"
}

Ao criar um filtro de métrica delimitado por espaço, é possível especificar qualquer um dos campos no filtro de métrica como uma dimensão. Por exemplo, para definir server como uma dimensão, use o seguinte:

"server" : $server

O filtro de métrica de exemplo contém uma dimensão nomeada server, e o valor da dimensão no evento de log de exemplo é "Prod".

Example: Match terms with AND (&&) and OR (||)

Você pode usar os operadores lógicos AND ("&&") e OR ("||") para criar filtros de métrica delimitados por espaço que contenham condições. O filtro de métrica a seguir retorna eventos de log em que a primeira palavra nos eventos é ERROR ou qualquer string que contenha WARN.

[w1=ERROR || w1=%WARN%, w2]
                            

Usando valores em eventos de log para incrementar o valor de uma métrica

Você pode criar filtros de métrica que publicam valores numéricos encontrados em eventos de log. O procedimento nesta seção usa o seguinte exemplo de filtro de métrica para mostrar como você pode publicar um valor numérico em um evento de log JSON em uma métrica.

{ $.latency = * } metricValue: $.latency

Criar um filtro de métrica que publique um valor em um evento de log

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

2. No painel de navegação, escolha Logs e, em seguida, escolha Grupos de log.

3. Selecione ou crie um grupo de logs.

   Para obter informações sobre como criar um grupo de registros, consulte Criar um grupo de CloudWatch registros em Logs no Guia do usuário do Amazon CloudWatch Logs.

4. Escolha Actions (Ações) e Create metric filter (Criar filtro de métrica).

5. Em Padrão de filtro, digite { $.latency = * } e escolha Próximo.

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

7. Em Valor da métrica, insira $.latency.

8. (Opcional) Em Valor padrão, insira 0 e escolha Próximo.

   Recomendamos que você especifique um valor padrão, mesmo que o valor seja 0. Definir um valor padrão ajuda a CloudWatch relatar dados com mais precisão e CloudWatch evita a agregação de métricas irregulares. CloudWatch agrega e relata valores métricos a cada minuto.

9. Escolha Criar filtro de métrica.

O filtro de métrica de exemplo corresponde ao termo "latency" no exemplo de evento de log JSON e publica um valor numérico de 50 na métrica MyMetric.

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