[](https://github.com/NREL/WattAMeter/actions/workflows/ci.yml)
**wattameter** is a Python package for monitoring and recording power usage over time, among other metrics. It enables time series data collection on hardware components such as CPUs and GPUs.
## Current Features
- Track power usage for CPU (using RAPL) and GPU (using nvidia-ml-py)
- Track GPU utilization and temperature
- Periodically log time series data to file
- Customizable logging and output options
- Command-line interface for easy usage
- Integration with SLURM for HPC environments
## Installation
You can install **wattameter** via pip:
```bash
pip install wattameter
```
## Usage
### As a Python module
```python
from wattameter import Tracker
from wattameter.readers import NVMLReader
tracker = Tracker(
reader=NVMLReader((Power,)),
dt_read=0.1, # Time interval for reading power data (seconds)
freq_write=600, # Frequency (# reads) for writing power data to file
output="power_log.txt",
)
tracker.start()
# ... your code ...
tracker.stop()
# ... or ...
with Tracker(
reader=NVMLReader((Power,)),
dt_read=0.1,
freq_write=600,
output="power_log.txt",
) as tracker:
# ... your code ...
```
### Command-line interface
```sh
wattameter --suffix test --id 0 --dt-read 0.1 --freq-write 600 --log-level info
```
| Option | Short | Default | Description |
| ------------ | ----- | -------- | -------------------------------------------------------- |
| --suffix | -s | None | Suffix for output files |
| --id | -i | None | Identifier for the experiment |
| --dt-read | -t | 1 | Time interval (seconds) between readings |
| --freq-write | -f | 3600 | Frequency (# reads) for writing data to file |
| --log-level | -l | warning | Logging level: debug, info, warning, error, critical |
| --help | -h | | Show the help message and exit |
### Command-line interface with SLURM
For asynchronous usage with SLURM, we recommend using [wattameter.sh](src/wattameter/utils/wattameter.sh). Follow the example [examples/slurm.sh](examples/slurm.sh), i.e.,
```bash
#SBATCH --signal=USR1@0 # Send USR1 signal at the end of the job to stop wattameter
# Load Python environment with wattameter installed...
# Get the path of the wattameter script
WATTAPATH=$(python -c 'import wattameter; import os; print(os.path.dirname(wattameter.__file__))')
WATTASCRIPT="${WATTAPATH}/utils/wattameter.sh"
WATTAWAIT="${WATTAPATH}/utils/wattawait.sh"
# Run wattameter on all nodes
srun --overlap --wait=0 --nodes=$SLURM_JOB_NUM_NODES --ntasks-per-node=1 "${WATTAWAIT}" $SLURM_JOB_ID &
WAIT_PID=$!
srun --overlap --wait=0 --output=slurm-$SLURM_JOB_ID-wattameter.txt --nodes=$SLURM_JOB_NUM_NODES --ntasks-per-node=1 "${WATTASCRIPT}" -i $SLURM_JOB_ID & # Use other options here as needed
wait $WAIT_PID
# Run your script here...
# Cancel the job to stop wattameter
scancel $SLURM_JOB_ID
```
All options are the same as the regular command-line interface. The script will automatically handle the output file naming based on the provided SLURM_JOB_ID and node information.
## Contributing
Contributions are welcome! Please open issues or submit pull requests.
## License
See the [LICENSE](LICENSE) file for details.
---
_NREL Software Record number: SWR-25-101_
Raw data
{
"_id": null,
"home_page": null,
"name": "wattameter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "power-monitoring, energy-tracking, gpu-monitoring, cpu-monitoring, nvidia-ml, rapl, hpc, performance-monitoring",
"author": null,
"author_email": "Weslley da Silva Pereira <wdasilv@nrel.gov>",
"download_url": "https://files.pythonhosted.org/packages/72/da/e0709c323b45c0bc5af9eab3c310b0cf114e62ffa75b842df698cd63ff1e/wattameter-0.7.1.tar.gz",
"platform": null,
"description": "[](https://github.com/NREL/WattAMeter/actions/workflows/ci.yml)\n\n\n\n**wattameter** is a Python package for monitoring and recording power usage over time, among other metrics. It enables time series data collection on hardware components such as CPUs and GPUs.\n\n## Current Features\n\n- Track power usage for CPU (using RAPL) and GPU (using nvidia-ml-py)\n- Track GPU utilization and temperature\n- Periodically log time series data to file\n- Customizable logging and output options\n- Command-line interface for easy usage\n- Integration with SLURM for HPC environments\n\n## Installation\n\nYou can install **wattameter** via pip:\n\n```bash\npip install wattameter\n```\n\n## Usage\n\n### As a Python module\n\n```python\nfrom wattameter import Tracker\nfrom wattameter.readers import NVMLReader\n\ntracker = Tracker(\n reader=NVMLReader((Power,)),\n dt_read=0.1, # Time interval for reading power data (seconds)\n freq_write=600, # Frequency (# reads) for writing power data to file\n output=\"power_log.txt\",\n)\ntracker.start()\n# ... your code ...\ntracker.stop()\n\n# ... or ...\n\nwith Tracker(\n reader=NVMLReader((Power,)),\n dt_read=0.1,\n freq_write=600,\n output=\"power_log.txt\",\n) as tracker:\n # ... your code ...\n```\n\n### Command-line interface\n\n```sh\nwattameter --suffix test --id 0 --dt-read 0.1 --freq-write 600 --log-level info\n```\n\n| Option | Short | Default | Description |\n| ------------ | ----- | -------- | -------------------------------------------------------- |\n| --suffix | -s | None | Suffix for output files |\n| --id | -i | None | Identifier for the experiment |\n| --dt-read | -t | 1 | Time interval (seconds) between readings |\n| --freq-write | -f | 3600 | Frequency (# reads) for writing data to file |\n| --log-level | -l | warning | Logging level: debug, info, warning, error, critical |\n| --help | -h | | Show the help message and exit |\n\n### Command-line interface with SLURM\n\nFor asynchronous usage with SLURM, we recommend using [wattameter.sh](src/wattameter/utils/wattameter.sh). Follow the example [examples/slurm.sh](examples/slurm.sh), i.e.,\n\n```bash\n#SBATCH --signal=USR1@0 # Send USR1 signal at the end of the job to stop wattameter\n\n# Load Python environment with wattameter installed...\n\n# Get the path of the wattameter script\nWATTAPATH=$(python -c 'import wattameter; import os; print(os.path.dirname(wattameter.__file__))')\nWATTASCRIPT=\"${WATTAPATH}/utils/wattameter.sh\"\nWATTAWAIT=\"${WATTAPATH}/utils/wattawait.sh\"\n\n# Run wattameter on all nodes\nsrun --overlap --wait=0 --nodes=$SLURM_JOB_NUM_NODES --ntasks-per-node=1 \"${WATTAWAIT}\" $SLURM_JOB_ID &\nWAIT_PID=$!\nsrun --overlap --wait=0 --output=slurm-$SLURM_JOB_ID-wattameter.txt --nodes=$SLURM_JOB_NUM_NODES --ntasks-per-node=1 \"${WATTASCRIPT}\" -i $SLURM_JOB_ID & # Use other options here as needed\nwait $WAIT_PID\n\n# Run your script here...\n\n# Cancel the job to stop wattameter\nscancel $SLURM_JOB_ID\n```\n\nAll options are the same as the regular command-line interface. The script will automatically handle the output file naming based on the provided SLURM_JOB_ID and node information.\n\n## Contributing\n\nContributions are welcome! Please open issues or submit pull requests.\n\n## License\n\nSee the [LICENSE](LICENSE) file for details.\n\n---\n\n_NREL Software Record number: SWR-25-101_\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Python package for monitoring and recording power usage, energy consumption, and performance metrics from hardware components such as GPUs and CPUs",
"version": "0.7.1",
"project_urls": {
"Bug Reports": "https://github.com/NREL/WattAMeter/issues",
"Changelog": "https://github.com/NREL/WattAMeter/releases",
"Documentation": "https://github.com/NREL/WattAMeter#readme",
"Homepage": "https://github.com/NREL/WattAMeter"
},
"split_keywords": [
"power-monitoring",
" energy-tracking",
" gpu-monitoring",
" cpu-monitoring",
" nvidia-ml",
" rapl",
" hpc",
" performance-monitoring"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "16b3c0c1d8f7dd0e635f1a8614aef33b0725011df58fc10522cbe49b9865ccc2",
"md5": "9d8c3366f3db2cd58610a7f39bfd9617",
"sha256": "c66530bb2d6adb5788280d46b829e55bbc6e751648087ae9e73ed47629f8b5ee"
},
"downloads": -1,
"filename": "wattameter-0.7.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9d8c3366f3db2cd58610a7f39bfd9617",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 22262,
"upload_time": "2025-10-23T21:54:35",
"upload_time_iso_8601": "2025-10-23T21:54:35.488335Z",
"url": "https://files.pythonhosted.org/packages/16/b3/c0c1d8f7dd0e635f1a8614aef33b0725011df58fc10522cbe49b9865ccc2/wattameter-0.7.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "72dae0709c323b45c0bc5af9eab3c310b0cf114e62ffa75b842df698cd63ff1e",
"md5": "4dda6f84a34f3c5c145dc60ebb020f2b",
"sha256": "850ac57347851ae37ae40bb961ea677b2c76c20fa6d88abe882ff5e27525a677"
},
"downloads": -1,
"filename": "wattameter-0.7.1.tar.gz",
"has_sig": false,
"md5_digest": "4dda6f84a34f3c5c145dc60ebb020f2b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 29737,
"upload_time": "2025-10-23T21:54:36",
"upload_time_iso_8601": "2025-10-23T21:54:36.934781Z",
"url": "https://files.pythonhosted.org/packages/72/da/e0709c323b45c0bc5af9eab3c310b0cf114e62ffa75b842df698cd63ff1e/wattameter-0.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 21:54:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NREL",
"github_project": "WattAMeter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wattameter"
}
JSON
