{"id":43492817,"url":"https://github.com/scrrlt/carbon-ops","last_synced_at":"2026-03-02T03:07:54.427Z","repository":{"id":335431249,"uuid":"1145716072","full_name":"scrrlt/carbon-ops","owner":"scrrlt","description":"Application performance monitor (APM) for energy logging and carbon estimation in Python applications with uncertainty-aware marginal emissions.","archived":false,"fork":false,"pushed_at":"2026-02-03T02:20:49.000Z","size":176,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-03T21:32:01.538Z","etag":null,"topics":["audit-ledger","carbon-accounting","carbon-estimation","compliance","cpu-monitoring","cryptographic-signing","energy-efficiency","energy-logging","esg","gpu-monitoring","green-computing","marginal-carbon","memory-profiling","observability","performance-monitoring","python-library","scope-3","sustainability","telemetry","uncertainty-propagation"],"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/scrrlt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":"audit_schema_v0.1.0.json","citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-30T05:54:48.000Z","updated_at":"2026-02-03T02:20:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"87d7e0a8-cb3e-4e5f-9d42-d531d0551386","html_url":"https://github.com/scrrlt/carbon-ops","commit_stats":null,"previous_names":["scrrlt/carbon-ops"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/scrrlt/carbon-ops","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scrrlt%2Fcarbon-ops","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scrrlt%2Fcarbon-ops/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scrrlt%2Fcarbon-ops/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scrrlt%2Fcarbon-ops/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scrrlt","download_url":"https://codeload.github.com/scrrlt/carbon-ops/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scrrlt%2Fcarbon-ops/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29991309,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["audit-ledger","carbon-accounting","carbon-estimation","compliance","cpu-monitoring","cryptographic-signing","energy-efficiency","energy-logging","esg","gpu-monitoring","green-computing","marginal-carbon","memory-profiling","observability","performance-monitoring","python-library","scope-3","sustainability","telemetry","uncertainty-propagation"],"created_at":"2026-02-03T10:16:31.275Z","updated_at":"2026-03-02T03:07:54.422Z","avatar_url":"https://github.com/scrrlt.png","language":"Python","readme":"# carbon-ops\n\n`carbon-ops` is an application performance monitor (APM) for energy logging and\ncarbon estimation in Python workloads. It measures marginal carbon emissions for\nindividual tasks, tracks CPU, GPU, and memory usage, and propagates uncertainty\nthrough each estimate. Output is written as canonical JSON lines with hash\nchaining for auditability. The repository includes the core Python library, a\nprivileged polling daemon, and supporting scripts for audit workflows.\n\n## Components\n\n- **Library**: Energy logging utilities, carbon estimation methods, and ledger\n    emitters that produce tamper-evident records.\n- **Governance daemon**: Polls RAPL counters at 10 Hz, maintains a monotonic\n    accumulator, and exposes readings over a Unix domain socket for unprivileged\n    access.\n- **Examples**: Reference scripts demonstrating integration patterns, including\n    a comparison between the governance daemon and a 15-second Prometheus-style\n    scraper.\n- **Documentation**: Markdown files covering deployment, telemetry modes,\n    limitations, and planned features.\n\n## Use Cases\n\n- Collect host-level telemetry (CPU, GPU, memory, RAPL) for training or\n    inference jobs.\n- Estimate carbon emissions for a time span using location-specific grid\n    intensity data. The estimator records the method (`analytical_truncated` or\n    `monte_carlo`) and includes confidence interval metadata.\n- Emit audit ledger entries with hash-linked JSON lines to support tamper\n    detection.\n- Attribute energy usage to individual processes using governance daemon totals\n    and per-process CPU time (`allocation_ratio`).\n\n## Installation\n\nSupports Python 3.10 and later on Linux. RAPL-based telemetry requires access to\n`/sys/class/powercap` or `/dev/cpu/*/msr` (via `intel_rapl_common` and `msr`\nkernel modules). Install with extras to enable optional features and\ndevelopment tools:\n\n```bash\npython -m pip install carbon-ops[all,dev]\n```\n\nFor local development, use the helpers in `scripts/` or standard tools like\n`venv` and `pip`.\n\n## Quick Start\n\n```python\nfrom carbon_ops import CarbonEstimator, EnergyLogger\n\ntry:\n    logger = EnergyLogger()\nexcept Exception as exc:\n    raise SystemExit(f\"EnergyLogger initialisation failed: {exc}\")\n\nmetric = logger.log_metrics(\"training_step\")\n\nestimator = CarbonEstimator()\nrecord = estimator.estimate_over_span(\n    start_ts=metric[\"timestamp_start\"],\n    end_ts=metric[\"timestamp_end\"],\n    energy_wh=metric[\"energy\"][\"energy_wh_total\"],\n)\nprint(record.to_dict())\n```\n\nIf the governance daemon is unavailable, the logger reports\n`attribution_mode=\"monitor_only\"` and continues execution without raising an\nexception.\n\n## Telemetry Modes\n\nTwo RAPL backends are supported:\n\n- **Sysfs mode** (default): Reads from `/sys/class/powercap/.../energy_uj`.\n    Samples are masked to 32 bits before accumulation to reduce noise.\n- **MSR mode** (privileged): Reads from `/dev/cpu/\u003cn\u003e/msr`. The daemon reads\n    MSR `0x606` (power unit register), applies a 32-bit mask to counters\n    (e.g., MSR `0x611`), converts to microjoules, and uses the same accumulator as\n    sysfs. Enable with `--rapl-mode=msr [--msr-cpus=…]`. Requires root or\n    `CAP_SYS_RAWIO` and the `msr` kernel module.\n\n## Governance Daemon\n\nStart the daemon using the default sysfs mode:\n\n```bash\nsudo python -m carbon_ops.governor.daemon\n```\n\nTo use MSR mode on CPUs 0 and 1:\n\n```bash\nsudo python -m carbon_ops.governor.daemon --rapl-mode=msr --msr-cpus=0,1\n```\n\nThe daemon listens on `/var/run/carbon-ops.sock` with `root:carbon-users`\nownership and `0o660` permissions. If the socket is unavailable, the library\nfalls back to monitor-only mode.\n\n## Aliasing Demonstration\n\nThe script `examples/aliasing_demo.py` compares the 10 Hz governance daemon\noutput with a simulated Prometheus scraper polling every 15 seconds. It runs a\nCPU-bound loop, logs energy via the Unix socket, and reports energy missed by\nthe slower scraper due to RAPL counter wrapping.\n\n```bash\nsudo python examples/aliasing_demo.py --duration 120\n```\n\n## Ledger Output\n\nLedger entries are emitted as canonical JSON lines. Each entry includes the hash\nof the previous record (`prev_hash`) to form a hash chain. Writes are atomic,\nusing a temporary file followed by `os.replace`.\n\n## Testing\n\nRun the test suite after installing development dependencies:\n\n```bash\npython -m pytest\npython -m ruff check .\npython -m black --check .\npython -m mypy --strict .\npython -m bandit -r src\n```\n\nTool versions are pinned in `pyproject.toml` to match CI.\n\n## Contributing\n\nSee [Contributing](./CONTRIBUTING.md) for contribution guidelines.\n\n## License\n\nThis project is licensed under the terms of [MIT License](./LICENSE).\n\n## Support\n\n- Issues: [https://github.com/scrrlt/carbon-ops/issues](https://github.com/scrrlt/carbon-ops/issues)\n- Discussions: GitHub Discussions coming soon\n- Email: [s@scrrlt.dev](mailto:s@scrrlt.dev)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscrrlt%2Fcarbon-ops","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscrrlt%2Fcarbon-ops","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscrrlt%2Fcarbon-ops/lists"}