Observabilité pour les bases de connaissances gérées

Pour une base de connaissances gérée, Amazon Bedrock publie des statistiques opérationnelles et des journaux d'ingestion sur votre AWS compte afin que vous puissiez surveiller l'état et l'utilisation de votre base de connaissances. Les métriques d'exécution vous permettent de suivre le volume de demandes, les erreurs et le ralentissement des opérations d'API de votre base de connaissances, tandis que les journaux d'ingestion vous permettent de suivre l'état de chaque document lors d'une tâche d'ingestion de données. Les sections suivantes décrivent les données d'observabilité disponibles et la manière d'y accéder.

Mesures d'exécution pour les bases de connaissances gérées

Amazon Bedrock publie des métriques d'exécution pour les opérations d'API de votre base de connaissances sur Amazon CloudWatch sous l'espace de AWS/Bedrock/KnowledgeBases noms. Utilisez ces mesures pour surveiller le volume d'appels, les taux d'erreur et la limitation pour des opérations telles que. Retrieve Les statistiques sont publiées sur votre compte sans frais supplémentaires et apparaissent dans la CloudWatch console.

Le tableau suivant décrit les métriques d'exécution publiées par Amazon Bedrock pour les bases de connaissances gérées.

Nom de la métrique	Unité	Description
Invocations	Nombre	Nombre de demandes adressées à l'opération de base de connaissances. Cette métrique est publiée pour chaque demande, y compris les demandes qui entraînent une erreur.
ClientErrors	Nombre	Nombre de requêtes ayant entraîné une erreur côté client (une 4xx réponse HTTP autre qu'une limitation).
ServerErrors	Nombre	Nombre de requêtes ayant entraîné une erreur côté serveur (5xxréponse HTTP).
Throttles	Nombre	Nombre de demandes limitées (une 429 réponse HTTP). Les demandes limitées ne sont pas comptabilisées comme ClientErrors ou. ServerErrors

Les Throttles métriques ClientErrorsServerErrors,, et ne sont publiées que lorsque la condition correspondante se produit. La Invocations métrique est publiée pour chaque demande.

Métrique supplémentaire pour l' AgenticRetrieveStream opération

Outre les mesures du tableau précédent, l'AgenticRetrieveStreamopération publie la métrique suivante.

Nom de la métrique	Unité	Description
TotalIterationCount	Nombre	Nombre total d'itérations de récupération agentique effectuées pendant la demande. Cette métrique est publiée uniquement pour l'AgenticRetrieveStreamopération, lorsque la demande est terminée avec succès.

Cette métrique utilise la Operation dimension avec une valeur deAgenticRetrieveStream.

Dimensions pour les métriques de la base de connaissances gérée

Amazon Bedrock utilise les dimensions suivantes pour les métriques d'exécution de la base de connaissances gérée.

Dimension	Description
Opération	Opération d'API de la base de connaissances pour laquelle la métrique est publiée. Les valeurs possibles sont Retrieve et AgenticRetrieveStream.
KnowledgeBaseId	La base de connaissances ciblée par la demande, au formatknowledge-base/knowledge-base-id. Cette dimension est incluse pour l'Retrieveopération, qui cible une base de connaissances unique. Les opérations qui ne ciblent pas une seule base de connaissances sont publiées uniquement avec la Operation dimension.

Autorisations pour publier des statistiques

Amazon Bedrock publie ces statistiques sur votre compte en utilisant les informations d'identification associées à la demande :

• Pour le Retrieve fonctionnement, Amazon Bedrock utilise le rôle de service de base de connaissances.

• Pour les autres opérations, Amazon Bedrock utilise les informations d'identification de l'identité appelante (l'utilisateur ou le rôle IAM qui appelle l'opération), via une session d'accès direct.

Pour que les métriques soient publiées, cette identité doit être autorisée à appeler cloudwatch:PutMetricData l'espace de AWS/Bedrock/KnowledgeBases noms. Associez une politique qui accorde cette autorisation au rôle de service de base de connaissances et à toute identité qui appelle les opérations de la base de connaissances. L'exemple suivant accorde l'autorisation requise.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "cloudwatch:PutMetricData",
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "cloudwatch:namespace": "AWS/Bedrock/KnowledgeBases"
                }
            }
        }
    ]
}

