Amazon DocumentDB
Developer Guide

Monitoring Amazon DocumentDB with CloudWatch

Amazon DocumentDB (with MongoDB compatibility) integrates with Amazon CloudWatch so that you can gather and analyze operational metrics for your clusters. You can monitor these metrics using the CloudWatch console, the Amazon DocumentDB console, the AWS Command Line Interface (AWS CLI), or the CloudWatch API.

CloudWatch also lets you set alarms so that you can be notified if a metric value breaches a threshold that you specify. You can even set up Amazon CloudWatch Events to take corrective action if a breach occurs. For more information about using CloudWatch and alarms, see the Amazon CloudWatch documentation.

Viewing CloudWatch Data

You can view Amazon CloudWatch data using the CloudWatch console, the Amazon DocumentDB console, AWS Command Line Interface (AWS CLI), or the CloudWatch API.

CloudWatch Instance Metrics That Appear in the Amazon DocumentDB Console

To monitor the health and performance of your Amazon DocumentDB instance, you can view the following instance metrics in the Amazon DocumentDB console.

  • CPUUtilization

  • DatabaseConnections

  • FreeLocalStorage

  • FreeableMemory

  • WriteIOPS

  • ReadIOPS

  • WriteLatency

  • ReadLatency

  • WriteThroughput

  • ReadThroughput

  • NetworkThroughput

  • NetworkTransmitThroughput

  • NetworkReceiveThroughput

  • EngineUptime

  • SwapUsage

  • DiskQueueDepth

  • BufferCacheHitRatio

  • BackupRetentionPeriodStorageUsed

  • SnapshotStorageUsed

  • TotalBackupStorageBilled

Viewing CloudWatch Data (Amazon DocumentDB Console)

To view CloudWatch metrics using the Amazon DocumentDB console

  1. Sign in to the AWS Management Console, and open the Amazon DocumentDB console at https://console.aws.amazon.com/docdb.

  2. In the navigation pane, choose Instances. Then from the list of instances, choose the name of the instance that you want metrics for.

    Tip

    If you do not see the navigation pane on the left side of your screen, choose the menu icon () in the upper-left corner of the page.

    To view graphical representations of the instances' metrics, scroll down the page until you get to the CloudWatch section. Because a graph must be generated for each metric, it might take a few minutes for the CloudWatch graphs to populate. The following image shows 2 of the 17 CloudWatch metrics in the Amazon DocumentDB console.

    
                     Two of the 17 CloudWatch metrics in the Amazon DocumentDB console, writeiops and readiops.

Viewing CloudWatch Data (AWS CLI)

You can view CloudWatch data for Amazon DocumentDB using the CloudWatch get-metric-statistics operation with the following parameters:

Parameters

  • --namespace—Required. The service namespace for which you want CloudWatch metrics. For Amazon DocumentDB, this must be AWS/DocDB.

  • --metric-name—Required. The name of the metric for which you want data.

  • --start-time—Required. The timestamp that determines the first data point to return.

    The value specified is inclusive; results include data points with the specified timestamp. The timestamp must be in ISO 8601 UTC format (for example, 2016-10-03T23:00:00Z).

  • --end-time—Required. The timestamp that determines the last data point to return.

    The value specified is inclusive; results include data points with the specified timestamp. The timestamp must be in ISO 8601 UTC format (for example, 2016-10-03T23:00:00Z).

  • --period—Required. The granularity, in seconds, of the returned data points. For metrics with regular resolution, a period can be as short as one minute (60 seconds) and must be a multiple of 60. For high-resolution metrics that are collected at intervals of less than one minute, the period can be 1, 5, 10, 30, 60, or any multiple of 60.

  • --dimensions—Optional. If the metric contains multiple dimensions, you must include a value for each dimension. CloudWatch treats each unique combination of dimensions as a separate metric. If a specific combination of dimensions was not published, you can't retrieve statistics for it. You must specify the same dimensions that were used when the metrics were created.

  • --statistics—Optional. The metric statistics, other than percentile. For percentile statistics, use ExtendedStatistics. When calling GetMetricStatistics, you must specify either Statistics or ExtendedStatistics, but not both.

    Permitted values:

    • SampleCount

    • Average

    • Sum

    • Minimum

    • Maximum

  • --extended-statistics—Optional. The percentile statistics. Specify values between p0.0 and p100. When calling GetMetricStatistics, you must specify either Statistics or ExtendedStatistics, but not both.

  • --unit—Optional. The unit for a given metric. Metrics may be reported in multiple units. Not supplying a unit results in all units being returned. If you specify only a unit that the metric does not report, the results of the call are null.

    Possible values:

    • Seconds

    • Microseconds

    • Milliseconds

    • Bytes

    • Kilobytes

    • Megabytes

    • Gigabytes

    • Terabytes

    • Bits

    • Kilobytes

    • Megabits

    • Gigabits

    • Terabits

    • Percent

    • Count

    • Bytes/Second

    • Kilobytes/Second

    • Megabytes/Second

    • Gigabytes/Second

    • Terabytes/Second

    • Bits/Second

    • Kilobits/Second

    • Megabits/Second

    • Gigabits/Second

    • Terabits/Second

    • Count/Second

    • None

