Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Monitoring with Amazon CloudWatch

You can monitor your Amazon KMS keys using Amazon CloudWatch, an Amazon service that collects and processes raw data from Amazon KMS into readable, near real-time metrics. These data are recorded for a period of two weeks so that you can access historical information and gain a better understanding of the usage of your KMS keys and their changes over time.

You can use Amazon CloudWatch to alert you to important events, such as the following ones.

You can also create an Amazon CloudWatch alarm that alerts you when your request rate reaches a certain percentage of a quota value. For details, see Manage your Amazon KMS API request rates using Service Quotas and Amazon CloudWatch in the Amazon Security Blog.

Amazon KMS metrics and dimensions

Amazon KMS predefines Amazon CloudWatch metrics to make it easier for you to monitor critical data and create alarms. You can view the Amazon KMS metrics using the Amazon Web Services Management Console and the Amazon CloudWatch API.

This section lists each Amazon KMS metrics and the dimensions for each metric, and provides some basic guidance for creating CloudWatch alarms based on these metrics and dimensions.

SecondsUntilKeyMaterialExpiration

The number of seconds remaining until the imported key material in a KMS key expires. This metric is valid only for KMS keys with imported key material (a key material origin of EXTERNAL) and an expiration date.

Use this metric to track the time that remains until your imported key material expires. When that time falls below a threshold that you define, you might want to reimport the key material with a new expiration date. The SecondsUntilKeyMaterialExpiration metric is specific to a KMS key. You cannot use this metric to monitor multiple KMS keys or KMS keys that you might create in the future. For help with creating a CloudWatch alarm to monitor this metric, see Creating a CloudWatch alarm for expiration of imported key material.

The most useful statistic for this metric is Minimum, which tells you the smallest amount of time remaining for all data points in the specified statistical period. The only valid unit for this metric is Seconds.

Dimension group name: Per-Key Metrics

ExternalKeyStoreThrottle

The number of requests for cryptographic operations on KMS keys in each external key store that Amazon KMS throttles (responds with a ThrottlingException). This metric applies only to external key stores.

The ExternalKeyStoreThrottle metric applies only to KMS keys in an external key store and only to requests for cryptographic operations and the DescribeKey operation. Amazon KMS throttles these requests when the request rate exceeds the custom key store request quota for your external key store. This metric does not include throttling by your external key store proxy or external key manager.

Use this metric to review and adjust the value of the your custom key store request quota. If this metric indicates that Amazon KMS is frequently throttling your requests for these KMS keys, you might consider requesting an increase in your custom key store request quota value. For help, see Requesting a quota increase in the Service Quotas User Guide.

If you are getting very frequent KMSInvalidStateException errors with a message that explains that the request was rejected "due to a very high request rate" or the request was rejected "because the external key store proxy did not respond in time," it might indicate that your external key manager or external key store proxy cannot keep pace with the current request rate. If possible, lower your request rate. You might also consider requesting a decrease in your custom key store request quota value. Decreasing this quota value might increase throttling (and the ExternalKeyStoreThrottle metric value), but it indicates that Amazon KMS is rejecting excess requests quickly before they are sent to your external key store proxy or external key manager. To request a quota decrease, please visit the Amazon Web Services Support Center and create a case.

Dimension group name: Keystore Throttle Metrics

XksProxyCertificateDaysToExpire

The number of days until the TLS certificate for your external key store proxy endpoint (XksProxyUriEndpoint) expires. This metric applies only to external key stores.

Use this metric to create a CloudWatch alarm that notifies you about the upcoming expiration of your TLS certificate. When the certificate expires, Amazon KMS cannot communicate with the external key store proxy. All data protected by KMS keys in your external key store becomes inaccessible until you renew the certificate.

A certificate alarm prevents certificate expiration that might prevent you from accessing your encrypted resources. Set the alarm to give your organization time to renew the certificate before it expires.

Dimension group name: XKS Proxy Certificate Metrics

XksProxyCredentialAge

