Surveillance d'Amazon Quick à l'aide CloudWatch des journaux

Vous pouvez utiliser Amazon CloudWatch Logs pour diffuser les conversations par chat, les commentaires des utilisateurs, l'utilisation des heures d'ouverture des agents et l'utilisation du stockage d'index dans Amazon Quick à des fins d'analyse. Ces journaux peuvent être envoyés vers plusieurs destinations CloudWatch, telles qu'Amazon S3 ou Amazon Data Firehose (les tarifs standard s'appliquent).

Important

Configurez la livraison automatique de journaux peu de temps après avoir activé les fonctionnalités Amazon Quick AI. Les journaux ne sont pas rétroactifs : vous ne recevez que les événements qui se produisent une fois la livraison configurée.

Voici des exemples de tâches que vous pouvez effectuer à l'aide des journaux d'Amazon Quick :

• Identifiez les requêtes et les problèmes courants des utilisateurs en examinant le contenu des messages de chat.

• Surveillez la qualité des réponses en examinant des métriques comme feedbackReason.

• Déterminez le sentiment et la satisfaction des utilisateurs en analysant les données de feedback, y compris les commentaires et les notes données au contenu.

• Générez des tableaux de bord et des rapports personnalisés pour suivre les métriques clés et les tendances au fil du temps.

• Identifiez et analysez les cas où le chat n'a renvoyé aucune réponse ou où la requête de l'utilisateur a été bloquée.

• Surveillez l'utilisation des heures d'ouverture des agents.

• Suivez l'utilisation du stockage des index dans les bases de connaissances et Spaces.

• Suivez les opérations de synchronisation de la base de connaissances et identifiez les échecs d'exploration ou d'indexation des documents.

Important

Les journaux issus des conversations peuvent inclure des données sensibles ou personnellement identifiables transmises lors des chats. Vous pouvez filtrer ces informations de vos journaux lors de la configuration de l'abonnement aux journaux. Vous pouvez également masquer ces données dans vos journaux à l'aide des politiques de masquage CloudWatch des journaux. Pour plus d’informations, consultez Aider à protéger les données sensibles des journaux grâce au masquage.

Destinations de journaux prises en charge

Amazon Quick peut envoyer des journaux vers les destinations suivantes :

• Amazon CloudWatch Logs — Pour une surveillance et une analyse en temps réel

• Amazon S3 — Pour le stockage à long terme et le traitement par lots

• Amazon Data Firehose  : pour le streaming, l'analyse et la transformation des données

Conditions préalables

Avant de pouvoir activer la journalisation, assurez-vous que vous disposez des éléments suivants :

• Une instance Amazon Quick active avec des abonnements Enterprise ou Professional

• Autorisations IAM appropriées pour configurer la livraison des journaux

• Une destination configurée pour vos CloudWatch journaux (Logs, compartiment Amazon S3 ou Firehose)

Configurer la journalisation

Pour activer la journalisation pour Amazon Quick Chat et les commentaires, configurez les autorisations IAM, créez une source et une destination de diffusion et vérifiez la livraison du journal.

Définir des autorisations IAM

Pour configurer CloudWatch Logs for Amazon Quick, utilisez les exemples de politiques IAM suivants afin d'accorder les autorisations nécessaires.

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

Vous devez également autoriser le responsable du delivery.logs.amazonaws.com service dans votre politique relative aux AWS KMS clés gérées par le client.

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

Configurer l'abonnement aux journaux

Par exemple, des politiques IAM avec toutes les autorisations requises pour votre destination de journalisation spécifique, consultez la section Activer la journalisation à partir AWS des services dans le guide de l'utilisateur Amazon CloudWatch Logs.

Créez une source de diffusion à l'aide de l'opération d'API PutDeliverySource CloudWatch Logs. Donnez un nom à la source de livraison et pour resourceArn, spécifiez l’ARN de votre application. PourlogType, spécifiez CHAT_LOGS AGENT_HOURS_LOGSAGENT_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"
}

Pour activer la journalisation des conversations des utilisateurs à l'aide des opérations de l'API CloudWatch LogsPutDeliverySource, vous devez appeler les opérations CreateDelivery d'APIPutDeliveryDestination, et.