The following example finds the maximum CPUUtilization for a 2-hour period taking a sample every 60 seconds.

For Linux, macOS, or Unix:

aws cloudwatch get-metric-statistics \ --namespace AWS/DocDB \ --dimensions \ Name=DBInstanceIdentifier,Value=docdb-2019-01-09-23-55-38 \ --metric-name CPUUtilization \ --start-time 2019-02-11T05:00:00Z \ --end-time 2019-02-11T07:00:00Z \ --period 60 \ --statistics Maximum

For Windows:

aws cloudwatch get-metric-statistics ^ --namespace AWS/DocDB ^ --dimensions ^ Name=DBInstanceIdentifier,Value=docdb-2019-01-09-23-55-38 ^ --metric-name CPUUtilization ^ --start-time 2019-02-11T05:00:00Z ^ --end-time 2019-02-11T07:00:00Z ^ --period 60 ^ --statistics Maximum

Output from this operation looks something like the following (JSON format).

{ "Label": "CPUUtilization", "Datapoints": [ { "Unit": "Percent", "Maximum": 4.49152542374361, "Timestamp": "2019-02-11T05:51:00Z" }, { "Unit": "Percent", "Maximum": 4.25000000000485, "Timestamp": "2019-02-11T06:44:00Z" }, ********* some output omitted for brevity ********* { "Unit": "Percent", "Maximum": 4.33333333331878, "Timestamp": "2019-02-11T06:07:00Z" } ] }

Amazon DocumentDB Metrics

The following Amazon DocumentDB metrics are available through Amazon CloudWatch. You can use them to monitor various aspects of your Amazon DocumentDB deployment, such as replication lag, disk usage, CPU usage, and more. Amazon DocumentDB sends metrics to CloudWatch only when they have a non-zero value.

Metric Description
BackupRetentionPeriodStorageUsed The total amount of backup storage in GiB used to support the point-in-time restore feature within the Amazon DocumentDB's retention window. Included in the total reported by the TotalBackupStorageBilled metric. Computed separately for each Amazon DocumentDB cluster.
BufferCacheHitRatio The percentage of requests that are served by the buffer cache.
CPUUtilization The percentage of CPU used by an instance.
DatabaseConnections The number of connections to an instance.
DBInstanceReplicaLag The amount of lag, in milliseconds, when replicating updates from the primary instance to a replica instance.
DBClusterReplicaLagMaximum The maximum amount of lag, in milliseconds, between the primary instance and each Amazon DocumentDB instance in the cluster.
DBClusterReplicaLagMinimum The minimum amount of lag, in milliseconds, between the primary instance and each replica instance in the cluster.
DiskQueueDepth The number of outstanding read/write requests waiting to access the disk.
EngineUptime The amount of time, in seconds, that the instance has been running.
FreeableMemory The amount of available random access memory, in bytes.
FreeLocalStorage

This metric reports the amount of storage available to each instance for temporary tables and logs. This value depends on the instance class. You can increase the amount of free storage space for an instance by choosing a larger instance class for your instance.

