{"id":13561715,"url":"https://github.com/prometheus/cloudwatch_exporter","last_synced_at":"2025-04-03T17:31:30.188Z","repository":{"id":25291664,"uuid":"28717741","full_name":"prometheus/cloudwatch_exporter","owner":"prometheus","description":"Metrics exporter for Amazon AWS CloudWatch","archived":false,"fork":false,"pushed_at":"2024-12-28T07:22:38.000Z","size":679,"stargazers_count":913,"open_issues_count":47,"forks_count":327,"subscribers_count":19,"default_branch":"master","last_synced_at":"2024-12-28T08:20:53.736Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prometheus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-01-02T15:49:44.000Z","updated_at":"2024-12-28T07:22:40.000Z","dependencies_parsed_at":"2024-02-22T22:26:54.849Z","dependency_job_id":"14adc1aa-6cb3-43be-95a7-a6fcd85c2828","html_url":"https://github.com/prometheus/cloudwatch_exporter","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fcloudwatch_exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fcloudwatch_exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fcloudwatch_exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prometheus%2Fcloudwatch_exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prometheus","download_url":"https://codeload.github.com/prometheus/cloudwatch_exporter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247046948,"owners_count":20874745,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T13:01:00.300Z","updated_at":"2025-04-03T17:31:25.176Z","avatar_url":"https://github.com/prometheus.png","language":"Java","funding_links":[],"categories":["HarmonyOS","Java","指标库","Exporters"],"sub_categories":["Windows Manager","Other monitoring systems"],"readme":"CloudWatch Exporter\n=====\n\nA Prometheus exporter for [Amazon CloudWatch](http://aws.amazon.com/cloudwatch/).\n\n## Alternatives\n\nFor ECS workloads, there is also an [ECS exporter](https://github.com/prometheus-community/ecs_exporter).\n\nFor a different approach to CloudWatch metrics, with automatic discovery, consider [Yet Another CloudWatch Exporter (YACE)](https://github.com/nerdswords/yet-another-cloudwatch-exporter).\n\n## Building and running\n\nCloudwatch Exporter requires at least Java 11.\n\n`mvn package` to build.\n\n`java -jar target/cloudwatch_exporter-*-SNAPSHOT-jar-with-dependencies.jar 9106 example.yml` to run.\n\nThe most recent pre-built JAR can be found at http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22cloudwatch_exporter%22\n\n## Credentials and permissions\n\nThe CloudWatch Exporter uses the\n[AWS Java SDK](http://docs.aws.amazon.com/AWSSdkDocsJava/latest/DeveloperGuide/welcome.html),\nwhich offers [a variety of ways to provide credentials](http://docs.aws.amazon.com/AWSSdkDocsJava/latest/DeveloperGuide/credentials.html).\nThis includes the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment\nvariables.\n\nThe `cloudwatch:ListMetrics`, `cloudwatch:GetMetricStatistics` and `cloudwatch:GetMetricData` IAM permissions are required.\nThe `tag:GetResources` IAM permission is also required to use the `aws_tag_select` feature.\n\n## Configuration\nThe configuration is in YAML.\n\nAn example with common options and `aws_dimension_select`:\n```\n---\nregion: eu-west-1\nmetrics:\n - aws_namespace: AWS/ELB\n   aws_metric_name: RequestCount\n   aws_dimensions: [AvailabilityZone, LoadBalancerName]\n   aws_dimension_select:\n     LoadBalancerName: [myLB]\n   aws_statistics: [Sum]\n```\n\nA similar example with common options and `aws_tag_select`:\n```\n---\nregion: eu-west-1\nmetrics:\n - aws_namespace: AWS/ELB\n   aws_metric_name: RequestCount\n   aws_dimensions: [AvailabilityZone, LoadBalancerName]\n   aws_tag_select:\n     tag_selections:\n       Monitoring: [\"enabled\"]\n     resource_type_selection: \"elasticloadbalancing:loadbalancer\"\n     resource_id_dimension: LoadBalancerName\n   aws_statistics: [Sum]\n```\n**Note:** configuration examples for different namespaces can be found in [examples](./examples) directory\n\n**Note:** A configuration builder can be found [here](https://github.com/djloude/cloudwatch_exporter_metrics_config_builder).\n\nName     | Description\n---------|------------\nregion   | Optional. The AWS region to connect to. If none is provided, an attempt will be made to determine the region from the [default region provider chain](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/java-dg-region-selection.html#default-region-provider-chain).\nrole_arn   | Optional. The AWS role to assume. Useful for retrieving cross account metrics.\nmetrics  | Required. A list of CloudWatch metrics to retrieve and export\naws_namespace  | Required. Namespace of the CloudWatch metric.\naws_metric_name  | Required. Metric name of the CloudWatch metric.\naws_dimensions | Required. This should contain exactly all the dimensions available for a metric. Run `aws cloudwatch list-metrics` to find out which dimensions you need to include for your metric.\naws_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.\naws_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.\naws_tag_select | Optional. A tag configuration to filter on, based on mapping from the tagged resource ID to a CloudWatch dimension.\ntag_selections | Optional, under `aws_tag_select`. Specify a map from a tag key to a list of tag values to apply [tag filtering](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_GetResources.html#resourcegrouptagging-GetResources-request-TagFilters) on resources from which metrics will be gathered.\nresource_type_selection | Required, under `aws_tag_select`. Specify the [resource type](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#genref-aws-service-namesspaces) to filter on. `resource_type_selection` should be comprised as `service:resource_type`, as per the [resource group tagging API](https://docs.aws.amazon.com/resourcegroupstagging/latest/APIReference/API_GetResources.html#resourcegrouptagging-GetResources-request-TagFilters). Where `resource_type` could be an empty string, like in S3 case: `resource_type_selection: \"s3:\"`.\nresource_id_dimension | Required, under `aws_tag_select`. For the current metric, specify which CloudWatch dimension maps to the ARN [resource ID](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html#arns-syntax).\n arn_resource_id_regexp | If the Cloudwatch dimension specified in `resource_id_dimension` doesn't conform to the convention for resource ID an alternative regular expression to extract the resource ID from the ARN can be given here. The default is `(?:([^:/]+)|[^:/]+/([^:]+))$`. The first non empty match group will be used. \naws_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.\naws_extended_statistics | Optional. A list of extended statistics to retrieve. Extended statistics currently include percentiles in the form `pN` or `pN.N`.\ndelay_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.\nrange_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.\nperiod_seconds | Optional. [Period](http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/cloudwatch_concepts.html#CloudWatchPeriods) to request the metric for. Only the most recent data point is used. Defaults to 60s. Can be set globally and per metric.\nset_timestamp | Optional. Boolean for whether to set the Prometheus metric timestamp as the original Cloudwatch timestamp. For some metrics which are updated very infrequently (such as S3/BucketSize), Prometheus may refuse to scrape them if this is set to true (see #100). Defaults to true. Can be set globally and per metric.\nuse_get_metric_data | Optional. Boolean (experimental) Use GetMetricData API to get metrics instead of GetMetricStatistics. Can be set globally and per metric.\nlist_metrics_cache_ttl | Optional. Number of seconds to cache the result of calling the ListMetrics API. Defaults to 0 (no cache). Can be set globally and per metric.\nwarn_on_empty_list_dimensions | Optional. Boolean Emit warning if the exporter cannot determine what metrics to request\n\n\nThe above config will export time series such as\n```\n# HELP aws_elb_request_count_sum CloudWatch metric AWS/ELB RequestCount Dimensions: [\"AvailabilityZone\",\"LoadBalancerName\"] Statistic: Sum Unit: Count\n# TYPE aws_elb_request_count_sum gauge\naws_elb_request_count_sum{job=\"aws_elb\",instance=\"\",load_balancer_name=\"mylb\",availability_zone=\"eu-west-1c\",} 42.0\naws_elb_request_count_sum{job=\"aws_elb\",instance=\"\",load_balancer_name=\"myotherlb\",availability_zone=\"eu-west-1c\",} 7.0\n```\n\nIf the `aws_tag_select` feature was used, an additional information metric will be exported for each AWS tagged resource matched by the resource type selection and tag selection (if specified), such as\n```\n# HELP aws_resource_info AWS information available for resource\n# TYPE aws_resource_info gauge\naws_resource_info{job=\"aws_elb\",instance=\"\",arn=\"arn:aws:elasticloadbalancing:eu-west-1:121212121212:loadbalancer/mylb\",load_balancer_name=\"mylb\",tag_Monitoring=\"enabled\",tag_MyOtherKey=\"MyOtherValue\",} 1.0\n```\naws_recource_info can be joined with other metrics using group_left in PromQL such as the following:\n```\n  aws_elb_request_count_sum\n* on(load_balancer_name) group_left(tag_MyOtherKey)\n  aws_resource_info\n```\nAll metrics are exported as gauges.\n\nIn addition `cloudwatch_exporter_scrape_error` will be non-zero if an error\noccurred during the scrape, and `cloudwatch_exporter_scrape_duration_seconds`\ncontains the duration of that scrape. `cloudwatch_exporter_build_info` contains\nlabels referencing the current build version and build release date.\n\n### Build Info Metric\n\n`cloudwatch_exporter_build_info` is a default cloudwatch exporter metric that contains the current\ncloudwatch exporter version and release date as label values. The numeric metric value is statically\nset to 1. If the metrics label values are \"unknown\" the build information scrap failed.\n\n### CloudWatch doesn't always report data\n\nCloudwatch reports data either always or only in some cases, example only if there is a non-zero value. The CloudWatch Exporter mirrors this behavior, so you should refer to the Cloudwatch documentation to find out if your metric is always reported or not.\n\n### Timestamps\n\nCloudWatch has been observed to sometimes take minutes for reported values to converge. The\ndefault `delay_seconds` will result in data that is at least 10 minutes old\nbeing requested to mitigate this. The samples exposed will have the timestamps of the\ndata from CloudWatch, so usual staleness semantics will not apply and values will persist\nfor 5m for instant vectors.\n\nIn practice this means that if you evaluate an instant vector at the current\ntime, you will not see data from CloudWatch. An expression such as\n`aws_elb_request_count_sum offset 10m` will allow you to access the data, and\nshould be used in recording rules and alerts.\n\nFor certain metrics which update relatively rarely, such as from S3,\n`set_timestamp` should be configured to false so that they are not exposed with\na timestamp. This is as the true timestamp from CloudWatch could be so old that\nPrometheus would reject the sample.\n\n#### FAQ: I can see the metrics in `/metrics` but not in the Prometheus web console\n\nThe metrics will be visible in Prometheus if you look more than `delay_seconds` in the past.\nTry the graph view.\n\nThis is an unfortunate result of a fundamental mismatch between CloudWatch and Prometheus.\nCloudWatch metrics converge over time, that is, the value at time `T` can change up to some later time `T+dT`.\nMeanwhile, Prometheus assumes that once it has scraped a sample, that is the truth, and the past does not change.\n\nTo compensate for this, by default the exporter [delays fetching metrics](https://github.com/prometheus/cloudwatch_exporter/blob/master/README.md#timestamps), that is, it only asks for data 10 minutes later, when _almost_ all AWS services have converged.\nIt also reports to Prometheus that this sample is from the past.\nBecause Prometheus, for an instant request, only looks back 5 minutes, it never sees any data \"now\".\n\n### Special handling for certain DynamoDB metrics\n\nThe DynamoDB metrics listed below break the usual CloudWatch data model.\n\n * ConsumedReadCapacityUnits\n * ConsumedWriteCapacityUnits\n * ProvisionedReadCapacityUnits\n * ProvisionedWriteCapacityUnits\n * ReadThrottleEvents\n * WriteThrottleEvents\n\nWhen these metrics are requested in the TableName dimension CloudWatch will\nreturn data only for the table itself, not for its Global Secondary Indexes.\nRetrieving data for indexes requires requesting data across both the TableName\nand GlobalSecondaryIndexName dimensions. This behaviour is different to that\nof every other CloudWatch namespace and requires that the exporter handle these\nmetrics differently to avoid generating duplicate HELP and TYPE lines.\n\nWhen exporting one of the problematic metrics for an index the exporter will use\na metric name in the format `aws_dynamodb_METRIC_index_STATISTIC` rather than\nthe usual `aws_dynamodb_METRIC_STATISTIC`. The regular naming scheme will still\nbe used when exporting these metrics for a table, and when exporting any other\nDynamoDB metrics not listed above.\n\n### Reloading Configuration\n\nThere are two ways to reload configuration:\n\n1. Send a SIGHUP signal to the pid: `kill -HUP 1234`\n2. POST to the `reload` endpoint: `curl -X POST localhost:9106/-/reload`\n\nIf an error occurs during the reload, check the exporter's log output.\n\n### Cost\n\nAmazon charges for every CloudWatch API request or for every Cloudwatch metric requested, see the [current charges](http://aws.amazon.com/cloudwatch/pricing/).\n\n- In case of using `GetMetricStatistics` (default) - Every metric retrieved requires one API request, which can include multiple\nstatistics. \n- 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.\n\nIn the case that all `aws_dimensions` are provided in the `aws_dimension_select` list, the exporter will not perform the\nabove API request.  It will request all possible combination of values for those dimensions.\nThis will reduce cost as the values for the dimensions do not need to be queried anymore, assuming that all possible value combinations are present in CloudWatch.\n\nIf you have 100 API requests every minute, with the price of USD$10 per million\nrequests (as of Aug 2018), that is around $45 per month. The\n`cloudwatch_requests_total` counter tracks how many requests are being made.\n\nWhen using the `aws_tag_select` feature, additional requests are made to the Resource Groups Tagging API, but these are [free](https://aws.amazon.com/blogs/aws/new-aws-resource-tagging-api/).\nThe `tagging_api_requests_total` counter tracks how many requests are being made for these.\n\n### Experimental GetMetricData\nWe are transitioning to use `GetMetricsData` instead of `GetMetricsStatistics`.\nThe benefits of using `GetMetricsData` is mainly around much better performence.\n\nPlease refer to [this doc](https://aws.amazon.com/premiumsupport/knowledge-center/cloudwatch-getmetricdata-api/) explaining why it is best practice to use `GetMetricData`\n\nAPI | performence | Costs | Stability \n--- |--- |--- |--- \n`GetMetricStatistics` | May be slow at scale | Charged per API request | stable. (Default option)\n`GetMetricData` | Can retrieve data faster at scale | Charged per **metric** requested | New (opt-in via configuration)\n\n#### Transition plan\nAt first this feature would be opt-in to allow you to decide when and how to test it\nOn later versions we would swap the default so everyone can enjoy the benefits.\n\nCloudwatch exporter also expose a new self metric called `cloudwatch_metrics_requested_total` that allows you to track number of requested metrics in addition to the number of API requests.\n\n## Docker Images\n\nTo run the CloudWatch exporter on Docker, you can use the image from\n\n* [prom/cloudwatch-exporter](https://hub.docker.com/r/prom/cloudwatch-exporter/)\n* [quay.io/prometheus/cloudwatch-exporter](https://quay.io/repository/prometheus/cloudwatch-exporter)\n\nThe available tags are\n\n* `main`: snapshot updated on every push to the main branch\n* `latest`: the latest released version\n* `vX.Y.Z`: the specific version X.Y.Z. Note that up to version 0.11.0, the format was `cloudwatch-exporter_X.Y.Z`.\n\nThe image exposes port 9106 and expects the config in `/config/config.yml`.\nTo configure it, you can bind-mount a config from your host:\n\n```sh\ndocker run -p 9106 -v /path/on/host/config.yml:/config/config.yml quay.io/prometheus/cloudwatch-exporter\n```\n\nSpecify the config as the CMD:\n\n```sh\ndocker run -p 9106 -v /path/on/host/us-west-1.yml:/config/us-west-1.yml quay.io/prometheus/cloudwatch-exporter /config/us-west-1.yml\n```\n\nOr create a config file named `config.yml` along with following\nDockerfile in the same directory and build it with `docker build`:\n\n```Dockerfile\nFROM prom/cloudwatch-exporter\nADD config.yml /config/\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprometheus%2Fcloudwatch_exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprometheus%2Fcloudwatch_exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprometheus%2Fcloudwatch_exporter/lists"}