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.

Amazon DocumentDB Metrics

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

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.

To view CloudWatch metrics using the Amazon DocumentDB Management Console, complete the following steps.

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 Clusters.

   Tip

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

3. In the Clusters navigation box, you’ll see the column Cluster Identifier. Your instances are listed under clusters, similar to the screenshot below.

   

4. From the list of instances, choose the name of the instance that you want metrics for.

5. In the resulting instance summary page, choose the Monitoring tab to view graphical representations of your Amazon DocumentDB instance’s metrics. 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 the graphical representations of two CloudWatch metrics in the Amazon DocumentDB console, WriteIOPS and ReadIOPS.

   ![

                       Two of the 18 CloudWatch metrics in the Amazon DocumentDB console,
                          writeiops and readiops.
                    ](/projects/DocumentDB-20201111-en/50e0cedef3945b0631ae9a4d22a081aa.png)

To view CloudWatch metrics using the CloudWatch Management Console, complete the following steps.

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

2. In the navigation pane, choose Metrics. Then, from the list of service names, choose DocDB.

3. Choose a metric dimension (for example, Cluster Metrics).

4. The All metrics tab displays all metrics for that dimension in DocDB.

   1. To sort the table, use the column heading.

   2. To graph a metric, select the check box next to the metric. To select all metrics, select the check box in the heading row of the table.

   3. To filter by metric, hover over the metric name and select the drop-down arrow next tot he metric name. Then, choose Add to search, as shown in the image below.

      ![

                                Filter for a metric by hovering over the 
                                   metric and selecting "Add to search".
                             ](/projects/DocumentDB-20201111-en/fdf65743bb13c8dd32bd4f915cca6d46.png)

To view CloudWatch data for Amazon DocumentDB, use 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 look something like the following.

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

Monitoring Opcounters

Opcounter metrics have a non-zero value (usually ~50) for idle clusters. This is because Amazon DocumentDB performs periodic health checks, internal operations, and metrics collection tasks.

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.