The number of days since the current external key store proxy authentication credential (XksProxyAuthenticationCredential) was associated with the external key store. This count begins when you enter the authentication credential as part of creating or updating your external key store. This metric applies only to external key stores.

This value is designed to remind you about the age of your authentication credential. However, because we begin the count when you associate the credential with your external key store, not when you create your authentication credential on your external key store proxy, this might not be an accurate indicator of the credential age on the proxy.

Use this metric to create a CloudWatch alarm that reminds you to rotate your external key store proxy authentication credential.

Dimension group name: Per-Keystore Metrics

XksProxyErrors

The number of exceptions related to Amazon KMS requests to your external key store proxy. This count includes exceptions that the external key store proxy returns to Amazon KMS and timeout errors that occur when the external key store proxy does not respond to Amazon KMS within the 250 millisecond timeout interval. This metric applies only to external key stores.

Use this metric to track the error rate of KMS keys in your external key store. It reveals the most frequent errors, so you can prioritize your engineering effort. For example, KMS keys that are generating high rates of non-retryable errors might indicate a problem with the configuration of your external key store. To view your external key store configuration, see Viewing an external key store. To edit your external key store settings, see Editing external key store properties.

Dimension group name: XKS Proxy Error Metrics

XksExternalKeyManagerStates

A count of the number of external key manager instances in each of the following health states: Active, Degraded, and Unavailable. The information for this metric comes from the external key store proxy associated with each external key store. This metric applies only to external key stores.

The following are the health states for the external key manager instances associated with an external key store. Each external key store proxy might use different indicators to measure the health states of your external key manager. For details, see the documentation for your external key store proxy.

Use this metric to create a CloudWatch alarm that alerts you to degraded and unavailable external key manager instances. To determine which external key manager instances are in each state, consult your external key store proxy logs.

Dimension group name: XKS External Key Manager Metrics

XksProxyLatency

The number of milliseconds it takes for an external key store proxy to respond to an Amazon KMS request. If the request timed out, the recorded value is the 250 millisecond timeout limit. This metric applies only to external key stores.

Use this metric to evaluate the performance of your external key store proxy and external key manager. For example, if the proxy is frequently timing out on encryption and decryption operations, consult your external proxy administrator.

Slow responses might also indicate that your external key manager cannot handle the current request traffic. Amazon KMS recommends that your external key manager be able to handle up to 1800 requests for cryptographic operations per second. If your external key manager cannot handle the 1800 requests per second rate, consider requesting a decrease in your request quota for KMS keys in a custom key store. Requests for cryptographic operations using the KMS keys in your external key store will fail fast with a throttling exception, rather than being processed and later rejected by your external key store proxy or external key manager.

Dimension group name: XKS Proxy Latency Metrics

Viewing Amazon KMS metrics

You can view the Amazon KMS metrics using the Amazon Web Services Management Console and the Amazon CloudWatch API.

To view metrics using the Amazon CloudWatch API

To view Amazon KMS metrics using the CloudWatch API, send a ListMetrics request with Namespace set to AWS/KMS. The following example shows how to do this with the Amazon Command Line Interface (Amazon CLI).

$  aws cloudwatch list-metrics --namespace AWS/KMS

