本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 托管知识库的可观察性
<a name="kb-managed-observability"></a>

对于托管知识库，Amazon Bedrock 会将操作指标和摄取日志发布到您的 AWS 账户，以便您可以监控知识库的运行状况和使用情况。运行时指标允许您跟踪知识库 API 操作的请求量、错误和限制，而摄取日志则允许您在数据摄取任务期间跟踪各个文档的状态。以下各节描述了可用的可观测性数据以及如何访问这些数据。

## 托管知识库的运行时指标
<a name="kb-managed-observability-runtime-metrics"></a>

Amazon Bedrock 在`AWS/Bedrock/KnowledgeBases`命名空间 CloudWatch下向亚马逊发布知识库 API 操作的运行时指标。使用这些指标来监控诸如之类的操作的调用量、错误率和限制。`Retrieve`指标将免费发布到您的账户，并显示在 CloudWatch 控制台中。

下表描述了 Amazon Bedrock 为托管知识库发布的运行时指标。


| 指标名称 | 单位 | 说明 | 
| --- | --- | --- | 
| Invocations | 计数 | 对知识库操作的请求数。此指标针对每个请求发布，包括导致错误的请求。 | 
| ClientErrors | 计数 | 导致客户端错误（除限制之外的 HTTP `4xx` 响应）的请求数。 | 
| ServerErrors | 计数 | 导致服务器端错误（HTTP `5xx` 响应）的请求数。 | 
| 节流 | 计数 | 被限制的请求数（HTTP `429` 响应）。受限制的请求不计为或。`ClientErrors` `ServerErrors` | 

`ClientErrors``ServerErrors`、和`Throttles`指标仅在出现相应条件时才会发布。每个请求都会发布该`Invocations`指标。

### 该 AgenticRetrieveStream 操作的其他指标
<a name="kb-managed-observability-runtime-metrics-agentic"></a>

除了上表中的指标外，该`AgenticRetrieveStream`操作还发布了以下指标。


| 指标名称 | 单位 | 说明 | 
| --- | --- | --- | 
| TotalIterationCount | 计数 | 请求期间执行的代理检索迭代总数。仅当请求成功完成时，才会针对该`AgenticRetrieveStream`操作发布此指标。 | 

此指标使用值为的`Operation`维度`AgenticRetrieveStream`。

### 托管知识库指标的维度
<a name="kb-managed-observability-runtime-metrics-dimensions"></a>

Amazon Bedrock 使用以下维度来管理知识库运行时指标。


| 维度 | 说明 | 
| --- | --- | 
| 操作 | 发布指标所针对的知识库 API 操作。可能的值为 `Retrieve` 和 `AgenticRetrieveStream`。 | 
| KnowledgeBaseId | 请求所针对的知识库，格式为`knowledge-base/{{knowledge-base-id}}`。此维度包含在针对单一知识库的`Retrieve`操作中。不针对单个知识库的操作仅与该`Operation`维度一起发布。 | 

### 发布指标的权限
<a name="kb-managed-observability-runtime-metrics-permissions"></a>

Amazon Bedrock 使用与请求关联的凭证将这些指标发布到您的账户：
+ 在该`Retrieve`操作中，Amazon Bedrock 使用知识库服务角色。
+ 对于其他操作，Amazon Bedrock 通过正向访问会话使用调用身份（调用操作的 IAM 用户或角色）的证书。

要发布指标，必须允许该身份调`cloudwatch:PutMetricData`用`AWS/Bedrock/KnowledgeBases`命名空间。附上向知识库服务角色和调用知识库操作的任何身份授予此权限的策略。以下示例授予所需的权限。

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

指标发布是尽力而为。如果身份没有所需的权限，则不会发布相应的指标，但知识库请求本身不会受到影响。

### 查看运行时指标
<a name="kb-managed-observability-runtime-metrics-view"></a>

您可以使用 AWS 管理控制台、或 CloudWatch API 获取知识库的指标。 AWS CLI您可以通过其中一个 AWS 软件开发套件 (SDK) 或 CloudWatch API 工具来使用 API。 CloudWatch 

要在 CloudWatch 控制台中查看托管知识库指标，请转至导航窗格中的指标部分并选择所有指标选项，然后搜索`AWS/Bedrock/KnowledgeBases`命名空间。

您必须拥有相应的 CloudWatch 权限才能监控您的知识库 CloudWatch。有关更多信息，请参阅《亚马逊* CloudWatch 用户指南》 CloudWatch*中的 [Amazon 身份验证和访问控制](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/auth-and-access-control-cw.html)。

## 托管知识库的存储指标
<a name="kb-managed-observability-storage-metrics"></a>

对于托管知识库，Amazon Bedrock 会在`AWS/Bedrock/KnowledgeBases`命名空间 CloudWatch 下向亚马逊发布存储指标。该指标报告存储在知识库中的源数据的总原始大小，并在数据摄取任务完成后发布到您的账户，以便您可以跟踪知识库中随时间推移存储了多少数据。

下表描述了 Amazon Bedrock 为托管知识库发布的存储指标。


