As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Salve e execute novamente as consultas do CloudWatch Logs Insights

Depois de criar uma consulta, você pode salvá-la para que possa ser executada novamente mais tarde. As consultas são salvas em uma estrutura de pastas para que você possa organizá-las. Você pode salvar até 1.000 consultas por região e por conta.

As consultas são salvas em um nível específico da região, não em um nível específico do usuário. Se você criar e salvar uma consulta, outros usuários com acesso aos CloudWatch registros na mesma região poderão ver todas as consultas salvas e suas estruturas de pastas na região.

Para salvar uma consulta, você deve estar conectado a uma função que tenha a permissão logs:PutQueryDefinition. Para ver uma lista de consultas salvas, você deve estar conectado a uma função que tenha a permissãologs:DescribeQueryDefinitions.

Console

Para salvar uma consulta

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

2. No painel de navegação à esquerda, escolha Logs e, em seguida, escolha Log Insights(Insights de log).

3. No editor de consultas, crie uma consulta.

4. Escolha Salvar.

5. Insira um nome para a consulta.

6. (Opcional) Escolha uma pasta na qual deseja salvar a consulta. Selecione Criar novo para criar uma pasta. Se você criar uma pasta, poderá usar caracteres de barra (/) no nome da pasta para definir uma estrutura de pasta. Por exemplo, dar o nome folder-level-1/folder-level-2 a uma nova pasta cria uma pasta de nível superior chamada folder-level-1, com outra pasta chamada folder-level-2 dentro dela. A consulta é salva em folder-level-2.

7. (Opcional) Altere os grupos de log da consulta ou o texto da consulta.

8. (Opcional) Para usar parâmetros em sua consulta, siga estas etapas adicionais:

   1. Adicione parâmetros à sua consulta. Substitua valores estáticos por espaços reservados usando a {{parameter}} sintaxe (chaves duplas antes e depois do nome do parâmetro).

      Exemplo: consulta original com valores estáticos:

      fields @timestamp, @message
      | filter level = "Error"
      | filter applicationName = "OrderService"

      Consulta atualizada com parâmetros:

      fields @timestamp, @message
      | filter level = {{logLevel}}
      | filter applicationName = {{applicationName}}

   2. Defina os parâmetros usados na sua consulta. Para cada parâmetro de espaço reservado, especifique:

      • Nome: deve corresponder exatamente ao nome do espaço reservado (por exemplo,logLevel,applicationName).

      • Valor padrão (opcional): o valor a ser usado se nenhum valor de parâmetro for fornecido.

      • Descrição (opcional): explica a finalidade do parâmetro.

   3. As consultas com parâmetros podem ser executadas usando o nome da consulta com um $ prefixo e passando os nomes dos parâmetros como pares de valores-chave. Consulte Para executar uma consulta salva para obter detalhes.

9. Escolha Salvar.

AWS CLI

Para salvar uma consulta, useput-query-definition:

aws logs put-query-definition \
  --name "ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = \"ERROR\"" \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1

(Opcional) Para salvar uma consulta com parâmetros, adicione a --parameters opção e use {{parameterName}} espaços reservados na sequência de caracteres de consulta:

aws logs put-query-definition \
  --name "ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}" \
  --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"},{"name":"applicationName","defaultValue":"OrderService","description":"Application name to filter"}]' \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1

Para salvar uma consulta em uma pasta, prefixe o nome da consulta com o caminho da pasta:

aws logs put-query-definition \
  --name "my-folder/ErrorsByLevel" \
  --query-string "fields @timestamp, @message | filter level = {{logLevel}}" \
  --parameters '[{"name":"logLevel","defaultValue":"ERROR","description":"Log level to filter"}]' \
  --log-group-names "/aws/lambda/my-function" \
  --region us-east-1

API

Para salvar uma consulta, chame PutQueryDefinition:

{
  "name": "ErrorsByLevel",
  "queryString": "fields @timestamp, @message | filter level = \"ERROR\"",
  "logGroupNames": ["/aws/lambda/my-function"]
}

(Opcional) Para salvar uma consulta com parâmetros, inclua o parameters campo e use {{parameterName}} espaços reservados na sequência de caracteres de consulta:

{
  "name": "ErrorsByLevel",
  "queryString": "fields @timestamp, @message | filter level = {{logLevel}} | filter applicationName = {{applicationName}}",
  "logGroupNames": ["/aws/lambda/my-function"],
  "parameters": [
    {
      "name": "logLevel",
      "defaultValue": "ERROR",
      "description": "Log level to filter"
    },
    {
      "name": "applicationName",
      "defaultValue": "OrderService",
      "description": "Application name to filter"
    }
  ]
}