Note

Vended-log la livraison se fait par région. Chaque livraison ne capture que l'activité qui se produit dans la région spécifiée par le resourceArn pointPutDeliverySource. Pour recevoir des journaux provenant de plusieurs régions, configurez une diffusion distincte dans chaque région.

Vérifier la livraison du journal

Après avoir configuré la livraison des journaux, vérifiez que les journaux sont envoyés à votre destination :

• Vérifiez la configuration : vérifiez la liste des livraisons qui ont été créées dans le compte à l'aide de l'DescribeDeliveriesAPI dans CloudWatch Logs.

• CloudWatch Journaux  : vérifiez le groupe de journaux spécifié pour les nouveaux flux de journaux.

• Amazon S3  : surveillez la présence de nouveaux fichiers journaux dans votre compartiment.

• Firehose  : vérifiez que les données circulent dans votre flux de diffusion.

Schéma et format du journal

Les journaux Amazon Quick suivent un schéma structuré avec des champs communs partagés entre tous les types de journaux et des champs spécifiques pour les journaux de discussion et de commentaires.

Champs communs

Tous les événements du journal incluent les champs communs suivants :

• resource_arn— ARN de ressource de votre compte Amazon Quick (par exemple,arn:aws:quicksight:us-east-1:111122223333:account/111122223333:)

• event_timestamp— Durée de l'époque Unix en millisecondes (par exemple,) 1763532110061

• logType— Type de journal (par exemple, CHAT_LOGS ouFEEDBACK_LOGS)

• accountId— identifiant de AWS compte (par exemple,123456789012)

• user_arn— ARN utilisateur Amazon Quick associé à l'événement (par exemple,"arn:aws:quicksight:us-west-2:111122223333:user/default/user")

Journaux de discussion

Les journaux de discussion capturent les interactions entre les conversations :

Note

Les conversations temporaires qui sont exclues de l'historique et de la mémoire sont toujours enregistrées dans les journaux de discussion. Chaque enregistrement inclut le nom user_arn et user_type de l'utilisateur qui a initié la conversation.

• user_arn— ARN utilisateur Amazon Quick associé à l'événement

• user_type— Type d'utilisateur Amazon Quick associé à l'événement (par exemple,ADMIN_PRO)

• status_code— État de la demande de chat (par exemple,success,request_blocked,no_answer_found)

• conversation_id— Identifiant unique pour la conversation avec l'utilisateur

• system_message_id— identifiant System-generated du message

• message_scope— Portée du message (par exemple,all_resources,specific_resources,no_resources)

• user_message_id— Identifiant unique du message de l'utilisateur

• user_message— Message de l'utilisateur dans la conversation

• agent_id— Identifiant unique de l'agent de chat ou SYSTEM de l'agent par défaut

• flow_id— Identifiant unique de l'Amazon Quick Flow, ou - s'il ne s'agit pas d'une invocation de flux

• system_text_message— Réponse du système lors de la conversation

• user_selected_resources— Liste des ressources sélectionnées par l'utilisateur

• action_connectors— Liste des connecteurs d'action disponibles dans la conversation

• cited_resource— Liste des ressources citées

• file_attachment— Liste des fichiers joints par utilisateur

• resource_arn— L'ARN de ressource de votre compte Amazon Quick

• event_timestamp— Horodatage de l'événement

• logType – CHAT_LOGS

• accountId— identifiant AWS de compte

Voici un exemple de journal de discussion :

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

Journaux de commentaires

Les journaux de commentaires enregistrent les commentaires des utilisateurs sur les réponses au chat :

• user_arn— ARN utilisateur Amazon Quick associé à l'événement

• user_type— Type d'utilisateur Amazon Quick associé à l'événement (par exemple,ADMIN_PRO)

• status_code— État de la livraison de l'événement

• conversation_id— Identifiant unique de la conversation

• system_message_id— ID de message généré par le système

• user_message_id— Identifiant unique du message de l'utilisateur

• feedback_type— Type de feedback (par exemple,Not Useful,Useful)

