service-quotas

AWS service quotas near their limit, by CloudWatch

Returns, for each resource AWS counts against a service quota in a region (the vCPUs of a family of EC2 instances, the Elastic IPs, the tables of DynamoDB…), its usage, its quota and the part of the quota in use, read through CloudWatch with an access key that may only read. A quota reached refuses the next resource, or the next instance. One watch is offered, set on the probe.

The Service Quotas API is not asked: it gives a quota's limit, never its usage. The usage is a metric of the namespace AWS/Usage, which some services send to CloudWatch, and the CloudWatch function SERVICE_QUOTA() gives the quota of such a metric: the pair AWS documents for an alarm near a quota (m1/SERVICE_QUOTA(m1)*100).

Versions

Generic: the usage metrics are sent by the services that integrate them with Service Quotas (Amazon EC2, DynamoDB, CloudWatch Logs, Elastic Load Balancing, AWS Fargate, AWS KMS… the list of "Visualizing your service quotas and setting alarms"). The collector asks for the version 2010-08-01 of the CloudWatch API in the Query protocol, which AWS says it keeps supporting beside the JSON protocol its newer SDKs use.

How it works

1. GET https://monitoring.<aws:region>.amazonaws.com/?Action=ListMetrics&MetricName=ResourceCount&Namespace=AWS%2FUsage&Version=2010-08-01, with Dimensions.member.1.Name=Service&Dimensions.member.1.Value=<aws:service> when it is set, page after page by NextToken: the usage metrics of the region, each with its dimensions Service, Type, Resource and Class.

<ListMetricsResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
  <ListMetricsResult>
    <Metrics>
      <member>
        <Dimensions>
          <member><Name>Service</Name><Value>EC2</Value></member>
          <member><Name>Type</Name><Value>Resource</Value></member>
          <member><Name>Resource</Name><Value>vCPU</Value></member>
          <member><Name>Class</Name><Value>Standard/OnDemand</Value></member>
        </Dimensions>
        <MetricName>ResourceCount</MetricName>
        <Namespace>AWS/Usage</Namespace>
      </member>
    </Metrics>
    <NextToken>…</NextToken>
  </ListMetricsResult>
  <ResponseMetadata><RequestId>…</RequestId></ResponseMetadata>
</ListMetricsResponse>

2. GET https://monitoring.<aws:region>.amazonaws.com/?Action=GetMetricData&StartTime=<now − 1 h>&EndTime=<now>&Version=2010-08-01&MetricDataQueries.member.1.Id=u1&MetricDataQueries.member.1.MetricStat.Metric.Namespace=AWS%2FUsage&MetricDataQueries.member.1.MetricStat.Metric.MetricName=ResourceCount&MetricDataQueries.member.1.MetricStat.Metric.Dimensions.member.1.Name=Service&…&MetricDataQueries.member.1.MetricStat.Period=300&MetricDataQueries.member.1.MetricStat.Stat=Maximum&MetricDataQueries.member.2.Id=q1&MetricDataQueries.member.2.Expression=SERVICE_QUOTA(u1)&…, twenty metrics a request: for each, the query u<n> reads its maximum over five minutes, and the query q<n> its quota.

<GetMetricDataResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
  <GetMetricDataResult>
    <MetricDataResults>
      <member><Id>u1</Id><StatusCode>Complete</StatusCode><Timestamps><member>2026-10-28T08:00:00Z</member></Timestamps><Values><member>17</member></Values></member>
      <member><Id>q1</Id><StatusCode>Complete</StatusCode><Timestamps><member>2026-10-28T08:00:00Z</member></Timestamps><Values><member>32</member></Values></member>
    </MetricDataResults>
  </GetMetricDataResult>
  <ResponseMetadata><RequestId>…</RequestId></ResponseMetadata>
</GetMetricDataResponse>

Every request is signed by aws.sign (Signature Version 4, service monitoring).

• A quota is named by its Service, Resource and Class, joined by /, a Class of None left out: EC2/vCPU/Standard/OnDemand, EC2/IPv4Address.
• usage and limit are the newest values of u<n> and q<n>, which GetMetricData gives newest first; used is usage × 100 / limit, to the tenth. A quota of 0 gives no used: the account may not use that resource at all.
• A usage metric without a value in the hour, or without a quota (SERVICE_QUOTA returns nothing for a metric Service Quotas does not know), is left out.
• No usage metric in the region stops the collector misconfigured: a region or a service that sends none. Usage metrics without a single quota read stop it misconfigured too, rather than leave a probe that can never raise.
• A region with other characters than lower-case letters, digits and hyphens stops the collector misconfigured before anything leaves. A code 400, 401 or 403 stops it misconfigured, with the error code AWS writes (InvalidParameterValue, AccessDenied, SignatureDoesNotMatch…); a throttled request (Throttling), a code 500 or above, or any other code but 200 stops it unreachable.

The keys come from protocol:aws: the secret key never leaves the poller, only the signature it makes. The answers are not secret.

Prerequisites

• An IAM user with an access key, or a role whose temporary keys are set with their session token, allowed these actions and nothing else:

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": ["cloudwatch:ListMetrics", "cloudwatch:GetMetricData"], "Resource": "*" }
  ]
}

AWS does not say whether SERVICE_QUOTA() needs a permission of Service Quotas besides (below): if the collector stops on "no quota" while the usage metrics are listed, servicequotas:GetServiceQuota is the one to try. The access key ID goes in protocol:aws:access-key-id, the secret key in protocol:aws:secret-access-key, the session token, for temporary keys only, in protocol:aws:session-token.

• The poller reaches monitoring.<region>.amazonaws.com in HTTPS, and its clock is right within a few minutes: AWS refuses a request signed more than fifteen minutes away from its own time. The certificates of AWS are issued by public authorities: the profile "Standard" trusts them.

Variables

Outputs

Watches

Limits

• The usage counted is that of the metric ResourceCount: the quotas of resources. The rates of API calls (CallCount), whose quotas are per second, are not read.
• A service that does not send its usage to CloudWatch has none of its quotas here.
• Not checked against an AWS account, and less certain than the other AWS collectors of this collection: - the shape of the request and of the answer of GetMetricData in the Query protocol (the nested parameters MetricDataQueries.member.N.MetricStat.Metric.Dimensions.member.K.Name, the lists Timestamps and Values under member) is read from the Smithy specification "AWS query protocol" and the structure of the API Reference, which gives its samples in JSON only; - that SERVICE_QUOTA() answers through GetMetricData as it does on a graph, and the permissions it needs, are not written by AWS: its documentation shows it on a graph and an alarm of the console; - that the statistic Maximum over five minutes is the one to read is the collector's choice; AWS does not name one for ResourceCount.
• The action and its limits (500 queries a request, the values newest first by default) are those of the Amazon CloudWatch API Reference ("GetMetricData", "ListMetrics"); the usage metrics and SERVICE_QUOTA those of the CloudWatch User Guide ("AWS usage metrics", "Visualizing your service quotas and setting alarms").