.*?)/ | stats avg(latency2) by @method2,
@user2
```
**Extrai os campos `loggingTime`, `loggingType` e `loggingMessage`, aplica o filtro para eventos de logs que contêm strings `ERROR` ou `INFO` e exibe apenas os campos `loggingMessage` e `loggingType` para eventos que contêm uma string `ERROR`.**
```
FIELDS @message
| PARSE @message "* [*] *" as loggingTime, loggingType, loggingMessage
| FILTER loggingType IN ["ERROR", "INFO"]
| DISPLAY loggingMessage, loggingType = "ERROR" as isError
```
# sort
Use `sort` para exibir eventos de log em ordem crescente (`asc`) ou decrescente (`desc`) por um campo especificado. Use-o com o comando `limit` para criar consultas de “N principais” ou “N inferiores”.
O algoritmo de classificação é uma versão atualizada da classificação natural. Se você classificar em ordem crescente, a lógica a seguir será usada.
+ Todos os valores não numéricos vêm antes de todos os valores numéricos. *Valores numéricos* são valores que só incluem números, não uma mistura de números e outros caracteres.
+ Para valores não numéricos, o algoritmo agrupa caracteres numéricos consecutivos e caracteres alfabéticos consecutivos em blocos separados para comparação. Ele ordena as partes não numéricas pelos valores Unicode e as partes numéricas primeiro pelo tamanho e depois pelo valor numérico.
Para obter mais informações sobre a ordem Unicode, consulte [Lista de caracteres Unicode](https://en.wikipedia.org/wiki/List_of_Unicode_characters).
Por exemplo, o resultado a seguir é classificado na ordem crescente.
```
!: >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> sorted by unicode order
#
*%04
0# >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Alphanumeric starting with numbers
5A
111A >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Starts with more digits than 5A, so it sorted to be later than 5A
2345_
@ >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> 2345 is compared with @ in the unicode order,
@_
A >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Values starting with letters
A9876fghj
a12345hfh
0 >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> Number values
01
1
2
3
```
Se você classificar na ordem decrescente, os resultados da classificação serão invertidos.
Por exemplo, a consulta a seguir de logs de fluxo da Amazon VPC localiza as 15 principais transferências de pacotes entre hosts.
```
stats sum(packets) as packetsTransferred by srcAddr, dstAddr
| sort packetsTransferred desc
| limit 15
```
# stats
Use `stats` para criar visualizações dos seus dados de log, como gráficos de barras, gráficos de linhas e gráficos de áreas empilhadas. Isso ajuda você a identificar padrões em seus dados de registro com mais eficiência. CloudWatch O Logs Insights gera visualizações para consultas que usam a `stats` função e uma ou mais funções de agregação.
Por exemplo, a consulta a seguir em um grupo de logs do Route 53 retorna visualizações que mostram a distribuição dos registros do Route 53 por hora, por tipo de consulta.
```
stats count(*) by queryType, bin(1h)
```
Todas essas consultas podem produzir gráficos de barras. Se sua consulta usar a função `bin()` para agrupar os dados por um campo ao longo do tempo, você também poderá ver gráficos de linhas e gráficos de áreas empilhadas.
As unidades e abreviações de tempo a seguir são compatíveis com a função `bin`. Para todas as unidades e abreviações que incluem mais de um caractere, é permitido adicionar "s" para formar o plural. Assim, ambos `hr` e `hrs` funcionam para especificar horas.
+ `millisecond` `ms` `msec`
+ `second` `s` `sec`
+ `minute` `m` `min`
+ `hour` `h` `hr`
+ `day` `d`
+ `week` `w`
+ `month` `mo` `mon`
+ `quarter` `q` `qtr`
+ `year` `y` `yr`
**Topics**
+ [Visualizar dados de séries temporais](#CWL_Insights-Visualizing-TimeSeries)
+ [Visualizar dados de log agrupados por campos](#CWL_Insights-Visualizing-ByFields)
+ [Use vários comandos de estatísticas em uma única consulta](#CWL_QuerySyntax-stats-multi)
+ [Funções para uso com estatísticas](#CWL_QuerySyntax-stats-functions)
## Visualizar dados de séries temporais
As visualizações de séries temporais funcionam para consultas com as seguintes características:
+ A consulta contém uma ou mais funções de agregação. Para obter mais informações, consulte [Aggregation Functions in the Stats Command](#CWL_Insights_Aggregation_Functions).
+ A consulta usa a função `bin()` para agrupar os dados por um campo.
Essas consultas podem produzir gráficos de linha, gráficos de áreas empilhadas, gráficos de barras e gráficos de pizza.
**Exemplos**
Para obter um tutorial completo, consulte [Tutorial: Executar uma consulta que produz uma visualização de séries temporais](CWL_AnalyzeLogData_VisualizationQuery.md).
Aqui estão mais exemplos de consultas que funcionam para visualização de séries temporais.
A consulta a seguir gera uma visualização dos valores médios do campo `myfield1`, com um ponto de dados criado a cada cinco minutos. Cada ponto de dados é a agregação das médias dos valores `myfield1` dos logs dos últimos cinco minutos.
```
stats avg(myfield1) by bin(5m)
```
A consulta a seguir gera uma visualização dos três valores com base em campos diferentes, com um ponto de dados criado a cada cinco minutos. A visualização é gerada porque a consulta contém funções de agregação e usa `bin()` como o campo de agrupamento.
```
stats avg(myfield1), min(myfield2), max(myfield3) by bin(5m)
```
**Restrições do gráfico de linhas e do gráfico de áreas empilhadas**
Consultas que agregam informações de entrada de log, mas que não usam a função `bin()`, podem gerar gráficos de barras. No entanto, as consultas não podem gerar gráficos de linha ou gráficos de áreas empilhadas. Para obter mais informações sobre esses tipos de políticas, consulte [Visualizar dados de log agrupados por campos](#CWL_Insights-Visualizing-ByFields).
## Visualizar dados de log agrupados por campos
É possível produzir gráficos de barras para consultas que usam a função `stats` e uma ou mais funções de agregação. Para obter mais informações, consulte [Aggregation Functions in the Stats Command](#CWL_Insights_Aggregation_Functions).
Para ver a visualização, execute sua consulta. Depois, escolha a guia **Visualization**(Visualização), selecione a seta ao lado de **Line**(Linha) e escolha **Bar**(Barra). As visualizações estão limitadas a até 100 barras no gráfico de barras.
**Exemplos**
Para obter um tutorial completo, consulte [Tutorial: Executar uma consulta que produz uma visualização agrupada por campos de log](CWL_AnalyzeLogData_VisualizationFieldQuery.md). Os parágrafos a seguir incluem mais consultas de exemplo para a visualização por campos.
A consulta de log de fluxo da VPC a seguir localiza o número médio de bytes transferidos por sessão para cada endereço de destino.
```
stats avg(bytes) by dstAddr
```
Também é possível produzir um gráfico que inclua mais de uma barra para cada valor resultante. Por exemplo, a consulta de log de fluxo da VPC a seguir localiza o número médio e máximo de bytes transferidos por sessão para cada endereço de destino.
```
stats avg(bytes), max(bytes) by dstAddr
```
A consulta a seguir localiza o número de logs de consulta do Amazon Route 53 para cada tipo de consulta.
```
stats count(*) by queryType
```
## Use vários comandos de estatísticas em uma única consulta
Você pode usar até dois comandos `stats` em uma única consulta. Isso permite executar uma agregação adicional na saída da primeira agregação.
**Exemplo: consulta com dois comandos `stats`**
Por exemplo, a consulta a seguir localiza primeiro o volume total de tráfego em compartimentos de cinco minutos e, em seguida, calcula o volume de tráfego mais alto, mais baixo e médio entre esses compartimentos de cinco minutos.
```
FIELDS strlen(@message) AS message_length
| STATS sum(message_length)/1024/1024 as logs_mb BY bin(5m)
| STATS max(logs_mb) AS peak_ingest_mb,
min(logs_mb) AS min_ingest_mb,
avg(logs_mb) AS avg_ingest_mb
```
**Exemplo: combine vários comandos de estatísticas com outras funções, como `filter`, `fields` e `bin`**
Você pode combinar dois comandos `stats` com outros comandos, como `filter` e `fields`, em uma única consulta. Por exemplo, a consulta a seguir localiza o número de endereços IP distintos nas sessões e localiza o número de sessões por plataforma do cliente, filtra esses endereços IP e, por fim, localiza a média de solicitações de sessão por plataforma do cliente.
```
STATS count_distinct(client_ip) AS session_ips,
count(*) AS requests BY session_id, client_platform
| FILTER session_ips > 1
| STATS count(*) AS multiple_ip_sessions,
sum(requests) / count(*) AS avg_session_requests BY client_platform
```
Você pode usar as funções `bin` e `dateceil` em consultas com vários comandos `stats`. Por exemplo, a consulta a seguir primeiro combina mensagens em blocos de cinco minutos, depois agrega esses blocos de cinco minutos em blocos de dez minutos e calcula os volumes de tráfego mais altos, mais baixos e médios dentro de cada bloco de dez minutos.
```
FIELDS strlen(@message) AS message_length
| STATS sum(message_length) / 1024 / 1024 AS logs_mb BY BIN(5m) as @t
| STATS max(logs_mb) AS peak_ingest_mb,
min(logs_mb) AS min_ingest_mb,
avg(logs_mb) AS avg_ingest_mb BY dateceil(@t, 10m)
```
**Observações e limitações**
Uma consulta pode ter no máximo dois comandos `stats`. Não é possível alterar esta cota.
Se você usar um comando `sort` ou `limit`, ele deverá aparecer após o segundo comando `stats`. Se estiver antes do segundo comando `stats`, a consulta não é válida.
Quando uma consulta tem dois comandos `stats`, a exibição dos resultados parciais da consulta só começará quando a primeira agregação `stats` for concluída.
No segundo comando `stats` de uma única consulta, você pode se referir somente aos campos definidos no primeiro comando `stats`. Por exemplo, a consulta a seguir não é válida porque o campo `@message` não estará disponível após a primeira agregação `stats`.
```
FIELDS @message
| STATS SUM(Fault) by Operation
# You can only reference `SUM(Fault)` or Operation at this point
| STATS MAX(strlen(@message)) AS MaxMessageSize # Invalid reference to @message
```
Todos os campos que você referenciar após o primeiro comando `stats` devem ser definidos nesse primeiro comando `stats`.
```
STATS sum(x) as sum_x by y, z
| STATS max(sum_x) as max_x by z
# You can only reference `max(sum_x)`, max_x or z at this point
```
**Importante**
A função `bin` sempre usa implicitamente o campo `@timestamp`. Isso significa que você não pode usar `bin` no segundo comando `stats` sem usar o primeiro comando `stats` para propagar o campo `timestamp`. Por exemplo, a consulta a seguir não é válida.
```
FIELDS strlen(@message) AS message_length
| STATS sum(message_length) AS ingested_bytes BY @logStream
| STATS avg(ingested_bytes) BY bin(5m) # Invalid reference to @timestamp field
```
Em vez disso, defina o campo `@timestamp` no primeiro comando `stats` e, em seguida, você poderá usá-lo com `dateceil` no segundo comando `stats`, como no exemplo a seguir.
```
FIELDS strlen(@message) AS message_length
| STATS sum(message_length) AS ingested_bytes, max(@timestamp) as @t BY @logStream
| STATS avg(ingested_bytes) BY dateceil(@t, 5m)
```
## Funções para uso com estatísticas
CloudWatch O Logs Insights suporta funções de agregação de estatísticas e funções de não agregação de estatísticas.
Use funções de agregação de estatísticas no comando `stats` e como argumentos de outras funções.
| Função | Tipo de resultado | Description |
| --- | --- | --- |
| `avg(fieldName: NumericLogField)` | número | A média dos valores no campo especificado. |
| `count()` `count(fieldName: LogField)` | número | Faz a contagem dos eventos de log. `count()` (ou `count(*)`) conta todos os eventos retornados pela consulta, e o `count(fieldName)` conta todos os registros que incluam o nome do campo especificado. |
| `count_distinct(fieldName: LogField)` | número | Retorna o número de valores exclusivos do campo. Se o campo tiver cardinalidade muito alta (muitos valores exclusivos), o valor retornado por `count_distinct` será apenas uma aproximação. |
| `max(fieldName: LogField)` | LogFieldValue | O máximo dos valores desse campo de log nos logs consultados. |
| `min(fieldName: LogField)` | LogFieldValue | O mínimo dos valores desse campo de log nos logs consultados. |
| `pct(fieldName: LogFieldValue, percent: number)` | LogFieldValue | Um percentil indica a posição relativa de um valor no conjunto de dados. Por exemplo, `pct(@duration, 95)` retorna o valor `@duration` em que 95% dos valores de `@duration` são menores que esse valor e 5% são maiores que esse valor. |
| `stddev(fieldName: NumericLogField)` | número | O desvio padrão dos valores no campo especificado. |
| `sum(fieldName: NumericLogField)` | número | A soma dos valores no campo especificado. |
**Funções de estatísticas de não agregação**
Use funções de não agregação no comando `stats` e como argumentos de outras funções.
| Função | Tipo de resultado | Description |
| --- | --- | --- |
| `earliest(fieldName: LogField)` | LogField | Retorna o valor de `fieldName` do evento do log que tem o primeiro time stamp nos logs consultados. |
| `latest(fieldName: LogField)` | LogField | Retorna o valor de `fieldName` do evento do log que tem o último time stamp nos logs consultados. |
| `sortsFirst(fieldName: LogField)` | LogField | Retorna o valor do `fieldName` que aparece em primeiro lugar nos logs consultados. |
| `sortsLast(fieldName: LogField)` | LogField | Retorna o valor do `fieldName` que aparece em último lugar nos logs consultados. |
# limite
Use `limit` para especificar o número de eventos de log que você deseja que sua consulta retorne. Se você omitir `limit`, a consulta retornará até 10.000 eventos de log nos resultados.
Por exemplo, o exemplo a seguir retorna apenas os 25 eventos de log mais recentes
```
fields @timestamp, @message | sort @timestamp desc | limit 25
```
# dedup
Use `dedup` para remover resultados duplicados com base em valores específicos em campos que você especifica. É possível usar `dedup` com um ou mais campos. Se você especificar um campo com `dedup`, apenas um evento de log será retornado para cada valor exclusivo desse campo. Se especificar vários campos, um evento de log será retornado para cada combinação exclusiva de valores desses campos.
As duplicatas serão descartadas em ordem de classificação, e apenas o primeiro resultado dessa ordem será mantido. Convém classificar os resultados antes de os submeter ao comando `dedup`. Se os resultados não forem classificados antes de serem executados por `dedup`, a ordem de classificação decrescente padrão `@timestamp` será usada.
Valores nulos não são considerados duplicatas para avaliação. Eventos de log com valores nulos para qualquer um dos campos especificados são mantidos. Para eliminar campos com valores nulos, use **`filter`** com a função `isPresent(field)`.
O único comando de consulta que você pode usar em uma consulta após o comando `dedup` é `limit`.
Quando você usa `dedup` em uma consulta, o console exibe uma mensagem como **Mostrar registros X de Y**, em que X é o número de resultados desduplicados e Y é o número total de registros correspondidos antes da desduplicação. Isso indica que os registros duplicados foram removidos e não significa que faltam dados.
**Exemplo: visualizar somente o evento de log mais recente de cada valor exclusivo do campo chamado `server`**
O exemplo a seguir mostra os campos `timestamp`, `server`, `severity` e `message` somente para o evento mais recente de cada valor exclusivo de `server`.
```
fields @timestamp, server, severity, message
| sort @timestamp desc
| dedup server
```
Para ver mais exemplos de consultas do CloudWatch Logs Insights, consulte[Consultas gerais](CWL_QuerySyntax-examples.md#CWL_QuerySyntax-examples-general).
# unmask
Use `unmask` para exibir todo o conteúdo de um evento de log que tenha algum conteúdo mascarado devido à política de proteção de dados. Para usar este comando, você deve ter a permissão `logs:Unmask`.
Para mais informações sobre a proteção de dados nos grupos de logs, acesse [Ajude a proteger dados de log confidenciais com mascaramento](mask-sensitive-log-data.md).
# unnest
Use `unnest` para nivelar uma lista usada como entrada para gerar vários registros com um único registro para cada elemento na lista. Com base no número de itens que um campo contém, esse comando descarta o registro atual e gera novos registros. Cada registro inclui o `unnested_field`, que representa um item. Todos os outros campos vêm do registro original.
A entrada para `unnest` é `LIST`, que vem da função `jsonParse`. Para obter mais informações, consulte [Tipos de estrutura](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax-operations-functions.html#CWL_QuerySyntax-structure-types). Quaisquer outros tipos, como `MAP`, `String` e `numbers`, são tratados como uma lista com um item no `unnest`.
**Estrutura do comando**
O exemplo a seguir descreve o formato desse comando.
```
unnest field into unnested_field
```
**Consulta de exemplo**
O exemplo a seguir analisa uma string de objeto JSON e expande uma lista de eventos de campo.
```
fields jsonParse(@message) as json_message
| unnest json_message.events into event
| display event.name
```
O evento de logs para essa consulta de exemplo pode ser uma string JSON da seguinte forma:
```
{
"events": [
{
"name": "exception"
},
{
"name": "user action"
}
]
}
```
Nesse caso, a consulta de amostra produz dois registros no resultado da consulta, um com `event.name` como `exception` e outro com `event.name` como **ação do usuário**.
**Consulta de exemplo**
O exemplo a seguir nivela uma lista e depois filtra os itens.
```
fields jsonParse(@message) as js
| unnest js.accounts into account
| filter account.type = "internal"
```
**Consulta de exemplo**
O exemplo a seguir nivela uma lista para agregação.
```
fields jsonParse(trimmedData) as accounts
| unnest accounts into account
| stats sum(account.droppedSpans) as n by account.accountId
| sort n desc
| limit 10
```
# lookup
Use `lookup` para enriquecer os resultados da consulta com dados de referência de uma tabela de pesquisa. Uma tabela de pesquisa contém dados CSV que você carrega para o Amazon CloudWatch Logs. Quando uma consulta é executada, o `lookup` comando combina um campo em seus eventos de log com um campo na tabela de pesquisa e acrescenta os campos de saída especificados aos resultados.
Use tabelas de pesquisa para cenários de enriquecimento de dados, como mapear detalhes do usuário IDs para o usuário, códigos do produto para informações do produto ou códigos de erro para descrições de erros.
## Criação e gerenciamento de tabelas de pesquisa
Antes de usar o `lookup` comando em uma consulta, você deve criar uma tabela de pesquisa. Você pode criar e gerenciar tabelas de pesquisa a partir do CloudWatch console ou usando a API Amazon CloudWatch Logs.
**Para criar uma tabela de pesquisa (console)**
1. Abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. No painel de navegação, escolha **Configurações** e, em seguida, escolha a guia **Registros**.
1. Role até **Pesquisar tabelas** e escolha **Gerenciar**.
1. Escolha **Criar tabela de pesquisa**.
1. Insira um nome para a tabela de pesquisa. O nome só pode conter caracteres alfanuméricos, hífens e sublinhados.
1. (Opcional) Insira uma descrição.
1. Faça upload de um arquivo CSV. O arquivo deve incluir uma linha de cabeçalho com nomes de colunas, usar a codificação UTF-8 e não exceder 10 MB.
1. (Opcional) Especifique uma AWS KMS chave para criptografar os dados da tabela.
1. Escolha **Criar**.
Depois de criar uma tabela de pesquisa, você pode visualizá-la no editor de consultas do CloudWatch Logs Insights. Escolha a guia **Pesquisar tabelas** para procurar tabelas disponíveis e seus campos.
Para atualizar uma tabela de pesquisa, selecione a tabela e escolha **Ações**, **Atualizar**. Faça upload de um novo arquivo CSV para substituir todo o conteúdo existente. Para excluir uma tabela de pesquisa, escolha **Ações**, **Excluir**.
**nota**
Você pode criar até 100 tabelas de pesquisa por conta por Região da AWS. Os arquivos CSV podem ter até 10 MB. Você também pode gerenciar tabelas de pesquisa usando a API Amazon CloudWatch Logs. Para obter mais informações, consulte [CreateLookupTable](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateLookupTable.html)a *Referência da API Amazon CloudWatch Logs*.
**nota**
Se a tabela de pesquisa for criptografada com uma chave KMS, o chamador deverá ter a `kms:Decrypt` permissão na chave (a chave KMS usada para criptografar a tabela de pesquisa) para usar a `StartQuery` API com uma consulta que faça referência a essa tabela de pesquisa. Para obter mais informações, consulte [Criptografe tabelas de pesquisa em CloudWatch registros usando AWS Key Management Service](encrypt-lookup-tables-kms.md).
## Sintaxe de consulta para pesquisa
**Estrutura do comando**
O seguinte mostra o formato desse comando.
```
lookup table lookup-field as log-field [,...] output-mode output-field[,...]
```
O comando usa os seguintes argumentos:
+ `table`— O nome da tabela de pesquisa a ser usada.
+ `lookup-field`— O campo na tabela de pesquisa a ser comparado.
+ `log-field`— O campo em seu registro de eventos correspondente. A correspondência é exata e diferencia maiúsculas de minúsculas.
+ `output-mode`— Especifique `OUTPUT` para adicionar os campos de saída aos resultados. Se um campo com o mesmo nome já existir no evento de log, ele será substituído.
+ `output-field`— Um ou mais campos da tabela de pesquisa para adicionar aos resultados.
**Exemplo: enriqueça eventos de registro com detalhes do usuário**
Suponha que você tenha um grupo de registros com eventos que contêm um `id` campo e uma tabela de pesquisa chamada `user_data` com colunas `id` `name``email`,, `department` e. A consulta a seguir enriquece cada evento de log com o nome do usuário, e-mail e departamento da tabela de pesquisa.
```
fields action, status, name, email, department
| lookup user_data id OUTPUT name, email, department
```
**Exemplo: Use a pesquisa com agregação**
Você pode usar campos de saída de pesquisa com funções de agregação. A consulta a seguir enriquece os eventos de log com detalhes do usuário e, em seguida, conta os eventos agrupados por endereço de e-mail.
```
fields user_id, action, username, email, department
| lookup user_data user_id OUTPUT username, email, department
| stats count(*) by email
```
**Exemplo: Use a pesquisa com filtro**
Você pode filtrar os resultados com base nos campos retornados pela pesquisa. A consulta a seguir enriquece os eventos de registro e depois filtra para mostrar somente os eventos de um departamento específico.
```
fields user_id, action
| lookup user_data user_id OUTPUT username, email, department
| filter department = "Engineering"
```
# Funções booleanas, de comparação, numéricas e de data e hora, entre outras
CloudWatch O Logs Insights oferece suporte a muitas outras operações e funções em consultas, conforme explicado nas seções a seguir.
**Topics**
+ [Operadores aritméticos](#CWL_QuerySyntax-operations-arithmetic)
+ [Operadores booleanos](#CWL_QuerySyntax-operations-Boolean)
+ [Operadores de comparação](#CWL_QuerySyntax-operations-comparison)
+ [Operadores numéricos](#CWL_QuerySyntax-operations-numeric)
+ [Tipos de estrutura](#CWL_QuerySyntax-structure-types)
+ [Funções de data e hora](#CWL_QuerySyntax-datetime)
+ [Funções gerais](#CWL_QuerySyntax-general-functions)
+ [Funções JSON](#CWL_QuerySyntax-json-functions)
+ [Funções de string de endereço IP](#CWL_QuerySyntax-IPaddress-functions)
+ [Funções de string](#CWL_QuerySyntax-string-functions)
## Operadores aritméticos
Os operadores aritméticos aceitam tipos de dados numéricos como argumentos e retornam resultados numéricos. Use operadores aritméticos nos comandos `filter` e `fields` e como argumentos de outras funções.
| Operation | Description |
| --- | --- |
| `a + b` | Adição |
| `a - b` | Subtração |
| `a * b` | Multiplicação |
| `a / b` | Divisão |
| `a ^ b` | Exponenciação (`2 ^ 3` retorna `8`) |
| `a % b` | Resto ou módulo (`10 % 3` retorna `1`) |
## Operadores booleanos
Use os operadores booleanos `and`, `or` e `not`.
**nota**
Use operadores booleanos somente em funções que retornam um valor de **TRUE** ou **FALSE**.
## Operadores de comparação
Os operadores de comparação aceitam todos os tipos de dados como argumentos e retornam um resultado booliano. Use operadores de comparação no comando `filter` e como argumentos de outras funções.
| Operador | Description |
| --- | --- |
| `=` | Equal |
| `!=` | Not equal |
| `<` | Menor que |
| `>` | Maior que |
| `<=` | Menor ou igual a |
| `>=` | Maior ou igual a |
## Operadores numéricos
As operações numéricas aceitam tipos de dados numéricos como argumentos e retornam resultados numéricos. Use operadores numéricos nos comandos `filter` e `fields` e como argumentos de outras funções.
| Operation | Tipo de resultado | Description |
| --- | --- | --- |
| `abs(a: number)` | número | Valor absoluto |
| `ceil(a: number)` | número | Arredonde para o máximo (o menor inteiro maior que o valor de `a`) |
| `floor(a: number)` | número | Arredonde para o mínimo (o maior inteiro menor que o valor de `a`) |
| `greatest(a: number, ...numbers: number[])` | número | Retorna o maior valor |
| `least(a: number, ...numbers: number[])` | número | Retorna o menor valor |
| `log(a: number)` | número | Log natural |
| `sqrt(a: number)` | número | Raiz quadrada |
## Tipos de estrutura
Um mapa ou lista é um tipo de estrutura no CloudWatch Logs Insights que permite acessar e usar atributos para consultas.
**Exemplo: para obter um mapa ou uma lista**
Use `jsonParse` para analisar um campo que é uma string json em um mapa ou uma lista.
```
fields jsonParse(@message) as json_message
```
**Exemplo: para acessar atributos**
Use o operador de acesso por ponto (map.attribute) para acessar itens em um mapa. Se um atributo em um mapa contiver caracteres especiais, use crases para delimitar o nome do atributo (map.attributes). `special.char`).
```
fields jsonParse(@message) as json_message
| stats count() by json_message.status_code
```
Use o operador de acesso por colchetes (list[index]) para recuperar um item em uma posição específica na lista.
```
fields jsonParse(@message) as json_message
| filter json_message.users[1].action = "PutData"
```
Coloque caracteres especiais entre crases (``) quando caracteres especiais estiverem presentes no nome da chave.
```
fields jsonParse(@message) as json_message
| filter json_message.`user.id` = "123"
```
**Exemplo: resultados vazios**
Mapas e listas são tratados como nulos para funções de string, número e data e hora.
```
fields jsonParse(@message) as json_message
| display toupper(json_message)
```
A comparação do mapa e da lista com quaisquer outros campos resulta em `false`.
**nota**
O uso de mapa e lista em `dedup`, `pattern`, `sort` e `stats` não é suportado.
## Funções de data e hora
**Funções de data e hora**
Use funções de data e hora nos comandos `fields` e `filter` e como argumentos de outras funções. Use essas funções para criar buckets de tempo para consultas com funções de agregação. Use períodos que consistam em um número e uma das seguintes abreviaturas:
+ `ms` para milissegundos
+ `s` para segundos
+ `m` para minutos
+ `h` para horas
Por exemplo, `10m` é 10 minutos, e `1h` é uma hora.
**nota**
Use a unidade de tempo mais apropriada para a função de data e hora. CloudWatch Os registros limitam sua solicitação de acordo com a unidade de tempo que você escolher. Por exemplo, o limite máximo será 60 para qualquer solicitação que use `s`. Então, se você especificar`bin(300s)`, o CloudWatch Logs realmente implementa isso como 60 segundos, porque 60 é o número de segundos em um minuto, então o CloudWatch Logs não usará um número maior que 60 com`s`. Para criar um bucket de 5 minutos, use `bin(5m)` em vez disso.
O limite para `ms` é 1.000, o limite para `s` e `m` é 60 e o limite para `h` é 24.
A tabela a seguir contém uma lista das diferentes funções de data e hora que você pode usar nos comandos de consulta. A tabela lista o tipo de resultado de cada função e contém uma descrição de cada função.
**dica**
Quando você cria um comando de consulta, é possível usar o seletor de intervalo de tempo para selecionar um período que deseja consultar. Por exemplo, você pode definir um período entre intervalos de 5 e 30 minutos; intervalos de 1, 3 e 12 horas; ou um período personalizado. Você também pode definir períodos entre datas específicas.
| Função | Tipo de resultado | Description |
| --- | --- | --- |
| `bin(period: Period)` | Timestamp | Arredonda o valor de `@timestamp` para o período indicado e trunca. Por exemplo, `bin(5m)` arredonda o valor de `@timestamp` para os 5 minutos mais próximos. Você pode usar isso para agrupar várias entradas de log em uma consulta. O seguinte exemplo conta a quantidade de exceções por hora: filter @message like /Exception/
| stats count(*) as exceptionCount by bin(1h)
| sort exceptionCount desc
As unidades e abreviações de tempo a seguir são compatíveis com a função `bin`. Para todas as unidades e abreviações que incluem mais de um caractere, é permitido adicionar "s" para formar o plural. Assim, ambos `hr` e `hrs` funcionam para especificar horas. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonCloudWatch/latest/logs/CWL_QuerySyntax-operations-functions.html) |
| `datefloor(timestamp: Timestamp, period: Period)` | Timestamp | Trunca o time stamp para o período indicado. Por exemplo, `datefloor(@timestamp, 1h)` trunca todos os valores de `@timestamp` no final. |
| `dateceil(timestamp: Timestamp, period: Period)` | Timestamp | Arredonda o time stamp para o período indicado e trunca. Por exemplo, `dateceil(@timestamp, 1h)` trunca todos os valores de `@timestamp` no início. |
| `fromMillis(fieldName: number)` | Timestamp | Interpreta o campo de entrada como o número de milissegundos desde a epoch do Unix e o converte em um time stamp. |
| `toMillis(fieldName: Timestamp)` | número | Converte o time stamp encontrado no campo nomeado em um número que representa os milissegundos desde a epoch do Unix. Por exemplo, `toMillis(@timestamp)` converte o carimbo de data/hora `2022-01-14T13:18:031.000-08:00` para `1642195111000`. |
| `now()` | número | Retorna a hora em que o processamento da consulta foi iniciado, em segundos de época. Essa função não usa argumentos. Você pode usá-la para filtrar os resultados da consulta de acordo com a hora atual. Por exemplo, a consulta a seguir gera todos os erros 4xx das últimas duas horas: parse @message "Status Code: *;" as statusCode\n
| filter statusCode >= 400 and statusCode <= 499 \n
| filter toMillis(@timestamp) >= (now() * 1000 - 7200000)
O exemplo a seguir retorna todas as entradas de log das últimas cinco horas que contêm a palavra `error` ou `failure` fields @timestamp, @message
| filter @message like /(?i)(error|failure)/
| filter toMillis(@timestamp) >= (now() * 1000 - 18000000)
|
**nota**
Atualmente, o CloudWatch Logs Insights não oferece suporte à filtragem de registros com carimbos de data/hora legíveis por humanos.
## Funções gerais
**Funções gerais**
Use funções gerais nos comandos `fields` e `filter` e como argumentos de outras funções.
| Função | Tipo de resultado | Description |
| --- | --- | --- |
| `ispresent(fieldName: LogField)` | Booleano | Retorna `true` se o campo existir |
| `coalesce(fieldName: LogField, ...fieldNames: LogField[])` | LogField | Retorna o primeiro valor não nulo da lista |
## Funções JSON
**Funções JSON**
Use funções JSON nos comandos `fields` e `filter` como argumentos de outras funções.
| Função | Tipo de resultado | Description |
| --- | --- | --- |
| `jsonParse(fieldName: string)` | Mapa \$1 Lista \$1 Vazio | Retorna um mapa ou uma lista quando a entrada é uma representação de string do objeto JSON ou de uma matriz JSON. Retorna um valor vazio, se a entrada não for uma das representações. |
| `jsonStringify(fieldName: Map \| List)` | String | Retorna uma string JSON de um mapa ou dados da lista. |
## Funções de string de endereço IP
**Funções de string de endereço IP**
Use funções de string no endereço IP dos comandos `filter` e `fields` e como argumentos de outras funções.
| Função | Tipo de resultado | Description |
| --- | --- | --- |
| `isValidIp(fieldName: string)` | booliano | Retorna `true` se o campo for um IPv6 endereço válido IPv4 ou. |
| `isValidIpV4(fieldName: string)` | booleano | Retorna `true` se o campo for um IPv4 endereço válido. |
| `isValidIpV6(fieldName: string)` | booleano | Retorna `true` se o campo for um IPv6 endereço válido. |
| `isIpInSubnet(fieldName: string, subnet: string)` | booleano | Retorna `true` se o campo for um IPv6 endereço válido IPv4 ou dentro da sub-rede v4 ou v6 especificada. Ao especificar a sub-rede, use a notação CIDR, como `192.0.2.0/24` ou `2001:db8::/32`, onde `192.0.2.0` ou`2001:db8::` é o início do bloco CIDR. |
| `isIpv4InSubnet(fieldName: string, subnet: string)` | booleano | Retorna `true` se o campo for um IPv4 endereço válido dentro da sub-rede v4 especificada. Ao especificar a sub-rede, use a notação CIDR, como `192.0.2.0/24`, em que `192.0.2.0` é o início do bloco CIDR. |
| `isIpv6InSubnet(fieldName: string, subnet: string)` | booleano | Retorna `true` se o campo for um IPv6 endereço válido dentro da sub-rede v6 especificada. Ao especificar a sub-rede, use a notação CIDR, como `2001:db8::/32`, em que `2001:db8::` é o início do bloco CIDR. |
## Funções de string
**Funções de string**
Use funções de string nos comandos `fields` e `filter` e como argumentos de outras funções.
| Função | Tipo de resultado | Description |
| --- | --- | --- |
| `isempty(fieldName: string)` | Número | Retornará `1` se o campo não for encontrado ou for uma string vazia. |
| `isblank(fieldName: string)` | Número | Retornará `1` se o campo não for encontrado, for uma string vazia ou só contiver espaço branco. |
| `concat(str: string, ...strings: string[])` | string | Concatena as strings. |
| `ltrim(str: string)` `ltrim(str: string, trimChars: string)` | string | Se a função não tiver um segundo argumento, ela removerá os caracteres em branco da esquerda da string. Se a função tiver um segundo argumento de string, ela não removerá os caracteres em branco. Em vez disso, remove os caracteres em `trimChars` à esquerda de `str`. Por exemplo, `ltrim("xyZxyfooxyZ","xyZ")` exibe `"fooxyZ"`. |
| `rtrim(str: string)` `rtrim(str: string, trimChars: string)` | string | Se a função não tiver um segundo argumento, ela removerá os caracteres em branco da direita da string. Se a função tiver um segundo argumento de string, ela não removerá os caracteres em branco. Em vez disso, remove os caracteres de `trimChars` à direita de `str`. Por exemplo, `rtrim("xyZfooxyxyZ","xyZ")` exibe `"xyZfoo"`. |
| `trim(str: string)` `trim(str: string, trimChars: string)` | string | Se a função não tiver um segundo argumento, ela removerá os caracteres em branco nas duas extremidades da string. Se a função tiver um segundo argumento de string, ela não removerá os caracteres em branco. Em vez disso, remove os caracteres de `trimChars` de ambos os lados de `str`. Por exemplo, `trim("xyZxyfooxyxyZ","xyZ")` exibe `"foo"`. |
| `strlen(str: string)` | número | Retorna o tamanho da string em pontos de código Unicode. |
| `toupper(str: string)` | string | Converte a string em letras maiúsculas. |
| `tolower(str: string)` | string | Converte a string em letras minúsculas. |
| `substr(str: string, startIndex: number)` `substr(str: string, startIndex: number, length: number)` | string | Retorna uma substring do índice especificado pelo argumento de número ao final da string. Se tiver um segundo argumento de número, a função conterá o tamanho da substring a ser recuperada. Por exemplo, `substr("xyZfooxyZ",3, 3)` exibe `"foo"`. |
| `replace(fieldName: string, searchValue: string, replaceValue: string)` | string | Substitui todas as instâncias de `searchValue` em `fieldName: string` por `replaceValue`. Por exemplo, a função `replace(logGroup,"smoke_test","Smoke")` pesquisa eventos de log em que o campo `logGroup` contém o valor da string `smoke_test` e substitui o valor pela string `Smoke`. |
| `strcontains(str: string, searchValue: string)` | número | Retornará 1 se `str` contiver `searchValue` e 0, do contrário. |
# Campos contendo caracteres especiais
Se um campo contiver caracteres não alfanuméricos, exceto o símbolo `@` ou o ponto (`.`), você deverá delimitá-lo com caracteres de crase (```). Por exemplo, o campo de log `foo-bar` deve estar entre acentos graves (``foo-bar``) porque contém um caractere não alfanumérico, o hífen (`-`).
# Usar aliases e comentários em consultas
Crie consultas que contenham aliases. Use aliases para renomear campos de log ou ao extrair valores em campos. Use a palavra-chave `as` para dar um campo de log ou resultar em um alias. Você pode usar mais de um alias em uma consulta. Você pode usar aliases nos comandos a seguir:
+ `fields`
+ `parse`
+ `sort`
+ ` stats `
Os exemplos a seguir mostram como criar consultas que contenham aliases.
**Exemplo**
A consulta contém um alias no comando `fields`.
```
fields @timestamp, @message, accountId as ID
| sort @timestamp desc
| limit 20
```
A consulta retorna os valores dos campos `@timestamp`, `@message` e `accountId`. Os resultados são classificados em ordem decrescente e limitados a 20. Os valores para `accountId` estão listados sob o alias `ID`.
**Exemplo**
A consulta contém um alias nos comandos `sort` e `stats`.
```
stats count(*) by duration as time
| sort time desc
```
A consulta conta o número de vezes que o campo `duration` ocorre no grupo de logs e classifica os resultados em ordem decrescente. Os valores para `duration` estão listados sob o alias `time`.
## Usar comentários
CloudWatch O Logs Insights oferece suporte a comentários em consultas. Use o caractere jogo da velha (**\$1**) para separar comentários. Você pode usar comentários para ignorar linhas em consultas ou consultas de documentos.
**Exemplo: consulta**
Quando a consulta a seguir é executada, a segunda linha é ignorada.
```
fields @timestamp, @message, accountId
# | filter accountId not like "7983124201998"
| sort @timestamp desc
| limit 20
```
# Comece a usar o Logs Insights QL: tutoriais de consulta
As seções a seguir incluem exemplos de tutoriais de consulta para ajudar você a começar a usar o Logs Insights QL.
**Topics**
+ [Tutorial: executar e modificar um exemplo de consulta](CWL_AnalyzeLogData_RunSampleQuery.md)
+ [Tutorial: Executar uma consulta com uma função de agregação](CWL_AnalyzeLogData_AggregationQuery.md)
+ [Tutorial: Executar uma consulta que produz uma visualização agrupada por campos de log](CWL_AnalyzeLogData_VisualizationFieldQuery.md)
+ [Tutorial: Executar uma consulta que produz uma visualização de séries temporais](CWL_AnalyzeLogData_VisualizationQuery.md)
# Tutorial: executar e modificar um exemplo de consulta
O tutorial a seguir ajuda você a começar a usar o CloudWatch Logs Insights. Você executa uma consulta de amostra no Logs Insights QL e vê como modificá-la e voltar a executá-la.
Para executar uma consulta, você já deve ter registros armazenados em CloudWatch Registros. Se você já usa o CloudWatch Logs e tem grupos e fluxos de registros configurados, você está pronto para começar. Você também pode já ter registros se usar serviços como AWS CloudTrail Amazon Route 53 ou Amazon VPC e tiver configurado os registros desses serviços para CloudWatch acessar Logs. Para obter mais informações sobre o envio de registros para o CloudWatch Logs, consulte[Introdução ao CloudWatch Logs](CWL_GettingStarted.md).
As consultas no CloudWatch Logs Insights retornam um conjunto de campos de eventos de log ou o resultado de uma agregação matemática ou outra operação realizada em eventos de log. Este tutorial demonstra uma consulta que retorna uma lista de eventos de log.
## Executar um exemplo de consulta
**Para executar uma consulta de amostra do CloudWatch Logs Insights**
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).
Na página **Logs Insights** (Insights de log), o editor de consultas contém uma consulta padrão no Logs Insights QL que retorna os 20 eventos de logs mais recentes.
1. No menu suspenso **Select log group(s)** (Selecione grupo(s) de logs), escolha um ou mais grupos de logs a serem consultados.
Se for uma conta de monitoramento na observabilidade CloudWatch entre contas, você poderá selecionar grupos de registros nas contas de origem e na conta de monitoramento. Uma única consulta pode consultar logs de diferentes contas ao mesmo tempo.
Você pode filtrar os grupos de log por nome de grupo de log, ID de conta ou rótulo de conta.
Quando você seleciona um grupo de registros na classe de registros padrão, o CloudWatch Logs Insights detecta automaticamente os campos de dados no grupo. Para ver esses campos descobertos, selecione o menu **Fields** (Campos) próximo ao canto superior direito da página.
**nota**
A descoberta de campos só é compatível com os grupos de logs da classe de logs Padrão. Para obter mais informações sobre classes de logs, consulte [Classes de logs](CloudWatch_Logs_Log_Classes.md).
1. (Opcional) Use o seletor de tempo para selecionar o período que você deseja consultar.
Você pode escolher intervalos de 5 a 30 minutos, intervalos de 1, 3 e 12 horas ou um período personalizado.
1. Selecione **Run** (Executar) para visualizar os resultados.
Para este tutorial, os resultados incluem os 20 eventos de log adicionados mais recentemente.
CloudWatch Os registros exibem um gráfico de barras dos eventos de registro no grupo de registros ao longo do tempo. O gráfico de barras mostra não apenas os eventos na tabela. mas também a distribuição de eventos no grupo de logs correspondente à consulta e ao intervalo de tempo.
1. Para ver todos os campos de um evento de log retornado, escolha o ícone suspenso triangular à esquerda do evento numerado.
## Modificar o exemplo de consulta
Neste tutorial, você modifica a consulta de amostra para mostrar os 50 eventos de log mais recentes.
Se você ainda não tiver executado o tutorial anterior, faça isso agora. Este tutorial começa onde esse tutorial anterior termina.
**nota**
Alguns exemplos de consultas fornecidos com o CloudWatch Logs Insights usam `tail` comandos `head` ou em vez de`limit`. Esses comandos estão defasados e foram substituídos por `limit`. Use `limit` em vez de `head` ou `tail` em todas as consultas que você gravar.
**Para modificar a consulta de amostra do CloudWatch Logs Insights**
1. No editor de consultas, altere **20** para **50**, e escolha **Executar**.
Os resultados da nova consulta são exibidos. Pressupondo-se que haja dados suficientes no grupo de logs no intervalo de tempo padrão, agora há 50 eventos de log listados.
1. (Opcional) Você pode salvar consultas que você criou. Para salvar essa consulta, escolha **Salvar**. Para obter mais informações, consulte [Salve e execute novamente as consultas do CloudWatch Logs Insights](CWL_Insights-Saving-Queries.md).
## Adicionar um comando de filtro ao exemplo de consulta
Este tutorial mostra como fazer uma alteração mais eficiente na consulta no editor. Neste tutorial, filtre os resultados da consulta anterior com base em um campo nos eventos de log recuperados.
Se você ainda não tiver executado os tutoriais anteriores, faça isso agora. Este tutorial começa onde esse tutorial anterior termina.
**Para adicionar um comando de filtro à consulta anterior**
1. Decida um campo a ser filtrado. Para ver os campos mais comuns que o CloudWatch Logs detectou nos eventos de log contidos nos grupos de log selecionados nos últimos 15 minutos e a porcentagem desses eventos de log nos quais cada campo aparece, selecione **Campos** no lado direito da página.
Para ver os campos contidos em um determinado evento de log, escolha o ícone à esquerda dessa linha.
O campo **awsRegion** pode ser exibido no evento de log, dependendo de quais eventos estão nos logs. No restante deste tutorial, usamos **awsRegion** como o campo de filtro, mas você pode usar um campo diferente caso esse campo não esteja disponível.
1. Na caixa do editor de consultas, coloque o cursor após **50** e pressione Enter.
1. Na nova linha, digite primeiro \$1 (o caractere de barra vertical) e um espaço. Os comandos em uma consulta do CloudWatch Logs Insights devem ser separados pelo caractere de barra vertical.
1. Insira **filter awsRegion="us-east-1"**.
1. Escolha **Executar**.
A consulta é reexecutada e agora exibe os 50 resultados mais recentes correspondentes ao novo filtro.
Se tiver filtrado em um campo diferente e obtido um resultado de erro, você poderá precisar inserir caracteres de escape no nome do campo. Se o nome do campo incluir caracteres não alfanuméricos, você deverá inserir caracteres de apóstrofo (`) antes e depois do nome do campo (por exemplo, **`error-code`="102"**).
Você deve usar os caracteres de apóstrofo para nomes de campo que contenham caracteres não alfanuméricos, mas não para valores. Os valores estão sempre entre aspas (").
O Logs Insights QL contém recursos de consulta eficientes, inclusive vários comandos e suporte para expressões regulares, além de operações matemáticas e estatísticas. Para obter mais informações, consulte [CloudWatch Sintaxe de consulta de linguagem do Logs Insights](CWL_QuerySyntax.md).
# Tutorial: Executar uma consulta com uma função de agregação
Você pode usar funções de agregação no comando `stats` e como argumentos de outras funções. Neste tutorial, você executará um comando de consulta que conta o número de eventos de log contendo um campo especificado. O comando de consulta retorna uma contagem total agrupada pelo valor ou valores do campo especificado. Para obter mais informações sobre funções de agregação, consulte [Operações e funções suportadas](https://docs.aws.amazon.com/en_us/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html#CWL_QuerySyntax-operations-functions) no *Guia do usuário do Amazon CloudWatch Logs*.
**Executar uma consulta com uma função de agregação**
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. Confirme se a guia **Logs Insights QL** está selecionada.
1. No menu suspenso **Select log group(s)** (Selecione grupo(s) de logs), escolha um ou mais grupos de logs a serem consultados.
Se for uma conta de monitoramento na observabilidade CloudWatch entre contas, você poderá selecionar grupos de registros nas contas de origem e na conta de monitoramento. Uma única consulta pode consultar logs de diferentes contas ao mesmo tempo.
Você pode filtrar os grupos de log por nome de grupo de log, ID de conta ou rótulo de conta.
Quando você seleciona um grupo de CloudWatch registros, o Logs Insights detecta automaticamente os campos de dados no grupo de registros se for um grupo de registros de classe padrão. Para ver esses campos descobertos, selecione o menu **Fields** (Campos) próximo ao canto superior direito da página.
1. Exclua a consulta padrão no editor de consultas e insira o seguinte comando:
```
stats count(*) by fieldName
```
1. *fieldName*Substitua por um campo descoberto no menu **Campos**.
O menu **Campos** está localizado no canto superior direito da página e exibe todos os campos descobertos que o CloudWatch Logs Insights detecta em seu grupo de registros.
1. Selecione **Run** (Executar) para visualizar os resultados da consulta.
Os resultados da consulta mostram o número de registros no grupo de logs que correspondem ao comando de consulta e a contagem total agrupada pelo valor ou valores do campo especificado.
# Tutorial: Executar uma consulta que produz uma visualização agrupada por campos de log
Ao executar uma consulta que usa a função `stats` para agrupar os resultados retornados pelos valores de um ou mais campos nas entradas de log, é possível visualizar os resultados como gráfico de barras, gráfico de pizza, grafo de linhas ou grafo de área empilhada. Isso ajuda a visualizar as tendências em seus logs de forma mais eficiente.
**Para executar uma consulta de visualização**
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 menu suspenso **Select log group(s)** (Selecione grupo(s) de logs), escolha um ou mais grupos de logs a serem consultados.
Se for uma conta de monitoramento na observabilidade CloudWatch entre contas, você poderá selecionar grupos de registros nas contas de origem e na conta de monitoramento. Uma única consulta pode consultar logs de diferentes contas ao mesmo tempo.
Você pode filtrar os grupos de log por nome de grupo de log, ID de conta ou rótulo de conta.
1. No editor de consultas, exclua o conteúdo atual, insira a função `stats` a seguir e escolha **Run query**(Executar consulta).
```
stats count(*) by @logStream
| limit 100
```
Os resultados mostram o número de eventos de log no grupo de logs para cada fluxo de log. Os resultados são limitados a somente 100 linhas.
1. Escolha a guia **Visualization** (Visualização).
1. Selecione a seta ao lado de **Linha**, e escolha **Barra**.
O gráfico de barras será exibido, mostrando uma barra para cada fluxo de log no grupo de logs.
# Tutorial: Executar uma consulta que produz uma visualização de séries temporais
Ao executar uma consulta que usa a função `bin()` para agrupar os resultados retornados por um período, é possível visualizar os resultados como um grafo de linhas, um grafo de áreas empilhadas, um gráfico de pizza ou gráfico de barras. Isso ajuda a visualizar as tendências em eventos de log ao longo do tempo de modo mais eficiente.
**Para executar uma consulta de visualização**
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. Confirme se a guia **Logs Insights QL** está selecionada.
1. No menu suspenso **Select log group(s)** (Selecione grupo(s) de logs), escolha um ou mais grupos de logs a serem consultados.
Se for uma conta de monitoramento na observabilidade CloudWatch entre contas, você poderá selecionar grupos de registros nas contas de origem e na conta de monitoramento. Uma única consulta pode consultar logs de diferentes contas ao mesmo tempo.
Você pode filtrar os grupos de log por nome de grupo de log, ID de conta ou rótulo de conta.
1. No editor de consultas, exclua o conteúdo atual, insira a função `stats` a seguir e escolha **Run query**(Executar consulta).
```
stats count(*) by bin(30s)
```
Os resultados mostram o número de eventos de registro no grupo de registros que foram recebidos pelo CloudWatch Logs em cada período de 30 segundos.
1. Escolha a guia **Visualization** (Visualização).
Os resultados são mostrados como um gráfico de linhas. Para alternar para um gráfico de barras, de pizza ou de áreas empilhadas, escolha a seta ao lado de **Line** (Linha) no canto superior direito do grafo.
# Exemplos de consultas
Esta seção contém uma lista de comandos de consulta gerais e úteis que você pode executar no [CloudWatchconsole](https://console.aws.amazon.com/cloudwatch/). Para obter informações sobre como executar um comando de consulta, consulte [Tutorial: Executar e modificar uma consulta de amostra](https://docs.aws.amazon.com/en_us/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_RunSampleQuery.html) no *Guia do usuário do Amazon CloudWatch Logs*.
Para obter mais informações sobre a sintaxe das consultas, consulte [CloudWatch Sintaxe de consulta de linguagem do Logs Insights](CWL_QuerySyntax.md).
**Topics**
+ [Consultas gerais](#CWL_QuerySyntax-examples-general)
+ [Consultas de logs do Lambda](#CWL_QuerySyntax-examples-Lambda)
+ [Consultas para logs de fluxo da Amazon VPC](#CWL_QuerySyntax-examples-VPC)
+ [Consultas de logs do Route 53](#CWL_QuerySyntax-examples-Route53)
+ [Consultas para registros CloudTrail](#CWL_QuerySyntax-examples-CloudTrail)
+ [Consultas para Amazon API Gateway](#CWL_QuerySyntax-examples-APIGateway)
+ [Consultas para gateway NAT](#CWL_QuerySyntax-examples-NATGateway)
+ [Consultas para logs do servidor Apache](#CWL_QuerySyntax-examples-Apache)
+ [Consultas para a Amazon EventBridge](#CWL_QuerySyntax-examples-EventBridge)
+ [Exemplos do comando de análise](#CWL_QuerySyntax-examples-parse)
## Consultas gerais
**Encontre os 25 eventos de log adicionados mais recentemente.**
```
fields @timestamp, @message | sort @timestamp desc | limit 25
```
**Obtenha uma lista do número de exceções por hora.**
```
filter @message like /Exception/
| stats count(*) as exceptionCount by bin(1h)
| sort exceptionCount desc
```
**Obtenha uma lista de eventos de log que não sejam exceções.**
```
fields @message | filter @message not like /Exception/
```
**Obtenha o evento de log mais recente para cada valor exclusivo do campo `server`.**
```
fields @timestamp, server, severity, message
| sort @timestamp asc
| dedup server
```
**Obtenha o evento de log mais recente para cada valor exclusivo do campo `server` para cada tipo `severity`.**
```
fields @timestamp, server, severity, message
| sort @timestamp desc
| dedup server, severity
```
## Consultas de logs do Lambda
**Determine a quantidade de memória provisionada excessivamente.**
```
filter @type = "REPORT"
| stats max(@memorySize / 1000 / 1000) as provisonedMemoryMB,
min(@maxMemoryUsed / 1000 / 1000) as smallestMemoryRequestMB,
avg(@maxMemoryUsed / 1000 / 1000) as avgMemoryUsedMB,
max(@maxMemoryUsed / 1000 / 1000) as maxMemoryUsedMB,
provisonedMemoryMB - maxMemoryUsedMB as overProvisionedMB
```
**Crie um relatório de latência.**
```
filter @type = "REPORT" |
stats avg(@duration), max(@duration), min(@duration) by bin(5m)
```
**Procure invocações de funções lentas e elimine solicitações duplicadas que podem surgir de novas tentativas ou código no lado do cliente. Nessa consulta, `@duration` está em milissegundos.**
```
fields @timestamp, @requestId, @message, @logStream
| filter @type = "REPORT" and @duration > 1000
| sort @timestamp desc
| dedup @requestId
| limit 20
```
## Consultas para logs de fluxo da Amazon VPC
**Encontre as 15 principais transferências de pacotes nos hosts:**
```
stats sum(packets) as packetsTransferred by srcAddr, dstAddr
| sort packetsTransferred desc
| limit 15
```
**Encontre as 15 principais transferências de bytes para hosts em uma determinada sub-rede.**
```
filter isIpv4InSubnet(srcAddr, "192.0.2.0/24")
| stats sum(bytes) as bytesTransferred by dstAddr
| sort bytesTransferred desc
| limit 15
```
**Encontre os endereços IP que usam o UDP como um protocolo de transferência de dados.**
```
filter protocol=17 | stats count(*) by srcAddr
```
**Encontre os endereços IP nos quais os registros do fluxo foram ignorados durante a janela de captura.**
```
filter logStatus="SKIPDATA"
| stats count(*) by bin(1h) as t
| sort t
```
**Encontre um único registro para cada conexão para ajudar a solucionar problemas de conectividade com a rede.**
```
fields @timestamp, srcAddr, dstAddr, srcPort, dstPort, protocol, bytes
| filter logStream = 'vpc-flow-logs' and interfaceId = 'eni-0123456789abcdef0'
| sort @timestamp desc
| dedup srcAddr, dstAddr, srcPort, dstPort, protocol
| limit 20
```
## Consultas de logs do Route 53
**Encontre a distribuição de registros por hora por tipo de consulta.**
```
stats count(*) by queryType, bin(1h)
```
**Encontre os 10 resolvedores DNS com o maior número de solicitações.**
```
stats count(*) as numRequests by resolverIp
| sort numRequests desc
| limit 10
```
**Encontre o número de registros por domínio e subdomínio em que o servidor deixou de concluir a solicitação DNS.**
```
filter responseCode="SERVFAIL" | stats count(*) by queryName
```
## Consultas para registros CloudTrail
**Encontre o número de entradas de registro para cada serviço, tipo de evento e AWS região.**
```
stats count(*) by eventSource, eventName, awsRegion
```
**Encontre os hosts do Amazon EC2 que foram iniciados ou parados em uma determinada AWS região.**
```
filter (eventName="StartInstances" or eventName="StopInstances") and awsRegion="us-east-2"
```
**Encontre as AWS regiões, os nomes ARNs de usuário e os usuários recém-criados do IAM.**
```
filter eventName="CreateUser"
| fields awsRegion, requestParameters.userName, responseElements.user.arn
```
**Encontre o número de registros em que ocorreu uma exceção durante a invocação da API `UpdateTrail`.**
```
filter eventName="UpdateTrail" and ispresent(errorCode)
| stats count(*) by errorCode, errorMessage
```
**Encontre entradas de log em que TLS 1.0 ou 1.1 foi usado**
```
filter tlsDetails.tlsVersion in [ "TLSv1", "TLSv1.1" ]
| stats count(*) as numOutdatedTlsCalls by userIdentity.accountId, recipientAccountId, eventSource, eventName, awsRegion, tlsDetails.tlsVersion, tlsDetails.cipherSuite, userAgent
| sort eventSource, eventName, awsRegion, tlsDetails.tlsVersion
```
**Encontre o número de chamadas por serviço que usaram o TLS versões 1.0 ou 1.1**
```
filter tlsDetails.tlsVersion in [ "TLSv1", "TLSv1.1" ]
| stats count(*) as numOutdatedTlsCalls by eventSource
| sort numOutdatedTlsCalls desc
```
## Consultas para Amazon API Gateway
Encontre os 10 últimos erros 4XX
```
fields @timestamp, status, ip, path, httpMethod
| filter status>=400 and status<=499
| sort @timestamp desc
| limit 10
```
Identifique as 10 Amazon API Gateway solicitações mais antigas em seu grupo de registros de Amazon API Gateway acesso
```
fields @timestamp, status, ip, path, httpMethod, responseLatency
| sort responseLatency desc
| limit 10
```
Retorne a lista dos caminhos de API mais populares no seu grupo de logs de acesso do Amazon API Gateway
```
stats count(*) as requestCount by path
| sort requestCount desc
| limit 10
```
Crie um relatório de latência de integração para seu grupo de logs de acesso do Amazon API Gateway
```
filter status=200
| stats avg(integrationLatency), max(integrationLatency),
min(integrationLatency) by bin(1m)
```
## Consultas para gateway NAT
Se você notar custos mais altos do que o normal em sua AWS fatura, você pode usar o CloudWatch Logs Insights para encontrar os principais contribuidores. Para obter mais informações sobre os seguintes comandos de consulta, consulte [Como posso encontrar os principais contribuidores para o tráfego por meio do gateway NAT na minha VPC](https://aws.amazon.com/premiumsupport/knowledge-center/vpc-find-traffic-sources-nat-gateway/)? na página de suporte AWS premium.
**nota**
Nos comandos de consulta a seguir, substitua “x.x.x.x” pelo IP privado do gateway NAT e substitua “y.y” pelos dois primeiros octetos do intervalo CIDR da VPC.
**Encontre as instâncias que estão enviando mais tráfego por meio de seu gateway NAT.**
```
filter (dstAddr like 'x.x.x.x' and srcAddr like 'y.y.')
| stats sum(bytes) as bytesTransferred by srcAddr, dstAddr
| sort bytesTransferred desc
| limit 10
```
**Determine o tráfego de/para as instâncias em seus gateways NAT.**
```
filter (dstAddr like 'x.x.x.x' and srcAddr like 'y.y.') or (srcAddr like 'xxx.xx.xx.xx' and dstAddr like 'y.y.')
| stats sum(bytes) as bytesTransferred by srcAddr, dstAddr
| sort bytesTransferred desc
| limit 10
```
**Determine os destinos da Internet com os quais as instâncias em sua VPC se comunicam com mais frequência para uploads e downloads.**
*****Para uploads*****
```
filter (srcAddr like 'x.x.x.x' and dstAddr not like 'y.y.')
| stats sum(bytes) as bytesTransferred by srcAddr, dstAddr
| sort bytesTransferred desc
| limit 10
```
*****Para downloads*****
```
filter (dstAddr like 'x.x.x.x' and srcAddr not like 'y.y.')
| stats sum(bytes) as bytesTransferred by srcAddr, dstAddr
| sort bytesTransferred desc
| limit 10
```
## Consultas para logs do servidor Apache
Você pode usar o CloudWatch Logs Insights para consultar os registros do servidor Apache. Para obter mais informações sobre as consultas a seguir, consulte [Simplificando os registros do servidor Apache com CloudWatch o Logs Insights no blog](https://aws.amazon.com/blogs/mt/simplifying-apache-server-logs-with-amazon-cloudwatch-logs-insights/) AWS Cloud Operations & Migrations.
**Encontre os campos mais relevantes para que você possa revisar seus logs de acesso e verificar se há tráfego no caminho */admin* da aplicação.**
```
fields @timestamp, remoteIP, request, status, filename| sort @timestamp desc
| filter filename="/var/www/html/admin"
| limit 20
```
**Encontre o número de solicitações GET exclusivas que acessaram sua página principal com o código de status “200” (sucesso).**
```
fields @timestamp, remoteIP, method, status
| filter status="200" and referrer= http://34.250.27.141/ and method= "GET"
| stats count_distinct(remoteIP) as UniqueVisits
| limit 10
```
**Encontre o número de vezes que o serviço Apache foi reiniciado.**
```
fields @timestamp, function, process, message
| filter message like "resuming normal operations"
| sort @timestamp desc
| limit 20
```
## Consultas para a Amazon EventBridge
Obtenha o número de EventBridge eventos agrupados por tipo de detalhe do evento
```
fields @timestamp, @message
| stats count(*) as numberOfEvents by `detail-type`
| sort numberOfEvents desc
```
## Exemplos do comando de análise
**Use uma expressão de glob para extrair os campos `@user`, `@method` e `@latency` do campo de log `@message` e retornar a latência média para cada combinação exclusiva de `@method` e `@user`.**
```
parse @message "user=*, method:*, latency := *" as @user,
@method, @latency | stats avg(@latency) by @method,
@user
```
**Use uma expressão regular para extrair os campos `@user2`, `@method2` e `@latency2` do campo de log `@message` e retornar a latência média para cada combinação exclusiva de `@method2` e `@user2`.**
```
parse @message /user=(?.*?), method:(?.*?),
latency := (?.*?)/ | stats avg(latency2) by @method2,
@user2
```
**Extrai os campos `loggingTime`, `loggingType` e `loggingMessage`, aplica o filtro para eventos de logs que contêm strings `ERROR` ou `INFO` e exibe apenas os campos `loggingMessage` e `loggingType` para eventos que contêm uma string `ERROR`.**
```
FIELDS @message
| PARSE @message "* [*] *" as loggingTime, loggingType, loggingMessage
| FILTER loggingType IN ["ERROR", "INFO"]
| DISPLAY loggingMessage, loggingType = "ERROR" as isError
```
# Compare (diff) com intervalos de tempo anteriores
Você pode usar o CloudWatch Logs Insights com o QL do Logs Insights para comparar as alterações em seus eventos de registro ao longo do tempo. Você pode comparar os eventos de log ingeridos durante um intervalo de tempo recente com os logs do período imediatamente anterior. Ou então, pode comparar com períodos passados similares. Isso pode ajudar a descobrir se um erro nos logs foi introduzido recentemente ou se já estava ocorrendo, além de ajudar a encontrar outras tendências.
As consultas de comparação retornam apenas padrões nos resultados, não eventos de log brutos. Os padrões retornados ajudarão você a ver rapidamente tendências e mudanças nos eventos de log ao longo do tempo. Depois que você executa uma consulta de comparação e obtém resultados de padrões, pode ver exemplos de eventos de log brutos para os padrões em que estiver interessado. Para obter mais informações sobre padrões de log, consulte [Análise de padrões](CWL_AnalyzeLogData_Patterns.md).
Quando você executa uma consulta de comparação, ela é analisada em relação a dois períodos diferentes: o período original de consulta que você seleciona e o período de comparação. O período de comparação é sempre igual ao período de consulta original. Os intervalos de tempo padrão para as comparações são que se seguem.
+ **Período anterior**: compara com o período imediatamente anterior ao período da sua consulta.
+ **Dia anterior**: compara com o período um dia antes do período da sua consulta.
+ **Semana anterior**: compara com o período uma semana antes do período da sua consulta.
+ **Mês anterior**: compara com o período um mês antes do período da sua consulta.
**nota**
As consultas que usam comparações geram cobranças semelhantes às da execução de uma única consulta do CloudWatch Logs Insights no intervalo de tempo combinado. Para obter mais informações, consulte [Definição de preço do Amazon CloudWatch](https://aws.amazon.com/cloudwatch/pricing/).
**Para executar uma consulta de comparação**
1. Abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. No painel de navegação, escolha **Logs**, **Logs Insights**.
Uma consulta padrão aparece na caixa de consulta.
1. Confirme se a guia **Logs Insights QL** está selecionada.
1. Mantenha a consulta padrão ou insira outra consulta.
1. No menu suspenso **Selecionar grupos de logs**, escolha um ou mais grupos de logs para consultar.
1. (Opcional) Use o seletor de tempo para selecionar o período que você deseja consultar. A consulta padrão é para a hora anterior de dados de log.
1. No seletor de intervalos de tempo, escolha **Comparar**. Depois, escolha o período anterior com o qual você deseja comparar os logs originais e escolha **Aplicar**.
1. Selecione **Executar consulta**.
Para que a consulta busque os dados no período de comparação, o comando `diff` é adicionado ao fim da consulta ela.
1. Escolha a guia **Padrões** para ver os resultados.
A tabela exibe as seguintes informações:
+ Cada **padrão**, com as partes variáveis do padrão substituídas pelo símbolo de token dinâmico ``. *string*É uma descrição do tipo de dados que o token representa. *number*Mostra onde esse token aparece no padrão, em comparação com os outros tokens dinâmicos. Para obter mais informações, consulte [Análise de padrões](CWL_AnalyzeLogData_Patterns.md).
+ **Número de eventos** é o número de eventos de log com esse padrão no período original mais atual.
+ **Diferença de número de eventos** é a diferença entre o número de eventos de log correspondentes no período atual em relação ao período de comparação. Uma diferença positiva significa que há mais eventos desse tipo no período atual.
+ **Descrição da diferença** resume brevemente a alteração no padrão entre o período atual e o período de comparação.
+ **Tipo de gravidade** é a provável gravidade dos eventos de log com esse padrão, baseado nas palavras encontradas nos eventos de log, como `FATAL`, `ERROR`, e `WARN`.
1. Para inspecionar melhor um dos padrões na lista, escolha o ícone na coluna **Inspecionar** para um dos padrões.
O painel **Inspeção de padrões** aparece e exibe o seguinte:
+ O **padrão**. Selecione um token no padrão para analisar os valores desse token.
+ Um histograma mostrando o número de ocorrências do padrão no intervalo consultado. Isso pode ajudar a identificar tendências interessantes, como um aumento repentino na ocorrência de um padrão.
+ A guia **Exemplos de log** exibe alguns eventos de log que correspondem ao padrão selecionado.
+ A guia **Valores do token** exibe os valores do token dinâmico selecionado, se você tiver selecionado um.
**nota**
No máximo de 10 valores de token são capturados para cada token. A contagem de tokens pode não ser precisa. CloudWatch O Logs usa um contador probabilístico para gerar a contagem de tokens, não o valor absoluto.
+ A guia **Padrões relacionados** exibe outros padrões que ocorreram com frequência quase ao mesmo tempo que o padrão que você está inspecionando. Por exemplo, se um padrão para uma mensagem `ERROR` geralmente foi acompanhado por outro evento de log marcado como `INFO` com detalhes adicionais, esse padrão será exibido aqui.
# Visualize dados de log em grafos
Você pode usar visualizações como gráficos de barras, gráficos de linhas e gráficos de áreas empilhadas para identificar com mais eficiência padrões em seus dados de registro. CloudWatch O Logs Insights gera visualizações para consultas que usam a `stats` função e uma ou mais funções de agregação. Para obter mais informações, consulte [stats](CWL_QuerySyntax-Stats.md).
# OpenSearch Linguagem de processamento canalizado (PPL)
Esta seção contém uma introdução básica à consulta de CloudWatch registros usando OpenSearch PPL. Com a PPL, você pode recuperar, consultar e analisar dados usando comandos agrupados, facilitando a compreensão e a composição de consultas complexas. Sua sintaxe é baseada em pipes Unix e permite o encadeamento de comandos para transformar e processar dados. Com a PPL, você pode filtrar e agregar dados e usar um amplo conjunto de funções matemáticas, de sequências de caracteres, de data, condicionais e outras para análise.
Incluir `SOURCE` em uma consulta PPL é uma forma útil de especificar os grupos de registros, os índices de campo e as fontes de dados a serem incluídos em uma consulta quando você estiver usando a API AWS CLI ou para criar uma consulta. O `SOURCE` comando é suportado somente na API AWS CLI and, não no CloudWatch console. Ao usar o CloudWatch console para iniciar uma consulta, você usa a interface do console para especificar os grupos de log e o nome e o tipo da fonte de dados.
Use `aws:fieldIndex` para retornar somente dados indexados, forçando uma consulta a verificar somente grupos de logs indexados em um campo especificado na consulta. Os grupos de registros relevantes são selecionados automaticamente, com base nos campos especificados no `filterIndex` comando. Isso reduz o volume escaneado ignorando grupos de registros que não têm nenhum evento de registro contendo o campo especificado na consulta e somente grupos de registros de varredura que correspondam ao valor especificado na consulta para esse índice de campo. Use `aws:fieldIndex` para especificar o nome do campo, junto com o nome e o valor do campo no comando de origem para consultar somente dados indexados contendo o campo e o valor especificados. Para obter mais informações, consulte [Crie índices de campo para melhorar o desempenho da consulta e reduzir o volume de escaneamento](CloudWatchLogs-Field-Indexing.md).
Você pode usar o OpenSearch PPL para consultas de grupos de registros na Classe de Registro Padrão.
**nota**
Para obter informações sobre todos os comandos de consulta OpenSearch PPL compatíveis com CloudWatch os registros e informações detalhadas sobre sintaxe e restrições, consulte [Comandos PPL compatíveis](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/supported-ppl.html) no OpenSearch Service Developer Guide.
Para obter informações sobre outras linguagens de consulta que você pode usar, consulte [CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html), [OpenSearch Service SQL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_SQL.html) e [CloudWatch Metrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html)
| Comando ou função | Consulta de exemplo | Description |
| --- | --- | --- |
| fields | `fields field1, field2` | Exibe um conjunto de campos que precisam de projeção. |
| ingressar | `LEFT JOIN left=l, right=r on l.id = r.id `join_right_lg` \| fields l.field_1, r.field_2` | Une dois conjuntos de dados. |
| para onde | `where field1="success" \| where field2 != "i-023fe0a90929d8822" \| fields field3, field4, field5,field6 \| head 1000` | Filtra os dados com base nas condições que você especifica. |
| AWS: Índice de campo | `source = [`aws:fieldIndex`="region", `region` = "us-west-2"] \| where status = 200 \| head 10` | Retorna somente dados indexados, forçando uma consulta a examinar somente grupos de registros que estão indexados em um campo que você especifica na consulta. |
| stats | `stats count(), count(field1), min(field1), max(field1), avg(field1) by field2 \| head 1000` | Executa agregações e cálculos |
| parse | `parse field1 ".*/(?[^/]+$)" \| where field2 = "requestId" \| fields field1, field2 \| head 1000` | Extrai um padrão de expressão regular (regex) de uma string e exibe o padrão extraído. O padrão extraído pode ser usado posteriormente para criar novos campos ou filtrar dados. |
| sort | `stats count(), count(field1), min(field1) as field1Alias, max(`field1`), avg(`field1`) by field2 \| sort -field1Alias \| head 1000` | Classifique os resultados exibidos por um nome de campo. Use classificar - FieldName para classificar em ordem decrescente. |
| eval | `eval field2 = field1 * 2 \| fields field1, field2 \| head 20` | Modifica ou processa o valor de um campo e o armazena em um campo diferente. Esse comando é útil para modificar matematicamente uma coluna, aplicar funções de string a uma coluna ou aplicar funções de data a uma coluna. |
| rename | `rename field2 as field1 \| fields field1;` | Renomeia um ou mais campos no resultado da pesquisa. |
| head | `fields `@message` \| head 20` | Limita os resultados da consulta exibidos às primeiras N linhas. |
| top | `top 2 field1 by field2` | Encontra os valores mais frequentes para um campo. |
| dedup | `dedup field1 \| fields field1, field2, field3` | Remove entradas duplicadas com base nos campos que você especifica. |
| rare | `rare field1 by field2` | Localiza os valores menos frequentes de todos os campos na lista de campos. |
| subconsulta | `where field_1 IN [ search source= `subquery_lg` \| fields field_2 ] \| fields id, field_1 ` | Executa consultas complexas e aninhadas em suas instruções de PPL. |
| trendline | `trendline sma(2, field1) as field1Alias` | Calcula as médias móveis dos campos. |
| eventStats | `eventstats sum(field1) by field2` | Enriquece os dados do seu evento com estatísticas resumidas calculadas. Esse comando analisa campos especificados em seus eventos, calcula várias medidas estatísticas e, em seguida, anexa esses resultados a cada evento original como novos campos. |
| expandir | `eval tags_array_string = json_extract(`@message`, '$.tags')\| eval tags_array = json_array(json_extract(tags_string, '$[0]'), json_extract(tags_string, '$[1]'))\| expand tags_array as color_tags` | Divide um campo contendo vários valores em linhas separadas, criando uma nova linha para cada valor no campo especificado. |
| fillnull | `fields `@timestamp`, error_code, status_code \| fillnull using status_code = "UNKNOWN", error_code = "UNKNOWN"` | Preenche campos nulos com o valor que você fornece. Pode ser usado em um ou mais campos. |
| nivelamento | `eval metadata_struct = json_object('size', json_extract(metadata_string, '$.size'), 'color', json_extract(metadata_string, '$.color')) \| flatten metadata_struct as (meta_size, meta_color) ` | Nivela um campo. O campo deve ser do tipo: `struct` ou `array>`. |
| cidrmatch | `where cidrmatch(ip, '2003:db8::/32') \| fields ip ` | Verifica se o endereço IP especificado está dentro do intervalo CIDR especificado. |
| fieldsummary | `where field1 != 200 \| fieldsummary includefields= field1 nulls=true` | Calcula estatísticas básicas para cada campo (contagem, contagem distinta, mín, máx, méd., stddev e mediana). |
| grok | `grok email '.+@%{HOSTNAME:host}' \| fields email, host` | Analisa um campo de texto com um padrão Grok e anexa os resultados ao resultado da pesquisa. |
| Funções de string | `eval field1Len = LENGTH(field1) \| fields field1Len` | Funções integradas na PPL que podem manipular e transformar dados de string e texto em consultas PPL. Por exemplo, converter maiúsculas e minúsculas, combinar strings, extrair partes e apagar texto. |
| Funções de data e hora | `eval newDate = ADDDATE(DATE('2020-08-26'), 1) \| fields newDate ` | Funções integradas para manipular e transformar dados de data e carimbo de data/hora em consultas PPL. Por exemplo: date\$1add, date\$1format, datediff, date-sub, timestampadd, timestampdiff, current\$1timezone, utc\$1timestamp, e current\$1date. |
| Funções de condição | `eval field2 = isnull(field1) \| fields field2, field1, field3` | Funções integradas que verificam condições de campo específicas e avaliam expressões condicionalmente. Por exemplo, se campo1 for nulo, retorne campo2. |
| Funções matemáticas | `eval field2 = ACOS(field1) \| fields field1` | Funções integradas para realizar cálculos matemáticos e transformações em consultas PPL. Por exemplo: abs (valor absoluto), round (arredonda números), sqrt (raiz quadrada), pow (cálculo de potência) e ceil (arredonda até o número inteiro mais próximo). |
| CryptoGraphic funções | `eval crypto = MD5(field)\| head 1000` | Para calcular o hash de um determinado campo |
| Funções JSON | `eval valid_json = json('[1,2,3,{"f1":1,"f2":[5,6]},4]') \| fields valid_json` | Funções integradas para manipular JSON, incluindo matrizes, extração e validação. Por exemplo: json\$1object, json\$1array, to\$1json\$1string, json\$1array\$1length, json\$1extract, json\$1keys e json\$1valid. |
## Escopo da consulta
Incluir SOURCE em uma consulta é uma forma útil de especificar os grupos de registros a serem incluídos em uma consulta quando você estiver usando a API AWS CLI ou para criar uma consulta. O comando SOURCE é suportado somente na API AWS CLI e, não no CloudWatch console. Ao usar o CloudWatch console para iniciar uma consulta, você usa a interface do console para especificar os grupos de log e o nome e o tipo da fonte de dados.
O comando source do PPL agora oferece suporte a várias maneiras de especificá-los:
1. Grupo de registros
1. Índices de campo - Novo
1. Fonte e tipo de dados - Novo
### Grupo de logs
A seleção da fonte do grupo de registros pode ser usada quando os clientes sabem quais grupos de registros exatos precisam ser pesquisados
```
source = [lg:`/aws/lambda/my-function`] | where status = 200 | head 10
```
### Índices de campo
A seleção da fonte com base no índice de campo reduz a quantidade de dados consultados ao limitar os resultados somente aos dados indexados quando seus filtros segmentam campos que foram indexados. Os grupos de registros relevantes são selecionados automaticamente, com base nos campos especificados no `filterIndex` comando. Para obter mais informações sobre índices de campo e como criá-los, consulte [Criar índices de campo para melhorar o desempenho da consulta e reduzir o volume de varredura](CloudWatchLogs-Field-Indexing.md).
Use `aws:fieldIndex` para retornar somente dados indexados, forçando uma consulta a verificar somente grupos de logs indexados em um campo especificado na consulta. Para esses grupos de logs indexados nesse campo, ele otimiza ainda mais a consulta ignorando os grupos que não têm nenhum evento de logs contendo o campo especificado na consulta do campo indexado. Isso reduz ainda mais o volume escaneado ao tentar verificar somente eventos de logs desses grupos que correspondam ao valor especificado na consulta para esse índice de campo. Para obter mais informações sobre índices de campo e como criá-los, consulte Criar índices de campo para melhorar o desempenho da consulta e reduzir o volume de varredura.
Em PPL, `aws:fieldIndex` é usado para especificar quais pares de valores-chave devem ser tratados como índices. A sintaxe é a seguinte
```
source = [`aws:fieldIndex`="region", `region` = "us-west-2"] | where status = 200 | head 10
```
em que,
1. ``aws:fieldIndex`="region"`identifica a região como índice de campo.
1. Observação: em vez de =, os clientes podem usar IN para especificar vários índices (exemplo abaixo)
1. ``region`="us-west-2"`identifica a condição do filtro a ser aplicada
1. Observação: em vez de =, os clientes podem usar IN para especificar vários valores (exemplo abaixo)
Os clientes podem especificar vários índices de campo da seguinte forma
```
source = [`aws:fieldIndex` IN ("status", "region"), `status` = 200, `region` IN ("us-west-2", "us-east-1")] | head 10
```
### Fonte e tipo de dados
A seleção da fonte de dados e da fonte baseada no tipo pode ser usada quando os clientes sabem quais fontes de dados exatas precisam ser consultadas. Essa consulta é executada em um ou mais grupos de registros que contêm a fonte e o tipo de dados especificados.
```
source = [ds:`data_source.type`] | where status = 200 | head 10
```
#### PPL compatível para consultas de fontes de dados
Para oferecer suporte ao caso de uso da consulta de fontes de dados no PPL, você pode usar a cláusula seletora dinâmica de origem. Usando essa sintaxe, você pode consultar fontes de dados especificando-as no comando search. Você pode especificar até 10 fontes de dados.
**Sintaxe**
```
source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`, ...ds:`DataSourcen.Typen`]
```
**Consulta de exemplo**
```
search source=[ds:`DataSource1.Type1`, ds:`DataSource2.Type2`] | fields field1, field2
```
### Exemplo de combinação
Os clientes podem especificar todos os operadores de seleção de origem em qualquer ordem e os resultados seriam a interseção de todas as condições aplicadas.
Por exemplo,/aws/lambda/my-function-1 pode conter várias fontes e tipos de dados, incluindo uma grande variedade de índices. Quando a consulta a seguir for executada, os resultados retornados terão apenas eventos de origem e tipo DataSource 1.Type1 e corresponderão aos critérios de 'status' = 200.
```
search source=[
ds:`DataSource1.Type1`,
lg:`/aws/lambda/my-function-1`,
`aws:fieldIndex` IN ("status"), `status` = 200
]
```
## Restrições
As restrições a seguir se aplicam quando você usa o OpenSearch PPL para fazer consultas no CloudWatch Logs Insights.
+ Você não pode usar comandos de junção ou subconsulta com consultas de fonte de dados.
# OpenSearch Linguagem de consulta estruturada (SQL)
Esta seção contém uma introdução básica à consulta de CloudWatch registros usando OpenSearch SQL. Ela fornece uma opção mais conhecida se você estiver acostumado a trabalhar com bancos de dados relacionais. OpenSearch O SQL oferece um subconjunto da funcionalidade SQL, o que o torna uma boa opção para realizar consultas ad-hoc e tarefas de análise de dados. Com o OpenSearch SQL, você pode usar comandos como SELECT, FROM, WHERE, GROUP BY, HAVING e vários outros comandos e funções SQL. Você pode executar JOINs vários grupos de registros, correlacionar dados entre grupos de registros usando subconsultas e usar o rico conjunto de funções JSON, matemáticas, de sequência de caracteres, condicionais e outras funções SQL para realizar análises poderosas em dados de log e de segurança.
Use `filterIndex` para retornar somente dados indexados, forçando uma consulta a verificar somente grupos de logs indexados em um campo especificado na consulta. Reduza o volume escaneado ignorando grupos de registros que não têm nenhum evento de registro contendo o campo especificado na consulta e somente grupos de registros de varredura que correspondam ao valor especificado na consulta para esse índice de campo. Use `filterIndex` para especificar o nome do campo, junto com o nome e o valor do campo para consultar somente dados indexados contendo o campo e o valor especificados.
Você pode usar o OpenSearch SQL para consultas de grupos de registros na Classe de Registro Padrão. O SQL também oferece suporte à consulta usando o nome e o tipo da fonte de dados.
**nota**
A tabela a seguir lista os comandos e funções SQL compatíveis com os CloudWatch registros. Para obter informações sobre todos os comandos OpenSearch SQL, incluindo a sintaxe, consulte [Comandos SQL compatíveis](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/supported-directquery-sql.html) no OpenSearch Service Developer Guide.
Para obter informações sobre outras linguagens de consulta que você pode usar, consulte [CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html), [OpenSearch Service PPL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_PPL.html) e. [CloudWatch Metrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html)
## Comandos SQL compatíveis
**nota**
Na coluna de consulta de exemplo, substitua `` conforme necessário, dependendo da fonte de dados que você está consultando.
| Comando ou função | Consulta de exemplo | Description |
| --- | --- | --- |
| SELECT | `SELECT `@message`, Operation FROM `LogGroupA`` | Exibe os valores projetados. |
| FROM | `SELECT `@message`, Operation FROM `LogGroupA`` | Cláusula integrada que especifica a(s) tabela(s) ou visualização(ões) de origem a partir da(s) qual(is) recuperar dados, oferecendo suporte a vários tipos de junções e sub-consultas. |
| WHERE | `SELECT * FROM `LogGroupA` WHERE Operation = 'x'` | Filtra eventos de logs com base nos critérios de campo fornecidos. |
| filterIndex | `SELECT * FROM `filterIndex('region' = 'us-east-1')` WHERE status = 200 LIMIT 10;` | Retorna somente dados indexados, forçando uma consulta a examinar somente grupos de registros que estão indexados em um campo que você especifica na consulta. |
| GROUP BY | `SELECT `@logStream`, COUNT(*) as log_count FROM `LogGroupA` GROUP BY `@logStream`` | Agrupa eventos de logs com base na categoria e encontra a média com base nas estatísticas. |
| HAVING | `SELECT `@logStream`, COUNT(*) as log_count FROM `LogGroupA` GROUP BY `@logStream` HAVING log_count > 100` | Filtra os resultados com base nas condições de agrupamento. |
| ORDER BY | `SELECT * FROM `LogGroupA` ORDER BY `@timestamp` DESC` | Ordena os resultados com base nos campos da cláusula ORDER BY. É possível classificar em ordem crescente ou decrescente. |
| JOIN | `SELECT A.`@message`, B.`@timestamp`FROM `LogGroupA` as A INNER JOIN `LogGroupB` as B ON A.`requestId` = B.`requestId`` | Une os resultados de duas tabelas com base em campos comuns. Deve-se especificar Inner JOIN ou Left Outer Join |
| LIMIT | `Select * from `LogGroupA` limit 10` | Limita os resultados da consulta exibidos às primeiras N linhas. |
| Funções de string | `SELECT upper(Operation) , lower(Operation), Operation FROM `LogGroupA`` | Funções integradas na SQL que podem manipular e transformar dados de string e texto em consultas SQL. Por exemplo, converter maiúsculas e minúsculas, combinar strings, extrair partes e apagar texto. |
| Funções de data | `SELECT current_date() as today, date_add(current_date(), 30) as thirty_days_later, last_day(current_date()) as month_end FROM `LogGroupA`` | Funções integradas para manipular e transformar dados de data e carimbo de data/hora em consultas SQL. Por exemplo: date\$1add, date\$1format, datediff e current\$1date. |
| Funções condicionais | `SELECT Operation, IF(Error > 0, 'High', 'Low') as error_category FROM `LogGroupA`;` | Funções integradas que executam ações com base em condições especificadas ou que avaliam expressões condicionalmente. Por exemplo: CASE e IF. |
| Funções agregadas | `SELECT AVG(bytes) as bytesWritten FROM `LogGroupA`` | Funções integradas que realizam cálculos em várias linhas para produzir um único valor resumido. Por exemplo: SUM, COUNT, AVG, MAX e MIN. |
| Funções JSON | `SELECT get_json_object(json_column, '$.name') as name FROM `LogGroupA`` | Funções integradas para analisar, extrair, modificar e consultar dados formatados em JSON em consultas SQL (por exemplo, from\$1json, to\$1json, get\$1json\$1object, json\$1tuple), permitindo a manipulação de estruturas JSON em conjuntos de dados. |
| Funções de array | `SELECT scores, size(scores) as length, array_contains(scores, 90) as has_90 FROM `LogGroupA`;` | Funções integradas para trabalhar com colunas do tipo array em consultas SQL, permitindo operações como acessar, modificar e analisar dados de matriz (por exemplo, size, explode, array\$1contains). |
| Funções de janela | `SELECT field1, field2, RANK() OVER (ORDER BY field2 DESC) as field2Rank FROM `LogGroupA`;` | Funções integradas que executam cálculos em um conjunto específico de linhas relacionadas à linha (janela) atual, permitindo operações como classificação, totais acumulados e médias móveis. Por exemplo: ROW\$1NUMBER, RANK, LAG e LEAD |
| Funções de conversão | `SELECT CAST('123' AS INT) as converted_number, CAST(123 AS STRING) as converted_string FROM `LogGroupA`` | Funções integradas para converter dados de um tipo para outro em consultas SQL, permitindo transformações de tipos de dados e conversões de formato. Por exemplo: CAST, TO\$1DATE, TO\$1TIMESTAMP e BINARY. |
| Funções de predicado | `SELECT scores, size(scores) as length, array_contains(scores, 90) as has_90 FROM `LogGroupA`;` | Funções integradas que avaliam condições e retornam valores booleanos (verdadeiro/falso) com base em critérios ou padrões especificados. Por exemplo: IN, LIKE, BETWEEN, IS NULL e EXISTS. |
| Selecione vários grupos de logs | `SELECT lg1.field1, lg1.field2 from `logGroups( logGroupIdentifier: ['LogGroup1', 'LogGroup2'])` as lg1 where lg1.field3= "Success"` | Permite que você especifique vários grupos de logs em uma instrução SELECT |
| Selecione várias fontes de dados | `SELECT ds1.field1, ds1.field2 from `dataSource(['DataSource1', 'DataSource2'])` as ds1 where ds1.field3= "Success"` | Permite que você especifique várias fontes de dados em uma instrução SELECT |
## SQL compatível para multi-log-group consultas
Para oferecer suporte ao caso de uso para consultar vários grupos de logs no SQL, você pode usar o comando `logGroups`. Usando essa sintaxe, é possível consultar vários grupos de logs especificando-os no comando FROM.
Sintaxe:
```
`logGroups(
logGroupIdentifier: ['LogGroup1','LogGroup2', ...'LogGroupn']
)
```
Nessa sintaxe, é possível especificar até 50 grupos de logs no parâmetro `logGroupIdentifier`. Para referenciar grupos de registros em uma conta de monitoramento, use ARNs em vez de `LogGroup` nomes.
Consulta de exemplo:
```
SELECT LG1.Column1, LG1.Column2 from `logGroups(
logGroupIdentifier: ['LogGroup1', 'LogGroup2']
)` as LG1 WHERE LG1.Column1 = 'ABC'
```
A sintaxe a seguir, envolvendo vários grupos de registros após a `FROM` declaração, NÃO é compatível com a consulta CloudWatch de registros.
```
SELECT Column1, Column2 FROM 'LogGroup1', 'LogGroup2', ...'LogGroupn'
WHERE Column1 = 'ABC'
```
## SQL compatível para consultas de fontes de dados
Para oferecer suporte ao caso de uso para consultar fontes de dados em SQL, você pode usar o comando DataSource. Usando essa sintaxe, você pode consultar fontes de dados especificando-as no `FROM` comando. Você pode especificar até 10 fontes de dados.
**Sintaxe**
```
`dataSource(
['DataSource1', 'DataSource2', ...'DataSourcen']
)`
```
**Exemplo de consulta**
```
SELECT DS1.Column1, DS1.Column2 from `dataSource(
['DataSource1', 'DataSource2']
)` as DS1 WHERE DS1.Column1 = 'ABC'
```
## Escopo da consulta
Na API AWS CLI and, você pode especificar quais registros consultar usando o grupo de registros, a fonte e o tipo de dados e os índices de campo.
### Grupo de logs
A seleção da fonte do grupo de registros pode ser usada quando os clientes sabem quais grupos de registros exatos precisam ser pesquisados
```
SELECT * FROM `logGroups(logGroupIdentifier: ['/aws/lambda/my-function'])`;
```
### Fonte e tipo de dados
Os clientes podem consultar seus registros usando o nome e o tipo da fonte de dados.
A seleção da fonte de dados e da fonte baseada no tipo pode ser usada quando os clientes sabem quais fontes de dados exatas precisam ser consultadas. Essa consulta é executada em um ou mais grupos de registros que contêm a fonte e o tipo de dados especificados.
Para oferecer suporte ao caso de uso para consultar fontes de dados em SQL, você pode usar o comando DataSource. Usando essa sintaxe, você pode consultar fontes de dados especificando-as no comando FROM. Você pode especificar até 10 fontes de dados.
Sintaxe:
```
`dataSource(
['DataSource1.Type1', 'DataSource2.Type2', ...'DataSourcen.Typen']
)`
```
Consulta de exemplo:
```
SELECT DS1.Column1, DS1.Column2 from `dataSource(
['DataSource1.Type1', 'DataSource2.Type2']
)` as DS1 WHERE DS1.Column1 = 'ABC'
```
Para obter mais informações sobre consultas por fontes de dados, consulte[Use facetas para agrupar e explorar registros](CloudWatchLogs-Facets.md).
### Exemplo de combinação
Os clientes podem especificar todos os operadores de seleção de origem dentro dos acentos em qualquer ordem e os resultados seriam baseados na interseção de todas as condições aplicadas.
Por exemplo,/aws/lambda/my-function-1 pode conter várias fontes e tipos de dados, incluindo uma grande variedade de índices. Quando a consulta a seguir for executada, os resultados retornados terão apenas eventos de origem e tipo DataSource 1.Type1 e corresponderão aos critérios de 'status' = 200.
```
SELECT * FROM `
logGroups(logGroupIdentifier: ['/aws/lambda/my-function'])
filterIndex('status' = 200)
dataSource(['DataSource1.Type1'])
`;
```
### Índices de campo
A seleção de fontes com base no índice de campos identifica automaticamente grupos de registros relevantes quando seus filtros têm como alvo campos indexados, reduzindo o volume de escaneamento e o tempo de execução da consulta.
Use `filterIndex` para retornar somente dados indexados, forçando uma consulta a verificar somente grupos de logs indexados em um campo especificado na consulta. Para esses grupos de logs indexados nesse campo, ele otimiza ainda mais a consulta ignorando os grupos que não têm nenhum evento de logs contendo o campo especificado na consulta do campo indexado. Isso reduz ainda mais o volume escaneado ao tentar verificar somente eventos de logs desses grupos que correspondam ao valor especificado na consulta para esse índice de campo. Para obter mais informações sobre índices de campo e como criá-los, consulte [Criar índices de campo para melhorar o desempenho da consulta e reduzir o volume de varredura](CloudWatchLogs-Field-Indexing.md).
No SQL, filterIndex é usado para especificar quais pares de valores-chave devem ser tratados como índices. A sintaxe é a seguinte
```
SELECT * FROM `filterIndex('region' = 'us-east-1')`;
```
em que,
1. filterIndex (...) especifica, trata os valores-chave dentro deles como índices de campo. Cada par de valores-chave é separado por uma vírgula (exemplo abaixo)
1. 'region' = 'us-east-1' especifica a condição real a ser aplicada
1. Observação: em vez de =, os clientes podem usar IN para especificar vários valores (exemplo abaixo)
Usar vários FilterIndex combinaria as condições usando “AND”. No exemplo, registros que correspondam a status=200 e region em us-east-1 ou us-west-2 seriam consultados.
```
SELECT * FROM `filterIndex('status' = 200, 'region' IN ['us-east-1', 'us-west-2'])`;
```
## Restrições
As restrições a seguir se aplicam quando você usa OpenSearch SQL para fazer consultas no CloudWatch Logs Insights.
+ É possível incluir somente um JOIN em uma instrução SELECT.
+ Você não pode usar JOIN ou subconsultas com consultas de fonte de dados.
+ Somente um nível de sub-consultas aninhadas é suportado.
+ Não há suporte para várias consultas de instruções separadas por ponto e vírgula (;).
+ Consultas contendo nomes de campo idênticos, mas que diferem somente em maiúsculas e minúsculas (como field1 e FIELD1) não são suportadas.
Por exemplo, a consulta a seguir não é suportada:
```
Select AWSAccountId, AwsAccountId from LogGroup
```
No entanto, a consulta a seguir é compatível porque o nome do campo (`@logStream`) é idêntico nos dois grupos de logs:
```
Select a.`@logStream`, b.`@logStream` from Table A INNER Join Table B on a.id = b.id
```
+ Funções e expressões devem operar em nomes de campo e fazer parte de uma instrução SELECT com um grupo de logs especificado na cláusula FROM.
Por exemplo, esta consulta não é compatível:
```
SELECT cos(10) FROM LogGroup
```
Esta consulta é suportada:
```
SELECT cos(field1) FROM LogGroup
```
+ Ao usar comandos SQL ou PPL, coloque certos campos entre crases para consultá-los com êxito. As crases são necessárias para campos com caracteres especiais (não alfabéticos e não numéricos). Por exemplo, coloque `@message`, `Operation.Export` e `Test::Field` entre crases. Você não precisa colocar entre crases os campos com nomes puramente alfabéticos.
Exemplo de consulta com campos simples:
```
SELECT SessionToken, Operation, StartTime FROM `LogGroup-A`
LIMIT 1000;
```
Consulta semelhante com acentos graves acrescentados:
```
SELECT `@SessionToken`, `@Operation`, `@StartTime` FROM `LogGroup-A` LIMIT 1000;
```
# Use linguagem natural para gerar e atualizar consultas do CloudWatch Logs Insights
CloudWatch O Logs oferece suporte a um recurso de consulta em linguagem natural para ajudar você a gerar e atualizar consultas para [CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html), [OpenSearch Service PPL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_PPL.html), [OpenSearch Service SQL](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_AnalyzeLogData_SQL.html) e. [CloudWatch Metrics Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/query_with_cloudwatch-metrics-insights.html)
Com esse recurso, você pode fazer perguntas ou descrever os dados de CloudWatch registros que está procurando em inglês simples. O recurso de linguagem natural gera uma consulta com base em uma solicitação que você insere e fornece uma line-by-line explicação de como a consulta funciona. Você também pode atualizar a consulta para investigar melhor seus dados.
Dependendo do ambiente, você pode inserir prompts, como "Quais os 100 principais endereços IP de origem por bytes transferidos?" e "Encontre as dez solicitações de função do Lambda mais lentas".
**nota**
O recurso de consulta em linguagem natural é um serviço regional. Para algumas regiões, o recurso faz chamadas entre regiões para regiões nos Estados Unidos para processar os prompts de consulta. Para obter mais informações, consulte [Amazon CloudWatch expande o suporte regional para resumo de resultados de consultas em linguagem natural e geração de consultas](https://aws.amazon.com/about-aws/whats-new/2025/08/amazon-cloudwatch-region-support-query-result-summarization-query-generation/).
Para gerar uma consulta do CloudWatch Logs Insights com esse recurso, abra o editor de consultas do CloudWatch Logs Insights, selecione o grupo de registros que você deseja consultar e escolha **Gerar consulta**.
**Importante**
Para usar o recurso de consulta em linguagem natural, você deve estar conectado com as políticas [CloudWatchLogsFullAccess[CloudWatchLogsReadOnlyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsReadOnlyAccess.html)](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsFullAccess.html), [AdministratorAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AdministratorAccess.html), ou [ReadOnlyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/ReadOnlyAccess.html)do IAM, ou ter a `cloudwatch:GenerateQuery` permissão.
## Consultas de exemplo
Os exemplos nesta seção descrevem como gerar e atualizar consultas usando o recurso de linguagem natural.
**nota**
Para obter mais informações sobre o editor de consultas e a sintaxe do CloudWatch Logs Insights, consulte Sintaxe de [consulta do CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html).
### Exemplos: gerar uma consulta em linguagem natural
Para gerar uma consulta usando linguagem natural, insira um prompt e escolha **Gerar nova consulta**. Este exemplo mostra consultas que executam uma pesquisa básica.
**Prompt**
O exemplo de prompt a seguir instrui o recurso a pesquisar as dez invocações de funções do Lambda mais lentas.
```
Find the 10 slowest requests
```
**Consulta**
A seguir está a consulta usando a linguagem de consulta do CloudWatch Logs Insights que o recurso de linguagem natural gerou com base na solicitação. Observe como o prompt aparece em um comentário antes da consulta. Depois da consulta, você pode ler uma explicação que descreve como a consulta funciona.
```
# Find the 10 slowest requests
fields @timestamp, @message, @duration
| sort @duration desc
| limit 10
# This query retrieves the timestamp, message and duration fields from the logs and sorts them in descending order by duration to find the 10 slowest requests.
```
**nota**
Para desativar o surgimento do prompt e a explicação de como a consulta funciona, use o ícone de engrenagem no editor.
**Prompt**
Para gerar uma consulta OpenSearch SQL, selecione a guia OpenSearch SQL e, em seguida, abra a caixa de solicitação do gerador de consultas para inserir sua solicitação de linguagem natural. Veja a seguir um exemplo de um prompt que usa o recurso de linguagem natural para gerar uma consulta OpenSearch SQL.
```
Give me the number of errors and exceptions per hour
```
**Consulta**
A seguir está a consulta SQL gerada por esse prompt que você pode usar para encontrar o número de erros e exceções agregados por hora:
```
SELECT DATE_FORMAT(`@timestamp`, 'yyyy-MM-dd HH') AS hour,
COUNT(*) AS error_count
FROM `/aws/lambda/CloudWatchOdysseyQueryGen`
WHERE `@message` LIKE '%error%'
OR `@message` LIKE '%exception%'
GROUP BY DATE_FORMAT(`@timestamp`, 'yyyy-MM-dd HH')
ORDER BY hour
```
**Prompt**
Para gerar uma consulta OpenSearch PPL, selecione a guia OpenSearch PPL e, em seguida, abra a caixa de solicitação do gerador de consultas para inserir sua solicitação em linguagem natural. Veja a seguir um exemplo de um prompt que usa o recurso de linguagem natural para gerar uma consulta OpenSearch PPL.
```
Give me all unique exception messages
```
**Consulta**
Veja a seguir a consulta PPL gerada por esse prompt que você pode usar para encontrar as mensagens de exceção exclusivas em seus logs:
```
dedup @message
| fields @message
```
### Exemplo: atualizar uma consulta em linguagem natural
Você pode atualizar uma consulta editando o prompt inicial e escolhendo **Atualizar consulta**.
**Prompt atualizado**
O exemplo a seguir mostra uma versão atualizada do prompt anterior. Em vez de um prompt que pesquisa as dez invocações de funções do Lambda mais lentas, esse prompt agora instrui o recurso a pesquisar as vinte invocações de funções do Lambda mais lentas e a incluir outra coluna para eventos de log adicionais.
```
Show top 20 slowest requests instead and display requestId as a column
```
**Consulta atualizada**
Veja a seguir um exemplo da consulta atualizada usando a linguagem de consulta CloudWatch Logs Insights. Observe como o prompt atualizado aparece em um comentário antes da consulta atualizada. Depois da consulta, você pode ler uma explicação que descreve como a consulta original foi atualizada.
```
# Show top 20 slowest requests instead and display requestId as a column
fields @timestamp, @message, @requestId, @duration
| sort @duration desc
| limit 20
# This query modifies the original query by replacing the @message field with the @requestId field and changing the limit from 10 to 20 to return the top 20 log events by duration instead of the top 10.
```
## Optar por não usar seus dados para melhorar o serviço
Os dados dos prompts em linguagem natural que você fornece para treinar o modelo de IA e gerar consultas relevantes são usados exclusivamente para fornecer e manter seu serviço. Esses dados podem ser usados para melhorar a qualidade do CloudWatch Logs Insights. Sua confiança e privacidade, além da segurança do seu conteúdo, são nossas maiores prioridades. Para obter mais informações, consulte [Termos de Serviço da AWS](https://aws.amazon.com/service-terms/) e [AWS responsible AI policy](https://aws.amazon.com/machine-learning/responsible-ai/policy/).
Você pode se recusar a ter seu conteúdo usado para desenvolver ou melhorar a qualidade das consultas em linguagem natural ao criar uma política de rejeição de serviços de IA. Para desativar a coleta de dados de todos os recursos do CloudWatch Logs AI, incluindo o recurso de geração de consultas, você deve criar uma política de exclusão para o Logs. CloudWatch Para obter mais informações, consulte [Políticas de exclusão dos serviços de IA](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_ai-opt-out.html) no *Guia do usuário do AWS Organizations *.
# Logs compatíveis e campos descobertos
CloudWatch O Logs Insights oferece suporte a diferentes tipos de registros. Para cada registro enviado para um grupo de registros da classe Standard no Amazon CloudWatch Logs, o CloudWatch Logs Insights gera automaticamente cinco campos do sistema:
+ `@message` contém o evento de log bruto não avaliado. Isso é o equivalente ao `message` campo em [InputLogevent](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_InputLogEvent.html).
+ `@timestamp` contém o timestamp do evento contido no campo `timestamp` do evento de log. Isso é o equivalente ao `timestamp` campo em [InputLogevent](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_InputLogEvent.html).
+ `@ingestionTime`contém a hora em que o CloudWatch Logs recebeu o evento de log.
+ `@logStream` contém o nome do fluxo de logs ao qual o evento de log foi adicionado. Os fluxos de logs agrupam logs pelo mesmo processo que os gerou.
+ `@log` é um identificador de grupo de logs na forma de `account-id:log-group-name`. Ao consultar vários grupos de logs, isso pode ser útil para identificar a que grupo de logs um determinado evento pertence.
+ `@entity` contém JSON nivelado relacionado a entidades para o recurso de [telemetria relacionado ao Explore](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ExploreRelated.html).
Por exemplo, esse JSON pode representar uma entidade.
```
{
"Entity": {
"KeyAttributes": {
"Type": "Service",
"Name": "PetClinic"
},
"Attributes": {
"PlatformType": "AWS::EC2",
"EC2.InstanceId": "i-1234567890123"
}
}
}
```
Para essa entidade, os campos extraídos do sistema seriam os seguintes:
```
@entity.KeyAttributes.Type = Service
@entity.KeyAttributes.Name = PetClinic
@entity.Attributes.PlatformType = AWS::EC2
@entity.Attributes.EC2.InstanceId = i-1234567890123
```
**nota**
A descoberta de campos só é compatível com os grupos de logs da classe de logs Padrão. Para obter mais informações sobre classes de logs, consulte [Classes de logs](CloudWatch_Logs_Log_Classes.md).
CloudWatch O Logs Insights insere o símbolo **@** no início dos campos que ele gera.
Para muitos tipos de registro, o CloudWatch Logs também descobre automaticamente os campos de registro contidos nos registros. Esses campos de descoberta automática são mostrados na tabela a seguir.
Para outros tipos de registros com campos que o CloudWatch Logs Insights não descobre automaticamente, você pode usar o `parse` comando para extrair e criar campos extraídos para uso nessa consulta. Para obter mais informações, consulte [CloudWatch Sintaxe de consulta de linguagem do Logs Insights](CWL_QuerySyntax.md).
Se o nome de um campo de registro descoberto começar com o `@` caractere, o CloudWatch Logs Insights o exibirá com um adicional `@` anexado ao início. Por exemplo, se um nome de campo de log for `@example.com`, o nome desse campo será exibido como `@@example.com`.
**nota**
Com exceção de `@message`, `@timestamp` ou `@log`, é possível criar índices de campo para campos descobertos. Para ter mais informações sobre índices de campo, consulte [Crie índices de campo para melhorar o desempenho da consulta e reduzir o volume de escaneamento](CloudWatchLogs-Field-Indexing.md).
| Tipo de log | Campos de log descobertos |
| --- | --- |
| Logs de fluxo do Amazon VPC | `@timestamp`, `@logStream`, `@message`, `accountId`, `endTime`, `interfaceId`, `logStatus`, `startTime`, `version`, `action`, `bytes`, `dstAddr`, `dstPort`, `packets`, `protocol`, `srcAddr`, `srcPort` |
| Logs do Route 53 | `@timestamp`, `@logStream`, `@message`, `edgeLocation`, `ednsClientSubnet`, `hostZoneId`, `protocol`, `queryName`, `queryTimestamp`, `queryType`, `resolverIp`, `responseCode`, `version` |
| Logs do Lambda | `@timestamp`, `@logStream`, `@message`, `@requestId`, `@duration, ``@billedDuration`, `@type`, `@maxMemoryUsed`, `@memorySize` Se uma linha de log do Lambda contiver um ID de rastreamento do X-Ray, ela também incluirá os seguintes campos: `@xrayTraceId` e `@xraySegmentId`. CloudWatch O Logs Insights descobre automaticamente os campos de log nos registros do Lambda, mas somente para o primeiro fragmento JSON incorporado em cada evento de log. Se um evento de log do Lambda contiver vários fragmentos JSON, será possível analisar e extrair os campos de log usando o comando `parse`. Para obter mais informações, consulte [Campos em logs JSON](#CWL_AnalyzeLogData-discoverable-JSON-logs). |
| CloudTrail troncos Logs em formato JSON | Para obter mais informações, consulte [Campos em logs JSON](#CWL_AnalyzeLogData-discoverable-JSON-logs). |
| Outros tipos de log | `@timestamp`, `@ingestionTime`, `@logStream`, `@message`, `@log`. |
## Campos em logs JSON
Com o CloudWatch Logs Insights, você usa a notação de pontos para representar campos JSON. Esta seção contém um exemplo de evento JSON e trecho de código que mostra como você pode acessar campos JSON usando notação de ponto.
**Exemplo: evento JSON**
```
{
"eventVersion": "1.0",
"userIdentity": {
"type": "IAMUser",
"principalId": "EX_PRINCIPAL_ID",
"arn": "arn: aws: iam: : 123456789012: user/Alice",
"accessKeyId": "EXAMPLE_KEY_ID",
"accountId": "123456789012",
"userName": "Alice"
},
"eventTime": "2014-03-06T21: 22: 54Z",
"eventSource": "ec2.amazonaws.com",
"eventName": "StartInstances",
"awsRegion": "us-east-2",
"sourceIPAddress": "192.0.2.255",
"userAgent": "ec2-api-tools1.6.12.2",
"requestParameters": {
"instancesSet": {
"items": [
{
"instanceId": "i-abcde123"
}
]
}
},
"responseElements": {
"instancesSet": {
"items": [
{
"instanceId": "i-abcde123",
"currentState": {
"code": 0,
"name": "pending"
},
"previousState": {
"code": 80,
"name": "stopped"
}
}
]
}
}
}
```
O exemplo de evento JSON contém um objeto chamado `userIdentity`. `userIdentity` contém um campo chamado `type`. Para representar o valor de `type` com notação de ponto, você usa `userIdentity.type`.
O exemplo de evento JSON contém matrizes que se nivelam em listas de nomes e valores de campos aninhados. Para representar o valor de `instanceId` para o primeiro item em `requestParameters.instancesSet`, use `requestParameters.instancesSet.items.0.instanceId`. O número `0` que é colocado antes do campo `instanceID` refere-se à posição dos valores para o campo `items`. O exemplo a seguir contém um trecho de código que mostra como você pode acessar campos JSON aninhados em um evento de log JSON.
**Exemplo: consulta**
```
fields @timestamp, @message
| filter requestParameters.instancesSet.items.0.instanceId="i-abcde123"
| sort @timestamp desc
```
O trecho de código mostra uma consulta que usa notação de ponto com o comando `filter` para acessar o valor do campo JSON aninhado `instanceId`. A consulta filtra as mensagens para as quais o valor de `instanceId` é igual a `"i-abcde123"` e retorna todos os eventos de log que contêm o valor especificado.
**nota**
CloudWatch O Logs Insights pode extrair no máximo 200 campos de eventos de log de um log JSON. Para os campos adicionais que não são extraídos, você pode usar o comando `parse` para extrair os campos do evento de log não analisado bruto no campo de mensagem. Para obter mais informações sobre o `parse` comando, consulte [Sintaxe de consulta](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html) no Guia do CloudWatch usuário da Amazon.
# Crie índices de campo para melhorar o desempenho da consulta e reduzir o volume de escaneamento
Você pode criar *índices de campos* em seus eventos de logs para fazer pesquisas eficientes com base na igualdade. Quando você usa um índice de campo em uma consulta do CloudWatch Logs Insights, a consulta tenta ignorar o processamento de eventos de registro que, sabidamente, não incluem o campo indexado. Isso reduz o volume de escaneamento de suas consultas que usam índices de campo, possibilitando o retorno mais rápido dos resultados. Isso pode ajudar você a pesquisar rapidamente petabytes do total de logs em milhares de grupos de logs e a aprimorar os logs relevantes com mais rapidez. Os campos que você precisa consultar com mais frequência são bons para serem indexados. Campos com alta cardinalidade de valores também são bons candidatos para índices de campo, pois uma consulta usando esses índices de campo será concluída mais rapidamente, já que limita os eventos de logs que estão sendo correspondidos ao valor alvo.
Por exemplo, suponha que você tenha criado um índice de campo para `requestId`. Em seguida, qualquer consulta do CloudWatch Logs Insights nesse grupo de registros que inclua `requestId = value` ou `requestId IN [value, value, ...]` tente processar somente os eventos de registro que são conhecidos por conter esse campo indexado e o valor consultado, e que o CloudWatch Logs tenha detectado um valor para esse campo no passado.
Você também pode aproveitar seus índices de campo para criar consultas eficientes de um grande número de grupos de logs. Quando você usa o comando `filterIndex` em sua consulta em vez do comando `filter`, a consulta é executada em grupos de logs selecionados em eventos de logs que têm índices de campo. Essas consultas podem verificar até 10.000 grupos de logs selecionados especificando até cinco prefixos de nome de grupos de logs. Se for uma conta de monitoramento na observabilidade CloudWatch entre contas, você pode escolher todas as contas de origem ou especificar contas de origem individuais para selecionar os grupos de registros”.
Os campos indexados diferenciam maiúsculas e minúsculas. Por exemplo, um índice de campo de `RequestId` não corresponderá a um evento de logs que contenha `requestId`.
Os índices de campos são compatíveis somente com os formatos de log estruturados de JSON e logs de serviço.
CloudWatch Os registros fornecem índices de campo padrão para todos os grupos de registros na classe de registros padrão. Os índices de campo padrão ficam disponíveis automaticamente para os seguintes campos:
+ `@logStream`
+ `@aws.region`
+ `@aws.account`
+ `@source.log`
+ `@data_source_name`
+ `@data_source_type`
+ `@data_format`
+ `traceId`
+ `severityText`
+ `attributes.session.id`
CloudWatch O Logs também fornece índices de campo padrão para determinadas combinações de nome e tipo de fonte de dados. Os índices de campo padrão estão disponíveis automaticamente para as seguintes combinações de nome e tipo de fonte de dados:
| Nome e tipo da fonte de dados | Índices de campo padrão |
| --- | --- |
| `amazon_vpc.flow` | `action` `logStatus` `region` `flowDirection` `type` |
| `amazon_route53.resolver_query` | `query_type` `transport` `rcode` |
| `aws_waf.access` | `action` `httpRequest.country` |
| `aws_cloudtrail.data` ` aws_cloudtrail.management` | `eventSource` `eventName` `awsRegion` `userAgent` `errorCode` `eventType` `managementEvent` `readOnly` `eventCategory` `requestId` |
Os índices de campo padrão são adicionais aos índices de campo personalizados definidos em sua política. Os índices de campo padrão não são contabilizados em sua [cota de índice de campo](CloudWatchLogs-Field-Indexing-Syntax.md).
CloudWatch Os registros indexam somente os eventos de registro ingeridos após a criação de uma política de índice. Ele não indexa eventos de logs ingeridos antes da criação da política. Depois de criar um índice de campo, cada evento de logs correspondente permanece indexado por 30 dias a partir do tempo de ingestão do evento de logs.
**nota**
Se você criar uma política de índice de campo em uma conta de monitoramento, essa política não será usada para grupos de logs em contas de origem vinculadas. Uma política de índice de campo se aplica somente na conta em que foi criada.
O restante dos tópicos desta seção explica como criar índices de campo. Para obter informações sobre como se referir aos índices de campo em suas consultas, consulte [filterIndex](CWL_QuerySyntax-FilterIndex.md) e [filtrar](CWL_QuerySyntax-Filter.md).
**Topics**
+ [Sintaxe e cotas do índice de campo](CloudWatchLogs-Field-Indexing-Syntax.md)
+ [Crie uma política de índice de campo ao nível da conta](CloudWatchLogs-Field-Indexing-CreateAccountLevel.md)
+ [Crie uma política de índice de campo em nível de grupo de logs](CloudWatchLogs-Field-Indexing-CreateLogGroupLevel.md)
+ [Opções de seleção de grupos de logs ao criar uma consulta](Field-Indexing-Selection.md)
+ [Efeitos da exclusão de uma política de índice de campo](CloudWatchLogs-Field-Indexing-Deletion.md)
# Sintaxe e cotas do índice de campo
É possível gerar índices de campo criando *políticas de índice de campo*. Você pode criar políticas de índice em nível de conta que se aplicam a toda a sua conta, bem como políticas que se aplicam somente a um único grupo de logs. Para políticas de indexação em toda a conta, você pode ter uma que se aplique a todos os grupos de logs da conta. Também é possível criar políticas de índice em nível de conta que se apliquem a um subconjunto de grupos de logs na conta, selecionados pelos prefixos dos nomes dos grupos de logs. Se você tiver várias políticas em nível de conta na mesma conta, os prefixos do nome do grupo de logs para essas políticas não podem se sobrepor. Da mesma forma, você pode criar políticas de índice em nível de conta que se apliquem a uma combinação específica de nome e tipo de fonte de dados. Somente uma política de conta pode ser criada por combinação de nome e tipo de fonte de dados.
As políticas de índice de campo em nível de grupo de registros substituem as políticas de índice de campo em nível de conta: que se aplicam ao grupo de registros como um todo (como políticas em nível de conta sem critérios de seleção ou com critérios de seleção baseados no prefixo do nome do grupo de registros). As políticas em nível de conta que correspondam ao nível do evento de registro (como, por exemplo, para uma determinada combinação de nome e tipo de fonte de dados) serão aplicadas, além das políticas que correspondam ao grupo de registros como um todo. Se você criar uma política de índice em nível de grupo de registros, esse grupo de registros não usará políticas em nível de conta que correspondam ao nível do grupo de registros.
As correspondências de eventos de logs com os nomes dos índices de campo diferenciam maiúsculas de minúsculas. Por exemplo, um índice de campo de `RequestId` não corresponderá a um evento de logs que contenha `requestId`.
Você pode ter até 40 políticas de índice em nível de conta. Dessas políticas, 20 podem usar critérios de seleção de prefixo de nome de grupo de log e 20 podem usar critérios de seleção baseados em fonte de dados. Se você tiver várias políticas de índice em nível de conta filtradas para prefixos de nome de grupo de logs, nenhuma delas poderá usar prefixos de nome de grupo de logs iguais ou sobrepostos. Por exemplo, se você tiver uma política filtrada para grupos de logs que começam com `my-log`, não pode ter outra política de índice de campo filtrada para `my-logpprod` ou `my-logging`. Da mesma forma, se você tiver várias políticas de índice em nível de conta filtradas para combinações de nome e tipo de fonte de dados, nenhuma delas poderá usar o mesmo nome e tipo de fonte de dados. Por exemplo, se você tiver uma política filtrada pelo nome `amazon_vpc` e tipo da fonte de dados, não `flow` poderá criar outra política com essa combinação.
Se você tiver uma política de índice em nível de conta que não tenha prefixos de nome e se aplique a todos os grupos de registros, nenhuma outra política de índice em nível de conta com filtros de prefixo de nome de grupo de registros poderá ser criada; você pode criar políticas de índice em nível de conta que usem filtros de nome e tipo de fonte de dados.
Cada política de indexação tem as seguintes cotas e restrições:
+ Podem ser incluídos até 20 campos na política.
+ Cada nome de campo pode incluir até 100 caracteres.
+ Para criar um índice de um campo personalizado em seus grupos de logs que comece com `@`, você deve especificar o campo com um `@` extra no início do nome do campo. Por exemplo, se seus eventos de logs incluírem um campo chamado `@userId`, você deverá especificar `@@userId` para criar um índice para esse campo.
Para políticas de índice em nível de conta com critérios de seleção baseados no nome da fonte de dados e tipo, uma restrição adicional se aplica: todos os campos devem ser tipos de dados primitivos, os primitivos aninhados só são compatíveis com estruturas.
**Campos gerados e campos reservados**
CloudWatch O Logs Insights gera automaticamente campos do sistema em cada evento de registro. Esses campos gerados são prefixados com `@`. Para obter mais informações sobre os campos gerados, consulte [Logs compatíveis e campos descobertos](CWL_AnalyzeLogData-discoverable-fields.md).
Os seguintes campos gerados são compatíveis para uso como índices de campo:
+ `@logStream`
+ `@ingestionTime`
+ `@requestId`
+ `@type`
+ `@initDuration`
+ `@duration`
+ `@billedDuration`
+ `@memorySize`
+ `@maxMemoryUsed`
+ `@xrayTraceId`
+ `@xraySegmentId`
Para indexar esses campos gerados, você não precisa adicionar um `@` extra ao especificá-los, como é necessário fazer com campos personalizados que começam com `@`. Por exemplo, para criar um índice de campo para `@logStream`, basta especificar `@logStream` como índice de campo.
CloudWatch Os registros fornecem índices de campo padrão para todos os grupos de registros na classe de registros padrão. Os índices de campo padrão ficam disponíveis automaticamente para os seguintes campos:
+ `@logStream`
+ `@aws.region`
+ `@aws.account`
+ `@source.log`
+ `@data_source_name`
+ `@data_source_type`
+ `@data_format`
+ `traceId`
+ `severityText`
+ `attributes.session.id`
CloudWatch O Logs também fornece índices de campo padrão para determinadas combinações de nome e tipo de fonte de dados. Os índices de campo padrão estão disponíveis automaticamente para as seguintes combinações de nome e tipo de fonte de dados:
| Nome e tipo da fonte de dados | Índices de campo padrão |
| --- | --- |
| `amazon_vpc.flow` | `action` `logStatus` `region` `flowDirection` `type` |
| `amazon_route53.resolver_query` | `query_type` `transport` `rcode` |
| `aws_waf.access` | `action` `httpRequest.country` |
| `aws_cloudtrail.data` ` aws_cloudtrail.management` | `eventSource` `eventName` `awsRegion` `userAgent` `errorCode` `eventType` `managementEvent` `readOnly` `eventCategory` `requestId` |
Os índices de campo padrão são adicionais aos índices de campo personalizados definidos em sua política. Os índices de campo padrão não são contabilizados em sua [cota de índice de campo](#CloudWatchLogs-Field-Indexing-Syntax).
**Campos secundários e campos de matriz em logs JSON**
Você pode indexar campos que são secundários aninhados ou de matriz em logs JSON.
Por exemplo, você pode criar um índice do campo filho `accessKeyId` dentro do campo `userIdentity` desse log:
```
{
"eventVersion": "1.0",
"userIdentity": {
"type": "IAMUser",
"principalId": "EXAMPLE_PRINCIPAL_ID",
"arn": "arn: aws: iam: : 123456789012: user/Alice",
"accessKeyId": "11112222",
"accountId": "123456789012",
"userName": "Alice"
},
"eventTime": "2014-03-06T21: 22: 54Z",
"eventSource": "ec2.amazonaws.com",
"eventName": "StartInstances",
"awsRegion": "us-east-2",
"sourceIPAddress": "192.0.2.255",
"userAgent": "ec2-api-tools1.6.12.2",
"requestParameters": {
"instancesSet": {
"items": [{
"instanceId": "i-abcde123",
"currentState": {
"code": 0,
"name": "pending"
},
"previousState": {
"code": 80,
"name": "stopped"
}
}]
}
}
}
```
Para criar esse campo, você se refere a ele usando a notação de ponto (`userIdentity.accessKeyId`) ao criar o índice do campo e ao especificá-lo em uma consulta. A consulta pode ser como esta:
```
fields @timestamp, @message
| filterIndex userIdentity.accessKeyId = "11112222"
```
No evento de exemplo anterior, o campo `instanceId` está em uma matriz em `requestParameters.instancesSet.items`. Para representar esse campo ao criar o índice de campos e para consultar, indique-o como `requestParameters.instancesSet.items.0.instanceId`. O 0 se refere ao lugar desse campo no array.
Em seguida, uma consulta para esse campo pode ser:
```
fields @timestamp, @message
| filterIndex requestParameters.instancesSet.items.0.instanceId="i-abcde123"
```
# Crie uma política de índice de campo ao nível da conta
Use as etapas desta seção para criar uma política de índice de campo que se aplique a todos ou vários grupos de logs na conta que tenham nomes começados com a mesma string.
**Para criar uma política de índice de campo ao nível da conta**
1. Abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. Na barra de navegação à esquerda, escolha **Configurações** e, em seguida, escolha **Logs**.
1. Na seção **Políticas de índice em nível de conta**, escolha **Gerenciar**.
1. Escolha **Criar política de índice**.
1. Em **Nome da política**, insira um nome para sua nova política.
1. Em **Selecionar escopo da política**, faça o seguinte:
+ Escolha **Todos os grupos de logs padrão** para que a política de índice se aplique a todos os grupos de logs da Classe Padrão na conta.
+ Escolha **Grupos de registros por correspondência de prefixo** para aplicar a política a um subconjunto de grupos de registros, todos com nomes que começam com a mesma string. Em seguida, insira o prefixo desses grupos de logs em **Inserir um nome de prefixo**.
Depois de inserir seu prefixo, você pode escolher **Visualizar grupos de logs correspondentes ao prefixo** para confirmar se seu prefixo corresponde aos grupos que você esperava.
Escolha **Dados de registros por fonte de dados** para aplicar a política a uma combinação específica de nome e tipo de fonte de dados. Em seguida, você pode selecionar a **Fonte de dados** **e o Tipo** de dados no menu suspenso.
Depois de selecionar o nome e o tipo da fonte de dados, você pode selecionar **Obter campos** para preencher a seção **Configurar índices e facetas de campo** com informações relevantes, como os campos disponíveis, os grupos de registros incluídos e os índices de campo padrão e personalizados.
1. Em **Configuração personalizada do campo de índice**, selecione **Adicionar caminho de campo** para inserir o primeiro campo a ser indexado.
Em seguida, insira a string a ser usada como valor do nome do campo ou selecione um campo no menu suspenso. Ela deve ter letras maiúsculas e minúsculas que correspondam exatamente ao que aparece nos eventos de logs. Por exemplo, se seus eventos de logs incluírem `requestId`, você deverá inserir `requestId` aqui. `RequestId`, `requestID` e `request Id` não corresponderão.
Se você quiser indexar um campo de log personalizado que comece com o caractere `@`, inclua um caractere extra `@` ao inserir a string de índice. Por exemplo, se você tiver um campo de log personalizado `@emailname`, insira `@@emailname` na caixa **Adicionar caminho do campo**.
Você também pode criar índices para os `@logStream` campos `@ingestionTime` e que o CloudWatch Logs gera automaticamente. Se você fizer isso, não será necessário adicionar um `@` extra ao especificá-los.
1. (Opcional) Além de especificar o caminho do campo, você pode selecionar **Definir como uma faceta** para criar o campo como uma faceta.
1. Repita a etapa anterior para adicionar até 20 índices de campo.
1. Quando terminar, selecione **Create (Criar)**.
# Crie uma política de índice de campo em nível de grupo de logs
Use as etapas desta seção para criar uma política de índice de campo que se aplique a um único grupo de logs.
**Para criar uma política de índice de campo em nível de grupo de logs**
1. Abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. No painel de navegação esquerdo, selecione **Logs**, **Log groups (Grupos de log)**.
1. Escolha o nome do grupo de logs.
1. Escolha a guia **Índices de campo**.
1. Escolha **Gerenciar índices de campo para esse grupo de logs**.
1. Em **Gerenciar índices de campo em nível de grupo de logs**, escolha **Adicionar caminho de campo** para inserir o primeiro campo a ser indexado.
Em seguida, insira a string a ser usada como valor do nome do campo. Ela deve ter letras maiúsculas e minúsculas que correspondam exatamente ao que aparece nos eventos de logs. Por exemplo, se seus eventos de logs incluírem `requestId`, você deverá inserir `requestId` aqui. `RequestId`, `requestID` e `request Id` não corresponderão.
Se você quiser indexar um campo de log personalizado que comece com o caractere `@`, inclua um caractere extra `@` ao inserir a string de índice. Por exemplo, se você tiver um campo de log personalizado `@emailname`, insira `@@emailname` na caixa **Adicionar caminho do campo**.
Você também pode criar índices para os `@logStream` campos `@ingestionTime` e que o CloudWatch Logs gera automaticamente. Se você fizer isso, não será necessário adicionar um `@` extra ao especificá-los.
1. (Opcional) Além de especificar o caminho do campo, você pode selecionar **Definir como uma faceta** para criar o campo como uma faceta.
1. Repita a etapa anterior para adicionar até 20 índices de campo.
1. Quando terminar, escolha **Salvar**.
# Opções de seleção de grupos de logs ao criar uma consulta
Esta seção explica as várias maneiras pelas quais você pode selecionar grupos de logs a serem incluídos em uma consulta.
**Para selecionar grupos de logs para uma consulta no console**
1. Abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. No painel de navegação, escolha **Logs**, **Logs Insights**.
1. Selecione a linguagem de consulta que deseja usar para esta consulta. Você pode escolher entre: **Logs Insights QL**, **OpenSearchPPL** ou **OpenSearch SQL**.
1. Há três maneiras de selecionar grupos de logs para a consulta:
+ Use a caixa **Nome do grupo de logs**. Este é o método de seleção padrão. Você pode inserir até 50 nomes de grupos de logs com esse método. Se for uma conta de monitoramento na observabilidade CloudWatch entre contas, você poderá selecionar grupos de registros nas contas de origem e na conta de monitoramento. Uma única consulta pode consultar logs de diferentes contas ao mesmo tempo.
+ Use a seção **Critérios do grupo de logs**. Nesta seção, você pode escolher grupos de logs com base no prefixo dos nomes dos grupos de logs. É possível incluir até cinco prefixos em uma consulta. Serão selecionados grupos de logs que tenham esses prefixos nos nomes. Como alternativa, a opção **Todos os grupos de logs** seleciona todos os grupos da conta.
+ Se for uma conta de monitoramento na observabilidade CloudWatch entre contas, você pode selecionar **Todas as contas** no menu suspenso de contas para selecionar os grupos de registros de todas as contas vinculadas. Como alternativa, você pode selecionar individualmente quais contas devem ser incluídas nessa consulta.
Se suas opções corresponderem a mais de 10.000 grupos de logs, será exibido um erro solicitando que você restrinja sua seleção.
1. A classe de log padrão para uma consulta é **Padrão**. Você pode usar a **classe Log** para alterá-la para **Acesso infrequente**.
**Usando o AWS CLI**
Para fazer esses tipos de seleções ao iniciar uma consulta na linha de comando, você pode usar o comando `source` na sua consulta. Para ter mais informações e exemplos, consulte [SOURCE](CWL_QuerySyntax-Source.md).
# Efeitos da exclusão de uma política de índice de campo
Se você excluir uma política de índice de campo que está em vigor há algum tempo, pode acontecer o seguinte:
+ Por até 30 dias após a exclusão da política, as consultas ainda podem se beneficiar dos eventos de logs indexados.
+ Se você excluir uma política de índice em nível de grupo de logs e já existir uma política em nível de conta que se aplicaria a esse grupo, a política em nível de conta acabará se aplicando a ele.
# Use facetas para agrupar e explorar registros
As facetas são úteis para analisar registros, pois permitem filtrar e agrupar seus dados de forma interativa sem executar consultas. Uma faceta é um campo em seus registros (como `ServiceName` ou`StatusCode`) que permite filtragem, agregação e análise entre grupos de registros. Você pode ver a lista de campos facetados no console do CloudWatch Logs Insights, junto com a contagem de eventos de registro para cada valor de faceta com base no intervalo de tempo selecionado. Conforme você seleciona diferentes facetas e valores, os valores e contagens das facetas são atualizados em tempo real, permitindo que você explore seus registros de forma interativa.
Cada faceta mostra valores e contagens disponíveis extraídos automaticamente dos campos em seus registros com base no intervalo de tempo e no escopo da consulta selecionados, e retidos por 30 dias. As contagens de facetas mostradas são aproximadas. Você pode usar as facetas padrão, como nome da fonte de dados ou tipo de fonte de dados, para explorar seus registros ou criar facetas personalizadas em qualquer um dos campos em seus registros. O nome da fonte de dados é um serviço ou aplicativo da AWS que gera os registros (por exemplo, Route 53, Amazon VPC ou CloudTrail) e o tipo de fonte de dados é o tipo específico de log gerado por esse serviço. As facetas padrão são criadas por CloudWatch e incluem `@aws.region``@data_source_name`,`@data_source_type`, e. `@data_format` Para obter mais informações, consulte [Gerenciamento de logs](LogManagement.md). As facetas só estão disponíveis para registros que são ingeridos na conta. Se você configurou a observabilidade entre contas, a conta de monitoramento não pode visualizar facetas com base nos registros das contas de origem.
Para criar facetas adicionais, selecione os campos em seus registros que são relevantes para sua solução de problemas e configure-os usando as políticas de índice. Para facetas personalizadas, recomendamos criá-las em campos de baixa cardinalidade (campos com menos de 100 valores exclusivos por dia, como Status e). ApplicationName Facetas com mais de 100 valores exclusivos por dia são classificadas como de alta cardinalidade e os valores dessas facetas não são exibidos. Selecione uma ou mais facetas e clique para executar consultas em seus registros.
Para começar a usar facetas no CloudWatch Logs Insights:
1. Abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. No painel de navegação, escolha **Logs**, **Logs Insights**.
1. (Opcional) Use o seletor de intervalo de tempo para selecionar um período que você deseja analisar. Para o intervalo de tempo selecionado, as facetas e valores disponíveis são mostrados no painel.
1. Selecione facetas para explorar seus dados e ver atualizações em tempo real das distribuições de valor entre as facetas.
Facetas com mais de 100 valores exclusivos não são exibidas. Para consultar valores específicos, use filtros em sua consulta em vez disso.
## Para executar uma consulta baseada em facetas
1. Selecione um ou mais valores em todas as facetas.
1. A contagem de eventos será atualizada com base nas facetas e valores selecionados.
1. Conforme os valores das facetas são selecionados, o escopo da consulta é atualizado para refletir a seleção.
1. Depois de selecionar os valores das facetas, clique em executar para executar sua consulta.
1. O número máximo de valores exclusivos suportados por faceta é 100. Por exemplo, se houver mais de 100 valores para uma faceta, todas as contagens serão exibidas como “-”, indicando que os valores são desconhecidos.
## Para salvar uma consulta baseada em facetas
1. Crie sua consulta usando um ou mais valores de faceta.
1. O restante das etapas é o mesmo que salvar uma consulta do Logs Insights. Consulte [Salvando consultas do CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_Insights-Saving-Queries.html).
1. Suas consultas salvas estão disponíveis na seção Consultas salvas. Quando você recupera uma consulta salva, ela inclui automaticamente as facetas e os valores usados para a consulta, facilitando a análise de seus registros.
## Para criar uma faceta no nível da conta
1. Para criar facetas, você precisa primeiro criar o campo como um índice e configurá-lo como uma faceta. No painel de navegação, escolha **Configurações**, **Registros**, **Políticas de índice em nível de conta**. Como alternativa, você pode selecionar **Gerenciar facetas** no painel de facetas.
1. Escolha **Criar nova política de índice**. Para obter detalhes sobre a criação de políticas de índice, consulte[Crie uma política de índice de campo ao nível da conta](CloudWatchLogs-Field-Indexing-CreateAccountLevel.md).
1. Para criar uma faceta, marque **Definir como faceta** para o campo selecionado na página de criação da política de índice.
## Gerenciamento de facetas usando APIs
O gerenciamento de facetas pode ser feito usando a política de índice de campo. Para mais detalhes, consulte [https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_FieldIndex.html](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_FieldIndex.html) APIs .
**Índice de campo APIs**
| Não. | Name (Nome) | Description |
| --- | --- | --- |
| 1 | PutIndexPolicy | Cria ou atualiza uma política de índice de campo para o grupo de registros específico |
| 2 | PutAccountPolicy | Cria uma política de proteção de dados em nível de conta, política de filtro de assinatura, política de índice de campo, política de transformador ou política de extração métrica que se aplica a todos os grupos de registros ou a um subconjunto de grupos de registros na conta |
| 3 | DeleteIndexPolicy | Exclui uma política de índice de campo em nível de grupo de registros que foi aplicada a um único grupo de registros |
| 4 | DeleteAccountPolicy | Exclui uma política de conta do CloudWatch Logs |
# Análise de padrões
CloudWatch O Logs Insights usa algoritmos de aprendizado de máquina para encontrar *padrões* quando você consulta seus registros. Um padrão é uma estrutura de texto compartilhada que se repete nos campos do log. Ao visualizar os resultados de uma consulta, você pode escolher a guia **Padrões** para ver os padrões que o CloudWatch Logs encontrou com base em uma amostra dos seus resultados. Ou então, você pode acrescentar o comando `pattern` ao final da consulta para analisar os padrões em todo o conjunto de eventos de log correspondentes.
Os padrões são úteis para analisar grandes conjuntos de logs porque um grande número de eventos de log geralmente pode ser resumido a apenas alguns padrões.
Considere o exemplo dos três eventos de log a seguir.
```
2023-01-01 19:00:01 [INFO] Calling DynamoDB to store for resource id 12342342k124-12345
2023-01-01 19:00:02 [INFO] Calling DynamoDB to store for resource id 324892398123-12345
2023-01-01 19:00:03 [INFO] Calling DynamoDB to store for resource id 3ff231242342-12345
```
No exemplo anterior, todos os três eventos de log seguem um único padrão:
```
[INFO] Calling DynamoDB to store for resource id
```
Os campos dentro de um padrão são chamados de *tokens*. Os campos que variam dentro de um padrão, como um ID de solicitação ou um timestamp, são *tokens dinâmicos*. Cada token dinâmico é representado por ``. *string*É uma descrição do tipo de dados que o token representa. *number*Mostra onde esse token aparece no padrão, em comparação com os outros tokens dinâmicos.
Exemplos comuns de tokens dinâmicos incluem códigos de erro, registros de data e hora e solicitações. IDs Um *valor de token* representa um determinado valor de um token dinâmico. Por exemplo, se um token dinâmico representasse um código de erro HTTP, o valor de um token poderia ser `501`.
A detecção de padrões também é usada no detector de anomalias CloudWatch Logs e nos recursos de comparação. Para obter mais informações, consulte [Detecção de anomalias de log](LogsAnomalyDetection.md) e [Compare (diff) com intervalos de tempo anteriores](CWL_AnalyzeLogData_Compare.md).
## Introdução à análise de padrões
A detecção de padrões é realizada automaticamente em qualquer consulta do CloudWatch Logs Insights. Os resultados das consultas que não incluem o comando `pattern` apresentam tanto eventos quando padrões de log.
Se você incluir o comando `pattern` em sua consulta, a análise de padrões será realizada em todo o conjunto de eventos de log correspondente. Isso fornece resultados de padrões mais exatos, mas os eventos de log brutos não são retornados quando você usa o comando `pattern`. Quando uma consulta não inclui `pattern`, os resultados de padrões são baseados nos primeiros 1.000 eventos de log retornados ou no valor limite usado na consulta. Se você incluir `pattern` na consulta, os resultados exibidos na guia **Padrões** serão extraídos de todos os eventos de log que corresponderem à consulta.
**Para começar com a análise de padrões no CloudWatch Logs Insights**
1. Abra o CloudWatch console em [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).
1. No painel de navegação, escolha **Logs**, **Logs Insights**.
Na página **Logs Insights** (Insights de log), o editor de consultas contém uma consulta padrão que retorna os 20 eventos de log mais recentes.
1. Remova a linha `| limit 20` da caixa de consulta para que a consulta fique assim:
```
fields @timestamp, @message, @logStream, @log
| sort @timestamp desc
```
1. No menu suspenso **Selecionar grupos de logs**, escolha um ou mais grupos de logs para consultar.
1. (Opcional) Use o seletor de tempo para selecionar o período que você deseja consultar.
Você pode escolher intervalos de 5 minutos, 30 minutos, 1 hora, 3 horas, 12 horas ou um período personalizado.
1. Escolha **Executar consulta** para iniciar a consulta.
Quando a consulta acaba de ser executada, a guia **Logs** exibe uma tabela dos eventos de log retornados pela consulta. Acima da tabela, vem uma mensagem sobre quantos registros corresponderam à consulta, como, por exemplo, **Mostrando 10.000 dos 71.101 registros encontrados**.
1. Escolha a guia **Padrões**.
1. A tabela agora exibe os padrões encontrados na consulta. Como a consulta não incluía o comando `pattern`, essa guia só exibe os padrões descobertos entre os 10.000 eventos de log que foram mostrados na tabela na guia **Logs**.
Para cada padrão, as seguintes informações são exibidas:
+ O **padrão**, com cada token dinâmico exibido como ``. *string*É uma descrição do tipo de dados que o token representa. *number*Mostra onde esse token aparece no padrão, em comparação com os outros tokens dinâmicos.
+ O **número de eventos**, que é o número de vezes que o padrão apareceu nos eventos de log consultados. Escolha o cabeçalho de coluna **Número de eventos** para classificar os padrões por frequência.
+ A **Taxa de eventos**, que é a porcentagem dos eventos de log consultados que contém esse padrão.
+ O **Tipo de gravidade**, que será um dos seguintes:
+ **ERRO** se o padrão contiver a palavra **Erro**.
+ **AVISO** **se o padrão contiver a palavra **Aviso**, mas não contiver Erro**.
+ **INFORMAÇÕES** se o padrão não contiver nem **aviso** nem **erro**.
Escolha o cabeçalho de coluna **Informações sobre a gravidade** para classificar os padrões por gravidade.
1. Agora altere a consulta. Substitua a linha `| sort @timestamp desc` da consulta por `| pattern @message`, de modo que a consulta completa fique assim:
```
fields @timestamp, @message, @logStream, @log
| pattern @message
```
1. Selecione **Executar consulta**.
Quando a consulta termina, não há resultados na guia **Logs**. Porém, a guia **Padrões** provavelmente tem um número maior de padrões listados, dependendo do número total de eventos de log que foram consultados.
1. Independentemente de ter incluído `pattern` na sua consulta, você pode inspecionar melhor os padrões que a consulta retorna. Para fazer isso, escolha o ícone na coluna **Inspecionar** para um dos padrões.
O painel **Inspeção de padrões** aparece e exibe o seguinte:
+ O **padrão**. Selecione um token no padrão para analisar os valores desse token.
+ Um histograma mostrando o número de ocorrências do padrão no intervalo consultado. Isso pode ajudar a identificar tendências interessantes, como um aumento repentino na ocorrência de um padrão.
+ A guia **Exemplos de log** exibe alguns eventos de log que correspondem ao padrão selecionado.
+ A guia **Valores do token** exibe os valores do token dinâmico selecionado, se você tiver selecionado um.
**nota**
No máximo de 10 valores de token são capturados para cada token. A contagem de tokens pode não ser precisa. CloudWatch O Logs usa um contador probabilístico para gerar a contagem de tokens, não o valor absoluto.
+ A guia **Padrões relacionados** exibe outros padrões que ocorreram com frequência quase ao mesmo tempo que o padrão que você está inspecionando. Por exemplo, se um padrão para uma mensagem `ERROR` geralmente foi acompanhado por outro evento de log marcado como `INFO` com detalhes adicionais, esse padrão será exibido aqui.
## Detalhes sobre o comando de padrão
Esta seção contém mais detalhes sobre o comando `pattern` e seus usos.
+ No tutorial anterior, removemos o comando `sort` quando o adicionamos `pattern` porque uma consulta não será válida se incluir um comando `pattern` após um comando `sort`. É válido ter um `pattern` antes de um `sort`.
Para obter detalhes sobre a sintaxe de `pattern`, consulte [pattern](CWL_QuerySyntax-Pattern.md).
+ Quando você usa `pattern` em uma consulta, `@message` deve ser um dos campos selecionados no comando `pattern`.
+ Você pode incluir o comando `filter` antes de um comando `pattern` para que apenas o conjunto de eventos de log filtrado seja usado como entrada na análise de padrões.
+ Para ver os resultados de padrões para um campo específico, como um campo obtido com o comando `parse`, use `pattern @fieldname`.
+ Consultas com saídas que não são logs, como consultas com o comando `stats`, não retornam resultados de padrões.
# 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.
# Adicionar consulta ao painel ou exportar os resultados da consulta
Depois de executar uma consulta, você pode adicionar a consulta a um CloudWatch painel ou copiar os resultados para a área de transferência.
As consultas adicionadas aos painéis são executadas sempre que você carrega o painel e sempre que o painel é atualizado. Essas consultas contam para seu limite de 100 consultas simultâneas do CloudWatch Logs Insights.
**Para adicionar resultados da consulta a um painel**
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. Escolha um ou mais grupos de logs e execute uma consulta.
1. Escolha **Add to dashboard** (Adicionar ao painel).
1. Selecione o painel ou escolha **Criar novo** a fim de criar um painel para os resultados da consulta.
1. Selecione o tipo de widget a ser usado para os resultados da consulta.
1. Insira um nome para o widget.
1. Escolha **Add to dashboard** (Adicionar ao painel).
**Como copiar os resultados da consulta para a área de transferência ou fazer download dos resultados da 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. Escolha um ou mais grupos de logs e execute uma consulta.
1. Escolha **Exportar resultados** e depois a opção desejada.
# Exibir as consultas em execução ou o histórico de consultas
Exiba as consultas atualmente em andamento, bem como o histórico de consultas recente.
As consultas em execução no momento incluem as consultas adicionadas a um painel. Você está limitado a 100 consultas simultâneas do CloudWatch Logs Insights por conta, incluindo consultas adicionadas aos painéis. Além disso, você pode executar 15 consultas simultâneas para OpenSearch Service PPL ou OpenSearch Service SQL.
**Para exibir o histórico de consultas recente**
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. Escolha **Histórico**, se você estiver usando o novo design do console de CloudWatch registros. Se estiver usando o design antigo, escolha **Ações**, **Exibir histórico de consultas para esta conta**.
Uma lista das consultas recentes é exibida. Você pode executar qualquer um deles novamente selecionando a consulta e escolhendo **Executar**.
Em **Status**, CloudWatch Registros exibe **Em andamento** para todas as consultas em execução no momento.
# Criptografe os resultados da consulta com AWS Key Management Service
Por padrão, o CloudWatch Logs criptografa os resultados armazenados de suas consultas do CloudWatch Logs Insights usando o método padrão de criptografia do lado do servidor do CloudWatch Logs. Em vez disso, você pode optar por usar uma AWS KMS chave para criptografar esses resultados. Se você associar uma AWS KMS chave aos resultados da criptografia, o CloudWatch Logs usará essa chave para criptografar os resultados armazenados de todas as consultas na conta.
Se, posteriormente, você desassociar a chave dos resultados da consulta, o CloudWatch Logs retornará ao método de criptografia padrão para consultas posteriores. Mas as consultas executadas enquanto a chave estava associada ainda são criptografadas com essa chave. CloudWatch Os registros ainda podem retornar esses resultados após a desassociação da chave KMS, porque CloudWatch os registros ainda podem continuar referenciando a chave. No entanto, se a chave for desativada posteriormente, o CloudWatch Logs não conseguirá ler os resultados da consulta que foram criptografados com essa chave.
**Importante**
CloudWatch O Logs suporta somente chaves KMS simétricas. Não use uma chave assimétrica para criptografar os resultados da consulta. Para obter mais informações, consulte [Usar chaves simétricas e assimétricas](https://docs.aws.amazon.com/kms/latest/developerguide/symmetric-asymmetric.html).
## Limites
+ Para executar as etapas a seguir, é necessário ter as seguintes permissões: `kms:CreateKey`, `kms:GetKeyPolicy` e `kms:PutKeyPolicy`.
+ Após uma chave ser associada ou desassociada dos resultados da consulta, até cinco minutos poderão ser necessários para que a operação seja efetivada.
+ Se você revogar o acesso do CloudWatch Logs a uma chave associada ou excluir uma chave KMS associada, seus dados criptografados no CloudWatch Logs não poderão mais ser recuperados.
+ Você não pode usar o CloudWatch console para associar uma chave, é preciso usar a API AWS CLI ou CloudWatch Logs.
## Etapa 1: criar um AWS KMS key
Para criar uma chave do KMS, use o seguinte comando [create-key](https://docs.aws.amazon.com/cli/latest/reference/kms/create-key.html):
```
aws kms create-key
```
A saída contém o ID de chave e o nome do recurso da Amazon (ARN) da chave. A seguir está um exemplo de saída:
```
{
"KeyMetadata": {
"Origin": "AWS_KMS",
"KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab",
"Description": "",
"KeyManager": "CUSTOMER",
"Enabled": true,
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"KeyUsage": "ENCRYPT_DECRYPT",
"KeyState": "Enabled",
"CreationDate": 1478910250.94,
"Arn": "arn:aws:kms:us-west-2:123456789012:key/6f815f63-e628-448c-8251-e40cb0d29f59",
"AWSAccountId": "123456789012",
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
]
}
}
```
## Etapa 2: definir permissões na chave do KMS
Por padrão, todas as chaves do KMS são privadas. Somente o proprietário do recurso pode usá-la para criptografar e descriptografar dados. No entanto, o proprietário do recurso pode conceder permissões para acessar a chave a outros usuários e recursos. Com essa etapa, você concede permissão principal ao serviço de CloudWatch registros para usar a chave. Esse principal de serviço deve estar na mesma AWS região em que a chave está armazenada.
Como prática recomendada, recomendamos que você restrinja o uso da chave somente às AWS contas que você especificar.
Primeiro, salve a política padrão para sua chave KMS `policy.json` usando o seguinte [get-key-policy](https://docs.aws.amazon.com/cli/latest/reference/kms/get-key-policy.html)comando:
```
aws kms get-key-policy --key-id key-id --policy-name default --output text > ./policy.json
```
Abra o arquivo `policy.json` em um editor de texto e adicione a seção em negrito de uma das instruções a seguir. Separe a instrução existente da nova instrução com uma vírgula. Essas declarações usam `Condition` seções para aumentar a segurança da AWS KMS chave. Para obter mais informações, consulte [AWS KMS chaves e contexto de criptografia](encrypt-log-data-kms.md#encrypt-log-data-kms-policy).
A `Condition` seção neste exemplo limita o uso da AWS KMS chave para os resultados da consulta do CloudWatch Logs Insights na conta especificada.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "key-default-1",
"Statement": [
{
"Sid": "Enable IAM User Permissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:root"
},
"Action": "kms:*",
"Resource": "*"
},
{
"Effect": "Allow",
"Principal": {
"Service": "logs.region.amazonaws.com"
},
"Action": [
"kms:Encrypt*",
"kms:Decrypt*",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:Describe*"
],
"Resource": "*",
"Condition": {
"ArnEquals": {
"aws:SourceArn": "arn:aws:logs:us-east-1:111122223333:query-result:*"
},
"StringEquals": {
"aws:SourceAccount": "111122223333"
}
}
}
]
}
```
------
Por fim, adicione a política atualizada usando o seguinte [put-key-policy](https://docs.aws.amazon.com/cli/latest/reference/kms/put-key-policy.html)comando:
```
aws kms put-key-policy --key-id key-id --policy-name default --policy file://policy.json
```
## Etapa 3: associar uma chave do KMS aos resultados da consulta
**Para associar a chave do KMS aos resultados da consulta na conta**
Use o comando [disassociate-kms-key](https://docs.aws.amazon.com/cli/latest/reference/logs/disassociate-kms-key.html) da seguinte forma:
```
aws logs associate-kms-key --resource-identifier "arn:aws:logs:region:account-id:query-result:*" --kms-key-id "key-arn"
```
## Etapa 4: desassociar uma chave dos resultados da consulta na conta
Para desassociar a chave KMS associada aos resultados da consulta, use o seguinte [disassociate-kms-key](https://docs.aws.amazon.com/cli/latest/reference/logs/disassociate-kms-key.html)comando:
```
aws logs disassociate-kms-key --resource-identifier "arn:aws:logs:region:account-id:query-result:*"
```
# Gere um resumo em linguagem natural a partir dos resultados da consulta do CloudWatch Logs Insights
Analisar os dados de registro é crucial para entender o comportamento de seus aplicativos, mas interpretar grandes volumes de entradas de registro pode ser demorado. CloudWatch O Logs Insights agora oferece um recurso de resumo em linguagem natural que transforma resultados complexos de consultas em resumos claros e concisos. Esse recurso ajuda você a identificar problemas rapidamente e obter insights acionáveis a partir de seus dados de log.
## Como funciona
CloudWatch O Logs Insights pode gerar um resumo legível por humanos dos resultados da sua consulta usando o Amazon Bedrock. O recurso é compatível com todas as linguagens de consulta do CloudWatch Logs Insights e fornece insights claros e acionáveis dos seus dados de registro.
## Disponibilidade regional e processamento de dados
**Importante**
Quando você usa esse recurso, os resultados da consulta podem ser processados em um Região da AWS diferente. Por exemplo, se você executar uma consulta no Leste dos EUA (N. da Virgínia), o resumo pode ser gerado no Oeste dos EUA (Oregon).
A tabela a seguir lista o possível processamento Região da AWS para as diferentes regiões nas quais o recurso de resultados da consulta está disponível:
| Geografia CloudWatch de registros suportada | Possível região de processamento |
| --- | --- |
| Estados Unidos (EUA) | Região Leste dos EUA (N. da Virgínia) Região Leste dos EUA (Ohio) US West (Oregon) Region |
| Europa | Região Europa (Frankfurt) Região Europa (Irlanda) Região Europa (Paris) Região Europa (Estocolmo) Região Europa (Londres) |
| Ásia-Pacífico | Região Leste dos EUA (N. da Virgínia) Região Leste dos EUA (Ohio) US West (Oregon) Region |
| América do Sul | Região Leste dos EUA (N. da Virgínia) Região Leste dos EUA (Ohio) US West (Oregon) Region |
## Introdução
**Para gerar um resumo em linguagem natural**
1. Execute sua consulta do CloudWatch Logs Insights.
1. Depois que a consulta for concluída, selecione **Resumir resultados**.
## Permissões
É necessário ter uma das seguintes opções:
+ Permissão `CloudWatchLogsFullAccess`
+ Permissão `CloudWatchLogsReadOnlyAccess`
+ Política personalizada do IAM, incluindo as ações `cloudwatch:GenerateQueryResultsSummary`, `logs:GetQueryResults`, `logs:DescribeQueries` e `logs:FilterLogEvents`
## Privacidade de dados
Os resultados da sua consulta são processados com segurança e não são usados para treinar ou melhorar o CloudWatch Logs Insights ou o Amazon Bedrock. Se você optar por fornecer feedback sobre o resumo dos resultados da consulta usando os botões de feedback, seu feedback indica seu nível de satisfação com o recurso fornecido no CloudWatch Logs Insights.