# @adobe/cgroup-metrics

> Node Module to read cgroup memory data

Latest version **3.0.6** (published 2022-01-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install @adobe/cgroup-metrics
pnpm add @adobe/cgroup-metrics
yarn add @adobe/cgroup-metrics
bun add @adobe/cgroup-metrics
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.6 |
| Published | 2022-01-10 |
| First published | 2020-04-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 23.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 18 |
| Author | Adobe Inc. |
| Maintainers | fullcolorcoder, marbec, tripod, garthdb, lazd, adobe-admin, patrickfulton, trieloff, shazron, krisnye, dcpfsdk, natebaldwin, devongovett, aspro83, symanovi, dpfister, stefan-guggisberg, korra, rofe, kptdobe |
| Keywords | node, cgroup, metrics, docker |

## Links

- npm: https://www.npmjs.com/package/@adobe/cgroup-metrics
- Repository: https://github.com/adobe/node-cgroup-metrics
- Homepage: https://github.com/adobe/node-cgroup-metrics#readme
- Issues: https://github.com/adobe/node-cgroup-metrics/issues
- npm.io page: https://npm.io/package/@adobe/cgroup-metrics

## Dependencies (1)

- [flat](https://npm.io/package/flat.md) ^5.0.2

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 3.0.6 (latest) — 2022-01-10
- 3.0.5 — 2021-08-17
- 3.0.4 — 2021-08-05
- 3.0.3 — 2021-03-29
- 3.0.2 — 2021-02-02
- 3.0.1 — 2020-07-22
- 3.0.0 — 2020-04-17

## README

[![Version](https://img.shields.io/npm/v/@adobe/cgroup-metrics.svg)](https://npmjs.org/package/@adobe/cgroup-metrics) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0) [![codecov](https://codecov.io/gh/adobe/node-cgroup-metrics/branch/master/graph/badge.svg)](https://codecov.io/gh/adobe/node-cgroup-metrics) [![Travis](https://travis-ci.com/adobe/node-cgroup-metrics.svg?branch=master)](https://travis-ci.com/adobe/node-cgroup-metrics)


### CGROUP-METRICS
Node Module for reading [cgroup](https://www.kernel.org/doc/Documentation/cgroup-v1/) metrics. Reads from `/sys/fs/cgroup/`. 

### Memory Metrics:
[Memory](https://www.kernel.org/doc/Documentation/cgroup-v1/memory.txt) reads from path `/sys/fs/cgroup/memory/memory`:

Raw values:
- `stat.rss`: # of bytes of anonymous and swap cache memory
- `kmem.usage_in_bytes`: current kernel memory allocation
- `limit_in_bytes`: limit of memory usage

Calculated values:
- `containerUsage()`: `stats.rss` + `kmem.usage_in_bytes`
- `containerUsagePercentage()`:`stats.rss` + `kmem.usage_in_bytes` / `limit_in_bytes`

### CPU Metrics:

Raw CPU values:
[CPU](https://www.kernel.org/doc/Documentation/cgroup-v1/cpuacct.txt) reads from path `/sys/fs/cgroup/`:

- `cpuacct.usage`: total CPU time (in nanoseconds) since the start of the container obtained by this cgroup (CPU time obtained by all the tasks) in the system
- `cpuacct.stat`: reports the user and system CPU time consumed by all tasks in this cgroup (including tasks lower in the hierarchy)
    - `user`: CPU time (in nanoseconds) spent by tasks of the cgroup in user mode
    - `system`: CPU time (in nanoseconds) spent by tasks of the cgroup in kernel mode
    - `timestamp`: timestamp of when the measurement was taken

Both calls will return an object containing one or more `CpuMetric` objects for a specific cpu task: 
- `cpuNanosSinceContainerStart`: total CPU time (in nanoseconds) since the start of the container obtained by this cgroup in the system
- `timestamp`: timestamp of when the measurement was taken

Calculated CPU values:
- `calculateUsage`: takes two instances of calls to `cpuacct.usage` or `cpuacct.stat` and returns the calculated usage in percentage of CPU time:
    ` second time since container start - first time since container start / total time`


### Installation

```
npm install cgroup-metrics
```

### Usage

You can access each metric separately using the async functions for each metric

#### Memory Metrics
```javascript
const cgroup = require('cgroup-metrics');

const memory = cgroup.memory();
const containerUsage = await memory.containerUsage();
console.log(containerUsage);

const containerUsagePercentage = await memory.containerUsagePercentage(containerUsage);
console.log(containerUsagePercentage);
```

#### CPU Metrics
```javascript
const cpu = cgroup.cpu();

/* Returns an object like:
* {
*    cpuNanosSinceContainerStart: 120234,
*    timestamp: 153686574
* }
* */
const cpuacct_usage = await cpu.usage();
console.log(`Total CPU time since start of container (ns): ${cpuacct_usage.cpuNanosSinceContainerStart}`);


/* Returns an object like:
* {
*     user: {
*               cpuNanosSinceContainerStart: 120234,
*               timestamp: 153686574
*          },
*    system: {
*               cpuNanosSinceContainerStart: 120234,
*               timestamp: 153686574
*           },
* }
* */
const cpuacct_stats = await cpu.stat();
console.log(`CPU user count object: ${cpuacct_stat.user}`);
console.log(`CPU system count object: ${cpuacct_stat.system}`);

const calculateUsage = await cpu.calculateUsage(cpuacct_usage1, cpuacct_usage2);

```
#### All Metrics

Or you can use the function `metrics` to get an object of all the metrics:

```javascript
const metrics = await cgroup.metrics();

console.log(`Container usage: ${metrics.memory.containerUsage}`);
console.log(`Container usage percentage: ${metrics.memory.containerUsagePercentage}`);

console.log(`Total CPU time since start of container (ns): ${metrics.cpuacct.usagecpuNanosSinceContainerStart}`);
console.log(`CPU user count: ${metrics.cpuacct.stat.user}`);
console.log(`CPU system count: ${metrics.cpuacct.stat.system}`);
```
If you call `metrics` with parameter `flatten` set to `true`, it will return a flattened (1D) js object:
```javascript
const metrics = await cgroup.metrics(true);
console.log(`Memory usage in the container: ${metrics["memory.containerUsage"]}`)
```

### Error Handling

If there is no container running or there is an issue reading the file path, the function call will error something like this:
```
Error: Error reading file /sys/fs/cgroup/memory/memory.stat, Message: ENOENT: no such file or directory, open '/sys/fs/cgroup/memory/memory.stat'
```

If one of the files is empty, it will return an error like this:
```
Error: Error reading file /sys/fs/cgroup/memory/memory.stat, Message: File is empty
```

If a file is malformed, it will return an error like this:
```
Error: One or more metrics are malformed. containerUsage: 1234, limit: NaN
```
Or:
```
Error reading file /sys/fs/cgroup/cpuacct/cpuacct.stat, Message: Cannot read property 'split' of undefined
```

### Contributing

Contributions are welcomed! Read the [Contributing Guide](./CONTRIBUTING.md) for more information.

### Licensing

This project is licensed under the Apache V2 License. See [LICENSE](LICENSE) for more information.

---
_Source: https://npm.io/package/@adobe/cgroup-metrics · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._