# Powerlog
[](https://pypi.org/project/powerlog/)
**Powerlog** is a lightweight command-line tool and Python package to profile Nvidia GPU power consumption during the execution of a command-line program. It uses `nvidia-smi` to sample power draw at regular intervals and reports total energy usage, average power, and min/max readings.
## Features
* Measures real-time GPU power draw using `nvidia-smi`
* Computes:
* Total runtime
* Total energy consumed (in Joules)
* Average (sampled and timed), min, and max power (Watts)
* Outputs both summary and raw samples as CSV
* Simple CLI interface
* Reports Avg Power Sampled (mean of all readings) and Avg Power Timed (energy divided by total time)
## Installation
Requires Python 3.6+ and NVIDIA's `nvidia-smi` available in your system PATH.
Project page at the Python Package Index (PyPI): [https://pypi.org/project/powerlog/](https://pypi.org/project/powerlog/)
Install with pip:
```bash
pip install powerlog
```
## Usage
```bash
powerlog --output power_report.csv --gpu 1 ./my_gpu_program arg1 arg2
```
### CLI Options
| Argument | Description |
| ------------ | ------------------------------------------- |
| `--output` | Base name for the output CSV files |
| `--gpu` | Number of GPUs to monitor (default: 1) |
| `cmd` | Command and arguments to run and profile |
## Output
If `--output power.csv` is specified:
* `power.csv`: Summary of runtime, energy, and power stats
* `power_samples.csv`: Raw timestamped power draw samples
## Example
```bash
powerlog --output matrix_power.csv --gpu 1 nvidia-smi
```
This will generate `matrix_power.csv` and `matrix_power_samples.csv`
Demo content of `matrix_power.csv`:
```text
Total Time (s),Total Energy (J),Avg Power Sampled (W),Avg Power Timed (W),Min Power Sampled (W),Max Power Sampled (W)
0.1001,1.2856,12.8400,12.8400,12.84,12.84
```
Demo content of `matrix_power_samples.csv`:
```text
Timestamp (ns),Power Draw (W)
1752198440220994393,12.84
```
## Dependencies
* Python standard library (`subprocess`, `argparse`, `time`, `csv`)
* NVIDIA GPU with drivers and `nvidia-smi` tool
## How power and energy are calculated?
### Power log collection
Powerlog uses `nvidia-smi` to measure GPU power draw at regular intervals (default: every 0.1 seconds). The Python wrapper script automatically runs this measurement loop from the start to the end of your program.
## Total energy consumption computation
Total energy ***E*** (in Joules) is computed as
$$
E = \sum_{i=1}^N P_i \cdot \Delta t_i
$$
where:
- **N**: total number of sampling intervals
- **P<sub>i</sub>**: GPU power draw (Watts) at interval *i*
- **Δt<sub>i</sub>**: elapsed time (seconds) between sample *i* and sample *i-1*
## Development
### Local Testing
To test Powerlog locally during development (before releasing to PyPI), you can install your package in "editable" mode:
```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```
### Publishing to PyPI
When the package is ready to publish (or update) Powerlog on PyPI, use the following commands:
```
python -m pip install --upgrade build
python3 -m build
python3 -m pip install --upgrade twine
twine upload dist/*
```
This will build the distribution files (.tar.gz and .whl) and upload them to PyPI.
It requires API token for authentication.
### Changelog
See the [Changelog.md](Changelog.md) file in this repository for version history and release notes.
## License
MIT License
## Acknowledgments
- Developed as part of GPU power-efficiency profiling experiments in Datalog-based engines.
- Inspired by the [EUMaster4HPC](https://eumaster4hpc.uni.lu/)
Raw data
{
"_id": null,
"home_page": null,
"name": "powerlog",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "energy, gpupower, power analysis, power log, powerlog",
"author": null,
"author_email": "Ahmedur Rahman Shovon <shovon.sylhet@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b4/0a/519b34ca075160563093807b8bf744ecb9eea75a1e2a789538393cbeab4c/powerlog-0.0.2.tar.gz",
"platform": null,
"description": "# Powerlog\n\n[](https://pypi.org/project/powerlog/)\n\n\n**Powerlog** is a lightweight command-line tool and Python package to profile Nvidia GPU power consumption during the execution of a command-line program. It uses `nvidia-smi` to sample power draw at regular intervals and reports total energy usage, average power, and min/max readings.\n\n## Features\n\n* Measures real-time GPU power draw using `nvidia-smi`\n* Computes:\n\n * Total runtime\n * Total energy consumed (in Joules)\n * Average (sampled and timed), min, and max power (Watts)\n* Outputs both summary and raw samples as CSV\n* Simple CLI interface\n* Reports Avg Power Sampled (mean of all readings) and Avg Power Timed (energy divided by total time)\n\n## Installation\n\nRequires Python 3.6+ and NVIDIA's `nvidia-smi` available in your system PATH.\n\nProject page at the Python Package Index (PyPI): [https://pypi.org/project/powerlog/](https://pypi.org/project/powerlog/)\n\nInstall with pip:\n```bash\npip install powerlog\n```\n\n## Usage\n\n```bash\npowerlog --output power_report.csv --gpu 1 ./my_gpu_program arg1 arg2\n```\n\n### CLI Options\n\n| Argument | Description |\n| ------------ | ------------------------------------------- |\n| `--output` | Base name for the output CSV files |\n| `--gpu` | Number of GPUs to monitor (default: 1) |\n| `cmd` | Command and arguments to run and profile |\n\n## Output\n\nIf `--output power.csv` is specified:\n\n* `power.csv`: Summary of runtime, energy, and power stats\n* `power_samples.csv`: Raw timestamped power draw samples\n\n## Example\n\n```bash\npowerlog --output matrix_power.csv --gpu 1 nvidia-smi\n```\n\nThis will generate `matrix_power.csv` and `matrix_power_samples.csv`\n\nDemo content of `matrix_power.csv`:\n```text\nTotal Time (s),Total Energy (J),Avg Power Sampled (W),Avg Power Timed (W),Min Power Sampled (W),Max Power Sampled (W)\n0.1001,1.2856,12.8400,12.8400,12.84,12.84\n```\n\nDemo content of `matrix_power_samples.csv`:\n```text\nTimestamp (ns),Power Draw (W)\n1752198440220994393,12.84\n```\n\n## Dependencies\n\n* Python standard library (`subprocess`, `argparse`, `time`, `csv`)\n* NVIDIA GPU with drivers and `nvidia-smi` tool\n\n## How power and energy are calculated?\n### Power log collection \nPowerlog uses `nvidia-smi` to measure GPU power draw at regular intervals (default: every 0.1 seconds). The Python wrapper script automatically runs this measurement loop from the start to the end of your program.\n\n## Total energy consumption computation\n\nTotal energy ***E*** (in Joules) is computed as\n$$\nE = \\sum_{i=1}^N P_i \\cdot \\Delta t_i\n$$\n\nwhere:\n\n- **N**: total number of sampling intervals \n- **P<sub>i</sub>**: GPU power draw (Watts) at interval *i* \n- **\u0394t<sub>i</sub>**: elapsed time (seconds) between sample *i* and sample *i-1*\n\n## Development\n\n### Local Testing\n\nTo test Powerlog locally during development (before releasing to PyPI), you can install your package in \"editable\" mode:\n\n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e .\n```\n\n### Publishing to PyPI\nWhen the package is ready to publish (or update) Powerlog on PyPI, use the following commands:\n\n```\npython -m pip install --upgrade build\npython3 -m build\npython3 -m pip install --upgrade twine\ntwine upload dist/*\n```\nThis will build the distribution files (.tar.gz and .whl) and upload them to PyPI.\n\nIt requires API token for authentication.\n\n### Changelog\n\nSee the [Changelog.md](Changelog.md) file in this repository for version history and release notes.\n\n## License\n\nMIT License\n\n## Acknowledgments\n\n- Developed as part of GPU power-efficiency profiling experiments in Datalog-based engines.\n- Inspired by the [EUMaster4HPC](https://eumaster4hpc.uni.lu/) \n",
"bugtrack_url": null,
"license": null,
"summary": "GPU power log",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/arsho/powerlog",
"Issues": "https://github.com/arsho/powerlog/issues"
},
"split_keywords": [
"energy",
" gpupower",
" power analysis",
" power log",
" powerlog"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "991ff6f30ef2f23455f18b0d9919e5ae582653d6149cf89a8887615056cc0951",
"md5": "b44bfa50244a8f1091e55cda14e538e0",
"sha256": "f674dfc17844b2f303531d53d95cee32934c25a228dd18e190f8a2b5f936c4a9"
},
"downloads": -1,
"filename": "powerlog-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b44bfa50244a8f1091e55cda14e538e0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5855,
"upload_time": "2025-07-11T02:37:02",
"upload_time_iso_8601": "2025-07-11T02:37:02.255788Z",
"url": "https://files.pythonhosted.org/packages/99/1f/f6f30ef2f23455f18b0d9919e5ae582653d6149cf89a8887615056cc0951/powerlog-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b40a519b34ca075160563093807b8bf744ecb9eea75a1e2a789538393cbeab4c",
"md5": "a1a60140844b4e4930d1985437345ed7",
"sha256": "faf421c56606e858bd172f2cbbbf546e6012da2491bfb48fbc69413716fcc9f4"
},
"downloads": -1,
"filename": "powerlog-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "a1a60140844b4e4930d1985437345ed7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5301,
"upload_time": "2025-07-11T02:37:02",
"upload_time_iso_8601": "2025-07-11T02:37:02.983828Z",
"url": "https://files.pythonhosted.org/packages/b4/0a/519b34ca075160563093807b8bf744ecb9eea75a1e2a789538393cbeab4c/powerlog-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 02:37:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "arsho",
"github_project": "powerlog",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "powerlog"
}
JSON
