As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Observabilidade para bases de conhecimento gerenciadas Para uma base de conhecimento gerenciada, o Amazon Bedrock publica métricas operacionais e registros de ingestão em sua AWS conta para que você possa monitorar a integridade e o uso de sua base de conhecimento. As métricas de tempo de execução permitem que você acompanhe o volume de solicitações, os erros e a limitação das operações de API da sua base de conhecimento, e os registros de ingestão permitem que você acompanhe o status de documentos individuais durante um trabalho de ingestão de dados. As seções a seguir descrevem os dados de observabilidade que estão disponíveis e como acessá-los. ## Métricas de tempo de execução para bases de conhecimento gerenciadas O Amazon Bedrock publica métricas de tempo de execução para suas operações de API da base de conhecimento na Amazon CloudWatch sob o `AWS/Bedrock/KnowledgeBases` namespace. Use essas métricas para monitorar o volume de invocações, as taxas de erro e a limitação de operações como. `Retrieve` As métricas são publicadas em sua conta sem custo adicional e aparecem no CloudWatch console. A tabela a seguir descreve as métricas de tempo de execução que o Amazon Bedrock publica para bases de conhecimento gerenciadas. | Nome da métrica | Unidade | Description | | --- | --- | --- | | Invocations | Contagem | Número de solicitações para a operação da base de conhecimento. Essa métrica é publicada para cada solicitação, incluindo solicitações que resultam em um erro. | | ClientErrors | Contagem | Número de solicitações que resultaram em um erro do lado do cliente (uma `4xx` resposta HTTP diferente de limitação). | | ServerErrors | Contagem | Número de solicitações que resultaram em um erro do lado do servidor (uma resposta HTTP`5xx`). | | Controles de utilização | Contagem | Número de solicitações que foram limitadas (uma `429` resposta HTTP). Solicitações limitadas não são contadas como `ClientErrors` ou. `ServerErrors` | As `Throttles` métricas `ClientErrors``ServerErrors`, e são publicadas somente quando a condição correspondente ocorre. A `Invocations` métrica é publicada para cada solicitação. ### Métrica adicional para a AgenticRetrieveStream operação Além das métricas na tabela anterior, a `AgenticRetrieveStream` operação publica a métrica a seguir. | Nome da métrica | Unidade | Description | | --- | --- | --- | | TotalIterationCount | Contagem | O número total de iterações de recuperação do agente realizadas durante a solicitação. Essa métrica é publicada somente para a `AgenticRetrieveStream` operação, quando a solicitação é concluída com êxito. | Essa métrica usa a `Operation` dimensão com um valor de`AgenticRetrieveStream`. ### Dimensões para métricas gerenciadas da base de conhecimento O Amazon Bedrock usa as seguintes dimensões para métricas de tempo de execução da base de conhecimento gerenciada. | Dimensão | Description | | --- | --- | | Operation | A operação da API da base de conhecimento para a qual a métrica é publicada. Os possíveis valores são `Retrieve` e `AgenticRetrieveStream`. | | KnowledgeBaseId | A base de conhecimento que a solicitação visa, no formato`knowledge-base/{{knowledge-base-id}}`. Essa dimensão está incluída na `Retrieve` operação, que tem como alvo uma única base de conhecimento. As operações que não têm como alvo uma única base de conhecimento são publicadas somente com a `Operation` dimensão. | ### Permissões para publicar métricas O Amazon Bedrock publica essas métricas em sua conta usando as credenciais associadas à solicitação: + Para a `Retrieve` operação, o Amazon Bedrock usa a função de serviço da base de conhecimento. + Para outras operações, o Amazon Bedrock usa as credenciais da identidade de chamada (o usuário ou função do IAM que chama a operação), por meio de uma sessão de acesso direto. Para que as métricas sejam publicadas, essa identidade deve ter permissão `cloudwatch:PutMetricData` para chamar o `AWS/Bedrock/KnowledgeBases` namespace. Anexe uma política que conceda essa permissão à função de serviço da base de conhecimento e a qualquer identidade que chame as operações da base de conhecimento. O exemplo a seguir concede a permissão necessária. ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "cloudwatch:PutMetricData", "Resource": "*", "Condition": { "StringEquals": { "cloudwatch:namespace": "AWS/Bedrock/KnowledgeBases" } } } ] } ``` A publicação de métricas é o melhor esforço. Se a identidade não tiver a permissão necessária, as métricas correspondentes não serão publicadas, mas a solicitação da base de conhecimento em si não será afetada. ### Exibir métricas de tempo de execução Você pode obter métricas para sua base de conhecimento com a Console de gerenciamento da AWS AWS CLI, a ou a CloudWatch API. Você pode usar a CloudWatch API por meio de um dos kits de desenvolvimento de AWS software (SDKs) ou das ferramentas da CloudWatch API. Para visualizar as métricas gerenciadas da base de conhecimento no CloudWatch console, acesse a seção de métricas no painel de navegação, selecione a opção todas as métricas e, em seguida, pesquise o `AWS/Bedrock/KnowledgeBases` namespace. Você deve ter as CloudWatch permissões apropriadas para monitorar sua base de conhecimento com CloudWatch. Para obter mais informações, consulte [Autenticação e controle de acesso para a Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/auth-and-access-control-cw.html) *no Guia CloudWatch do usuário* da Amazon. ## Métricas de armazenamento para bases de conhecimento gerenciadas Para uma base de conhecimento gerenciada, o Amazon Bedrock publica uma métrica de armazenamento na Amazon CloudWatch sob o `AWS/Bedrock/KnowledgeBases` namespace. Essa métrica relata o tamanho bruto total dos dados de origem armazenados na base de conhecimento e é publicada em sua conta após a conclusão de um trabalho de ingestão de dados, para que você possa acompanhar a quantidade de dados armazenados em sua base de conhecimento ao longo do tempo. A tabela a seguir descreve a métrica de armazenamento que o Amazon Bedrock publica para bases de conhecimento gerenciadas. | Nome da métrica | Unidade | Description | | --- | --- | --- | | RawDataSize | Gigabytes | O tamanho bruto total dos dados de origem armazenados na base de conhecimento, em gigabytes. Essa métrica é publicada após a conclusão de um trabalho de ingestão de dados. | A métrica de armazenamento usa a `KnowledgeBaseId` dimensão, no formato`knowledge-base/{{knowledge-base-id}}`. ## Observabilidade da ingestão para bases de conhecimento gerenciadas O Amazon Bedrock emite registros que rastreiam o progresso de um trabalho de ingestão de dados para sua base de conhecimento gerenciada, incluindo o status geral do trabalho e o status de cada documento processado. Você pode usar esses registros para confirmar quais documentos foram ingeridos, investigar por que um documento não foi retornado nos resultados da recuperação e solucionar falhas de ingestão. Os registros são entregues em um destino que você configura (CloudWatch Logs, Amazon S3 ou Amazon Data Firehose). As seções a seguir descrevem como habilitar a entrega de registros, o ciclo de vida de um documento durante a ingestão, os tipos de registros que são emitidos e exemplos de consultas. ### Ativar a entrega do registro de ingestão Para receber registros de ingestão, configure uma entrega de registros para sua base de conhecimento usando a API Console de gerenciamento da AWS ou a CloudWatch API. Você pode entregar registros para CloudWatch Logs, Amazon S3 ou Amazon Data Firehose. #### Ativar a entrega de registros usando o console 1. **Abra sua base de conhecimento**: no console do Amazon Bedrock, abra a base de conhecimento gerenciada que você deseja monitorar. 1. **Adicionar uma entrega de log**: edite a base de conhecimento para adicionar uma entrega de log e configure os seguintes detalhes: + O destino do registro (CloudWatch Logs, Amazon S3 ou Amazon Data Firehose). + (CloudWatch Registros) O nome do grupo de registros. + (Amazon S3) O nome do bucket. + (Amazon Data Firehose) O stream do Firehose. 1. **Confirme o status da entrega**: verifique se o status de entrega do log é *Entrega ativa* no console. #### Ative a entrega de registros usando a CloudWatch API 1. **Obtenha o ARN da sua base de conhecimento**: chame a [GetKnowledgeBase](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetKnowledgeBase.html)API para obter o Amazon Resource Name (ARN) da base de conhecimento. Um ARN de base de conhecimento tem o seguinte formato:. {{arn:aws:bedrock:your-region:your-account-id:knowledge-base/knowledge-base-id}} 1. **Chamada `PutDeliverySource`**: use a [PutDeliverySource](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliverySource.html)API para criar uma fonte de entrega para a base de conhecimento. Passe o ARN da base de conhecimento como o `resourceArn` e especifique `APPLICATION_LOGS` como o. `logType` ``` { "logType": "APPLICATION_LOGS", "name": "my-knowledge-base-delivery-source", "resourceArn": "arn:aws:bedrock:your-region:your-account-id:knowledge-base/knowledge_base_id" } ``` 1. **Chamada `PutDeliveryDestination`**: use a [PutDeliveryDestination](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestination.html)API para configurar onde os registros são armazenados. Especifique o ARN de um destino do CloudWatch Logs, Amazon S3 ou Amazon Data Firehose. Você pode `outputFormat` definir como `json``plain`,`w3c`,`raw`, ou`parquet`. ``` { "deliveryDestinationConfiguration": { "destinationResourceArn": "arn:aws:s3:::bucket-name" }, "name": "my-knowledge-base-delivery-destination", "outputFormat": "json" } ``` Se você estiver entregando registros para uma conta diferente, use a `PutDeliveryDestinationPolicy` API para anexar uma política AWS Identity and Access Management (IAM) à conta de destino. 1. **Chamada `CreateDelivery`**: use a [CreateDelivery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateDelivery.html)API para vincular a fonte de entrega ao destino da entrega. ``` { "deliveryDestinationArn": "string", "deliverySourceName": "my-knowledge-base-delivery-source" } ``` #### Tipos de registro e permissões compatíveis As bases de conhecimento gerenciadas oferecem suporte aos seguintes tipos de log: + `APPLICATION_LOGS`: registros que rastreiam o status da tarefa de ingestão e de cada documento processado durante a tarefa. + `TRACES`: rastreamentos distribuídos (extensões) para operações em tempo de execução. Os traços são emitidos somente para a `Retrieve` operação e são entregues para AWS X-Ray. Para obter mais informações, consulte [Rastreie a observabilidade para bases de conhecimento gerenciadas](#kb-managed-observability-traces). Para habilitar a entrega de registros, o usuário ou a função devem ter a `bedrock:AllowVendedLogDeliveryForResource` permissão para o recurso da base de conhecimento, além das permissões necessárias para gravar no destino escolhido. Por exemplo, políticas do IAM para cada destino, consulte [Permissões de registros vendidos para diferentes destinos de entrega](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html#AWS-vended-logs-permissions-V2) no *Guia do usuário do Amazon CloudWatch Logs*. ### Ciclo de vida do documento durante a ingestão Durante um trabalho de ingestão de dados, cada documento passa por três estágios, e o registro do documento registra o status de cada estágio: + **Crawl** (`crawl_status`): O Amazon Bedrock recupera o documento da fonte de dados e determina se ele deve ser adicionado, atualizado ou excluído. O `crawl_action` campo está definido como `ADD``DELETE`, ou`UNMODIFIED`. Um documento que `UNMODIFIED` é ignorado nos estágios restantes. + **Sincronizar** (`sync_status`): o documento é enviado para processamento na base de conhecimento. + **Índice** (`index_status`): o documento é fragmentado, incorporado e persiste na base de conhecimento. O `chunk_statistics` campo resume os fragmentos que foram criados ou excluídos. O status de cada estágio é `SUCCESS` ou`FAILED`. O `connector_document_status` campo relata o status consolidado do documento, e o `error_message` campo é preenchido somente quando há falha no processamento de um documento. ### Tipos e exemplos de registros O Amazon Bedrock emite dois tipos de entradas de registro para um trabalho gerenciado de ingestão da base de conhecimento, diferenciados pelo campo: `event_type` + `StartIngestionJob.StatusChanged`— registros no nível da tarefa que registram o progresso da tarefa geral de ingestão, como quando o rastreamento é iniciado e concluído. O `message` campo contém um status legível por humanos, por exemplo ou. `Crawling started` `Crawling completed` + `StartIngestionJob.ResourceStatusChanged`— registros em nível de documento que registram o status de processamento de um documento individual. Veja a seguir um exemplo de um registro de status em nível de trabalho. ``` { "event_timestamp": 1718677300000, "event": { "ingestion_job_id": "", "data_source_id": "", "knowledge_base_arn": "arn:aws:bedrock:::knowledge-base/", "message": "Crawling started" }, "event_version": "1.0", "event_type": "StartIngestionJob.StatusChanged", "level": "INFO" } ``` Veja a seguir um exemplo de um registro em nível de documento que registra o status de processamento de um único documento. ``` { "event_timestamp": 1718677342332, "event": { "ingestion_job_id": "", "data_source_id": "", "knowledge_base_arn": "arn:aws:bedrock:::knowledge-base/", "document_id": "", "source_uri": "", "content_type": "", "crawl_action": "ADD" | "DELETE" | "UNMODIFIED", "index_status": { "Status": "SUCCESS" | "FAILED", "UpdatedTime": "" }, "crawl_status": { "Status": "SUCCESS" | "FAILED", "UpdatedTime": "" }, "sync_status": { "Status": "SUCCESS" | "FAILED", "UpdatedTime": "" }, "chunk_statistics": { "created": int, "deleted": int, "failed_to_create": int, "failed_to_delete": int }, "error_message": "" }, "event_version": "1.0", "event_type": "StartIngestionJob.ResourceStatusChanged", "level": "INFO" | "ERROR" } ``` O `error_message` campo está presente somente quando um documento não é processado. O `chunk_statistics` campo resume os fragmentos que foram criados ou excluídos do documento. Alguns registros em nível de documento relatam uma mensagem de status do conector em vez dos campos de status mostrados acima. Esses registros incluem um `message` campo com uma descrição legível por humanos (por exemplo, uma mensagem indicando que um documento não pôde ser buscado ou excluído) e um `level` de`INFO`, ou. `WARN` `ERROR` ### Consultas de exemplo Se você entregar registros para o CloudWatch Logs, poderá usar o CloudWatch Logs Insights para consultar os registros de ingestão da sua base de conhecimento. A seguir estão algumas consultas comuns. + Liste todos os documentos que falharam no processamento durante a ingestão, com suas mensagens de erro. `filter event.connector_document_status.Status = "FAILED" | fields event.document_id, event.source_uri, event.error_message, @timestamp | sort @timestamp desc` + Encontre todas as entradas de registro de um documento específico pelo local de origem. `filter event.source_uri = "s3:///" | fields event.document_id, event.connector_document_status.Status, @timestamp | sort @timestamp desc` + Liste todos os documentos processados por um trabalho de ingestão específico. `filter event.ingestion_job_id = "" | fields event.document_id, event.connector_document_status.Status, @timestamp | sort @timestamp desc` + Veja o progresso geral de um trabalho de ingestão, inclusive quando o rastreamento foi iniciado e concluído. `filter event_type = "StartIngestionJob.StatusChanged" | fields event.message, @timestamp | sort @timestamp asc` ## Rastreie a observabilidade para bases de conhecimento gerenciadas O Amazon Bedrock pode emitir rastreamentos distribuídos (spans) para operações de tempo de execução da base de conhecimento, para que você possa analisar a latência da solicitação e as etapas internas de uma solicitação. Os traços são emitidos somente para a `Retrieve` operação e são entregues para [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html). O Trace Delivery usa o mesmo pipeline de entrega de registros vendidos que os registros de ingestão, com o tipo de `TRACES` registro e um destino de X-Ray entrega. ### Ative a entrega de rastreamento usando a CloudWatch API Para entregar rastreamentos AWS X-Ray, use a CloudWatch API para criar uma entrega, seguindo estas etapas. 1. **Chamada `PutDeliverySource`**: use a [PutDeliverySource](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliverySource.html)API para criar uma fonte de entrega para a base de conhecimento. Passe o ARN da base de conhecimento como o `resourceArn` e especifique `TRACES` como o. `logType` 1. **Chamada `PutDeliveryDestination`**: use a [PutDeliveryDestination](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestination.html)API com um `deliveryDestinationType` de`XRAY`. X-Ray é um destino gerenciado, então você não especifica um`destinationResourceArn`. Observe o ARN que é retornado na resposta. 1. **Chamada `CreateDelivery`**: use a [CreateDelivery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateDelivery.html)API para vincular o nome da fonte de entrega ao ARN do destino da X-Ray entrega. **nota** Essas chamadas de API são idempotentes. Se um recurso já existir, você pode ignorar com segurança um `ConflictException` ou`ResourceAlreadyExistsException`. ### Permissões para entrega de rastreamento Para habilitar a entrega de rastreamento, o usuário ou a função devem ter a `bedrock:AllowVendedLogDeliveryForResource` permissão para o recurso da base de conhecimento, além das permissões necessárias para a entrega AWS X-Ray. ### Exibir traços Depois de habilitar a entrega de rastreamento, chame a `Retrieve` operação para gerar rastreamentos e, em seguida, visualize-os no AWS X-Ray console. ## AgentCore observabilidade para bases de conhecimento gerenciadas O Amazon Bedrock integra dados gerenciados de observabilidade da base de conhecimento com a experiência de AgentCore observabilidade do Amazon Bedrock, oferecendo uma visão consolidada das métricas e dos traços da sua base de conhecimento junto com suas outras telemetrias. AgentCore Nenhuma configuração adicional é necessária para essa integração. Depois de ativar as métricas de tempo de execução e rastrear a entrega conforme descrito nas seções anteriores, sua página de AgentCore observabilidade é preenchida automaticamente com os dados correspondentes da base de conhecimento. Não há ações extras a serem tomadas. **nota** AgentCore a integração de observabilidade está disponível somente para bases de conhecimento gerenciadas. ## Suporte ao cliente e solução de problemas O Amazon Bedrock Managed Knowledge Bases armazena temporariamente as consultas dos clientes e os dados de recuperação associados exclusivamente para fornecer suporte de depuração em resposta aos problemas relatados pelo cliente. A AWS não acessa esses dados, a menos que o cliente consinta explicitamente durante um contrato de suporte. O Amazon Bedrock não usa esses dados para treinar ou melhorar os modelos subjacentes.