| 指标名称 | 单位 | 说明 | 
| --- | --- | --- | 
| RawDataSize  | 千兆字节 | 存储在知识库中的源数据的总原始大小（以 GB 为单位）。此指标是在数据摄取任务完成后发布的。 | 

存储指标使用`KnowledgeBaseId`维度，格式为`knowledge-base/{{knowledge-base-id}}`。

## 托管知识库的摄取可观察性
<a name="kb-managed-observability-ingestion"></a>

Amazon Bedrock 会生成日志，用于跟踪托管知识库的数据摄取任务的进度，包括总体任务状态和每个已处理文档的状态。您可以使用这些日志来确认收录了哪些文档，调查检索结果中未返回文档的原因，并对摄取失败进行故障排除。

日志将传送到您配置的目的地（CloudWatch 日志、Amazon S3 或 Amazon Data Firehose）。以下各节介绍如何启用日志传送、采集期间文档的生命周期、发出的日志类型以及示例查询。

### 启用摄取日志传输
<a name="kb-managed-observability-ingestion-enable"></a>

要接收摄取日志，请使用 AWS 管理控制台 或 API 为您的知识库配置日志传输。 CloudWatch 您可以将 CloudWatch 日志传输到 Logs、Amazon S3 或 Amazon Data Firehose。

#### 使用控制台启用日志传输
<a name="kb-managed-observability-ingestion-enable-console"></a>

1. **打开您的知识库**：在 Amazon Bedrock 控制台中，打开要监控的托管知识库。

1. **添加日志传输**：编辑知识库以添加日志传输，并配置以下详细信息：
   + 日志目标（CloudWatch 日志、亚马逊 S3 或 Amazon Data Firehose）。
   + （CloudWatch 日志）日志组名称。
   + （亚马逊 S3）存储桶名称。
   + （亚马逊 Data Firehose）Firehose 直播。

1. **确认传输状态**：在控制台中验证日志传输状态是否为 “已*激活*”。

#### 使用 CloudWatch API 启用日志传输
<a name="kb-managed-observability-ingestion-enable-api"></a>

1. **获取知识库的 ARN**：调用 [GetKnowledgeBase](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_GetKnowledgeBase.html)API 获取知识库的亚马逊资源名称 (ARN)。知识库ARN采用以下格式:. {{arn:aws:bedrock:your-region:your-account-id:knowledge-base/knowledge-base-id}} 

