{"id":19546305,"url":"https://github.com/hyperdxio/aws-ecs-opentelemetry-sidecar","last_synced_at":"2025-07-04T19:33:24.408Z","repository":{"id":241722783,"uuid":"807485609","full_name":"hyperdxio/aws-ecs-opentelemetry-sidecar","owner":"hyperdxio","description":"AWS ECS OpenTelemetry sidecar to send logs and metrics from your containers to HyperDX and other OpenTelemetry collectors. Powered by Firelens and AWS ECS Container Metrics Receiver.","archived":false,"fork":false,"pushed_at":"2024-10-14T18:22:07.000Z","size":8,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-19T18:45:27.642Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperdxio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-29T07:37:35.000Z","updated_at":"2025-03-15T13:46:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"67bea8df-104a-4baa-802d-e89a8f5e722f","html_url":"https://github.com/hyperdxio/aws-ecs-opentelemetry-sidecar","commit_stats":null,"previous_names":["hyperdxio/aws-ecs-opentelemetry-sidecar"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hyperdxio/aws-ecs-opentelemetry-sidecar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperdxio%2Faws-ecs-opentelemetry-sidecar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperdxio%2Faws-ecs-opentelemetry-sidecar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperdxio%2Faws-ecs-opentelemetry-sidecar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperdxio%2Faws-ecs-opentelemetry-sidecar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperdxio","download_url":"https://codeload.github.com/hyperdxio/aws-ecs-opentelemetry-sidecar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperdxio%2Faws-ecs-opentelemetry-sidecar/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263606747,"owners_count":23487689,"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-11-11T03:44:16.640Z","updated_at":"2025-07-04T19:33:24.355Z","avatar_url":"https://github.com/hyperdxio.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS ECS OpenTelemetry Sidecar\n\nThis repository contains a Docker image that can be used as a sidecar container\nin an AWS ECS task definition to collect metrics and logs from the application\ncontainer. The sidecar container runs an OpenTelemetry collector that collects\nECS task and container metrics and logs via Firelens from the application\ncontainer and sends them to [HyperDX](https://hyperdx.io) or another\nOpenTelemetry collector endpoint.\n\n## Usage\n\nTo use this sidecar container in an ECS task definition, you'll need to create a\nnew task definition with two containers: the application container and the\nOpenTelemetry sidecar container. The application container should be configured\nto use the `awsfirelens` log driver to forward the logs to the sidecar.\n\nTask definition example:\n\n```json\n{\n  \"family\": \"firelens-example-otel\",\n  \"containerDefinitions\": [\n    {\n      \"name\": \"app\",\n      \"image\": \"chentex/random-logger:latest\",\n      \"essential\": true,\n      \"logConfiguration\": {\n        \"logDriver\": \"awsfirelens\"\n      }\n    },\n    {\n      \"name\": \"otel-sidecar\",\n      \"image\": \"public.ecr.aws/hyperdx/aws-ecs-opentelemetry-sidecar:latest\",\n      \"essential\": true,\n      \"environment\": [\n        {\n          \"name\": \"HYPERDX_API_KEY\",\n          \"value\": \"YOUR_HYPERDX_API_KEY\"\n        }\n      ],\n      \"firelensConfiguration\": {\n        \"type\": \"fluentbit\"\n      }\n    }\n  ],\n  \"networkMode\": \"awsvpc\",\n  \"requiresCompatibilities\": [\"FARGATE\"],\n  \"cpu\": \"512\",\n  \"memory\": \"1024\"\n}\n```\n\nView the `examples` folder for more task definition examples and configuration\noptions.\n\n## Configuration\n\nYou'll need to set the `HYPERDX_API_KEY` environment variable in the sidecar\ncontainer to your HyperDX API key. You can get an API key by signing up for an\naccount at [HyperDX](https://hyperdx.io).\n\nBy default, the `service.name` is populated by the ECS task definition family\nname, but this can be overridden by setting the\n`OTEL_RESOURCE_ATTRIBUTES=\"service.name=my_service\"`.\n\nTo disable the collection of ECS metrics, set the\n`OTEL_ECS_CONTAINER_METRICS_DISABLED` environment variable to `true`.\n\nTo disable the collection of ECS logs, ensure that the `awsfirelens` log driver\nis not set on the application container.\n\nTo send to a different OpenTelemetry endpoint or collector, set the\n`OTEL_EXPORTER_OTLP_ENDPOINT` environment variable to the desired endpoint.\n\nTo disable the default `service.name` being populated with the ECS task, you can\nset `PROCESSOR_RESOURCE_SERVICE_NAME_DISABLED` to `true`.\n\nFor advanced configuration you can pass in a custom OpenTelemetry collector\nconfig via the `MERGED_OTEL_CONFIG` environment variable. This config will be\nmerged with the default config.\n\nTo debug the generated configuration, set the `DEBUG_GENERATED_OTEL_CONFIG`\nenvironment variable to `true`.\n\n## Collected ECS Metrics\n\nThe OpenTelemetry collector in the sidecar container collects the following\nmetrics from the ECS task and container via the\n[`awsecscontainermetrics` receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/awsecscontainermetricsreceiver/README.md)\nat a 1 minute interval:\n\n| Task Level Metrics                   | Container Level Metrics               | Unit         |\n| ------------------------------------ | ------------------------------------- | ------------ |\n| ecs.task.memory.usage                | container.memory.usage                | Bytes        |\n| ecs.task.memory.usage.max            | container.memory.usage.max            | Bytes        |\n| ecs.task.memory.usage.limit          | container.memory.usage.limit          | Bytes        |\n| ecs.task.memory.reserved             | container.memory.reserved             | Megabytes    |\n| ecs.task.memory.utilized             | container.memory.utilized             | Megabytes    |\n| ecs.task.cpu.usage.total             | container.cpu.usage.total             | Nanoseconds  |\n| ecs.task.cpu.usage.kernelmode        | container.cpu.usage.kernelmode        | Nanoseconds  |\n| ecs.task.cpu.usage.usermode          | container.cpu.usage.usermode          | Nanoseconds  |\n| ecs.task.cpu.usage.system            | container.cpu.usage.system            | Nanoseconds  |\n| ecs.task.cpu.usage.vcpu              | container.cpu.usage.vcpu              | vCPU         |\n| ecs.task.cpu.cores                   | container.cpu.cores                   | Count        |\n| ecs.task.cpu.onlines                 | container.cpu.onlines                 | Count        |\n| ecs.task.cpu.reserved                | container.cpu.reserved                | vCPU         |\n| ecs.task.cpu.utilized                | container.cpu.utilized                | Percent      |\n| ecs.task.network.rate.rx             | container.network.rate.rx             | Bytes/Second |\n| ecs.task.network.rate.tx             | container.network.rate.tx             | Bytes/Second |\n| ecs.task.network.io.usage.rx_bytes   | container.network.io.usage.rx_bytes   | Bytes        |\n| ecs.task.network.io.usage.rx_packets | container.network.io.usage.rx_packets | Count        |\n| ecs.task.network.io.usage.rx_errors  | container.network.io.usage.rx_errors  | Count        |\n| ecs.task.network.io.usage.rx_dropped | container.network.io.usage.rx_dropped | Count        |\n| ecs.task.network.io.usage.tx_bytes   | container.network.io.usage.tx_bytes   | Bytes        |\n| ecs.task.network.io.usage.tx_packets | container.network.io.usage.tx_packets | Count        |\n| ecs.task.network.io.usage.tx_errors  | container.network.io.usage.tx_errors  | Count        |\n| ecs.task.network.io.usage.tx_dropped | container.network.io.usage.tx_dropped | Count        |\n| ecs.task.storage.read_bytes          | container.storage.read_bytes          | Bytes        |\n| ecs.task.storage.write_bytes         | container.storage.write_bytes         | Bytes        |\n\n### Thanks\n\nThanks to\n[project0/aws-ecs-firelens-opentelemetry](https://github.com/project0/aws-ecs-firelens-opentelemetry)\nfor sharing their ECS Firelens configuration for OpenTelemetry that formed the\nbasis of the Firelens configuration in this repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperdxio%2Faws-ecs-opentelemetry-sidecar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperdxio%2Faws-ecs-opentelemetry-sidecar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperdxio%2Faws-ecs-opentelemetry-sidecar/lists"}