View a markdown version of this page

lookup - CloudWatch Registros da Amazon
Criação e gerenciamento de tabelas de pesquisaSintaxe de consulta para pesquisa

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

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 IDs de usuário para detalhes do usuário, códigos de 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/.

  2. No painel de navegação, escolha Configurações e, em seguida, escolha a guia Registros.

  3. Role até Pesquisar tabelas e escolha Gerenciar.

  4. Escolha Criar tabela de pesquisa.

  5. Insira um nome para a tabela de pesquisa. O nome só pode conter caracteres alfanuméricos, hífens e sublinhados.

  6. (Opcional) Insira uma descrição.

  7. Faça upload de um arquivo CSV. O arquivo deve incluir uma linha de cabeçalho com nomes de colunas, usar UTF-8 codificação e não exceder 10 MB.

  8. (Opcional) Especifique uma AWS KMS chave para criptografar os dados da tabela.

  9. 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 CreateLookupTablea 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.

Sintaxe de consulta para pesquisa

Estrutura do comando

O seguinte mostra o formato desse comando.

lookup table match-fields output-mode output-field[,...]

O comando usa os seguintes argumentos:

  • table— O nome da tabela de pesquisa a ser usada.

  • match-fields— Especifique um ou mais campos para comparar os eventos de log com a tabela de pesquisa. Você pode usar qualquer um dos seguintes formulários:

    • lookup-field as log-field [,...]— Use as quando o nome da coluna da tabela de pesquisa for diferente do nome do campo do evento de registro. Por exemplo, ip_address as srcAddr compara a ip_address coluna na tabela de pesquisa com o srcAddr campo em seus eventos de registro.

    • lookup-field [,...]— Quando o nome do campo do evento de registro é igual ao nome da coluna da tabela de pesquisa, você pode omitir as e especificar o nome do campo diretamente. Por exemplo, department, role compara as duas colunas aos campos de eventos de log com os mesmos nomes.

    Quando vários campos de correspondência são especificados, uma linha na tabela de pesquisa deve corresponder a todos os campos para produzir um resultado (lógica AND).

  • output-mode— Especifica como os campos de saída são adicionados aos resultados. Use uma das seguintes opções:

    • OUTPUT— Adiciona os campos de saída aos resultados. Se um campo com o mesmo nome já existir no evento de log, ele será substituído pelo valor da tabela de pesquisa. Se nenhuma correspondência for encontrada, o campo será definido como nulo.

    • OUTPUTNEW— Adiciona os campos de saída aos resultados somente se o campo ainda não existir no evento de log. Se o campo já tiver um valor, o valor original será mantido. Se nenhuma correspondência for encontrada, o campo permanecerá inalterado.

  • 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 nameemail,, 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"
Exemplo: use OUTPUTNEW para enriquecer sem sobrescrever

Se seus eventos de registro já contiverem um hostname campo, mas às vezes ele estiver vazio, use OUTPUTNEW para preencher os valores ausentes sem sobrescrever os existentes.

fields srcAddr, hostname
| lookup known_hosts ip_address as srcAddr OUTPUTNEW hostname, region
Exemplo: use a pesquisa com vários campos de correspondência

Você pode combinar em mais de um campo. A consulta a seguir corresponde à tabela de pesquisa srcAddr e dstPort à tabela de pesquisa para identificar serviços de rede conhecidos.

fields @timestamp, srcAddr, dstAddr, dstPort
| lookup network_services ip_address as srcAddr, port as dstPort OUTPUT service_name, owner
| filter ispresent(service_name)
Exemplo: Use a pesquisa com nomes de campo correspondentes

Quando os nomes dos campos do evento de log correspondem exatamente aos nomes das colunas da tabela de pesquisa, você pode omitir a as palavra-chave. A consulta a seguir combina os role campos department e os campos diretamente com a tabela de pesquisa.

fields @timestamp, department, role
| lookup employees department, role OUTPUT office, manager