View a markdown version of this page

Supervisión de Amazon Quick mediante CloudWatch registros - Amazon Quick
Destinos de registro compatiblesRequisitos previosConfiguración de registros deEsquema y formato del registroRegistros de horas de los agentesRegistros de metadatos del agenteRegistros de uso del índiceBase de conocimiento: registros de sincronización de archivosConsideraciones de seguridad

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Supervisión de Amazon Quick mediante CloudWatch registros

Puede usar Amazon CloudWatch Logs para mostrar las conversaciones de chat, los comentarios de los usuarios, las horas de uso de los agentes y el uso del almacenamiento de índices en Amazon Quick para que pueda analizarlos. Estos registros se pueden enviar a varios destinos CloudWatch, como Amazon S3 o Amazon Data Firehose (se aplican las tarifas estándar).

importante

Configure la entrega de registros vendidos poco después de habilitar las funciones de Amazon Quick AI. Los registros no son retroactivos: solo recibes los eventos que se producen después de configurar la entrega.

Los siguientes son ejemplos de tareas que puede realizar con los registros de Amazon Quick:

  • Identifique las consultas y los puntos críticos más comunes de los usuarios revisando el contenido del mensaje de chat.

  • Monitorice la calidad de las respuestas observando métricas como feedbackReason.

  • Comprenda el sentimiento y la satisfacción de los usuarios analizando los datos de retroalimentación, incluidos los comentarios y las calificaciones de utilidad.

  • Genere paneles e informes personalizados para realizar un seguimiento de métricas y tendencias clave a lo largo del tiempo.

  • Identifique y analice los casos en los que el chat no obtuvo respuesta o en los que la consulta del usuario se bloqueó.

  • Supervise el uso del horario de los agentes.

  • Realice un seguimiento del uso del almacenamiento de índices en las bases de conocimiento y en Spaces.

  • Realice un seguimiento de las operaciones de sincronización de la base de conocimientos e identifique los errores de rastreo o indexación de documentos.

importante

Los registros de conversaciones pueden incluir datos confidenciales o de identificación personal transmitidos en los chats. Puedes filtrar esta información de tus registros al configurar la suscripción a los registros. O puedes enmascarar estos datos en tus registros mediante las políticas de enmascaramiento de CloudWatch registros. Para obtener más información, consulte Ayuda para proteger los datos de registro confidenciales con el enmascaramiento.

Destinos de registro compatibles

Amazon Quick puede entregar los registros a los siguientes destinos:

  • Amazon CloudWatch Logs: para monitoreo y análisis en tiempo real

  • Amazon S3: para almacenamiento a largo plazo y procesamiento por lotes

  • Amazon Data Firehose: para el análisis de streaming y la transformación de datos

Requisitos previos

Antes de poder habilitar el registro, asegúrese de disponer de lo siguiente:

  • Una instancia activa de Amazon Quick con suscripciones Enterprise o Professional

  • Permisos de IAM adecuados para configurar la entrega de registros

  • Un destino configurado para sus CloudWatch registros (Logs, bucket de Amazon S3 o Firehose)

Configuración de registros de

Para habilitar el registro del chat y los comentarios de Amazon Quick, configure los permisos de IAM, cree un origen y un destino de entrega y verifique la entrega de los registros.

Configurar permisos de IAM

Para configurar CloudWatch los registros de Amazon Quick, utiliza los siguientes ejemplos de políticas de IAM para conceder los permisos necesarios.

{
    "Version": "2012-10-17",
    "Statement": [{
        "Sid": "QuicksightLogDeliveryPermissions",
        "Effect": "Allow",
        "Action": "quicksight:AllowVendedLogDeliveryForResource",
        "Resource": "arn:aws:quicksight:region:account-id:account/account-id"
    }]
}

También debes incluir al principal de delivery.logs.amazonaws.com servicio en tu política de AWS KMS claves gestionadas por el cliente.

{
    "Effect": "Allow",
    "Principal": {
        "Service": "delivery.logs.amazonaws.com"
    },
    "Action": [
        "kms:GenerateDataKey",
        "kms:Decrypt"
    ],
    "Resource": "*",
    "Condition": {
        "StringEquals": {
            "kms:EncryptionContext:SourceArn": "arn:partition:logs:region:account-id:*"
        }
    }
}