{
    "Metrics": [
        {
            "Namespace": "AWS/KMS",
            "MetricName": "SecondsUntilKeyMaterialExpiration",
            "Dimensions": [
                {
                    "Name": "KeyId",
                    "Value": "1234abcd-12ab-34cd-56ef-1234567890ab"
                }
            ]
        },
        {
            "Namespace": "AWS/KMS",
            "MetricName": "ExternalKeyStoreThrottle",
            "Dimensions": [
                {
                    "Name": "CustomKeyStoreId",
                    "Value": "cks-1234567890abcdef0"
                },
                {
                    "Name": "KmsOperation",
                    "Value": "Encrypt"
                },
                {
                    "Name": "KeySpec",
                    "Value": "SYMMETRIC_DEFAULT"
                }    
            ]
        },
        {
            "Namespace": "AWS/KMS",
            "MetricName": "XksProxyCertificateDaysToExpire",
            "Dimensions": [
                {
                    "Name": "CustomKeyStoreId",
                    "Value": "cks-1234567890abcdef0"
                },
                {
                    "Name": "CertificateName",
                    "Value": "myproxy.xks.example.com"
                }    
            ]
        },
        {
            "Namespace": "AWS/KMS",
            "MetricName": "XksProxyCredentialAge",
            "Dimensions": [
                {
                    "Name": "CustomKeyStoreId",
                    "Value": "cks-1234567890abcdef0"
                }
            ]
        },
        {
            "Namespace": "AWS/KMS",
            "MetricName": "XksProxyErrors",
            "Dimensions": [
                {
                    "Name": "CustomKeyStoreId",
                    "Value": "cks-1234567890abcdef0"
                },
                {
                    "Name": "KmsOperation",
                    "Value": "Decrypt"
                },
                {
                    "Name": "XksOperation",
                    "Value": "Decrypt"
                },
                {
                     "Name": "KeySpec",
                     "Value": "SYMMETRIC_DEFAULT"
                },
                {
                    "Name": "ErrorType",
                    "Value": "Retryable errors"
                },
                {
                     "Name": "ExceptionName",
                     "Value": "KMSInvalidStateException"
                }                
            ]
        },
        {
            "Namespace": "AWS/KMS",
            "MetricName": "XksProxyHsmStates",
            "Dimensions": [
                {
                    "Name": "CustomKeyStoreId",
                    "Value": "cks-1234567890abcdef0"
                },
                {
                    "Name": "XksProxyHsmState",
                    "Value": "Active"
                }
            ]
        },
        {
            "Namespace": "AWS/KMS",
            "MetricName": "XksProxyLatency",
            "Dimensions": [
                {
                    "Name": "CustomKeyStoreId",
                    "Value": "cks-1234567890abcdef0"
                },
                {
                    "Name": "KmsOperation",
                    "Value": "Decrypt"
                },
                {
                    "Name": "XksOperation",
                    "Value": "Decrypt"
                },
                {
                     "Name": "KeySpec",
                     "Value": "SYMMETRIC_DEFAULT"
                }                
            ]
        }
    ]
}

Creating CloudWatch alarms to monitor KMS keys

You can create an Amazon CloudWatch alarm based on an Amazon KMS metric. The alarm sends an email message when a metric value exceeds a threshold specified in the alarm configuration. The alarm can send the email message to an Amazon Simple Notification Service (Amazon SNS) topic or an Amazon EC2 Auto Scaling policy. For detailed information about CloudWatch alarms, see Using Amazon CloudWatch alarms in the Amazon CloudWatch User Guide

Create an alarm for expiring imported key material

You can use the SecondsUntilKeyMaterialExpiration metric to create a CloudWatch alarm that notifies you when the imported key material in a KMS key is about to expire.

When you import key material into a KMS key, you can optionally specify a date and time when the key material expires. When the key material expires, Amazon KMS deletes the key material and the KMS key becomes unusable. To use the KMS key again, you must reimport the key material.

For instructions, see Creating a CloudWatch alarm for expiration of imported key material.

Create an alarm for use of KMS keys that are pending deletion

When you schedule deletion of a KMS key, Amazon KMS enforces a waiting period before deleting the KMS key. You can use the waiting period to ensure that you don't need the KMS key now or in the future. You can also configure a CloudWatch alarm to warn you if a person or application attempts to use the KMS key in a cryptographic operation during the waiting period. If you receive a notification from such an alarm, you might want to cancel deletion of the KMS key.

For instructions, see Creating an alarm that detects use of a KMS key pending deletion.

Create an alarm to monitor an external key store

You can create CloudWatch alarms based on the metrics for external key stores and KMS keys in external key stores.

For example, we recommend that you set a CloudWatch alarm to notify you when the TLS certificate for your external key store is about to expire (XksProxyCertificateDaysToExpire), when your and when your external key store proxy reports that your external key manager instances are in a degraded or unavailable state (XksProxyHsmStates).

For instructions, see Monitoring an external key store.