• feedback_reason— Motif du feedback sélectionné par l'utilisateur

• feedback_details— (Facultatif) Informations supplémentaires fournies par l'utilisateur

• resource_arn— L'ARN de ressource de votre compte Amazon Quick

• event_timestamp— Horodatage de l'événement

• logType – FEEDBACK_LOGS

• accountId— identifiant AWS de compte

Voici un exemple de journal des commentaires :

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

Journaux d'heures des agents

Ce type de journal capture les journaux d'utilisation des différents agents de votre compte Quick utilisé pour la tarification :

• user_arn— ARN utilisateur Amazon Quick associé à l'événement

• subscription_type— Niveau d'abonnement de l'utilisateur. Valeurs :ENTERPRISE,PROFESSIONAL.

• reporting_service— La surface Quick qui a consommé des heures d'agent. Les valeurs actuelles incluent FLOWAUTOMATION, etRESEARCH. De nouvelles valeurs peuvent apparaître à mesure que des fonctionnalités rapides supplémentaires commencent à mesurer les heures d'ouverture des agents.

• usage_group— Si l'utilisation est couverte par le droit à l'abonnement ou facturée comme excédent. Valeurs :

  • Included— Utilisation dans le cadre de l'allocation journalière accordée pour le niveau d'abonnement. Aucuns frais supplémentaires.

  • Extra— Excédent au-delà de la subvention journalière. Facturé en fonction de la consommation.

• usage_hours— Valeur décimale indiquant les heures passées par l'agent pour cet enregistrement