Configure la suscripción al registro

Para ver, por ejemplo, las políticas de IAM con todos los permisos necesarios para su destino de registro específico, consulte Habilitar el registro desde AWS los servicios en la guía del usuario de Amazon CloudWatch Logs.

Crea una fuente de entrega con la operación de la API PutDeliverySource CloudWatch Logs. Asigne un nombre al origen de entrega y para resourceArn, especifique el ARN de la aplicación. ParalogType, especifique CHAT_LOGSAGENT_HOURS_LOGS,AGENT_METADATA_LOGS,FEEDBACK_LOGS,INDEX_USAGE_LOGS, oKB_FILE_SYNC_LOGS.

{
    "logType": "CHAT_LOGS",
    "name": "my-quick-suite-delivery-source",
    "resourceArn": "arn:aws:quicksight:your-region:your-account-id:account/account-id"
}
{
    "logType": "FEEDBACK_LOGS",
    "name": "my-quick-suite-delivery-source",
    "resourceArn": "arn:aws:quicksight:your-region:your-account-id:account/account-id"
}
{
    "logType": "AGENT_HOURS_LOGS",
    "name": "my-quick-suite-delivery-source",
    "resourceArn": "arn:aws:quicksight:your-region:your-account-id:account/account-id"
}
{
    "logType": "INDEX_USAGE_LOGS",
    "name": "my-quick-index-usage-delivery-source",
    "resourceArn": "arn:aws:quicksight:your-region:your-account-id:account/account-id"
}
{
    "logType": "KB_FILE_SYNC_LOGS",
    "name": "my-quick-kb-file-sync-delivery-source",
    "resourceArn": "arn:aws:quicksight:your-region:your-account-id:account/account-id"
}
{
    "logType": "AGENT_METADATA_LOGS",
    "name": "my-quick-agent-metadata-delivery-source",
    "resourceArn": "arn:aws:quicksight:your-region:your-account-id:account/account-id"
}

Para habilitar el registro de las conversaciones de los usuarios con las operaciones de la API de CloudWatch LogsPutDeliverySource, llame a las operaciones de la CreateDelivery APIPutDeliveryDestination, y.

nota

Vended-log la entrega es por región. Cada entrega captura solo la actividad que se produce en la región especificada por la resourceArn entradaPutDeliverySource. Para recibir registros de varias regiones, configure una entrega independiente en cada región.

Verifique la entrega de registros

Después de configurar la entrega de registros, verifique que los registros se entreguen a su destino:

  • Verifica la configuración: verifica la lista de entregas que se han creado en la cuenta mediante la DescribeDeliveries API de CloudWatch Logs.

  • CloudWatch Registros: compruebe el grupo de registros especificado para ver si hay nuevos flujos de registro.

  • Amazon S3: supervise su bucket para ver si hay nuevos archivos de registro.

  • Firehose: compruebe que los datos fluyen a través de su flujo de entrega.

Esquema y formato del registro

Los registros rápidos de Amazon siguen un esquema estructurado con campos comunes compartidos en todos los tipos de registro y campos específicos para los registros de chat y comentarios.

Campos comunes

Todos los eventos de registro incluyen los siguientes campos comunes:

  • resource_arn— El ARN del recurso de su cuenta de Amazon Quick (por ejemplo,arn:aws:quicksight:us-east-1:111122223333:account/111122223333:)

  • event_timestamp— Tiempo de época de Unix en milisegundos (por ejemplo,) 1763532110061

  • logType— Tipo de registro (por ejemplo, CHAT_LOGS o) FEEDBACK_LOGS

  • accountId— ID de AWS cuenta (por ejemplo,123456789012)

  • user_arn— El ARN del usuario de Amazon Quick asociado al evento (por ejemplo,"arn:aws:quicksight:us-west-2:111122223333:user/default/user")

Registros de chat

Los registros de chat capturan las interacciones de las conversaciones:

nota

