# 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. Esse conector não usa o Glue Connections para centralizar as propriedades de configuração no Glue. A configuração da conexão é feita por meio do Lambda. 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 + Implante o conector na sua Conta da AWS usando o console do Athena ou o AWS Serverless Application Repository. Para ter mais informações, consulte [Criar uma conexão de fonte de dados](connect-to-a-data-source.md) ou [Usar o AWS Serverless Application Repository para implantar um conector de fonte de dados](connect-data-source-serverless-app-repo.md). ## Parâmetros Use os parâmetros nesta seção para configurar o conector do CloudWatch. ### Conexões do Glue (recomendação) Recomendamos que você configure um conector do CloudWatch usando um objeto de conexões do Glue. Para fazer isso, defina a variável de ambiente `glue_connection` do Lambda do conector do CloudWatch como o nome da conexão do Glue a ser usada. **Propriedades das conexões do Glue** Use o comando apresentado a seguir para obter o esquema de um objeto de conexão do Glue. Esse esquema contém todos os parâmetros que você pode usar para controlar a conexão. ``` aws glue describe-connection-type --connection-type CLOUDWATCH ``` **Propriedades do ambiente do Lambda** + **glue\$1connection**: especifica o nome da conexão do Glue associada ao conector federado. **nota** Todos os conectores que usam conexões do Glue devem usar o AWS Secrets Manager para armazenar credenciais. O conector do CloudWatch criado usando conexões do Glue não é compatível com o uso de um manipulador de multiplexação. O conector do CloudWatch criado usando conexões do Glue é compatível apenas com o `ConnectionSchemaVersion` 2. ### Conexões legadas + **spill\$1bucket**: especifica o bucket do Amazon S3 para dados que excedem os limites da função do Lambda. + **spill\$1prefix**: (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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) do Amazon S3 neste local para excluir derramamentos anteriores a um número predeterminado de dias ou horas. + **spill\$1put\$1request\$1headers**: (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](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) na *Referência da API do Amazon Simple Storage Service*. + **kms\$1key\$1id**: (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\$1spill\$1encryption**: (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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/serv-side-encryption.html). O conector também oferece suporte a [Controle de congestionamento AIMD](https://en.wikipedia.org/wiki/Additive_increase/multiplicative_decrease) para lidar com eventos de limitação do CloudWatch por meio da construção `ThrottlingInvoker` do [SDK do Amazon Athena Query Federation](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-federation-sdk). É possível ajustar o comportamento do controle de utilização padrão definindo qualquer uma das seguintes variáveis de ambiente opcionais: + **throttle\$1initial\$1delay\$1ms**: o atraso inicial da chamada aplicado após o primeiro evento de congestionamento. O padrão é de 10 milissegundos. + **throttle\$1max\$1delay\$1ms**: o atraso máximo entre as chamadas. É possível derivar o TPS dividindo-o em 1000 ms. O padrão é de 1000 milissegundos. + **throttle\$1decrease\$1factor**: o fator pelo qual o Athena reduz a taxa de chamadas. O padrão é de 0,5 + **throttle\$1increase\$1ms**: 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\$1stream**: 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](https://github.com/awslabs/aws-athena-query-federation/blob/master/athena-cloudwatch/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. ## desempenho 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. **nota** O conector do CloudWatch não é compatível com nomes de banco de dados em maiúsculas. ## Consultas de passagem O conector do CloudWatch suporta [consultas de passagem](federated-query-passthrough.md) que usam a [sintaxe de consulta do CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CWL_QuerySyntax.html). Para obter mais informações sobre o CloudWatch Logs Insights, consulte [Analisar dados de log com o CloudWatch Logs Insights](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AnalyzingLogData.html) 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](https://www.apache.org/licenses/LICENSE-2.0.html). ## Recursos adicionais Para obter mais informações sobre esse conector, visite [o site correspondente](https://github.com/awslabs/aws-athena-query-federation/tree/master/athena-cloudwatch) em GitHub.com.