• service_resource_arn— ARN de la ressource qui a consommé les heures (par exemple, une session de flux, d'automatisation ou de recherche)

• resource_arn— L'ARN de ressource de votre compte Amazon Quick

• event_timestamp— Horodatage de l'événement

• logType – AGENT_HOURS_LOGS

• accountId— identifiant AWS de compte

Voici un exemple de journal des heures d'activité des agents :

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

Journaux de métadonnées des agents

Les journaux de métadonnées des agents capturent les événements du cycle de vie des agents de chat, notamment la création, les mises à jour, les modifications d'autorisation et la suppression. Un enregistrement est émis par opération de l'agent :

• user_arn— ARN utilisateur Amazon Quick associé à l'événement.

• event_name— L'opération du cycle de vie de l'agent. Les valeurs incluentCreateAgent,UpdateAgent, DeleteAgentUpdateAgentPermissions, et d'autres lorsque de nouvelles opérations sont ajoutées.

• event_version— Version du schéma de l'enregistrement du journal.

• agent_id— UUID de l'agent.

• agent_arn— ARN complet de l'agent.

• agent_name— Afficher le nom de l'agent.

• agent_status— État actuel de l'agent (par exemple,ACTIVE).

• request_id— Identifiant de la demande pour l'opération.

• description— Texte de description de l'agent.

• spaces— Tableau JSON d'espaces attachés à l'agent.

• permissions_granted— Autorisations ajoutées lors de cette opération.

• permissions_revoked— Autorisations supprimées lors de cette opération.

• permissions_state— Autorisations actuelles après l'opération.

• update_action— L'action de mise à jour effectuée.

• version— Numéro de version de l'agent.

• icon_id— Identifiant de l'icône de l'agent.

• magic_builder_query— La requête en langage naturel utilisée pour créer l'agent via le générateur.

• instructions— Instructions pour les agents.

• failed_to_add_spaces— Espaces qui n'ont pas pu être attachés.

• failed_to_remove_spaces— Espaces qui ne pouvaient pas être détachés.

• draft_discarded— Si un brouillon a été rejeté.

• custom_prompt_input— Saisie rapide personnalisée configurée pour l'agent.

• welcome_message— Message de bienvenue affiché aux utilisateurs de l'agent.

• starter_prompts— Des instructions de démarrage sont proposées aux utilisateurs de l'agent.

• resource_arn— L'ARN de ressource de votre compte Amazon Quick.

• event_timestamp— Horodatage de l'événement.

• log_type – AGENT_METADATA_LOGS.

• account_id— identifiant de AWS compte.

Note

Les starter_prompts champs custom_prompt_inputwelcome_message, et contiennent du contenu sensible. Lorsque vous configurez une AWS KMS clé gérée par le client pour la livraison, ces champs sont chiffrés. Sans clé, ils sont fournis en texte clair.

Voici un exemple de journal de métadonnées d'agent pour un CreateAgent événement :

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

Journaux d'utilisation de l'index

Les journaux d'utilisation des index capturent les mesures de stockage par source pour les bases de connaissances et les espaces. Les événements sont publiés chaque fois qu'un changement se produit (créé, mis à jour, synchronisé ou supprimé) :

• user_arn— ARN utilisateur Amazon Quick associé à l'événement

• consumed_index_size— Taille totale (en octets) consommée par l'ensemble de l'index

• source_type— Type de source : SPACE ou KB

• source_name— Afficher le nom de l'espace ou de la base de connaissances

• source_arn— ARN complet de la source

• consumed_source_size— Taille (en octets) consommée par cette source individuelle

• consumed_source_doc_count— Nombre de documents contenus dans cette source

• resource_arn— L'ARN de ressource de votre compte Amazon Quick

• event_timestamp— Horodatage de l'événement

• log_type – INDEX_USAGE_LOGS

• account_id— identifiant AWS de compte

Voici un exemple de journal d'utilisation des index :

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

Note

Les événements sont publiés par source sur le changement. Toutes les sources n'émettent pas d'événements tous les jours. Pour reconstruire l'état actuel, utilisez l'événement le plus récent par. source_arn

Pour plus d'informations sur la création de tableaux de bord et l'exécution de requêtes sur les journaux d'utilisation des index, consultezSurveiller l'utilisation du stockage des index.

Journaux de synchronisation de fichiers de la base de connaissances

Les journaux de synchronisation de fichiers de la base de connaissances capturent les événements d'état de synchronisation par document. Un enregistrement de journal est émis par document par exécution de synchronisation :

• document_id— Identifiant du document d'origine, tel qu'une URL ou un chemin de fichier.

• document_title— Titre du document.

• document_status— État du document du terminal. Valeurs :ADDED, MODIFIEDUNMODIFIED,DELETED,SKIPPED,FAILED.

• sync_result— résultat de High-level disponibilité. Valeurs : AVAILABLE ouUNAVAILABLE.

• sync_id— ID d'exécution de la tâche de synchronisation.

• data_source_id— Identifiant de la source de données à laquelle la base de connaissances est connectée.

• source_uri— URL source du document.

• error_message— Description de l'erreur lorsque le statut est FAILED ouSKIPPED.

• error_mitigation— Des conseils pratiques pour résoudre l'erreur.

• error_type— Code d'erreur lorsque le statut est FAILED ouSKIPPED.

• knowledge_base_id— UUID de la base de connaissances qui a produit le journal.

Le tableau suivant décrit les document_status valeurs et leurs valeurs correspondantessync_result.

état_du document	résultat de synchronisation	Signification
ADDED	AVAILABLE	Nouveau document indexé avec succès
MODIFIED	AVAILABLE	Document existant réindexé avec modifications
UNMODIFIED	AVAILABLE	Contenu du document inchangé, aucune réindexation nécessaire
DELETED	UNAVAILABLE	Document supprimé de l'index
SKIPPED	UNAVAILABLE	Document filtré lors de l'analyse, par exemple par robots.txt ou par une limite de taille
FAILED	UNAVAILABLE	Le document a échoué lors de l'exploration ou de l'indexation

L'exemple suivant montre un journal de synchronisation de fichiers de base de connaissances réussi dans lequel un document a été ajouté à la base de connaissances :

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

L'exemple suivant montre un journal de documents ignoré dans lequel l'exploration a été ignorée en raison d'une erreur de validation :

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

Considérations sur la sécurité

• Chiffrement  : utilisez des AWS KMS clés gérées par le client pour les données sensibles.

• Contrôle d'accès  : implémentez des politiques IAM avec le moindre privilège.

• Conservation des données  : configurez des politiques de conservation adaptées à vos exigences de conformité.