Las conversaciones temporales que están excluidas del historial y la memoria se siguen enviando a los registros de chat. Cada registro incluye el user_arn y user_type del usuario que inició la conversación.

  • user_arn— El ARN del usuario de Amazon Quick asociado al evento

  • user_type— El tipo de usuario de Amazon Quick asociado al evento (por ejemplo,ADMIN_PRO)

  • status_code— Estado de la solicitud de chat (por ejemplo,success,request_blocked,no_answer_found)

  • conversation_id— ID único para la conversación del usuario

  • system_message_id— ID del System-generated mensaje

  • message_scope— Alcance del mensaje (por ejemplo,all_resources,specific_resources,no_resources)

  • user_message_id— ID único del mensaje de usuario

  • user_message— Mensaje de usuario en la conversación

  • agent_id— ID único del agente de chat o SYSTEM del agente predeterminado

  • flow_id— ID único del Amazon Quick Flow o, - si no es una invocación de flujo

  • system_text_message— Respuesta del sistema en la conversación

  • user_selected_resources— Lista de recursos seleccionados por el usuario

  • action_connectors— Lista de conectores de acción disponibles en la conversación

  • cited_resource— Lista de recursos citados

  • file_attachment— Lista de archivos adjuntos por usuario

  • resource_arn— El ARN del recurso de su cuenta de Amazon Quick

  • event_timestamp— Marca de tiempo del evento

  • logType – CHAT_LOGS

  • accountId— ID de cuenta AWS

El siguiente es un ejemplo de registros de chat:

{
    "user_arn": "arn:aws:quicksight:us-east-1:111122223333:user/default/johndoe",
    "user_type": "ADMIN_PRO",
    "status_code": "success",
    "conversation_id": "c11ba72c-ff18-4213-9686-1952bb547c19",
    "system_message_id": "42a37690-1804-442b-8368-3d34570dd2cd",
    "message_scope": "all_resources",
    "user_message_id": "5ec45e03-bf22-40c7-b32a-d69eb015f86b",
    "user_message": "What is in this document?",
    "agent_id": "SYSTEM",
    "flow_id": "-",
    "system_text_message": "Here is a summary of the attached document.",
    "user_selected_resources": [{"resourceId": "ALL", "resourceType": "space"}],
    "action_connectors": [{"actionConnectorId": "quicksuite-documentation"}, {"actionConnectorId": "quicksuite-websearch"}],
    "cited_resource": [{"citedResourceType": "document", "citedResourceId": null, "citedResourceName": "example-document.html"}],
    "file_attachment": [{"fileAttachmentType": "html", "fileAttachmentName": "example-document.html"}],
    "resource_arn": "arn:aws:quicksight:us-east-1:111122223333:account/111122223333",
    "event_timestamp": 1787185484508,
    "logType": "CHAT_LOGS",
    "accountId": "111122223333"
}

Registros de comentarios

Los registros de comentarios recopilan los comentarios de los usuarios sobre las respuestas del chat:

  • user_arn— El ARN del usuario de Amazon Quick asociado al evento

  • user_type— El tipo de usuario de Amazon Quick asociado al evento (por ejemplo,ADMIN_PRO)

  • status_code— Estado de la entrega del evento

  • conversation_id— ID único de la conversación

  • system_message_id— ID de mensaje generado por el sistema

  • user_message_id— ID único del mensaje de usuario

  • feedback_type— Tipo de comentario (por ejemplo,Not Useful,Useful)

  • feedback_reason— Motivo del comentario seleccionado por el usuario

  • feedback_details— (Opcional) Detalles adicionales proporcionados por el usuario

  • resource_arn— El ARN del recurso de su cuenta de Amazon Quick

  • event_timestamp— Marca de tiempo del evento

  • logType – FEEDBACK_LOGS

  • accountId— ID de cuenta AWS

El siguiente es un ejemplo de registros de comentarios:

{
    "user_arn": "arn:aws:quicksight:us-east-1:111122223333:user/default/johndoe",
    "user_type": "ADMIN_PRO",
    "status_code": "success",
    "conversation_id": "c11ba72c-ff18-4213-9686-1952bb547c19",
    "system_message_id": "42a37690-1804-442b-8368-3d34570dd2cd",
    "user_message_id": "5ec45e03-bf22-40c7-b32a-d69eb015f86b",
    "feedback_type": "Not Useful",
    "feedback_reason": "Too wordy",
    "feedback_details": "The answer included too much background information.",
    "resource_arn": "arn:aws:quicksight:us-east-1:111122223333:account/111122223333",
    "event_timestamp": 1787185500123,
    "logType": "FEEDBACK_LOGS",
    "accountId": "111122223333"
}

Registros de horas de los agentes

Este tipo de registro captura los registros de uso de los diferentes agentes de tu cuenta Quick que se utilizan para fijar los precios:

  • user_arn— El ARN del usuario de Amazon Quick asociado al evento

  • subscription_type— Nivel de suscripción del usuario. Valores:ENTERPRISE,PROFESSIONAL.

  • reporting_service— La superficie Quick que consumía horas de agente. Los valores actuales incluyen FLOWAUTOMATION, yRESEARCH. Es posible que aparezcan nuevos valores a medida que las funciones rápidas adicionales comiencen a medir las horas de los agentes.

  • usage_group— Si el uso está cubierto por el derecho a la suscripción o se factura como excedente. Valores:

    • Included— Uso dentro de los límites de la asignación diaria para el nivel de suscripción. Sin cargos incrementales.

    • Extra— Excedente más allá de la subvención diaria. Se factura en función del consumo.

  • usage_hours— Valor decimal que indica las horas consumidas por el agente para este registro

  • service_resource_arn— ARN del recurso que consumió las horas (por ejemplo, una sesión de flujo, automatización o investigación)

  • resource_arn— El ARN del recurso de su cuenta de Amazon Quick

  • event_timestamp— Marca de tiempo del evento

  • logType – AGENT_HOURS_LOGS

  • accountId— ID de cuenta AWS

El siguiente es un ejemplo de los registros de Agent Hours:

{
    "user_arn": "arn:aws:quicksight:us-east-1:111122223333:user/default/johndoe",
    "subscription_type": "ENTERPRISE",
    "reporting_service": "RESEARCH",
    "usage_group": "Included",
    "usage_hours": 0.0928,
    "service_resource_arn": "arn:aws:quicksight::111122223333:research/a11b2bbc-c123-3abc-a12b-12a34b5c678d",
    "resource_arn": "arn:aws:quicksight:us-east-1:111122223333:account/111122223333",
    "event_timestamp": 1787183715000,
    "logType": "AGENT_HOURS_LOGS",
    "accountId": "111122223333"
}

Registros de metadatos del agente

Los registros de metadatos de los agentes capturan los eventos del ciclo de vida de los agentes de chat, como la creación, las actualizaciones, los cambios de permisos y la eliminación. Se emite un registro por cada operación del agente:

  • user_arn— El ARN del usuario de Amazon Quick asociado al evento.

  • event_name— La operación del ciclo de vida del agente. Los valores incluyen CreateAgentUpdateAgent, DeleteAgentUpdateAgentPermissions, y otros a medida que se agregan nuevas operaciones.

  • event_version— Versión esquemática del registro.

  • agent_id— UUID del agente.

  • agent_arn— ARN completo del agente.

  • agent_name— Mostrar el nombre del agente.

  • agent_status— Estado actual del agente (por ejemplo,ACTIVE).

  • request_id— Identificar la solicitud para la operación.

  • description— Texto de descripción del agente.

  • spaces— Matriz JSON de espacios adjuntos al agente.

  • permissions_granted— Permisos añadidos en esta operación.

  • permissions_revoked— Se eliminaron los permisos en esta operación.

  • permissions_state— Permisos actuales tras la operación.

  • update_action— La acción de actualización realizada.

  • version— Número de versión del agente.

  • icon_id— Identificador de icono del agente.

  • magic_builder_query— La consulta en lenguaje natural utilizada para crear el agente a través del generador.

  • instructions— Instrucciones para el agente.

  • failed_to_add_spaces— Espacios que no se pudieron adjuntar.

  • failed_to_remove_spaces— Espacios que no se pudieron separar.

  • draft_discarded— Si se descartó un borrador.

  • custom_prompt_input— Entrada de mensaje personalizada configurada para el agente.

  • welcome_message— Se muestra un mensaje de bienvenida a los usuarios del agente.

  • starter_prompts— Se sugieren mensajes de inicio a los usuarios del agente.

  • resource_arn— El ARN del recurso de su cuenta de Amazon Quick.

  • event_timestamp— Marca de tiempo del evento.

  • log_type – AGENT_METADATA_LOGS.

  • account_id— ID de AWS cuenta.

