Monitoring with Amazon CloudWatch - Amazon Quantum Ledger Database (Amazon QLDB)
Using metricsMetrics and dimensionsCreating alarms

Monitoring with Amazon CloudWatch

Important

End of support notice: Existing customers will be able to use Amazon QLDB until end of support on 07/31/2025. For more details, see Migrate an Amazon QLDB Ledger to Amazon Aurora PostgreSQL.

You can monitor Amazon QLDB using CloudWatch, which collects and processes raw data from Amazon QLDB into readable, near-real-time metrics. It records these statistics for two weeks so that you can access historical information and gain a better perspective on how your web application or service is performing. By default, QLDB metric data is automatically sent to CloudWatch in 1 or 15-minute periods. For more information, see What are Amazon CloudWatch, Amazon CloudWatch Events, and Amazon CloudWatch Logs? in the Amazon CloudWatch User Guide.

How do I use QLDB metrics?

The metrics reported by QLDB provide information that you can analyze in different ways. The following list shows some common uses for the metrics. These are suggestions to get you started, not a comprehensive list.

  • You can monitor JournalStorage and IndexedStorage over a specified time period, to track how much disk space your ledger is consuming.

  • You can monitor ReadIOs and WriteIOs over a specified time period, to track how many requests your ledger is processing.

  • You can monitor CommandLatency to track your ledger's performance for data operations and analyze the types of commands that result in the most latency.

Amazon QLDB metrics and dimensions

When you interact with Amazon QLDB, it sends the following metrics and dimensions to CloudWatch. Storage metrics are reported every 15 minutes, and all other metrics are aggregated and reported every minute. You can use the following procedures to view the metrics for QLDB.

To view metrics using the CloudWatch console

Metrics are grouped first by the service namespace, and then by the various dimension combinations within each namespace.

  1. Open the CloudWatch console at https://console.aws.amazon.com/cloudwatch/.

  2. If necessary, change the Region. On the navigation bar, choose the Region where your AWS resources reside. For more information, see Regions and endpoints.

  3. In the navigation pane, choose Metrics.

  4. Under the All metrics tab, choose QLDB.

To view metrics using the AWS CLI

  • At a command prompt, use the following command.

    aws cloudwatch list-metrics --namespace "AWS/QLDB"

CloudWatch displays the following metrics for QLDB.

Amazon QLDB dimensions and metrics

The metrics and dimensions that Amazon QLDB sends to Amazon CloudWatch are listed here.

QLDB metrics

Metric Description
JournalStorage

The total amount of disk space used by the ledger's journal, reported in 15-minute intervals. The journal contains the complete, immutable, and verifiable history of all the changes to your data.

Units: Bytes

Dimensions: LedgerName
IndexedStorage

The total amount of disk space used by the ledger's tables, indexes, and indexed history, reported in 15-minute intervals. Indexed storage consists of ledger data that is optimized for high-performance queries. The maximum is 16 TiB.

Units: Bytes

Dimensions: LedgerName
ReadIOs

The number of read I/O requests, reported in one-minute intervals. This captures all types of read operations, including data transactions, verification requests, journal exports, and journal streams.

Units: Count

Dimensions: LedgerName
WriteIOs

The number of write I/O requests, reported in one-minute intervals.

Units: Count

Dimensions: LedgerName
CommandLatency

The amount of time taken for data operations, reported in one-minute intervals.

Units: Milliseconds

Dimensions: CommandType, LedgerName
IsImpaired

The flag that indicates if a journal stream to Kinesis Data Streams is impaired, reported in one-minute intervals. A value of 1 indicates that the stream is in impaired state, and 0 indicates otherwise.

Units: Boolean (0 or 1)

Dimensions: LedgerName, StreamId
OccConflictExceptions

The number of requests to QLDB that generate an OccConflictException. For information about optimistic concurrency control (OCC), see Amazon QLDB concurrency model.

Units: Count
Session4xxExceptions

The number of requests to QLDB that generate an HTTP 4xx error.

Units: Count
Session5xxExceptions

The number of requests to QLDB that generate an HTTP 5xx error.

Units: Count
SessionRateExceededExceptions

The number of requests to QLDB that generate a SessionRateExceededException.

Units: Count

Dimensions for QLDB metrics

The metrics for QLDB are qualified by the values for the account, ledger name, stream ID, or command type. You can use the CloudWatch console to retrieve QLDB data along any of the dimensions in the following table.

Dimension Description
LedgerName

This dimension limits the data to a specific ledger. This value can be any ledger name in the current AWS Region and the current AWS account.
StreamId

This dimension limits the data to a specific journal stream. This value can be any stream ID for a ledger in the current AWS Region and the current AWS account.
CommandType

This dimension limits the data to one of the following QLDB data API commands:

  • AbortTransaction

  • CommitTransaction

  • EndSession

  • ExecuteStatement

  • FetchPage

  • StartSession

  • StartTransaction

To learn how QLDB uses these commands to manage data operations, see Session management with the driver.

Creating CloudWatch alarms to monitor Amazon QLDB

You can create an Amazon CloudWatch alarm that sends an Amazon Simple Notification Service (Amazon SNS) message when the alarm changes state. An alarm watches a single metric over a time period that you specify. It performs one or more actions based on the value of the metric relative to a given threshold over a number of time periods. The action is a notification sent to an Amazon SNS topic or Auto Scaling policy.

Alarms invoke actions for sustained state changes only. CloudWatch alarms do not invoke actions simply because they are in a particular state. The state must have changed and been maintained for a specified number of periods.

For more information about creating CloudWatch alarms, see Using Amazon CloudWatch alarms in the Amazon CloudWatch User Guide.