{"id":16963023,"url":"https://github.com/shayan-ghani/container-exporter","last_synced_at":"2025-05-06T21:28:48.503Z","repository":{"id":209659003,"uuid":"724091313","full_name":"Shayan-Ghani/Container-Exporter","owner":"Shayan-Ghani","description":"A resource-friendly, highly efficient, and minimal Prometheus exporter to track Memory, CPU, Disk and Network I/O usage of Docker containers along with their lifecycle (status).","archived":false,"fork":false,"pushed_at":"2025-05-02T16:12:37.000Z","size":17114,"stargazers_count":58,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-02T16:46:48.382Z","etag":null,"topics":["container-exporter","containers","cxp","docker","docker-prometheus","prometheus","prometheus-exporter","prometheus-metrics","prometheus-utility"],"latest_commit_sha":null,"homepage":"","language":"Python","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/Shayan-Ghani.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2023-11-27T11:32:17.000Z","updated_at":"2025-05-02T16:11:54.000Z","dependencies_parsed_at":"2024-01-05T11:08:40.636Z","dependency_job_id":"b6560df5-75c4-4795-9cc1-c64034c39238","html_url":"https://github.com/Shayan-Ghani/Container-Exporter","commit_stats":{"total_commits":74,"total_committers":4,"mean_commits":18.5,"dds":0.1216216216216216,"last_synced_commit":"72057395095497624ac19800f6f8b5813c67e22e"},"previous_names":["shayan-ghani/container-exporter"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shayan-Ghani%2FContainer-Exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shayan-Ghani%2FContainer-Exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shayan-Ghani%2FContainer-Exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shayan-Ghani%2FContainer-Exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shayan-Ghani","download_url":"https://codeload.github.com/Shayan-Ghani/Container-Exporter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252771482,"owners_count":21801718,"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":["container-exporter","containers","cxp","docker","docker-prometheus","prometheus","prometheus-exporter","prometheus-metrics","prometheus-utility"],"created_at":"2024-10-13T23:23:18.918Z","updated_at":"2025-05-06T21:28:48.496Z","avatar_url":"https://github.com/Shayan-Ghani.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Container Exporter (CXP)\n\nA resource-friendly, highly efficient, and minimal Prometheus exporter to track Memory, CPU, Disk and Network I/O usage of Docker containers along with their lifecycle (uptime).\n\n## Table of Contents\n1. [DEV STACK](#%EF%B8%8F-dev-stack)\n2. [DEMO](#-demo)\n3. [Step-by-Step Guide](#-step-by-step-guide)\n   1. [Before You start](#before-you-start)\n   2. [Getting started](#getting-started)\n      - [Deploy with Github Actions](#-deploy-with-github-actions)\n      - [Deploy with Docker](#-deploy-with-docker)\n      - [Deploy without Docker](#-cant-use-docker-ok-then-)\n      - [Run with a Custom Port](#-run-with-a-custom-port)\n   3. [Add CXP to Prometheus](#-add-cxp-to-prometheus)\n4. [Grafana Dashboards](#-grafana-dashboards)\n5. [TO-DO](#to-do)\n6. [Contributions](#contributions)\n7. [Contact Information](#contact-information)\n\n## 🛠️ DEV STACK\n![Python](https://img.shields.io/badge/python-3670A0?style=for-the-badge\u0026logo=python\u0026logoColor=ffdd54) ![Flask](https://img.shields.io/badge/flask-%23000.svg?style=for-the-badge\u0026logo=flask\u0026logoColor=ffdd54) ![Docker](https://img.shields.io/badge/docker-3670A0?style=for-the-badge\u0026logo=docker\u0026logoColor=ffff) ![Prometheus](https://img.shields.io/badge/Prometheus-E6522C?style=for-the-badge\u0026logo=Prometheus\u0026logoColor=white) ![Gunicorn](https://img.shields.io/badge/gunicorn-%298729.svg?style=for-the-badge\u0026logo=gunicorn\u0026logoColor=white)\n\nsee a sample of the metrics page in [here](./extra/metrics.txt).\n\n## 🎥 DEMO\n\u003cimg src=\"https://shayan-ghani.github.io/Container-Exporter/CXP-DEMO.gif\" width=\"100%\" height=\"50%\" /\u003e\n\n\n## 📋 Step-by-Step Guide\n\n### Before You start\n - Port 8000 must be open (default port)\n - Docker \u0026 Docker Compose should be installed (optional)\n - The presence of Git and Python3.10\n\n### Getting started\n\n#### ⚙️ Deploy with Github Actions\n- fork the repository.\n- go to the fork repository and switch to `Action` tab.\n- click the `I understand my workflows, go ahead and enable them` button.\n- now you have access to all of the workflows, **however make sure you change the secrets listed below accordingly**:\n  1. `secretes.DOCKER_TOKEN` : the personal access token docker hub of your(or your organization) account.\n  2. `secretes.GHCR_TOKEN` : github classic access token with (packages read:write permissions) or just simply use `${{github.token}}`. [help](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)\n\n*here's how workflows work:*\n  - on push to `master` the project will be `built`, `deployed` and `released`.\n*since deploying to your servers requires runner configuration it must be triggered manually, you can modify its behavior on `cd.yml` workflow.*\n  - on push to any branch **except for** `master` code will be `built` and `healthchecked`\n  - on pr the project will be `healthchecked` and `built`.\n\n*double check the required variables and secrets to prevent any unexpected failures*\n\n#### 🐳 Deploy with Docker\n- clone and checkout to the repository using the following commands:\n```bash\n  git clone https://github.com/Shayan-Ghani/Container-exporter.git\n  cd Container-Exporter\n```\n- Deploy the docker-compose file that suits you the best for instance :\n```bash \n# Make the file executable\n  chmod +x ./start.sh\n\n# With docker compose v1\n  docker-compose -f container-exporter.yml up -d\n# Or using v2\n  docker compose -f container-exporter.yml up -d\n# build from base with Dockerfile\n  docker-compose -f container-exporter-local.yml up --build -d\n```\n\n#### 🐍 Can't use Docker? Ok then :\n```bash\n# No need if done already\n  chmod +x ./start.sh\n\n# Set up virtualenv\n  python3 -m venv venv\n  source venv/bin/activate\n  pip install -U pip\n\n# Install the required python packages\n  pip install -r requirements.txt\n\n# start the initializer script.\n  ./start.sh \u0026\n``` \n\nYou can use nohup as well : \n```\nnohup ./start.sh -out ./nohup.out\n\n# to stop cxp without docker use this command \nkill -9 \u003cPID\u003e\n```\nReplace `\u003cPID\u003e` with the pid of ./start.sh script.\n\n#### 🚢 Run With A Custom Port:\n```bash\n./start.sh \u003cyour custome port\u003e \u0026\n```\n\nChange `\u003cyour custom port\u003e` with a port of your choice.\n\n### 🔥 Add CXP to Prometheus\n- Edit your `prometheus.yml` file and add the address of container-exporter in scrape_configs:\n\n![Prometheus config](./capture/scrape-config.png \"Prometheus configuration file\")\n\n- Reload or restart your Prometheus server and reach out to `http://127.0.0.1:8000/metrics`\n### That is it you are good to go, Enjoy Using CXP! \"}\"\n\n## 📊 Grafana Dashboards\nCheck out [dashboards](./dashboards) directory for Json files. including CPU \u0026 Memory usage + containers status (uptime).\n\n**Change `Your Prometheus data source uid` with the uid of Prometheus data source uid. you can find it this way:** \n- Reach out to Grafana then enter  `Home \u003e Administration \u003e Data sources`  then click on your Prometheus data source.\n- the characters after `datasources/edit/` are your uid. (e.g datasources/edit/**c8e586ac-4262-4aad5-a103-1240ss826424**)\n\n- alternatively, use `dashboard-gen.sh` script to change the dashboards' uid by providing the uid as the first argument of the script. do the following steps:\n\n```\n cd scripts \u0026\u0026 bash dashboard-gen.sh \u003cyour uid\u003e \n```\n- replace `\u003cyour uid\u003e` with your Prometheus datasource uid. \n\n- now head to Grafana dashboards and hit `new \u003e import` then copy the dashboard Json file and paste it into `Import via panel json`\n\n- hit the `load` button and Done!\n\n## TO-DO\n - [x]  Disk I/O usage \n - [x]  Network I/O Usage\n - [x]  Add metrics in units of byte\n - [x]  Check and Unregister *stat* metrics for containers that are not running\n - [ ]  Design grafana dashboards and share them on grafana cloud\n - [ ]  Design and develop a static website to showcase Documentation, new features, etc.\n## Contributions\nWelcome to CXP! This project is currently in an experimental yet stable version, and we encourage contributions to enhance its functionality, optimize code, and add new features\n\nFeel free to contribute in any wacacy you can. If you come across a bug or have a suggestion, please don't hesitate to file an issue. Your input is valuable and helps us improve CXP for everyone; Therefore, add any desired function or feature to TO DO section. We appreciate your contribution to making CXP even better! If you have any questions or need assistance, feel free to reach out. Thank you!\n\n- If you want to add metrics to cxp, make sure the naming convention is conformed to. (`cxp_metric_name`)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshayan-ghani%2Fcontainer-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshayan-ghani%2Fcontainer-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshayan-ghani%2Fcontainer-exporter/lists"}