nota

Los starter_prompts campos custom_prompt_inputwelcome_message, y contienen contenido confidencial. Al configurar una AWS KMS clave gestionada por el cliente para la entrega, estos campos se cifran. Sin una clave, se entregan en texto sin cifrar.

El siguiente es un ejemplo de un registro de metadatos de un agente para un CreateAgent evento:

{
    "user_arn": "arn:aws:quicksight:us-east-1:111122223333:user/default/johndoe",
    "event_version": "1.0",
    "event_name": "CreateAgent",
    "agent_id": "12345678-90ab-cdef-1234-567890abcdef",
    "request_id": "fedcba98-7654-3210-fedc-ba9876543210",
    "agent_arn": "arn:aws:quicksight:us-east-1:111122223333:agent/12345678-90ab-cdef-1234-567890abcdef",
    "agent_name": "Project Status Assistant",
    "agent_status": "ACTIVE",
    "description": "An agent that helps track project status and find relevant documentation.",
    "spaces": "[{\"Arn\": \"arn:aws:quicksight:us-east-1:111122223333:space/11112222-3333-4444-5555-666677778888\"}]",
    "resource_arn": "arn:aws:quicksight:us-east-1:111122223333:account/111122223333",
    "event_timestamp": 1787185396000,
    "log_type": "AGENT_METADATA_LOGS",
    "account_id": "111122223333"
}

Registros de uso del índice

Los registros de uso del índice recopilan las métricas de almacenamiento por fuente para las bases de conocimiento y los espacios. Los eventos se publican cada vez que se produce un cambio (se crean, actualizan, sincronizan o eliminan):

  • user_arn— El ARN del usuario de Amazon Quick asociado al evento

  • consumed_index_size— Tamaño total (en bytes) consumido por todo el índice

  • source_type— Tipo de fuente: SPACE o KB

  • source_name— Mostrar el nombre del espacio o base de conocimientos

  • source_arn— ARN completo de la fuente

  • consumed_source_size— Tamaño (en bytes) consumido por esta fuente individual

  • consumed_source_doc_count— Número de documentos de esta fuente

  • resource_arn— El ARN del recurso de su cuenta de Amazon Quick

  • event_timestamp— Marca de tiempo del evento

  • log_type – INDEX_USAGE_LOGS

  • account_id— ID de cuenta AWS

El siguiente es un ejemplo de registros de uso de índices:

{
    "account_id": "111122223333",
    "event_timestamp": 1774911984257,
    "log_type": "INDEX_USAGE_LOGS",
    "user_arn": "arn:aws:quicksight::111122223333:user/default/user",
    "resource_arn": "arn:aws:quicksight:us-west-2:111122223333:account/111122223333",
    "consumed_index_size": 500000,
    "source_type": "SPACE",
    "source_name": "my-space",
    "source_arn": "arn:aws:quicksight:us-west-2:111122223333:space/2744af89-31b2-423b-93a2-69b0cd0d7fa1",
    "consumed_source_size": 244436,
    "consumed_source_doc_count": 2
}
nota

Los eventos se publican por fuente al modificarse. No todas las fuentes emiten eventos todos los días. Para reconstruir el estado actual, utilice el evento más reciente por. source_arn

Para obtener información sobre la creación de paneles y la ejecución de consultas en los registros de uso de índices, consulte. Supervise el uso del almacenamiento de índices

Base de conocimiento: registros de sincronización de archivos

