diff --git a/README.md b/README.md index 161a973..529f9e4 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,21 @@ # ecs-container-exporter -[AWS ECS](https://aws.amazon.com/ecs/) side car that exports container level metrics to [Prometheus](https://prometheus.io) +[AWS ECS](https://aws.amazon.com/ecs/) side car that exports ECS container level docker stats metrics to [Prometheus](https://prometheus.io) as well as publish it via Statsd. # Motivation -The default metrics available in ECS are at the task level, which include all the side cars associated with a task. But the container metrics are what we are interested in which is not available in ECS. In addition, more detailed cgroup metrics are also not available, such as per cpu, and memory usage breakdown into cache, rss, etc. +The default metrics available in AWS ECS are limited, mostly at the task level, across all containers in a task; the container level metrics are not available. In addition, more detailed cgroup metrics are also not available, such as per cpu, and memory usage breakdown into cache, rss, etc. Luckily AWS exposes the [docker stats](https://docs.docker.com/engine/api/v1.40/#operation/ContainerInspect) data via a [Task metadata endpoint](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint.html). -The ecs-container-exporter just parses this data, and exposes it to Prometheus. +The ecs-container-exporter parses this data, and can expose it to Prometheus or push them via StatsD. # Usage -The Docker image is available on docker hub at: +Install via Pip: + +``` +pip3 install ecs-container-exporter +``` + +or via docker: ``` $ docker pull raags/ecs-container-exporter @@ -38,11 +44,16 @@ On ECS, add the following json to the task definition: The `PROMETHEUS_EXPORTER_PORT` label is for ECS discovery via https://github.com/teralytics/prometheus-ecs-discovery To include or exclude application containers use the `INCLUDE` or `EXCLUDE` environment variable. By default `ecs-container-exporter` -and `~internal~ecs~pause`, which is a Fargate internal sidecar, is excluded. +and `~internal~ecs~pause` (a Fargate internal sidecar) is excluded. + +## Statsd + +Version `2.0.0` add Statsd support with `--use-statsd` flag or env `USE_STATSD`. Metrics are emitted with DogStatsd Tag format. + # Metrics -The metrics are sampled twice as per the configured `interval` (default 60s). This should be set to the Prometheus scrape interval. +The metrics are sampled twice as per the configured `interval` (default 60s), and than aggregated in this interval. This should be set to the Prometheus scrape interval. ## CPU @@ -56,9 +67,13 @@ CPU usage ratio is calculated and scaled as per the applicable container or task | x | 0 | scale as per limit | scale as per task limit | | x | x | scale as per limit | scale as per container limit (can burst above 100%) | +Note that unlike `docker stats` command and others, CPU usage is not scaled to +the number of CPUs. This means a task with 4 CPUs with all 4 having full +utilization will show up as 400% in `docker stats`, but 100% here. + ## Memory -Memory usage and cache is emitted separately. Memory usage include cache, so +Memory usage and cache is emitted separately, but the memory usage also includes cache, so subtract cache from it to plot application memory usage specifically. ## IO @@ -66,3 +81,6 @@ subtract cache from it to plot application memory usage specifically. ## Network Network metrics were recently added in Fargate 1.4.0 and ECS agent 1.41.0 onwards. + +# TODO +[] - Support Non ECS docker host containers diff --git a/ecs_container_exporter/__init__.py b/ecs_container_exporter/__init__.py index 1f356cc..afced14 100644 --- a/ecs_container_exporter/__init__.py +++ b/ecs_container_exporter/__init__.py @@ -1 +1 @@ -__version__ = '1.0.0' +__version__ = '2.0.0'