La publication métrique est la meilleure solution. Si l'identité ne dispose pas de l'autorisation requise, les métriques correspondantes ne sont pas publiées, mais la demande de base de connaissances elle-même n'est pas affectée.

Afficher les métriques d'exécution

Vous pouvez obtenir des métriques pour votre base de connaissances à l'aide de AWS Management Console, de AWS CLI, ou de l' CloudWatch API. Vous pouvez utiliser l' CloudWatch API via l'un des kits de développement AWS logiciel (SDK) ou les outils CloudWatch d'API.

Pour afficher les métriques de la base de connaissances gérées dans la CloudWatch console, accédez à la section des métriques du volet de navigation et sélectionnez l'option Toutes les métriques, puis recherchez l'espace de AWS/Bedrock/KnowledgeBases noms.

Vous devez disposer des CloudWatch autorisations appropriées pour surveiller votre base de connaissances CloudWatch. Pour plus d'informations, consultez Authentification et contrôle d'accès pour Amazon CloudWatch dans le guide de CloudWatch l'utilisateur Amazon.

Métriques de stockage pour les bases de connaissances gérées

Pour une base de connaissances gérée, Amazon Bedrock publie une métrique de stockage sur Amazon CloudWatch sous l'espace de AWS/Bedrock/KnowledgeBases noms. Cette métrique indique la taille brute totale des données sources stockées dans la base de connaissances et est publiée sur votre compte une fois la tâche d'ingestion de données terminée, afin que vous puissiez suivre la quantité de données stockée dans votre base de connaissances au fil du temps.

Le tableau suivant décrit la métrique de stockage publiée par Amazon Bedrock pour les bases de connaissances gérées.

Nom de la métrique	Unité	Description
RawDataSize	Gigaoctets	Taille brute totale des données sources stockées dans la base de connaissances, en gigaoctets. Cette métrique est publiée une fois la tâche d'ingestion de données terminée.

La métrique de stockage utilise la KnowledgeBaseId dimension, au formatknowledge-base/knowledge-base-id.

Observabilité de l'ingestion pour les bases de connaissances gérées

Amazon Bedrock émet des journaux qui suivent la progression d'une tâche d'ingestion de données pour votre base de connaissances gérée, y compris le statut général de la tâche et le statut de chaque document traité. Vous pouvez utiliser ces journaux pour confirmer quels documents ont été ingérés, déterminer pourquoi un document n'a pas été renvoyé dans les résultats de récupération et résoudre les problèmes d'ingestion.

Les journaux sont envoyés vers une destination que vous configurez (CloudWatch Logs, Amazon S3 ou Amazon Data Firehose). Les sections suivantes décrivent comment activer la livraison des journaux, le cycle de vie d'un document pendant l'ingestion, les types de journaux émis et des exemples de requêtes.

Activer la livraison du journal d'ingestion

Pour recevoir des journaux d'ingestion, configurez une livraison de journaux pour votre base de connaissances à l'aide de l'API AWS Management Console ou de l' CloudWatch API. Vous pouvez envoyer des CloudWatch journaux à Logs, Amazon S3 ou Amazon Data Firehose.

Activer la livraison des journaux à l'aide de la console

1. Ouvrez votre base de connaissances : dans la console Amazon Bedrock, ouvrez la base de connaissances gérée que vous souhaitez surveiller.

