Conector do Amazon Athena para o CloudWatch - Amazon Athena
Pré-requisitosParâmetrosBancos de dados e tabelasPermissões obrigatóriasPerformanceConsultas de passagemInformações de licençaRecursos adicionais

Conector do Amazon Athena para o CloudWatch

O conector do CloudWatch no Amazon Athena permite que o Amazon Athena se comunique com o CloudWatch para que você possa consultar os dados de log com SQL.

O conector mapeia os LogGroups como esquemas e cada LogStream como uma tabela. O conector também mapeia uma exibição all_log_streams especial que contém todos os LogStreams no LogGroup. Essa exibição permite consultar todos os logs em um LogGroup de uma só vez, em vez de pesquisar cada LogStream individualmente.

Pré-requisitos

Parâmetros

Use as variáveis de ambiente do Lambda nesta seção para configurar o conector CloudWatch.

  • spill_bucket: especifica o bucket do Amazon S3 para dados que excedem os limites da função do Lambda.

  • spill_prefix: (opcional) assume como padrão uma subpasta no spill_bucket especificado chamado athena-federation-spill. Recomendamos que você configure um ciclo de vida de armazenamento do Amazon S3 neste local para excluir derramamentos anteriores a um número predeterminado de dias ou horas.

  • spill_put_request_headers: (opcional) um mapa codificado em JSON de cabeçalhos e valores de solicitações para a solicitação putObject do Amazon S3 usada para o derramamento (por exemplo, {"x-amz-server-side-encryption" : "AES256"}). Para outros cabeçalhos possíveis, consulte PutObject na Referência da API do Amazon Simple Storage Service.

  • kms_key_id: (opcional) por padrão, todos os dados transmitidos para o Amazon S3 são criptografados usando o modo de criptografia autenticado AES-GCM e uma chave gerada aleatoriamente. Para que sua função do Lambda use chaves de criptografia mais fortes geradas pelo KMS, como a7e63k4b-8loc-40db-a2a1-4d0en2cd8331, é possível especificar um ID de chave do KMS.

  • disable_spill_encryption: (opcional) quando definido como True, desativa a criptografia do derramamento. É padronizado como False, para que os dados transmitidos para o S3 sejam criptografados usando o AES-GCM — usando uma chave gerada aleatoriamente ou o KMS para gerar chaves. Desativar a criptografia do derramamento pode melhorar a performance, especialmente se o local do derramamento usar criptografia no lado do servidor.

O conector também oferece suporte a Controle de congestionamento AIMD para lidar com eventos de limitação do CloudWatch por meio da construção ThrottlingInvoker do SDK do Amazon Athena Query Federation. É possível ajustar o comportamento do controle de utilização padrão definindo qualquer uma das seguintes variáveis de ambiente opcionais:

  • throttle_initial_delay_ms: o atraso inicial da chamada aplicado após o primeiro evento de congestionamento. O padrão é de 10 milissegundos.

  • throttle_max_delay_ms: o atraso máximo entre as chamadas. É possível derivar o TPS dividindo-o em 1000 ms. O padrão é de 1000 milissegundos.

  • throttle_decrease_factor: o fator pelo qual o Athena reduz a taxa de chamadas. O padrão é de 0,5

  • throttle_increase_ms: a taxa na qual o Athena diminui o atraso da chamada. O padrão é de 10 milissegundos.

Bancos de dados e tabelas

O conector CloudWatch do Athena mapeia seus LogGroups como esquemas (ou seja, bancos de dados) e cada LogStream como uma tabela. O conector também mapeia uma exibição all_log_streams especial que contém todos os LogStreams no LogGroup. Essa exibição permite consultar todos os logs em um LogGroup de uma só vez, em vez de pesquisar cada LogStream individualmente.

Cada tabela mapeada pelo conector CloudWatch do Athena possui o esquema a seguir. Esse esquema corresponde aos campos fornecidos pelo CloudWatch Logs.

  • log_stream: um VARCHAR que contém o nome do LogStream de onde a linha pertence.

  • time: um INT64 que contém a época em que a linha de log foi gerada.

  • message: um VARCHAR que contém a mensagem de log.

Exemplos

O exemplo a seguir mostra como realizar uma consulta SELECT em um LogStream especificado.

SELECT * 
FROM "lambda:cloudwatch_connector_lambda_name"."log_group_path"."log_stream_name" 
LIMIT 100

O exemplo a seguir mostra como usar a visualização all_log_streams para executar uma consulta em todos os LogStreams em um LogGroup especificado. 

SELECT * 
FROM "lambda:cloudwatch_connector_lambda_name"."log_group_path"."all_log_streams" 
LIMIT 100

Permissões obrigatórias

Os detalhes completos sobre as políticas do IAM exigidas por esse conector podem ser encontrados na seção Policies do arquivo athena-cloudwatch.yaml. A lista a seguir resume as permissões necessárias.

  • Acesso de gravação do Amazon S3: o conector requer acesso de gravação a um local no Amazon S3 para mostrar resultados de grandes consultas.

  • Athena GetQueryExecution: o conector usa esta permissão para falhar rapidamente quando a consulta upstream do Athena é encerrada.

  • CloudWatch Logs Read/Write (Leitura/gravação do CloudWatch Logs): o conector usa esta permissão para ler seus dados de log e gravar seus logs de diagnóstico.

Performance

O conector CloudWatch do Athena tenta otimizar as consultas em relação ao CloudWatch paralelizando as varreduras dos fluxos de log necessários para sua consulta. Para determinados filtros de período de tempo, a redução de predicados é realizada tanto na função do Lambda quanto no CloudWatch Logs.

Para obter a melhor performance, use somente letras minúsculas em nomes de grupos de logs e nomes de fluxos de logs. O uso de maiúsculas e minúsculas mistas faz com que o conector execute uma pesquisa que não diferencia maiúsculas de minúsculas e é mais computacionalmente intensiva.

Consultas de passagem

O conector do CloudWatch suporta consultas de passagem que usam a sintaxe de consulta do CloudWatch Logs Insights. Para obter mais informações sobre o CloudWatch Logs Insights, consulte Analisar dados de log com o CloudWatch Logs Insights no Guia do usuário do Amazon CloudWatch Logs.

Para criar consultas de passagem com o CloudWatch, use a seguinte sintaxe:

SELECT * FROM TABLE(
        system.query(
            STARTTIME => 'start_time',
            ENDTIME => 'end_time',
            QUERYSTRING => 'query_string',
            LOGGROUPNAMES => 'log_group-names',
            LIMIT => 'max_number_of_results'
        ))

O exemplo a seguir filtra a consulta de passagem do CloudWatch para o campo duration quando ele não é igual a 1000.

SELECT * FROM TABLE(
        system.query(
            STARTTIME => '1710918615308',
            ENDTIME => '1710918615972',
            QUERYSTRING => 'fields @duration | filter @duration != 1000',
            LOGGROUPNAMES => '/aws/lambda/cloudwatch-test-1',
            LIMIT => '2'
            ))

Informações de licença

O projeto do conector CloudWatch do Amazon Athena é licenciado sob a Licença Apache-2.0.

Recursos adicionais

Para obter mais informações sobre esse conector, visite o site correspondente em GitHub.com.