This is a fork of the official repository.
Because of some specific requirements I have around performance, I decide to fork the official repository and implement some improvements.
Things that I have worked so far:
- Added thread support on the CloudWatch scraping, so a big list of metrics can be retrieved in an acceptable time;
- Adding proxy support, if you set the environment variable http_proxy, that will be passed on to the AWS SDK;
- Added support to configure the service using environment variables, for now:
- CLOUDWATCH_THREADS: number of threads while scraping Cloudwatch metrics. Default=10
- CLOUDWATCH_MAXCONNECTIONS: Max number of active connections on the AWS SDK. Default=150
- Improvements in error logs;
- Updated dependencies;
- Fixed use of deprecated AWS SDK classes;
If you have feedback, just let me know. Now on with the official documentation...
An exporter for Amazon CloudWatch, for Prometheus.
mvn package to build.
java -jar target/cloudwatch_exporter-0.5-SNAPSHOT-jar-with-dependencies.jar 9106 example.yml to run.
The most recent pre-built JAR can be found at http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22cloudwatch_exporter%22
The CloudWatch Exporter uses the
AWS Java SDK,
which offers a variety of ways to provide credentials.
This includes the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment
variables.
The cloudwatch:ListMetrics and cloudwatch:GetMetricStatistics IAM permissions are required.
The configuration is in YAML, an example with common options:
---
region: eu-west-1
metrics:
- aws_namespace: AWS/ELB
aws_metric_name: RequestCount
aws_dimensions: [AvailabilityZone, LoadBalancerName]
aws_dimension_select:
LoadBalancerName: [myLB]
aws_statistics: [Sum]
| Name | Description |
|---|---|
| region | Required. The AWS region to connect to. |
| role_arn | Optional. The AWS role to assume. Useful for retrieving cross account metrics. |
| metrics | Required. A list of CloudWatch metrics to retrieve and export |
| aws_namespace | Required. Namespace of the CloudWatch metric. |
| aws_metric_name | Required. Metric name of the CloudWatch metric. |
| aws_dimensions | Optional. Which dimension to fan out over. |
| aws_dimension_select | Optional. Which dimension values to filter. Specify a map from the dimension name to a list of values to select from that dimension. |
| aws_dimension_select_regex | Optional. Which dimension values to filter on with a regular expression. Specify a map from the dimension name to a list of regexes that will be applied to select from that dimension. |
| aws_statistics | Optional. A list of statistics to retrieve, values can include Sum, SampleCount, Minimum, Maximum, Average. Defaults to all statistics unless extended statistics are requested. |
| aws_extended_statistics | Optional. A list of extended statistics to retrieve. Extended statistics currently include percentiles in the form pN or pN.N. |
| delay_seconds | Optional. The newest data to request. Used to avoid collecting data that has not fully converged. Defaults to 600s. Can be set globally and per metric. |
| range_seconds | Optional. How far back to request data for. Useful for cases such as Billing metrics that are only set every few hours. Defaults to 600s. Can be set globally and per metric. |
| period_seconds | Optional. Period to request the metric for. Only the most recent data point is used. Defaults to 60s. Can be set globally and per metric. |
The above config will export time series such as
# HELP aws_elb_request_count_sum CloudWatch metric AWS/ELB RequestCount Dimensions: ["AvailabilityZone","LoadBalancerName"] Statistic: Sum Unit: Count
# TYPE aws_elb_request_count_sum gauge
aws_elb_request_count_sum{job="aws_elb",load_balancer_name="mylb",availability_zone="eu-west-1c",} 42.0
aws_elb_request_count_sum{job="aws_elb",load_balancer_name="myotherlb",availability_zone="eu-west-1c",} 7.0
All metrics are exported as gauges.
Timestamps from CloudWatch are not passed to Prometheus, pending resolution of
#398. CloudWatch has
been observed to sometimes take minutes for reported values to converge. The
default delay_seconds will result in data that is at least 10 minutes old
being requested to mitigate this.
In addition cloudwatch_exporter_scrape_error will be non-zero if an error
occurred during the scrape, and cloudwatch_exporter_scrape_duration_seconds
contains the duration of that scrape.
The DynamoDB metrics listed below break the usual CloudWatch data model.
- ConsumedReadCapacityUnits
- ConsumedWriteCapacityUnits
- ProvisionedReadCapacityUnits
- ProvisionedWriteCapacityUnits
- ReadThrottleEvents
- WriteThrottleEvents
When these metrics are requested in the TableName dimension CloudWatch will return data only for the table itself, not for its Global Secondary Indexes. Retrieving data for indexes requires requesting data across both the TableName and GlobalSecondaryIndexName dimensions. This behaviour is different to that of every other CloudWatch namespace and requires that the exporter handle these metrics differently to avoid generating duplicate HELP and TYPE lines.
When exporting one of the problematic metrics for an index the exporter will use
a metric name in the format aws_dynamodb_METRIC_index_STATISTIC rather than
the usual aws_dynamodb_METRIC_STATISTIC. The regular naming scheme will still
be used when exporting these metrics for a table, and when exporting any other
DynamoDB metrics not listed above.
Amazon charges for every API request, see the current charges.
Every metric retrieved requires one API request, which can include multiple
statistics. In addition, when aws_dimensions is provided, the exporter needs
to do API requests to determine what metrics to request. This should be
negligible compared to the requests for the metrics themselves.
If you have 100 API requests every minute, with the price of USD$10 per million
requests (as of Jan 2015), that is around $45 per month. The
cloudwatch_requests_total counter tracks how many requests are being made.
To run the CloudWatch exporter on Docker, you can use the prom/cloudwatch-exporter
image. It exposes port 9106 and expects the config in /config/config.yml. To
configure it, you can either bind-mount a config from your host:
$ docker run -p 9106 -v /path/on/host/config.yml:/config/config.yml prom/cloudwatch-exporter
Or you create a config file named /config/config.yml along with following
Dockerfile in the same directory and build it with docker build:
FROM prom/cloudwatch-exporter