Monitor KMS keys with Amazon CloudWatch

You can monitor your AWS KMS keys using Amazon CloudWatch, an AWS service that collects and processes raw data from AWS 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 AWS KMS API request rates using Service Quotas and Amazon CloudWatch in the AWS Security Blog.

AWS KMS metrics and dimensions

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

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

You can view AWS KMS metrics using the AWS Management Console and the Amazon CloudWatch API. For more information, see View available metrics in the Amazon CloudWatch User Guide.

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 Create 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

When you schedule deletion of a KMS key, AWS 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 Create an alarm that detects use of a KMS key pending deletion.

ExternalKeyStoreThrottle

The number of requests for cryptographic operations on KMS keys in each external key store that AWS 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. AWS 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 AWS 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 AWS 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 AWS 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, AWS 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

You can create CloudWatch alarms based on the metrics for external key stores and KMS keys in external key stores. For instructions, see Monitor external key stores.

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

You can create CloudWatch alarms based on the metrics for external key stores and KMS keys in external key stores. For instructions, see Monitor external key stores.

XksProxyErrors

The number of exceptions related to AWS KMS requests to your external key store proxy. This count includes exceptions that the external key store proxy returns to AWS KMS and timeout errors that occur when the external key store proxy does not respond to AWS 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 View external key stores. To edit your external key store settings, see Edit external key store properties.

Dimension group name: XKS Proxy Error Metrics

You can create CloudWatch alarms based on the metrics for external key stores and KMS keys in external key stores. For instructions, see Monitor external key stores.

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

You can create CloudWatch alarms based on the metrics for external key stores and KMS keys in external key stores. For instructions, see Monitor external key stores.

XksProxyLatency

The number of milliseconds it takes for an external key store proxy to respond to an AWS 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. AWS 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

You can create CloudWatch alarms based on the metrics for external key stores and KMS keys in external key stores. For instructions, see Monitor external key stores.