2. Ajouter une livraison de journal : modifiez la base de connaissances pour ajouter une livraison de journal et configurez les détails suivants :

   • La destination de journalisation (CloudWatch Logs, Amazon S3 ou Amazon Data Firehose).

   • (CloudWatch Logs) Le nom du groupe de journaux.

   • (Amazon S3) Le nom du compartiment.

   • (Amazon Data Firehose) Le stream Firehose.

3. Confirmer le statut de livraison : vérifiez que le statut de livraison du journal est Livraison active dans la console.

Activer la livraison des journaux à l'aide de l' CloudWatch API

1. Obtenez l'ARN de votre base de connaissances : appelez l'GetKnowledgeBaseAPI pour obtenir le nom de ressource Amazon (ARN) de la base de connaissances. L'ARN d'une base de connaissances a le format suivant :arn:aws:bedrock:your-region:your-account-id:knowledge-base/knowledge-base-id.

2. Appel PutDeliverySource : utilisez l'PutDeliverySourceAPI pour créer une source de diffusion pour la base de connaissances. Transmettez l'ARN de la base de connaissances en tant que resourceArn et APPLICATION_LOGS spécifiez-le en tant quelogType.

   {
       "logType": "APPLICATION_LOGS",
       "name": "my-knowledge-base-delivery-source",
       "resourceArn": "arn:aws:bedrock:your-region:your-account-id:knowledge-base/knowledge_base_id"
   }

3. Appel PutDeliveryDestination : utilisez l'PutDeliveryDestinationAPI pour configurer l'emplacement de stockage des journaux. Spécifiez l'ARN d'une CloudWatch destination Logs, Amazon S3 ou Amazon Data Firehose. Vous pouvez outputFormat définir sur jsonplain,w3c,raw, ouparquet.

   {
      "deliveryDestinationConfiguration": {
         "destinationResourceArn": "arn:aws:s3:::bucket-name"
      },
      "name": "my-knowledge-base-delivery-destination",
      "outputFormat": "json"
   }

   Si vous livrez des journaux à un autre compte, utilisez l'PutDeliveryDestinationPolicyAPI pour associer une politique Gestion des identités et des accès AWS (IAM) au compte de destination.

4. Appel CreateDelivery : utilisez l'CreateDeliveryAPI pour lier la source de livraison à la destination de livraison.

   {
      "deliveryDestinationArn": "string",
      "deliverySourceName": "my-knowledge-base-delivery-source"
   }

Types de journaux et autorisations pris en charge

Les bases de connaissances gérées prennent en charge les types de journaux suivants :

• APPLICATION_LOGS: journaux qui suivent l'état de la tâche d'ingestion et de chaque document traité pendant la tâche.

• TRACES: traces distribuées (spans) pour les opérations d'exécution. Les traces sont émises uniquement pour l'Retrieveopération et sont transmises à AWS X-Ray. Pour de plus amples informations, veuillez consulter Suivez l'observabilité pour les bases de connaissances gérées.

Pour activer la livraison des journaux, l'utilisateur ou le rôle doit disposer de l'bedrock:AllowVendedLogDeliveryForResourceautorisation d'accéder à la ressource de la base de connaissances, en plus des autorisations requises pour écrire vers la destination que vous avez choisie. Par exemple, les politiques IAM pour chaque destination, consultez la section Autorisations relatives aux journaux électroniques pour les différentes destinations de livraison dans le guide de l'utilisateur Amazon CloudWatch Logs.

Cycle de vie du document pendant l'ingestion

Au cours d'une tâche d'ingestion de données, chaque document passe par trois étapes, et le journal du document enregistre le statut de chaque étape :

• Crawl (crawl_status) : Amazon Bedrock extrait le document depuis la source de données et détermine s'il doit être ajouté, mis à jour ou supprimé. Le crawl_action champ est défini sur ADDDELETE, ouUNMODIFIED. Document ignoré au cours des étapes restantes. UNMODIFIED

• Sync (sync_status) : le document est soumis pour traitement dans la base de connaissances.