NetworkReceiveThroughput The amount of network throughput, in bytes per second, received from clients by each instance in the cluster. This throughput doesn't include network traffic between instances in the cluster and the cluster volume.
NetworkThroughput The amount of network throughput, in bytes per second, both received from and transmitted to clients by each instance in the Amazon DocumentDB cluster. This throughput doesn't include network traffic between instances in the cluster and the cluster volume.
NetworkTransmitThroughput The amount of network throughput, in bytes per second, sent to clients by each instance in the cluster. This throughput doesn't include network traffic between instances in the cluster and the cluster volume.
ReadIOPS The average number of disk read I/O operations per second. Amazon DocumentDB reports read and write IOPS separately, and on one-minute intervals.
ReadLatency The average amount of time taken per disk I/O operation.
ReadThroughput The average number of bytes read from disk per second.
SnapshotStorageUsed The total amount of backup storage in GiB consumed by all snapshots for a given Amazon DocumentDB cluster outside its backup retention window. Included in the total reported by the TotalBackupStorageBilled metric. Computed separately for each Amazon DocumentDB cluster.
SwapUsage The amount of swap space used on the instance.
TotalBackupStorageBilled The total amount of backup storage in GiB for which you are billed for a given Amazon DocumentDB cluster. Includes the backup storage measured by the BackupRetentionPeriodStorageUsed and SnapshotStorageUsed metrics. Computed separately for each Amazon DocumentDB cluster.
VolumeBytesUsed The amount of storage, in bytes, used by your cluster, in bytes. This value affects the cost of the cluster (for pricing information, see the Amazon DocumentDB product page).
VolumeReadIOPs The average number of billed read I/O operations from a cluster volume, reported at 5-minute intervals. Billed read operations are calculated at the cluster volume level, aggregated from all instances in the cluster, and then reported at 5-minute intervals. The value is calculated by taking the value of the read operations metric over a 5-minute period. You can determine the amount of billed read operations per second by taking the value of the billed read operations metric and dividing by 300 seconds. For example, if the billed read operations returns 13,686, then the billed read operations per second is 45 (13,686 / 300 = 45.62). You accrue billed read operations for queries that request database pages that are not present in the buffer cache and therefore must be loaded from storage. You might see spikes in billed read operations as query results are read from storage and then loaded into the buffer cache.
VolumeWriteIOPs The average number of billed write I/O operations from a cluster volume, reported at 5-minute intervals. Billed write operations are calculated at the cluster volume level, aggregated from all instances in the cluster, and then reported at 5-minute intervals. The value is calculated by taking the value of the write operations metric over a 5-minute period. You can determine the amount of billed write operations per second by taking the value of the billed write operations metric and dividing by 300 seconds. For example, if the billed write operations returns 13,686, then the billed write operations per second is 45 (13,686 / 300 = 45.62).
WriteIOPS The average number of disk write I/O operations per second. Read and write IOPS are reported separately, on 1-minute intervals.
WriteLatency The average amount of time, in milliseconds, taken per disk I/O operation.
WriteThroughput The average number of bytes written to disk per second.

Amazon DocumentDB Dimensions

The metrics for Amazon DocumentDB are qualified by the values for the account or operation. You can use the CloudWatch console to retrieve Amazon DocumentDB data filtered by any of the dimensions in the following table.

Dimension Description
DBClusterIdentifier Filters the data that you request for a specific Amazon DocumentDB cluster.
DBClusterIdentifier, Role Filters the data that you request for a specific Amazon DocumentDB cluster, aggregating the metric by instance role (WRITER/READER). For example, you can aggregate metrics for all READER instances that belong to a cluster.
DBInstanceIdentifier Filters the data that you request for a specific database instance.

Monitoring Database Connections

When you view the number of connections by using database engine commands such as db.runCommand( { serverStatus: 1 }), you might see up to 10 more connections than you see in DatabaseConnections through CloudWatch. This occurs because Amazon DocumentDB performs periodic health checks and metrics collection tasks that don't get accounted for in DatabaseConnections. DatabaseConnections represents customer-initiated connections only.