Monitorar consultas com eventos do Amazon EventBridge

Você pode usar o Amazon Athena com o Amazon EventBridge para receber notificações em tempo real sobre o estado das consultas. Quando uma consulta enviada muda de estado, o Athena publica um evento no EventBridge com informações sobre a transição de estado da consulta. É possível gravar regras simples para eventos do seu interesse e realizar ações automatizadas quando um evento corresponder a uma regra. Por exemplo, é possível criar uma regra que invoca uma função do AWS Lambda quando uma consulta atinge um estado terminal. Os eventos são emitidos com base no melhor esforço.

Antes de criar regras de eventos para o Athena, faça o seguinte:

• Familiarize-se com os eventos, regras e destinos no EventBridge. Para obter mais informações, consulte O que é o Amazon EventBridge? Para obter mais informações sobre a configuração de regras, consulte Getting started with Amazon EventBridge.

• Crie os destinos para usar em suas regras de evento.

nota

Atualmente, o Athena oferece um tipo de evento, a alteração de estado da consulta do Athena, mas pode adicionar outros tipos de eventos e detalhes. Caso você esteja desserializando programaticamente dados JSON do evento, certifique-se de que a aplicação esteja preparada para lidar com propriedades desconhecidas caso propriedades adicionais sejam incluídas.

Formato de eventos do Athena

O item a seguir é o padrão básico de um evento do Amazon Athena.

{
    "source":[
        "aws.athena"
    ],
    "detail-type":[
        "Athena Query State Change"
    ],
    "detail":{
        "currentState":[
            "SUCCEEDED"
        ]
    }
}

Evento de alteração de estado da consulta do Athena

O exemplo a seguir mostra um evento de alteração de estado da consulta do Athena com o valor currentState de SUCCEEDED.

{
    "version":"0",
    "id":"abcdef00-1234-5678-9abc-def012345678",
    "detail-type":"Athena Query State Change",
    "source":"aws.athena",
    "account":"123456789012",
    "time":"2019-10-06T09:30:10Z",
    "region":"us-east-1",
    "resources":[

    ],
    "detail":{
        "versionId":"0",
        "currentState":"SUCCEEDED",
        "previousState":"RUNNING",
        "statementType":"DDL",
        "queryExecutionId":"01234567-0123-0123-0123-012345678901",
        "workgroupName":"primary",
        "sequenceNumber":"3"
    }
}

O exemplo a seguir mostra um evento de alteração de estado da consulta do Athena com o valor currentState de FAILED. O bloco athenaError aparece somente quando currentState corresponde a FAILED. Para obter informações sobre os valores de errorCategory e errorType, consulte Catálogo de erros do Athena.

{
    "version":"0",
    "id":"abcdef00-1234-5678-9abc-def012345678",
    "detail-type":"Athena Query State Change",
    "source":"aws.athena",
    "account":"123456789012",
    "time":"2019-10-06T09:30:10Z",
    "region":"us-east-1",
    "resources":[ 
    ],
    "detail":{
        "athenaError": {
            "errorCategory": 2.0, //Value depends on nature of exception
            "errorType": 1306.0, //Type depends on nature of exception
            "errorMessage": "Amazon S3 bucket not found", //Message depends on nature of exception
            "retryable":false //Retryable value depends on nature of exception
        },
        "versionId":"0",
        "currentState": "FAILED",
        "previousState": "RUNNING",
        "statementType":"DML",
        "queryExecutionId":"01234567-0123-0123-0123-012345678901",
        "workgroupName":"primary",
        "sequenceNumber":"3"
    }
}

Propriedades de saída

A saída JSON inclui as seguintes propriedades.

Propriedade	Descrição
athenaError	Aparece somente quando currentState corresponde a FAILED. Contém informações sobre o erro ocorrido, incluindo a categoria do erro, o tipo de erro, a mensagem de erro e se a ação que levou ao erro pode ocorrer novamente. Os valores para cada um desses campos dependem da natureza do erro. Para obter informações sobre os valores de errorCategory e errorType, consulte Catálogo de erros do Athena.
versionId	O número da versão do esquema do objeto de detalhes.
currentState	O estado para o qual a consulta foi alterada no momento do evento.
previousState	O estado inicial da consulta no momento do evento.
statementType	O tipo de instrução da consulta executada.
queryExecutionId	O identificador exclusivo da execução da consulta.
workgroupName	O nome do grupo de trabalho no qual a consulta foi executada.
sequenceNumber	Um número continuamente crescente que permite a eliminação de duplicação e classificação de eventos de entrada que envolvem uma única execução de consulta. Quando eventos duplicados forem publicados para a mesma transição de estado, o valor sequenceNumber será o mesmo. Quando uma consulta apresentar mais de uma transição de estado, como consultas que apresentam raro reenfileiramento, é possível usar sequenceNumber para classificar eventos com valores idênticos de currentState e previousState.

Exemplo

O exemplo a seguir publica eventos em um tópico do Amazon SNS ao qual você se inscreveu. Quando o Athena é consultado, você recebe um e-mail. O exemplo pressupõe que o tópico do Amazon SNS existe e que você está inscrito nele.

Para publicar eventos do Athena em um tópico do Amazon SNS

1. Crie um destino para o tópico do Amazon SNS. Conceda a permissão events.amazonaws.com à entidade principal do serviço de eventos do EventBridge para publicar no tópico do Amazon SNS, como no exemplo a seguir.

   {
       "Effect":"Allow",
       "Principal":{
           "Service":"events.amazonaws.com"
       },
       "Action":"sns:Publish",
       "Resource":"arn:aws:sns:us-east-1:111111111111:your-sns-topic"
   }

2. Use o comando da AWS CLI events put-rule para criar uma regra para eventos do Athena, como no exemplo a seguir.

   aws events put-rule --name {ruleName} --event-pattern '{"source": ["aws.athena"]}'

3. Use o comando da AWS CLI events put-targets para anexar o destino do tópico do Amazon SNS à regra, conforme o exemplo a seguir.

   aws events put-targets --rule {ruleName} --targets Id=1,Arn=arn:aws:sns:us-east-1:111111111111:your-sns-topic

4. Consulte o Athena e observe o destino sendo invocado. Você receberá e-mails correspondentes do tópico do Amazon SNS.

Uso do Notificações de Usuários da AWS com o Amazon Athena

É possível usar o Notificações de Usuários da AWS para configurar canais de entrega para receber notificações sobre eventos do Amazon Athena. Você recebe uma notificação quando um evento corresponde a uma regra especificada. É possível receber notificações de eventos por meio de vários canais, incluindo e-mail, notificações de chat do AWS Chatbot ou notificações por push do AWS Console Mobile Application. Você também pode visualizar notificações na Central de Notificações do Console. O Notificações de Usuários oferece é compatível com agregação, o que pode reduzir o número de notificações que você recebe durante eventos específicos.

Para mais informações, consulte o Guia do usuário do Notificações de Usuários da AWS.