• Index (index_status) : le document est découpé, intégré et conservé dans la base de connaissances. Le chunk_statistics champ récapitule les segments créés ou supprimés.

Le statut de chaque étape est SUCCESS ouFAILED. Le connector_document_status champ indique le statut consolidé du document, et le error_message champ est renseigné uniquement lorsqu'un document ne parvient pas à être traité.

Types de journaux et exemples

Amazon Bedrock émet deux types d'entrées de journal pour une tâche d'ingestion de base de connaissances gérée, qui se distinguent par domaine : event_type

• StartIngestionJob.StatusChanged— des journaux au niveau de la tâche qui enregistrent la progression de l'ensemble de la tâche d'ingestion, par exemple le début et la fin de l'exploration. Le message champ contient un statut lisible par l'homme, par exemple Crawling started ouCrawling completed.

• StartIngestionJob.ResourceStatusChanged— des journaux au niveau du document qui enregistrent l'état de traitement d'un document individuel.

Voici un exemple de journal de statut au niveau des tâches.

{
    "event_timestamp": 1718677300000,
    "event": {
        "ingestion_job_id": "<IngestionJobId>",
        "data_source_id": "<DataSourceId>",
        "knowledge_base_arn": "arn:aws:bedrock:<region>:<accountId>:knowledge-base/<KnowledgeBaseId>",
        "message": "Crawling started"
    },
    "event_version": "1.0",
    "event_type": "StartIngestionJob.StatusChanged",
    "level": "INFO"
}

Voici un exemple de journal au niveau du document qui enregistre l'état de traitement d'un seul document.

{
    "event_timestamp": 1718677342332,
    "event": {
        "ingestion_job_id": "<IngestionJobId>",
        "data_source_id": "<DataSourceId>",
        "knowledge_base_arn": "arn:aws:bedrock:<region>:<accountId>:knowledge-base/<KnowledgeBaseId>",
        "document_id": "<DocumentId>",
        "source_uri": "<SourceUri>",
        "content_type": "<ContentType>",
        "crawl_action": "ADD" | "DELETE" | "UNMODIFIED",
        "index_status": { "Status": "SUCCESS" | "FAILED", "UpdatedTime": "<epochMillis>" },
        "crawl_status": { "Status": "SUCCESS" | "FAILED", "UpdatedTime": "<epochMillis>" },
        "sync_status": { "Status": "SUCCESS" | "FAILED", "UpdatedTime": "<epochMillis>" },
        "chunk_statistics": {
            "created": int,
            "deleted": int,
            "failed_to_create": int,
            "failed_to_delete": int
        },
        "error_message": "<ErrorMessage>"
    },
    "event_version": "1.0",
    "event_type": "StartIngestionJob.ResourceStatusChanged",
    "level": "INFO" | "ERROR"
}

Le error_message champ n'est présent que lorsqu'un document ne parvient pas à être traité. Le chunk_statistics champ récapitule les fragments créés ou supprimés pour le document.

Certains journaux au niveau du document signalent un message d'état du connecteur au lieu des champs d'état indiqués ci-dessus. Ces journaux incluent un message champ avec une description lisible par l'homme (par exemple, un message indiquant qu'un document n'a pas pu être récupéré ou supprimé) et un level de INFOWARN, ou. ERROR

Exemples de requêtes

Si vous transmettez des CloudWatch journaux à Logs, vous pouvez utiliser CloudWatch Logs Insights pour interroger les journaux d'ingestion pour votre base de connaissances. Les requêtes les plus courantes sont les suivantes.

• Répertoriez tous les documents qui n'ont pas pu être traités lors de l'ingestion, avec leurs messages d'erreur.

  filter event.connector_document_status.Status = "FAILED" | fields event.document_id, event.source_uri, event.error_message, @timestamp | sort @timestamp desc

