Destinos de registro compatíveis Pré-requisitos Configurar o registro em log da Esquema e formato do log Registros de horas do agente Registros de metadados do agente Registros de uso do índice Registros de sincronização de arquivos da base de conhecimento Considerações sobre segurança

Monitorando o Amazon Quick usando CloudWatch registros

Você pode usar o Amazon CloudWatch Logs para fornecer conversas de bate-papo, feedback de usuários, uso de horas de agentes e uso de armazenamento de índices no Amazon Quick para você analisar. Esses registros podem ser entregues em vários destinos CloudWatch, como Amazon S3 ou Amazon Data Firehose (taxas padrão se aplicam).

Importante

Configure a entrega automática de registros logo após ativar os recursos do Amazon Quick AI. Os registros não são retroativos — você só recebe eventos que ocorrem após a configuração da entrega.

Veja a seguir exemplos de tarefas que você pode concluir com os registros do Amazon Quick:

Identificar dúvidas e pontos problemáticos comuns dos usuários revisando o conteúdo da mensagem de chat.
Monitorar a qualidade das respostas analisando métricas como feedbackReason.
Entender o sentimento e a satisfação do usuário analisando os dados de feedback, incluindo comentários e classificações de utilidade.
Gerar painéis e relatórios personalizados para acompanhar as principais métricas e tendências ao longo do tempo.
Identifique e analise casos em que o bate-papo não retornou nenhuma resposta ou a consulta do usuário foi bloqueada.
Monitore o uso das horas do agente.
Acompanhe o uso do armazenamento de índices em bases de conhecimento e Spaces.
Acompanhe as operações de sincronização da base de conhecimento e identifique falhas no rastreamento ou na indexação de documentos.

Importante

Os logs das conversas podem incluir dados confidenciais ou de identificação pessoal transmitidos nos chats. Você pode filtrar essas informações dos seus registros ao configurar a assinatura de registros. Ou você pode mascarar esses dados em seus registros usando políticas de mascaramento de CloudWatch registros. Para obter mais informações, consulte Ajude a proteger dados de logs confidenciais com mascaramento.

Destinos de registro compatíveis

O Amazon Quick pode entregar registros nos seguintes destinos:

Amazon CloudWatch Logs — Para monitoramento e análise em tempo real
Amazon S3 — Para armazenamento de longo prazo e processamento em lote
Amazon Data Firehose — Para análise de streaming e transformação de dados

Pré-requisitos

Antes de ativar o registro, verifique se você tem o seguinte:

Uma instância ativa do Amazon Quick com assinaturas Enterprise ou Professional
Permissões de IAM apropriadas para configurar a entrega de registros
Um destino configurado para seus registros (CloudWatch Logs, bucket do Amazon S3 ou Firehose)

Configurar o registro em log da

Para habilitar o registro para bate-papo e feedback do Amazon Quick, configure as permissões do IAM, crie uma origem e um destino de entrega e verifique a entrega do log.

Configurar permissões do IAM.

Para configurar o CloudWatch Logs para o Amazon Quick, use os seguintes exemplos de políticas do IAM para conceder as permissões necessárias.


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

Você também deve permitir o responsável pelo delivery.logs.amazonaws.com serviço em sua política de AWS KMS chaves gerenciadas pelo 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:*"
        }
    }
}

Configurar assinatura de registro

Por exemplo, políticas do IAM com todas as permissões necessárias para seu destino de registro específico, consulte Habilitar o registro de AWS serviços no Guia do usuário do Amazon CloudWatch Logs.

Crie uma fonte de entrega com a operação da API PutDeliverySource CloudWatch Logs. Dê um nome à fonte de entrega e, para resourceArn, especifique o ARN da sua aplicação. ParalogType, especifique CHAT_LOGSAGENT_HOURS_LOGS,AGENT_METADATA_LOGS,FEEDBACK_LOGS,INDEX_USAGE_LOGS, ouKB_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 ativar o registro de conversas do usuário com as operações da API CloudWatch Logs PutDeliverySourcePutDeliveryDestination, você chama as operações CreateDelivery da API, e.

nota

Vended-log a entrega é por região. Cada entrega captura somente a atividade que ocorre na região especificada pelo resourceArn inPutDeliverySource. Para receber registros de várias regiões, configure uma entrega separada em cada região.

Verificar a entrega do registro

Depois de configurar a entrega de registros, verifique se os registros estão sendo entregues ao seu destino:

Verifique a configuração: verifique a lista de entregas que foram criadas na conta usando a DescribeDeliveries API no CloudWatch Logs.
CloudWatch Registros: verifique se há novos fluxos de registros no grupo de registros especificado.
Amazon S3: monitore seu bucket em busca de novos arquivos de log.
Firehose: verifique se os dados estão fluindo pelo seu fluxo de entrega.

Esquema e formato do log

Os registros do Amazon Quick seguem um esquema estruturado com campos comuns compartilhados em todos os tipos de registros e campos específicos para registros de bate-papo e feedback.

Campos comuns

Todos os eventos de registro incluem esses campos comuns:

resource_arn— ARN do recurso da sua conta Amazon Quick (por exemplo,arn:aws:quicksight:us-east-1:111122223333:account/111122223333:)
event_timestamp— Tempo de época do Unix em milissegundos (por exemplo,) 1763532110061
logType— Tipo de registro (por exemplo, CHAT_LOGS ouFEEDBACK_LOGS)
accountId— ID AWS da conta (por exemplo,123456789012)
user_arn— ARN de usuário do Amazon Quick associado ao evento (por exemplo,"arn:aws:quicksight:us-west-2:111122223333:user/default/user")

Registros de bate-papo

Os registros de bate-papo capturam as interações da conversa:

nota

As conversas temporárias excluídas do histórico e da memória ainda são enviadas aos registros de bate-papo. Cada registro inclui o user_arn e user_type do usuário que iniciou a conversa.

user_arn— ARN de usuário do Amazon Quick associado ao evento
user_type— Tipo de usuário do Amazon Quick associado ao evento (por exemplo,ADMIN_PRO)
status_code— Status da solicitação de bate-papo (por exemplo,success,request_blocked,no_answer_found)
conversation_id— ID exclusivo para a conversa do usuário
system_message_id— ID da System-generated mensagem
message_scope— Escopo da mensagem (por exemplo,all_resources,specific_resources,no_resources)
user_message_id— ID exclusivo da mensagem do usuário
user_message— Mensagem do usuário na conversa
agent_id— ID exclusiva do agente de chat ou SYSTEM do agente padrão
flow_id— ID exclusivo do Amazon Quick Flow ou, - se não, uma invocação de fluxo
system_text_message— Resposta do sistema na conversa
user_selected_resources— Lista de recursos selecionados pelo usuário
action_connectors— Lista de conectores de ação disponíveis na conversa
cited_resource— Lista de recursos citados
file_attachment— Lista de arquivos anexados pelo usuário
resource_arn— ARN de recursos da sua conta Amazon Quick
event_timestamp— Data e hora do evento
logType – CHAT_LOGS
accountId— ID AWS da conta

Veja a seguir um exemplo de registros de bate-papo:


{
    "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 feedback

Os registros de feedback capturam o feedback do usuário sobre as respostas do bate-papo:

user_arn— ARN de usuário do Amazon Quick associado ao evento
user_type— Tipo de usuário do Amazon Quick associado ao evento (por exemplo,ADMIN_PRO)
status_code— Status da entrega do evento
conversation_id— ID exclusivo da conversa
system_message_id— ID de mensagem gerada pelo sistema
user_message_id— ID exclusivo da mensagem do usuário
feedback_type— Tipo de feedback (por exemplo,Not Useful,Useful)
feedback_reason— Motivo do feedback selecionado pelo usuário
feedback_details— (Opcional) Detalhes adicionais fornecidos pelo usuário
resource_arn— ARN de recursos da sua conta Amazon Quick
event_timestamp— Data e hora do evento
logType – FEEDBACK_LOGS
accountId— ID AWS da conta

Veja a seguir um exemplo de registros de feedback:


{
    "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 do agente

Esse tipo de registro captura os registros de uso de diferentes agentes em sua conta rápida usada para definir preços:

user_arn— ARN de usuário do Amazon Quick associado ao evento
subscription_type— Nível de assinatura do usuário. Valores:ENTERPRISE,PROFESSIONAL.
reporting_service— A superfície Quick que consumiu horas do agente. Os valores atuais incluem FLOWAUTOMATION, RESEARCH e. Novos valores podem aparecer quando os recursos adicionais do Quick começarem a medir as horas do agente.
usage_group— Se o uso é coberto pelo direito à assinatura ou cobrado como excedente. Valores:
- Included— Uso dentro da concessão diária de direitos para o nível de assinatura. Sem cobrança incremental.
- Extra— Excesso além do subsídio diário. Faturado de acordo com o consumo.
usage_hours— Valor decimal indicando as horas do agente consumidas para esse registro
service_resource_arn— ARN do recurso que consumiu as horas (por exemplo, uma sessão de fluxo, automação ou pesquisa)
resource_arn— ARN de recursos da sua conta Amazon Quick
event_timestamp— Data e hora do evento
logType – AGENT_HOURS_LOGS
accountId— ID AWS da conta

Veja a seguir um exemplo de registros de horas do agente:


{
    "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 metadados do agente

Os registros de metadados do agente capturam eventos do ciclo de vida dos agentes de chat, incluindo criação, atualizações, alterações de permissão e exclusão. Um registro é emitido por operação do agente:

user_arn— ARN de usuário do Amazon Quick associado ao evento.
event_name— A operação do ciclo de vida do agente. Os valores incluemCreateAgent,UpdateAgent, DeleteAgentUpdateAgentPermissions, e outros à medida que novas operações são adicionadas.
event_version— Versão do esquema do registro de log.
agent_id— UUID do agente.
agent_arn— ARN completo do agente.
agent_name— Nome de exibição do agente.
agent_status— Status atual do agente (por exemplo,ACTIVE).
request_id— Identificador de solicitação para a operação.
description— Texto de descrição do agente.
spaces— Matriz JSON de espaços anexada ao agente.
permissions_granted— Permissões adicionadas nesta operação.
permissions_revoked— Permissões removidas nesta operação.
permissions_state— Permissões atuais após a operação.
update_action— A ação de atualização foi executada.
version— Número da versão do agente.
icon_id— Identificador de ícone para o agente.
magic_builder_query— A consulta de linguagem natural usada para criar o agente por meio do construtor.
instructions— Instruções do agente.
failed_to_add_spaces— Espaços que não puderam ser anexados.
failed_to_remove_spaces— Espaços que não puderam ser separados.
draft_discarded— Se um rascunho foi descartado.
custom_prompt_input— Entrada de aviso personalizada configurada para o agente.
welcome_message— Mensagem de boas-vindas mostrada aos usuários do agente.
starter_prompts— Solicitações iniciais sugeridas aos usuários do agente.
resource_arn— ARN do recurso da sua conta Amazon Quick.
event_timestamp— Data e hora do evento.
log_type – AGENT_METADATA_LOGS.
account_id— ID AWS da conta.

nota

Os starter_prompts campos custom_prompt_inputwelcome_message,, e contêm conteúdo confidencial. Quando você configura uma AWS KMS chave gerenciada pelo cliente para entrega, esses campos são criptografados. Sem uma chave, eles são entregues em texto não criptografado.

Veja a seguir um exemplo de um registro de metadados do agente para um 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 do índice

Os registros de uso do índice capturam métricas de armazenamento por fonte para bases de conhecimento e espaços. Os eventos são publicados sempre que ocorre uma alteração (criada, atualizada, sincronizada ou excluída):

user_arn— ARN de usuário do Amazon Quick associado ao evento
consumed_index_size— Tamanho total (em bytes) consumido por todo o índice
source_type— Tipo de fonte: SPACE ou KB
source_name— Nome de exibição do Espaço ou da base de conhecimento
source_arn— ARN completo da fonte
consumed_source_size— Tamanho (em bytes) consumido por essa fonte individual
consumed_source_doc_count— Número de documentos nesta fonte
resource_arn— ARN de recursos da sua conta Amazon Quick
event_timestamp— Data e hora do evento
log_type – INDEX_USAGE_LOGS
account_id— ID AWS da conta

Veja a seguir um exemplo de registros de uso do índice:


{
    "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

Os eventos são publicados por fonte após a alteração. Nem todas as fontes emitem eventos todos os dias. Para reconstruir o estado atual, use o evento mais recente por. source_arn

Para obter informações sobre a criação de painéis e a execução de consultas nos registros de uso do índice, consulte. Monitore o uso do armazenamento de índices

Registros de sincronização de arquivos da base de conhecimento

Os registros de sincronização de arquivos da base de conhecimento capturam eventos de status de sincronização por documento. Um registro de log é emitido por documento por execução de sincronização:

document_id— Identificador do documento original, como URL ou caminho de arquivo.
document_title— Título do documento.
document_status— Status do documento do terminal. Valores:ADDED,MODIFIED,UNMODIFIED,DELETED,SKIPPED,FAILED.
sync_result— resultado de High-level disponibilidade. Valores: AVAILABLE ouUNAVAILABLE.
sync_id— Sincronize o ID de execução do trabalho.
data_source_id— Identificador da fonte de dados à qual a base de conhecimento está conectada.
source_uri— URL de origem do documento.
error_message— Descrição do erro quando o status é FAILED ouSKIPPED.
error_mitigation— Orientação acionável para resolver o erro.
error_type— Código de erro quando o status é FAILED ouSKIPPED.
knowledge_base_id— UUID da base de conhecimento que produziu o log.

A tabela a seguir descreve os document_status valores e seus correspondentessync_result.

status_do_documento	resultado_de_sincronização	Significado
`ADDED`	`AVAILABLE`	Novo documento indexado com sucesso
`MODIFIED`	`AVAILABLE`	Documento existente reindexado com alterações
`UNMODIFIED`	`AVAILABLE`	Conteúdo do documento inalterado, sem necessidade de reindexação
`DELETED`	`UNAVAILABLE`	Documento removido do índice
`SKIPPED`	`UNAVAILABLE`	Documento filtrado durante o rastreamento, como por robots.txt ou limite de tamanho
`FAILED`	`UNAVAILABLE`	O documento falhou durante o rastreamento ou a indexação

O exemplo a seguir mostra um registro bem-sucedido de sincronização de arquivos da base de conhecimento em que um documento foi adicionado à base de conhecimento:


{
    "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"
}

O exemplo a seguir mostra um registro de documento ignorado em que o rastreamento foi ignorado devido a um erro de validação:


{
    "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"
}

Considerações sobre segurança

Criptografia — Use AWS KMS chaves gerenciadas pelo cliente para dados confidenciais.
Controle de acesso — implemente políticas de IAM com menos privilégios.
Retenção de dados — configure políticas de retenção apropriadas para seus requisitos de conformidade.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Resposta a incidentes, registro e monitoramento no Amazon Quick

Monitoramento usando CloudTrail