Observability for managed knowledge bases

For a managed knowledge base, Amazon Bedrock publishes operational metrics and ingestion logs to your AWS account so that you can monitor the health and usage of your knowledge base. Runtime metrics let you track request volume, errors, and throttling for your knowledge base API operations, and ingestion logs let you track the status of individual documents during a data ingestion job. The following sections describe the observability data that is available and how to access it.

Runtime metrics for managed knowledge bases

Amazon Bedrock publishes runtime metrics for your knowledge base API operations to Amazon CloudWatch under the AWS/Bedrock/KnowledgeBases namespace. Use these metrics to monitor invocation volume, error rates, and throttling for operations such as Retrieve. Metrics are published to your account at no additional charge and appear in the CloudWatch console.

The following table describes the runtime metrics that Amazon Bedrock publishes for managed knowledge bases.

The ClientErrors, ServerErrors, and Throttles metrics are published only when the corresponding condition occurs. The Invocations metric is published for every request.

Additional metric for the AgenticRetrieveStream operation

In addition to the metrics in the preceding table, the AgenticRetrieveStream operation publishes the following metric.

This metric uses the Operation dimension with a value of AgenticRetrieveStream.

Dimensions for managed knowledge base metrics

Amazon Bedrock uses the following dimensions for managed knowledge base runtime metrics.

Permissions for publishing metrics

Amazon Bedrock publishes these metrics to your account using the credentials associated with the request:

For metrics to be published, that identity must be allowed to call cloudwatch:PutMetricData for the AWS/Bedrock/KnowledgeBases namespace. Attach a policy that grants this permission to the knowledge base service role and to any identity that calls the knowledge base operations. The following example grants the required permission.

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

Metric publishing is best effort. If the identity does not have the required permission, the corresponding metrics are not published, but the knowledge base request itself is not affected.

View runtime metrics

You can get metrics for your knowledge base with the AWS Management Console, the AWS CLI, or the CloudWatch API. You can use the CloudWatch API through one of the AWS Software Development Kits (SDKs) or the CloudWatch API tools.

To view managed knowledge base metrics in the CloudWatch console, go to the metrics section in the navigation pane and select the all metrics option, then search for the AWS/Bedrock/KnowledgeBases namespace.

You must have the appropriate CloudWatch permissions to monitor your knowledge base with CloudWatch. For more information, see Authentication and Access Control for Amazon CloudWatch in the Amazon CloudWatch User Guide.

Storage metrics for managed knowledge bases

For a managed knowledge base, Amazon Bedrock publishes a storage metric to Amazon CloudWatch under the AWS/Bedrock/KnowledgeBases namespace. This metric reports the total raw size of the source data stored in the knowledge base, and is published to your account after a data ingestion job completes, so that you can track how much data is stored in your knowledge base over time.

The following table describes the storage metric that Amazon Bedrock publishes for managed knowledge bases.

The storage metric uses the KnowledgeBaseId dimension, in the format knowledge-base/knowledge-base-id.

Ingestion observability for managed knowledge bases

Amazon Bedrock emits logs that track the progress of a data ingestion job for your managed knowledge base, including the overall job status and the status of each document that is processed. You can use these logs to confirm which documents were ingested, investigate why a document was not returned in retrieval results, and troubleshoot ingestion failures.

Logs are delivered to a destination that you configure (CloudWatch Logs, Amazon S3, or Amazon Data Firehose). The following sections describe how to enable log delivery, the lifecycle of a document during ingestion, the log types that are emitted, and example queries.

Enable ingestion log delivery

To receive ingestion logs, configure a log delivery for your knowledge base using either the AWS Management Console or the CloudWatch API. You can deliver logs to CloudWatch Logs, Amazon S3, or Amazon Data Firehose.

Enable log delivery using the console

Enable log delivery using the CloudWatch API

Supported log types and permissions

Managed knowledge bases support the following log types:

To enable log delivery, the user or role must have the bedrock:AllowVendedLogDeliveryForResource permission for the knowledge base resource, in addition to the permissions required to write to your chosen destination. For example IAM policies for each destination, see Vended logs permissions for different delivery destinations in the Amazon CloudWatch Logs User Guide.

Document lifecycle during ingestion

During a data ingestion job, each document moves through three stages, and the log for the document records the status of each stage:

Each stage status is SUCCESS or FAILED. The connector_document_status field reports the consolidated status of the document, and the error_message field is populated only when a document fails to process.

Log types and examples

Amazon Bedrock emits two kinds of log entries for a managed knowledge base ingestion job, distinguished by the event_type field:

The following is an example of a job-level status log.

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

The following is an example of a document-level log that records the processing status of a single 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"
}

The error_message field is present only when a document fails to process. The chunk_statistics field summarizes the chunks that were created or deleted for the document.

Some document-level logs report a connector status message instead of the status fields shown above. These logs include a message field with a human-readable description (for example, a message indicating that a document could not be fetched or deleted) and a level of INFO, WARN, or ERROR.

Example queries

If you deliver logs to CloudWatch Logs, you can use CloudWatch Logs Insights to query the ingestion logs for your knowledge base. The following are some common queries.

Trace observability for managed knowledge bases

Amazon Bedrock can emit distributed traces (spans) for knowledge base runtime operations so that you can analyze request latency and the internal steps of a request. Traces are emitted only for the Retrieve operation and are delivered to AWS X-Ray. Trace delivery uses the same vended log delivery pipeline as ingestion logs, with the TRACES log type and an X-Ray delivery destination.

Enable trace delivery using the CloudWatch API

To deliver traces to AWS X-Ray, use the CloudWatch API to create a delivery, following these steps.

Permissions for trace delivery

To enable trace delivery, the user or role must have the bedrock:AllowVendedLogDeliveryForResource permission for the knowledge base resource, in addition to the permissions required to deliver to AWS X-Ray.

View traces

After you enable trace delivery, call the Retrieve operation to generate traces, and then view them in the AWS X-Ray console.

AgentCore observability for managed knowledge bases

Amazon Bedrock integrates managed knowledge base observability data with the Amazon Bedrock AgentCore observability experience, giving you a consolidated view of your knowledge base metrics and traces alongside your other AgentCore telemetry.

No additional configuration is required for this integration. After you enable runtime metrics and trace delivery as described in the preceding sections, your AgentCore observability page populates automatically with the corresponding knowledge base data. There are no extra actions to take.

Customer support and troubleshooting

Amazon Bedrock Managed Knowledge Bases temporarily stores customer queries and associated retrieval data solely to provide debugging support in response to customer-reported issues. AWS does not access this data unless the customer explicitly consents during a support engagement. Amazon Bedrock does not use this data for training or improving underlying models.