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ão`logs:DescribeQueryDefinitions`. **nota** Você pode criar e salvar consultas com parâmetros — modelos reutilizáveis com espaços reservados nomeados. Em vez de salvar várias variações da mesma consulta com valores diferentes, crie um modelo e forneça valores de parâmetros diferentes ao executá-lo. Atualmente, essa funcionalidade é compatível com consultas usando somente a linguagem de consulta do Logs Insights. Para obter mais informações, consulte [Usando consultas salvas com parâmetros](#CWL_Insights-Parameterized-Queries). ------ #### [ Console ] **Para salvar uma consulta** 1. Abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. No painel de navegação à esquerda, escolha **Logs** e, em seguida, escolha **Log Insights**(Insights de log). 1. No editor de consultas, crie uma consulta. 1. Escolha **Salvar**. 1. Insira um nome para a consulta. 1. (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**. 1. (Opcional) Altere os grupos de log da consulta ou o texto da consulta. 1. (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}} ``` 1. **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. 1. 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. 1. Escolha **Salvar**. ------ #### [ AWS CLI ] **Para salvar uma consulta**, use`put-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](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html): ``` { "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" } ] } ``` ------ **dica** Você pode criar uma pasta para consultas salvas usando `PutQueryDefinition`. Para criar uma pasta para as consultas salvas, use uma barra (/) para prefixar o nome da consulta desejada com o nome da pasta desejada: `/`. Para obter mais informações sobre a ação, consulte [PutQueryDefinition](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutQueryDefinition.html). ------ #### [ Console ] **Como executar uma consulta salva** 1. Abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. No painel de navegação à esquerda, escolha **Logs** e, em seguida, escolha **Log Insights**(Insights de log). 1. À direita, escolha **Consultas**. 1. Selecione sua consulta na lista **Consultas salvas**. O texto da consulta aparece no editor de consultas. 1. (Opcional) Para usar uma consulta com parâmetros: 1. Escolha o ícone **\$1** ao lado do nome da consulta no painel lateral **Consultas salvas**. 1. A consulta com parâmetros aparece no editor de consultas. Por exemplo, se você escolher o ícone **\$1** ao lado`ErrorsByLevel`, o editor de consultas será preenchido com: `$ErrorsByLevel(level=, applicationName=)` 1. Forneça os valores para os parâmetros (level, applicationName) e execute a consulta. Por exemplo: `$ErrorsByLevel(level= "ERROR", applicationName= "OrderService")` 1. 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 [StartQuery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_StartQuery.html)com a `$QueryName()` sintaxe no `queryString` campo: ``` { "logGroupNames": ["/aws/lambda/my-function"], "startTime": 1707566400, "endTime": 1707570000, "queryString": "$ErrorsByLevel(level=\"ERROR\", applicationName= \"OrderService\")" } ``` ------ **Como salvar uma nova versão de uma consulta salva** 1. Abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. No painel de navegação à esquerda, escolha **Logs** e, em seguida, escolha **Log Insights**(Insights de log). 1. À direita, escolha **Consultas**. 1. Selecione sua consulta na lista de **Consultas salvas**. Ela aparece no editor de consulta. 1. Modifique a consulta. Se você precisar executá-la para verificar seu trabalho, escolha **Executar consulta**. 1. Quando estiver pronto para salvar a nova versão, escolha **Ações**, **Salvar como**. 1. Insira um nome para a consulta. 1. (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**. 1. (Opcional) Altere os grupos de log da consulta ou o texto da consulta. 1. Escolha **Save**(Salvar). Para excluir uma consulta, você deve estar conectado a uma função que tenha a permissão `logs:DeleteQueryDefinition`. **Como editar ou excluir uma consulta salva** 1. Abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. No painel de navegação à esquerda, escolha **Logs** e, em seguida, escolha **Log Insights**(Insights de log). 1. À direita, escolha **Consultas**. 1. Selecione sua consulta na lista de **Consultas salvas**. Ela aparece no editor de consulta. 1. Escolha **Ações**, **Editar** ou **Ações**, **Excluir**. ## 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âmetro`count`, padrão`20`). 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 **nota** Cada consulta salva pode ter no máximo 20 parâmetros. 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). **Erros comuns** | Erro | Causa | | --- | --- | | Os parâmetros são suportados somente para a linguagem de consulta CWLI | Os parâmetros só são compatíveis com a linguagem de consulta do CloudWatch Logs Insights. | | Parâmetros obrigatórios não encontrados em QueryString | O nome de um parâmetro em `--parameters` não tem uma correspondência `{{placeholder}}` na sequência de caracteres de consulta. | | A contagem de parâmetros excede o máximo de 20 | No momento, as consultas salvas oferecem suporte a apenas 20 parâmetros. | | Nome do parâmetro duplicado | A definição da consulta tem parâmetros duplicados em`parameters`. | **nota** Para criar ou atualizar uma consulta salva com parâmetros, você precisa da `logs:PutQueryDefinition` permissão. Para executar um, você precisa `logs:StartQuery` `logs:DescribeQueryDefinitions` e.