Los registros de sincronización de archivos de la base de conocimiento capturan los eventos de estado de sincronización por documento. Se emite un registro por documento por cada ejecución de sincronización:

  • document_id— Identificador del documento original, como una URL o una ruta de archivo.

  • document_title— Título del documento.

  • document_status— Estado del documento terminal. Valores:ADDED,MODIFIED,UNMODIFIED,DELETED,SKIPPED,FAILED.

  • sync_result— resultado de High-level disponibilidad. Valores: AVAILABLE oUNAVAILABLE.

  • sync_id— Sincronizar el ID de ejecución del trabajo.

  • data_source_id— Identificador de la fuente de datos a la que está conectada la base de conocimientos.

  • source_uri— URL de origen del documento.

  • error_message— Descripción del error cuando el estado es FAILED oSKIPPED.

  • error_mitigation— Guía práctica para resolver el error.

  • error_type— Código de error cuando el estado es FAILED oSKIPPED.

  • knowledge_base_id— UUID de la base de conocimientos que generó el registro.

En la siguiente tabla se describen los document_status valores y sus correspondientes sync_result valores.

document_status sync_result Significado
ADDED AVAILABLE El nuevo documento se indexó correctamente
MODIFIED AVAILABLE El documento existente se ha vuelto a indexar con cambios
UNMODIFIED AVAILABLE El contenido del documento no ha cambiado, no es necesario volver a indexarlo
DELETED UNAVAILABLE Se ha eliminado el documento del índice
SKIPPED UNAVAILABLE Documento filtrado durante el rastreo, por ejemplo, por robots.txt o por límite de tamaño
FAILED UNAVAILABLE El documento falló durante el rastreo o la indexación

El siguiente ejemplo muestra un registro de sincronización correcta de archivos de una base de conocimientos en el que se agregó un documento a la base de conocimientos:

{
    "resource_arn": "arn:aws:quicksight:us-west-2:111122223333:account/111122223333",
    "event_timestamp": 1781296858575,
    "log_type": "KB_FILE_SYNC_LOGS",
    "account_id": "111122223333",
    "document_id": "https://docs.aws.amazon.com/quick/latest/userguide/monitoring-cloudwatch-logs.html",
    "document_title": "Monitoring Amazon QuickSight usage using CloudWatch Logs",
    "document_status": "ADDED",
    "sync_result": "AVAILABLE",
    "sync_id": "86a70a9a-cad9-4fc6-8881-e3909c8954d2",
    "data_source_id": "56225744-18bc-4373-a91f-861dd1c3d566",
    "source_uri": "https://docs.aws.amazon.com/quick/latest/userguide/monitoring-cloudwatch-logs.html",
    "knowledge_base_id": "b0bd0a47-8095-439d-9dff-c64bd5fe3fa3"
}

El siguiente ejemplo muestra un registro de documentos omitido en el que se omitió el rastreo debido a un error de validación:

{
    "resource_arn": "arn:aws:quicksight:us-west-2:111122223333:account/111122223333",
    "event_timestamp": 1781296492951,
    "log_type": "KB_FILE_SYNC_LOGS",
    "account_id": "111122223333",
    "document_id": "https://docs.aws.amazon.com/quick/latest/userguide/blocked-page.html",
    "document_title": "Blocked Page",
    "document_status": "SKIPPED",
    "sync_result": "UNAVAILABLE",
    "sync_id": "86a70a9a-cad9-4fc6-8881-e3909c8954d2",
    "data_source_id": "56225744-18bc-4373-a91f-861dd1c3d566",
    "source_uri": "https://docs.aws.amazon.com/quick/latest/userguide/blocked-page.html",
    "error_message": "This URL wasn't crawled because crawling isn't allowed by its robots.txt file.",
    "error_mitigation": "Contact the website administrator for assistance.",
    "error_type": "VALIDATION_ERROR",
    "knowledge_base_id": "b0bd0a47-8095-439d-9dff-c64bd5fe3fa3"
}

Consideraciones de seguridad

  • Cifrado: utilice claves administradas por el cliente para los AWS KMS datos confidenciales.

  • Control de acceso: implemente políticas de IAM con privilegios mínimos.

  • Retención de datos: configure las políticas de retención adecuadas para sus requisitos de cumplimiento.