Supervisión de eventos de Athena con Amazon EventBridge

Puede utilizar Amazon Athena con Amazon EventBridge para recibir notificaciones en tiempo real sobre el estado de las consultas. Cuando una consulta ha enviado estados de transiciones, Athena publica un evento en EventBridge que contiene información sobre esa transición de estado de consulta. Puede escribir reglas simples para eventos que le interesen y realizar acciones automatizadas cuando un evento coincida con una regla. Por ejemplo, puede crear una regla que invoque una función AWS Lambda cuando una consulta alcance un estado terminal. Los eventos se emiten en la medida de lo posible.

Antes de crear reglas de eventos para Athena, debe hacer lo siguiente:

• Familiarizarse con los eventos, las reglas y los destinos de EventBridge. Para obtener más información, consulte ¿Qué es Amazon EventBridge? Para obtener más información sobre cómo configurar reglas, consulte Introducción a Amazon EventBridge.

• Crear el destino o destinos que se van a usar en las reglas de eventos.

nota

Actualmente, Athena ofrece un tipo de evento, Athena Query State Change (Cambio de estado de consulta de Athena), pero puede agregar otros tipos de eventos y detalles. Si va a deserializar datos JSON de eventos mediante programación, asegúrese de que la aplicación esté preparada para tratar propiedades desconocidas para evitar problemas si se agregan estas propiedades adicionales.

Formato de eventos de Athena

El siguiente es el patrón básico de un evento de Amazon Athena.

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

Evento de cambio de estado de la consulta de Athena

En el ejemplo siguiente se muestra el evento de cambio de estado de la consulta de Athena con un 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"
    }
}

En el ejemplo siguiente se muestra el evento de cambio de estado de la consulta de Athena con un valor currentState de FAILED. El bloque athenaError aparece solo cuando el valor de currentState es FAILED. Para obtener información acerca de los valores para errorCategory y errorType, consulte Catálogo de errores de 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"
    }
}

Propiedades de salida

La salida JSON incluye las siguientes propiedades.

Propiedad	Descripción
athenaError	Aparece solo cuando el valor de currentState es FAILED. Contiene información sobre el error que se ha producido, incluida la categoría de error, el tipo de error, el mensaje de error y si se puede reintentar la acción que ha provocado el error. Los valores de cada uno de estos campos dependen de la naturaleza del error. Para obtener información acerca de los valores para errorCategory y errorType, consulte Catálogo de errores de Athena.
versionId	Número de versión del esquema del objeto de detalle.
currentState	El estado que adoptó la consulta cuando se produjo el evento.
previousState	El estado que tenía la consulta cuando se produjo el evento.
statementType	El tipo de instrucción de consulta que se ejecutó.
queryExecutionId	El identificador único de la consulta que se ejecutó.
workgroupName	El nombre del grupo de trabajo en el que se ejecutó la consulta.
sequenceNumber	Un número monótonamente creciente que permite la deduplicación y la ordenación de eventos entrantes que implican una sola ejecución de consulta. Cuando se publican eventos duplicados para la misma transición de estado, el valor de sequenceNumber es el mismo. Cuando una consulta experimenta una transición de estado más de una vez, como las consultas que experimentan una puesta en cola extraña, puede utilizar sequenceNumber para ordenar eventos con valores de previousState y currentState idénticos.

Ejemplo

En el siguiente ejemplo se publican eventos en un tema de Amazon SNS al que se ha suscrito. Cuando se realice una consulta en Athena, recibirá un correo electrónico. En el ejemplo se presupone que el tema de Amazon SNS existe y que se ha suscrito a él.

Para publicar eventos de Athena en un tema de Amazon SNS

1. Cree el destino del tema de Amazon SNS. Conceda a la entidad principal de EventBridge Events Service el permiso events.amazonaws.com para publicar en el tema de Amazon SNS, como en el siguiente ejemplo.

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

2. Utilice el comando events put-rule de la AWS CLI para crear una regla para eventos de Athena, como en el siguiente ejemplo.

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

3. Utilice el comando events put-targets de la AWS CLI para asociar el destino del tema de Amazon SNS, como en el siguiente ejemplo.

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

4. Realice una consulta en Athena y observe el destino que se está invocando. Debería recibir mensajes de correo electrónico correspondientes del tema de Amazon SNS.

Uso de AWS User Notifications con Amazon Athena

Puede utilizar las AWS User Notifications para configurar los canales de entrega a fin de recibir notificaciones sobre los eventos de Amazon Athena. Recibirá una notificación cuando un evento coincida con una regla que especifique. Puede recibir notificaciones de eventos a través de varios canales, como correo electrónico, notificaciones por chat de AWS Chatbot o notificaciones de inserción de AWS Console Mobile Application. También puede ver las notificaciones en el Centro de notificaciones de la consola. Las Notificaciones de usuario admiten la agregación, lo que puede reducir el número de notificaciones que recibe durante eventos específicos.

Para obtener más información, consulte la Guía del usuario de AWS User Notifications.