• Trouvez toutes les entrées du journal pour un document spécifique en fonction de son emplacement source.

  filter event.source_uri = "s3://<bucketName>/<objectKey>" | fields event.document_id, event.connector_document_status.Status, @timestamp | sort @timestamp desc

• Répertoriez tous les documents traités par une tâche d'ingestion spécifique.

  filter event.ingestion_job_id = "<IngestionJobId>" | fields event.document_id, event.connector_document_status.Status, @timestamp | sort @timestamp desc

• Consultez la progression globale d'une tâche d'ingestion, y compris le début et la fin de l'exploration.

  filter event_type = "StartIngestionJob.StatusChanged" | fields event.message, @timestamp | sort @timestamp asc

Suivez l'observabilité pour les bases de connaissances gérées

Amazon Bedrock peut émettre des traces distribuées (spans) pour les opérations d'exécution de la base de connaissances afin que vous puissiez analyser la latence des demandes et les étapes internes d'une demande. Les traces sont émises uniquement pour l'Retrieveopération et sont transmises à AWS X-Ray. La livraison de traces utilise le même pipeline de livraison de journaux vendus que les journaux d'ingestion, avec le type de TRACES journal et une destination X-Ray de livraison.

Activer la livraison de traces à l'aide de l' CloudWatch API

Pour envoyer des traces à AWS X-Ray, utilisez l' CloudWatch API pour créer une livraison, en suivant ces étapes.

1. Appel PutDeliverySource : utilisez l'PutDeliverySourceAPI pour créer une source de diffusion pour la base de connaissances. Transmettez l'ARN de la base de connaissances en tant que resourceArn et TRACES spécifiez-le en tant quelogType.

2. Appel PutDeliveryDestination : utilisez l'PutDeliveryDestinationAPI avec un deliveryDestinationType deXRAY. X-Ray est une destination gérée, vous ne spécifiez donc pas dedestinationResourceArn. Notez l'ARN renvoyé dans la réponse.

3. Appel CreateDelivery : utilisez l'CreateDeliveryAPI pour lier le nom de la source de livraison à l'ARN X-Ray de destination de livraison.

Note

Ces appels d'API sont idempotents. Si une ressource existe déjà, vous pouvez ignorer un ConflictException ou en toute sécuritéResourceAlreadyExistsException.

Autorisations pour la livraison de traces

Pour activer la livraison de traces, l'utilisateur ou le rôle doit disposer de l'bedrock:AllowVendedLogDeliveryForResourceautorisation d'accéder à la ressource de la base de connaissances, en plus des autorisations requises pour la diffusion à AWS X-Ray.

Afficher les traces

Après avoir activé la livraison des traces, appelez l'Retrieveopération pour générer des traces, puis affichez-les dans la AWS X-Ray console.

AgentCore observabilité pour les bases de connaissances gérées

Amazon Bedrock intègre les données d'observabilité de la base de connaissances gérées à l'expérience d' AgentCoreobservabilité d'Amazon Bedrock, vous offrant ainsi une vue consolidée des mesures et des traces de votre base de connaissances, ainsi que de vos autres mesures de télémétrie. AgentCore

Aucune configuration supplémentaire n'est requise pour cette intégration. Une fois que vous avez activé les métriques d'exécution et la diffusion des traces comme décrit dans les sections précédentes, votre page AgentCore d'observabilité est automatiquement renseignée avec les données de base de connaissances correspondantes. Il n'y a aucune action supplémentaire à effectuer.

Note

AgentCore l'intégration de l'observabilité n'est disponible que pour les bases de connaissances gérées.

Assistance client et résolution des problèmes

Les bases de connaissances gérées par Amazon Bedrock stockent temporairement les requêtes des clients et les données de récupération associées uniquement pour fournir une assistance au débogage en réponse aux problèmes signalés par les clients. AWS n'accède à ces données que si le client y consent explicitement lors d'un engagement d'assistance. Amazon Bedrock n'utilise pas ces données pour entraîner ou améliorer les modèles sous-jacents.