Console

Como executar uma consulta salva

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

2. No painel de navegação à esquerda, escolha Logs e, em seguida, escolha Log Insights(Insights de log).

3. À direita, escolha Consultas.

4. Selecione sua consulta na lista Consultas salvas. O texto da consulta aparece no editor de consultas.

5. (Opcional) Para usar uma consulta com parâmetros:

   1. Escolha o ícone + ao lado do nome da consulta no painel lateral Consultas salvas.

   2. A consulta com parâmetros aparece no editor de consultas. Por exemplo, se você escolher o ícone + ao ladoErrorsByLevel, o editor de consultas será preenchido com: $ErrorsByLevel(level=, applicationName=)

   3. Forneça os valores para os parâmetros (level, applicationName) e execute a consulta. Por exemplo: $ErrorsByLevel(level= "ERROR", applicationName= "OrderService")

6. Escolha Executar.

AWS CLI

Para executar uma consulta salva com parâmetros

Use start-query com a $QueryName() sintaxe:

aws logs start-query \
  --log-group-names "/aws/lambda/my-function" \
  --start-time 1707566400 --end-time 1707570000 \
  --query-string '$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")' \
  --region us-east-1

API

Para executar uma consulta salva com parâmetros

Ligue StartQuerycom a $QueryName() sintaxe no queryString campo:

{
  "logGroupNames": ["/aws/lambda/my-function"],
  "startTime": 1707566400,
  "endTime": 1707570000,
  "queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")"
}

Para excluir uma consulta, você deve estar conectado a uma função que tenha a permissão logs:DeleteQueryDefinition.

Usando consultas salvas com parâmetros

As consultas salvas com parâmetros são modelos de consulta reutilizáveis com espaços reservados nomeados. Em vez de manter várias cópias de consultas quase idênticas, você pode salvar um modelo e fornecer valores de parâmetros diferentes ao executar a consulta. Os parâmetros só são compatíveis com a linguagem de consulta do CloudWatch Logs Insights.

Como funciona

Ao salvar uma consulta, os espaços reservados identificam os valores que você pode fornecer no momento da execução da consulta. Os espaços reservados usam a {{parameterName}} sintaxe. Veja a seguir um exemplo de uma consulta salva chamada ErrorsByLevel com dois parâmetros logLevel applicationName e.

fields @timestamp, @message
| filter level = {{logLevel}}
| filter applicationName = {{applicationName}}

Para executar uma consulta salva, você pode invocá-la usando o nome da consulta prefixado com $ e transmitindo os valores dos parâmetros. O mecanismo de consulta do CloudWatch Logs Insights substitui cada espaço reservado. Se um parâmetro contiver valores padrão, esses valores serão usados se nenhum outro valor for fornecido.

# Run query by using query name and passing parameter values explicitly
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService")

# Run query without specifying parameter values - default values are used in this case.
$ErrorsByLevel()

Os nomes de consulta salvos contendo espaços ou caracteres especiais precisam ser colocados entre aspas:

$`Errors By Level`(logLevel = "WARN")

Exemplos de consultas salvas com parâmetros

Adicionando um limite de resultados como parâmetro

Nome da consulta: ErrorsByLevel com parâmetros logLevel (padrão:"ERROR"), applicationName (padrão:"OrderService") e maxResults (padrão:50)

fields @timestamp, @message, @logStream
| filter level = {{logLevel}}
| filter applicationName = {{applicationName}}
| sort @timestamp desc
| limit {{maxResults}}

# Run the query using the query name and passing parameter values
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService", maxResults = 100)

Usando várias consultas salvas com parâmetros

O exemplo abaixo usa ErrorsByLevel uma segunda consulta salva RecentN que é definida como sort @timestamp desc | limit {{count}} (com parâmetrocount, padrão20). O mecanismo de consulta do CloudWatch Logs Insights expande cada consulta antes de executá-la.

# Using multiple queries with parameters in sequence
$ErrorsByLevel(logLevel = "WARN", applicationName = "OrderService")
| $RecentN(count = 10)

# Each of the queries is expanded, resulting in the following query when it is run.
fields @timestamp, @message
| filter level = "WARN"
| filter applicationName = "OrderService"
| sort @timestamp desc
| limit 10

Cotas e tratamento de erros

A sequência de caracteres de consulta expandida não pode exceder 10.000 caracteres. Os nomes dos parâmetros devem começar com uma letra ou sublinhado. Uma consulta salva não pode fazer referência a outra consulta salva (não há suporte para invocações aninhadas).