You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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 (up/down) state used for alerting.
4
+
5
+
Check out the [web page](https://shayan-ghani.github.io/Container-Exporter/) for more information.
6
+
7
+
## Table of Contents
8
+
1.[DEV STACK](#%EF%B8%8F-dev-stack)
9
+
2.[DEMO](#-demo)
10
+
3.[Step-by-Step Guide](#-step-by-step-guide)
11
+
1.[Before You start](#before-you-start)
12
+
2.[Getting started](#getting-started)
13
+
-[Deploy with Github Actions](#-deploy-with-github-actions)
14
+
-[Deploy with Docker](#-deploy-with-docker)
15
+
-[Deploy without Docker](#-cant-use-docker-ok-then-)
16
+
-[Run with a Custom Port](#-run-with-a-custom-port)
17
+
3.[Add CXP to Prometheus](#-add-cxp-to-prometheus)
- Docker & Docker Compose should be installed (optional)
37
+
- The presence of Git and Python3.10
38
+
39
+
### Getting started
40
+
41
+
#### ⚙️ Deploy with Github Actions
42
+
- fork the repository.
43
+
- go to the fork repository and switch to `Action` tab.
44
+
- click the `I understand my workflows, go ahead and enable them` button.
45
+
- now you have access to all of the workflows, **however make sure you change the secrets listed below accordingly**:
46
+
1.`secretes.DOCKER_TOKEN` : the personal access token docker hub of your(or your organization) account.
47
+
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)
48
+
49
+
*here's how workflows work:*
50
+
- on push to `master` the project will be `built`, `deployed` and `released`.
51
+
*since deploying to your servers requires runner configuration it must be triggered manually, you can modify its behavior on `cd.yml` workflow.*
52
+
- on push to any branch **except for**`master` code will be `built` and `healthchecked`
53
+
- on pr the project will be `healthchecked` and `built`.
54
+
55
+
*double check the required variables and secrets to prevent any unexpected failures*
56
+
57
+
#### 🐳 Deploy with Docker
58
+
- clone and checkout to the repository using the following commands:
- Reload or restart your Prometheus server and reach out to `http://127.0.0.1:8000/metrics`
121
+
### That is it you are good to go, Enjoy Using CXP! "}"
122
+
123
+
## 📊 Grafana Dashboards
124
+
Check out [dashboards](./dashboards) directory for Json files. including CPU & Memory usage + containers status (uptime).
125
+
126
+
**Change `Your Prometheus data source uid` with the uid of Prometheus data source uid. you can find it this way:**
127
+
- Reach out to Grafana then enter `Home > Administration > Data sources` then click on your Prometheus data source.
128
+
- the characters after `datasources/edit/` are your uid. (e.g datasources/edit/**c8e586ac-4262-4aad5-a103-1240ss826424**)
129
+
130
+
- 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:
131
+
132
+
```
133
+
cd scripts && bash dashboard-gen.sh <your uid>
134
+
```
135
+
- replace `<your uid>` with your Prometheus datasource uid.
136
+
137
+
- now head to Grafana dashboards and hit `new > import` then copy the dashboard Json file and paste it into `Import via panel json`
138
+
139
+
- hit the `load` button and Done!
140
+
141
+
## TO-DO
142
+
-[x] Disk I/O usage
143
+
-[x] Network I/O Usage
144
+
-[x] Add metrics in units of byte
145
+
-[x] Check and Unregister *stat* metrics for containers that are not running
146
+
-[x] Design and develop a static website to showcase Documentation, new features, etc.
147
+
-[x] Enable functionality and smoke testing in ci
148
+
-[X] Add `clear_metrics` functionality to switch on clearing the labels or setting them to 0 to maintain time series data, on user's demand.
149
+
-[ ] Design grafana dashboards and share them on grafana cloud
150
+
-[ ] Add unit tests
151
+
152
+
## Contributions
153
+
Welcome to CXP! This project is production-ready now, and we encourage contributions to enhance its functionality, optimize code, and add new features
154
+
155
+
Feel 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!
156
+
157
+
- If you want to add metrics to cxp, make sure the naming convention is conformed to. (`cxp_metric_name`)
Disk, and Network I/O usage — with uptime tracking.</p>
169
-
<p>when a container is not running due to whatever reason <code>cxp</code> removes all its stats metrics (cpu, memory, etc.) but keeps its status (running/not-running) to facilitate alerting in case something goes wrong with that contaier.</p>
170
-
171
-
<p>Check out a sample of the metrics output <ahref="./metrics.html">here</a> to see how it works.</p>
198
+
Disk, and Network I/O usage — with uptime tracking.</p>
199
+
<p>when a container is not running due to whatever reason <code>cxp</code> removes all its stats metrics (cpu,
200
+
memory, etc.)
201
+
<code>(if CONTAINER_EXPORTER_CLEAR_METRICS=True otherwise they are set to 0 to retain time series data.)</code>
202
+
but keeps its status ( running/not-running/(restarting/unhealthy) ) to facilitate alerting in case something
203
+
goes wrong with that contaier.
204
+
</p>
205
+
206
+
<p>Check out a sample of the metrics output <ahref="./metrics.html">here</a> to see how it works.</p>
172
207
<divclass="section">
173
208
<h2>📚 Table of Contents</h2>
174
209
<ol>
175
210
<li><ahref="#dev-stack">DEV STACK</a></li>
176
211
<li><ahref="#demo">DEMO</a></li>
177
212
<li><ahref="#guide">Deployment Guide</a></li>
213
+
<li><ahref="#settings">Config and Settings</a></li>
<p>when set to False the metrics for container stats will not be fully cleared and set to zero to retain the time series data recorded for that container.
258
+
note that only <b>Gauge Metrics</b> can be set to zero, so <code>network</code> and <code>disk io</code> settings will be fully cleared either way.
259
+
</p>
260
+
</ul>
261
+
<divclass="config">
262
+
263
+
</div>
264
+
265
+
266
+
</div>
267
+
203
268
<divclass="section" id="guide">
204
269
<h2>📋 Deployment Guide</h2>
205
270
@@ -210,6 +275,36 @@ <h3>Before You Start</h3>
210
275
<li>Git and Python ≥ 3.10 available</li>
211
276
</ul>
212
277
278
+
<h3>⚙️ Deploy with GitHub Actions</h3>
279
+
<ul>
280
+
<li>Fork the repository.</li>
281
+
<li>Go to the forked repository and switch to the Actions tab.</li>
282
+
<li>Click the <code>I understand my workflows, go ahead and enable them</code> button.</li>
283
+
<li>Now you have access to all of the workflows; however, make sure you change the secrets listed below
284
+
accordingly:
285
+
<ul>
286
+
<li><code>secrets.DOCKER_TOKEN</code>: the personal access token for Docker Hub of your (or your
287
+
organization’s) account.</li>
288
+
<li><code>secrets.GHCR_TOKEN</code>: GitHub classic access token with
289
+
<code>packages:read-write</code> permissions, or simply use
290
+
<code>${{ github.token }}</code>.
291
+
</li>
292
+
</ul>
293
+
</li>
294
+
</ul>
295
+
296
+
<h3>How Workflows Work</h3>
297
+
<ul>
298
+
<li>On push to <code>master</code>, the project will be built, deployed, and released. Since deploying
299
+
to your servers requires runner configuration, it must be triggered manually; you can modify its
300
+
behavior in the <code>cd.yml</code> workflow.</li>
301
+
<li>On push to any branch except <code>master</code>, code will be built and health-checked.</li>
302
+
<li>On pull request, the project will be health-checked and built.</li>
303
+
</ul>
304
+
305
+
<bold>Double check the required variables and secrets to prevent any unexpected failures.</bold>
<p>Open for pull requests and issues. Help improve CXP!</p>
334
+
<divclass="section" id="alerting">
335
+
<h2>Alerting Rules</h2>
336
+
<p>
337
+
A page of sample Prometheus rules can be accessed <ahref="./rules.html">here</a> . setting alerts on <code>cxp_container_status</code> is one of the main points users prefer <code>CXP</code> over<code>cAdvisor.</code>
0 commit comments