v1.6.1 — HuggingFace Integration, CodeCarbon Drop-in API & Metrology Study. Native HuggingFace Trainer callback, CodeCarbon-compatible API layer (EmissionsTracker), Case 08 Metrology & Overhead benchmark, and Zenodo DOI archival integration.
EcoTrace is a lightweight library for granular carbon footprint measurement of Python applications. No configuration files, no background services—just real-time hardware-level transparency.
Real-time monitoring | 50+ Global Zones | AI-powered insights | Zero-configuration
[!TIP] Live Web Observatory: Stream and monitor your application carbon footprint in real-time on our hosted web platform at ecotracelibrary.com.
[!TIP] VS Code Extension: Monitor application carbon footprint in real-time during development. Download here.
Function-level carbon measurement with real-time monitoring
Latest Release. v1.6.1 introduces native HuggingFace Trainer callbacks, drop-in CodeCarbon API compatibility, the Case 08 Observer Effect benchmark study, and official Zenodo DOI archival indexing.
- HuggingFace Transformers Callback (
ecotrace.callbacks.huggingface) — NativeEcoTraceHuggingFaceCallbackinjecting instantaneous power draw (W) and cumulative carbon metrics directly intostate.log_historyon step and epoch intervals. - CodeCarbon Drop-in API (
ecotrace.tracker) — Zero-codebase-refactoring drop-in replacement (EmissionsTracker,OfflineEmissionsTracker,@track_emissions) enabling existing projects to switch to EcoTrace seamlessly. - Automated Multi-GPU Tracking & Aggregation (
ecotrace.gpu) — Automatically discovers all available NVIDIA GPUs via NVML (get_all_gpu_info) and aggregates instantaneous power draw at 50ms intervals across active accelerators. - Offline Disk Retry Queue (
CloudExporter) — Telemetry payloads are safely persisted to an isolated local disk queue during network outages, automatically flushing in chronological FIFO order upon reconnection. - Zenodo DOI Archival Integration — Standardized metadata (
.zenodo.json,CITATION.cff) ensuring verifiable scientific citation and permanent preservation.
pip install ecotraceOptional extras:
pip install ecotrace[gpu] # NVIDIA GPU support
pip install ecotrace[ai] # Gemini AI insights
pip install ecotrace[all] # EverythingAuthenticate your terminal once, then profile any script without changing source code:
# 1. Login with your ingestion key from https://ecotracelibrary.com
ecotrace login --key eco_usr_abc123...
# 2. Run your script — metrics automatically stream to your web dashboard!
ecotrace run my_script.pyDecorate functions for granular instrumentation and stream metrics to your web account:
from ecotrace import EcoTrace
# Connects directly to your hosted account at https://ecotracelibrary.com
eco = EcoTrace(api_key="eco_usr_abc123...", region_code="US")
@eco.track
def my_function():
# Your heavy processing here
pass
my_function()
# Export audit-ready reports or check cumulative totals
eco.generate_pdf_report("carbon_audit.pdf")
print(f"Total Carbon Emitted: {eco.total_carbon} gCO2")Set a limit and let EcoTrace enforce it:
eco = EcoTrace(
region_code="TR",
carbon_limit=5.0, # 5 gCO2 budget
on_budget_exceeded=lambda t, l: print(f"Budget exceeded: {t:.4f}/{l:.4f} gCO2")
)
@eco.track
def training_pipeline():
...
training_pipeline()
print(f"Remaining budget: {eco.remaining_budget} gCO2")Log step-by-step carbon emissions automatically inside HuggingFace Trainer:
from transformers import Trainer
from ecotrace.callbacks import EcoTraceHuggingFaceCallback
trainer = Trainer(
model=model,
args=training_args,
callbacks=[EcoTraceHuggingFaceCallback()],
)
trainer.train()Migrate legacy codebases with zero refactoring — just change your import:
# from codecarbon import EmissionsTracker <-- Change to EcoTrace:
from ecotrace import EmissionsTracker
tracker = EmissionsTracker(project_name="bert-finetuning")
tracker.start()
# ... your model training or inference ...
emissions = tracker.stop()
print(f"Emissions: {emissions:.6f} kg CO2")When initialized, EcoTrace performs automated hardware detection:
[EcoTrace] INFO: [INFO] EcoTrace instrumentation session initialized (STATIC).
[EcoTrace] INFO: -----------------------------------------------------
[EcoTrace] INFO: Region : TR (475 gCO2/kWh)
[EcoTrace] INFO: Hardware Logic: 13th Gen Intel Core i7-13700H
[EcoTrace] INFO: Specifications: 20 Cores | 45.0W TDP
[EcoTrace] INFO: Energy Sensor : Boavizta Advanced Estimation
[EcoTrace] INFO: Memory Config : 15.6 GB DDR4
[EcoTrace] INFO: GPU Accelerator: Intel Iris Xe Graphics (15.0W TDP)
[EcoTrace] INFO: -----------------------------------------------------
At process exit, a session summary is printed automatically:
=======================================================
EcoTrace — Session Summary
=======================================================
Duration : 12.34s
Functions : 5 tracked
Total Carbon : 0.00312000 gCO2
Region : TR (475 gCO2/kWh)
Budget : 0.003120 / 5.000000 gCO2 (0.1%) [OK]
Equivalent : 0.4 min of LED bulb (10W)
=======================================================
Enforce carbon emission budgets directly in your GitHub pull requests. Add this to your .github/workflows/ci.yml:
- name: Run Tests with Carbon Profiling
run: pytest --ecotrace
- name: EcoTrace Carbon Gate
uses: Zwony/ecotrace@v1.6.1
with:
budget: '5.0' # Fails pipeline if total test emissions exceed 5.0 gCO2
region: 'US'Measure per-test function carbon footprints directly from your test suite:
pytest --ecotraceRun the gate locally or inside custom continuous integration pipelines:
ecotrace gate --budget 5.0 --region USIf total emissions recorded in ecotrace_log.csv exceed the budget, the command exits with code 1 — preventing carbon-heavy regressions from merging into production.
| Feature | EcoTrace v1.6 | CodeCarbon | CarbonTracker |
|---|---|---|---|
| Sampling Interval | 50ms | 15s | Per Epoch |
| Isolation | Process-scoped | System-wide | System-wide |
| Cloud Dashboard Sync | Native | No | No |
| Multi-GPU Tracking | Continuous (Aggregated) | Single GPU | Per Epoch |
| CPU Dataset | 6,980+ CPUs | Limited | Limited |
| Budget Enforcement | Built-in | No | No |
| CI/CD Gate | Built-in | No | No |
| Idle Noise Subtraction | Automatic | No | No |
| Async Support | Native | Limited | No |
- Deep Transparency: Derived from 6,980+ verified manufacturer TDP specifications rather than category averages.
- Fail-Safe Architecture: Guaranteed application continuity even if hardware drivers or API keys are missing.
- Actionable AI: Integrates with Google Gemini to provide specific code optimization advice (optional).
Tip
📄 Official Technical Whitepaper: Download the comprehensive EcoTrace Technical Whitepaper (PDF) or view the online WHITE_PAPER.md for complete mathematical derivations, RAPL hardware validation metrics (
EcoTrace includes a reproducible Academic Benchmark Suite designed for peer-reviewed green computing research. Every article in benchmarks/articles/ is auto-generated from real measurement JSONs in benchmarks/results/ by benchmarks/report_generator.py — re-run the generator after new measurements to keep the published numbers in sync.
- Data Engineering: Pandas vs. Polars on 5M Rows — 83.8% carbon reduction via Arrow vectorization (real numbers from this machine).
-
Computer Science: Algorithmic Complexity Carbon Scaling — Insertion Sort at
$N = 50{,}000$ emits ~3,469× more carbon than NumPy on the same input (the quadratic carbon cliff). - Cloud Architecture: Web Framework Throughput vs. Carbon — Flask vs. FastAPI under identical load; FastAPI achieves 1.13× speedup and 9.8% carbon reduction (CPU mode).
- Generative AI: LLM Inference Carbon Footprint — Per-token energy and carbon cost of GPT-2 inference (CPU mode; medium/large models require GPU).
- Cloud Architecture: Spatial Carbon Arbitrage across 15 Countries — The same workload in South Africa emits ~73× more carbon than in Sweden (a 99% reduction is achievable by region selection alone).
- Metrology Validation: Empirical Accuracy vs. Intel RAPL Counters — model-vs-hardware validation methodology with honest synthetic-mode fallback for non-Linux systems.
- Machine Learning: PyTorch vs. TensorFlow CNN Training — Carbon per accuracy point analysis (CPU mode; numbers regenerate after each run).
If you use EcoTrace or its benchmark suite in scientific publications:
@software{ozkal2026ecotrace,
author = {Ozkal, Emre},
title = {EcoTrace: High-Precision Energy and Emissions Instrumentation for Python},
year = {2026},
url = {https://github.com/Zwony/ecotrace},
version = {1.6.0}
}Full documentation is available at ecotracelibrary.com and ecotrace.readthedocs.io.
- Official Website — Live carbon dashboard and web management platform.
- Architecture and Science — How the energy model and process isolation work.
- Advanced Usage — GPU tracking, AI insights, benchmarks, and comparison tables.
- API Reference — Technical documentation for core classes and functions.
- Support and Reference — Troubleshooting, region codes, and hardware compatibility.
- Technical Whitepaper (PDF) — Comprehensive metrology and empirical evaluation report.
If you use EcoTrace in academic research or sustainability audits, please cite:
@software{ecotrace2026,
author = {Ozkal, Emre},
title = {EcoTrace: High-Precision Energy and Emissions Instrumentation for Python},
year = {2026},
publisher = {Zenodo},
version = {v1.6.1},
doi = {10.5281/zenodo.22834060},
url = {https://doi.org/10.5281/zenodo.22834060}
}We welcome contributions! Please see our CONTRIBUTING.MD for guidelines on reporting bugs, suggesting features, or contributing hardware data.
Emre Ozkal — GitHub · ecotraceteam@gmail.com
MIT License — Use it however you like.
Developed for sustainable software development practices.