1. **调**用`PutDeliverySource`：使用 [PutDeliverySource](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliverySource.html)API 为知识库创建交付源。将知识库 ARN 传递为，`resourceArn`并指定`APPLICATION_LOGS`为。`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. **调**用`PutDeliveryDestination`：使用 [PutDeliveryDestination](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestination.html)API 配置日志的存储位置。指定 CloudWatch 日志、亚马逊 S3 或 Amazon Data Firehose 目标的 ARN。您可以设置`outputFormat`为`json`、`plain`、`w3c``raw`、或`parquet`。

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

   如果您要将日志传送到其他账户，请使用 `PutDeliveryDestinationPolicy` API 将一个 AWS Identity and Access Management (IAM) 策略附加到目标账户。

1. **调**用`CreateDelivery`：使用 [CreateDelivery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateDelivery.html)API 将传送源链接到配送目的地。

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

#### 支持的日志类型和权限
<a name="kb-managed-observability-ingestion-enable-logtypes"></a>

托管知识库支持以下日志类型：
+ `APPLICATION_LOGS`：跟踪摄取任务的状态以及作业期间处理的每个文档的状态的日志。
+ `TRACES`：运行时操作的分布式跟踪（跨度）。轨迹仅针对该`Retrieve`操作发出并传送到。 AWS X-Ray有关更多信息，请参阅 [跟踪托管知识库的可观察性](#kb-managed-observability-traces)。

要启用日志传送，用户或角色除了拥有写入所选目标所需的权限外，还必须拥有知识库资源的权限。`bedrock:AllowVendedLogDeliveryForResource`有关每个目的地的 IAM 策略示例，请参阅 A *mazon Logs 用户指南中的不同配送目的地的销售 CloudWatch 日志*[权限](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/AWS-logs-and-resource-policy.html#AWS-vended-logs-permissions-V2)。

### 摄取期间的文档生命周期
<a name="kb-managed-observability-ingestion-lifecycle"></a>

在数据摄取作业期间，每个文档都会经历三个阶段，文档的日志记录每个阶段的状态：
+ **Crawl** (`crawl_status`)：Amazon Bedrock 从数据源检索文档，并确定是必须添加、更新还是删除该文档。该`crawl_action`字段设置为`ADD``DELETE`、或`UNMODIFIED`。在剩余阶段`UNMODIFIED`被跳过的文档。
+ **同步** (`sync_status`)：将文档提交到知识库中进行处理。
+ **Index** (`index_status`)：文档被分块、嵌入并保留在知识库中。该`chunk_statistics`字段汇总了创建或删除的区块。

每个阶段的状态均为`SUCCESS`或`FAILED`。该`connector_document_status`字段报告文档的合并状态，并且只有在文档处理失败时才会填充该`error_message`字段。

### 日志类型和示例
<a name="kb-managed-observability-ingestion-example-log"></a>

Amazon Bedrock 会为托管知识库摄取作业发出两种日志条目，按字段区分：`event_type`
+ `StartIngestionJob.StatusChanged`— 记录整个摄取作业进度的作业级日志，例如抓取开始和完成的时间。该`message`字段包含人类可读的状态，例如`Crawling started`或`Crawling completed`。
+ `StartIngestionJob.ResourceStatusChanged`— 记录单个文档处理状态的文档级日志。

以下是作业级状态日志的示例。

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

以下是记录单个文档处理状态的文档级日志的示例。

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

仅当文档处理失败时，该`error_message`字段才会出现。该`chunk_statistics`字段汇总了为文档创建或删除的区块。

一些文档级日志报告的是连接器状态消息，而不是上面显示的状态字段。这些日志包括一个带有人类可读描述的`message`字段（例如，一条表明无法获取或删除文档的消息）和`INFO``WARN`、或`level`的字段。`ERROR`

### 示例查询
<a name="kb-managed-observability-ingestion-queries"></a>

如果您将日志传送到日 CloudWatch 志，则可以使用 CloudWatch Logs Insights 来查询知识库的摄取日志。以下是一些常见查询。
+ 列出所有在摄取过程中未能处理的文档及其错误消息。

  `filter event.connector_document_status.Status = "FAILED" | fields event.document_id, event.source_uri, event.error_message, @timestamp | sort @timestamp desc`
+ 按源位置查找特定文档的所有日志条目。

  `filter event.source_uri = "s3://<bucketName>/<objectKey>" | fields event.document_id, event.connector_document_status.Status, @timestamp | sort @timestamp desc`
+ 列出由特定摄取任务处理的所有文档。

  `filter event.ingestion_job_id = "<IngestionJobId>" | fields event.document_id, event.connector_document_status.Status, @timestamp | sort @timestamp desc`
+ 查看摄取作业的总体进度，包括开始和完成爬网的时间。

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

## 跟踪托管知识库的可观察性
<a name="kb-managed-observability-traces"></a>

Amazon Bedrock 可以为知识库运行时操作发出分布式跟踪（跨度），以便您可以分析请求延迟和请求的内部步骤。轨迹仅针对该`Retrieve`操作发出并传送到。[AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html)跟踪传输使用与摄取日志相同的预售日志传输管道，包括`TRACES`日志类型和传输目标。 X-Ray 

### 使用 CloudWatch API 启用追踪传送
<a name="kb-managed-observability-traces-enable"></a>

要向传送追踪数据 AWS X-Ray，请按照以下步骤使用 CloudWatch API 创建交付。

1. **调**用`PutDeliverySource`：使用 [PutDeliverySource](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliverySource.html)API 为知识库创建交付源。将知识库 ARN 传递为，`resourceArn`并指定`TRACES`为。`logType`

1. **调用 `PutDeliveryDestination`**：使用带有 o `deliveryDestinationType` f [PutDeliveryDestination](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_PutDeliveryDestination.html)的 API `XRAY`。 X-Ray 是托管目的地，因此您无需指定`destinationResourceArn`。记下响应中返回的 ARN。

1. **调**用`CreateDelivery`：使用 [CreateDelivery](https://docs.aws.amazon.com/AmazonCloudWatchLogs/latest/APIReference/API_CreateDelivery.html)API 将传送来源名称关联到 X-Ray传送目标 ARN。

**注意**  
这些 API 调用是等效的。如果资源已经存在，则可以放心地忽略`ConflictException`或`ResourceAlreadyExistsException`。

### 追踪传送权限
<a name="kb-managed-observability-traces-permissions"></a>

要启用跟踪交付，用户或角色必须拥有知识库资源的`bedrock:AllowVendedLogDeliveryForResource`权限以及交付到所需的权限 AWS X-Ray。

### 查看轨迹
<a name="kb-managed-observability-traces-view"></a>

启用跟踪传输后，调用`Retrieve`操作生成跟踪，然后在 AWS X-Ray 控制台中查看。

## AgentCore 托管知识库的可观察性
<a name="kb-managed-observability-agentcore"></a>

Amazon Bedrock 将托管知识库可观测性数据与 Amazon Bedrock AgentCore 可观测性体验相集成，使您可以综合查看知识库指标和跟踪以及其他遥测数据。 AgentCore 

此集成不需要其他配置。按照前几节所述启用运行时指标和跟踪交付后，您的 AgentCore可观察性页面将自动填充相应的知识库数据。无需采取任何额外行动。

**注意**  
AgentCore 可观察性集成仅适用于托管知识库。

## 客户支持和故障排除
<a name="kb-managed-observability-support"></a>

Amazon Bedrock 托管知识库会临时存储客户查询和相关的检索数据，只是为了提供调试支持，以应对客户报告的问题。除非客户在支持活动期间明确同意，否则 AWS 不会访问这些数据。Amazon Bedrock 不会使用这些数据来训练或改进底层模型。