EcoTrace

High-Precision Energy and Emissions Instrumentation

---

v1.7.1 — Performance & Telemetry Stability Patch. High-performance in-memory CPU database caching, defensive isolation in LangChain tracking callbacks, narrow terminal ASCII scaling fixes, and container environment safeguards.

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 | 200+ 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

---

Core Features in v1.7.0

Latest Release. v1.7.0 introduces native LangChain callback instrumentation, global carbon grid database expansion to 200+ countries, terminal ASCII table reporting, and streamlined CPU architecture resolution.

• Native LangChain Callback (ecotrace.callbacks.langchain) — Thread-safe EcoTraceLangChainCallback for LangChain and chat models. Measures process-scoped energy and carbon consumption per run_id, recording model names, execution durations, emissions ($gCO_2$), and provider token usage.
• Global Grid Expansion (200+ Countries/Zones) — Built-in CARBON_INTENSITY_MAP upgraded with verified country-level generation intensity data from the Ember Climate 2025/2026 dataset, providing offline local grid resolution across 209 countries and territories with zero configuration.
• Terminal ASCII Analysis Table (ecotrace analyze --table) — Bordered per-function breakdown table with responsive terminal width auto-scaling, column totals, and zero new third-party dependencies.
• Unified Hardware Specification Resolution — Direct matching against the 6,980+ CPU specification dataset for all x86 and Apple Silicon architectures, eliminating deprecated hardcoded mappings.
• HuggingFace & CodeCarbon Drop-in Interoperability — Full compatibility with HuggingFace TrainerCallback and CodeCarbon API signatures (EmissionsTracker, @track_emissions).

---

Quick Install

pip install ecotrace

Optional extras:

pip install ecotrace[gpu]   # NVIDIA GPU support
pip install ecotrace[ai]    # Gemini AI insights
pip install ecotrace[all]   # Everything

---

Quick Start

Option 1: Zero-Code Profiling (CLI + Cloud Sync)

Authenticate 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.py

Option 2: Programmatic Tracking & Cloud Dashboard

Decorate 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")

Option 3: Carbon Budget Mode

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")

Option 4: HuggingFace Transformers Integration

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()

Option 5: LangChain Integration

Measure the carbon footprint of every LLM call, chain, or agent run. Concurrent calls (batch(), async agents) are tracked separately by run_id:

from ecotrace.callbacks import EcoTraceLangChainCallback

cb = EcoTraceLangChainCallback(project_name="rag-pipeline")
llm.invoke("Summarise this document...", config={"callbacks": [cb]})

print(cb.total_emissions_g)  # gCO2 across all LLM calls
print(cb.records)            # per-call breakdown (model, duration, emissions, token usage)

Option 6: Drop-in CodeCarbon Compatibility

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")

Expected Output

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)
=======================================================

---

CI/CD & Testing Integration

Official GitHub Action (Carbon Gate)

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.7.0
  with:
    budget: '5.0'    # Fails pipeline if total test emissions exceed 5.0 gCO2
    region: 'US'

Pytest Plugin Integration

Measure per-test function carbon footprints directly from your test suite:

pytest --ecotrace

Manual CLI Gate

Run the gate locally or inside custom continuous integration pipelines:

ecotrace gate --budget 5.0 --region US

If total emissions recorded in ecotrace_log.csv exceed the budget, the command exits with code 1 — preventing carbon-heavy regressions from merging into production.

---

Why EcoTrace?

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).

---

Academic Benchmarks & Empirical Research

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 ($MAPE \le 6.8%$), and empirical study analyses.

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).

Citing EcoTrace

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}
}

---

Documentation

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.

---

Citation

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.7.1},
  doi = {10.5281/zenodo.22834060},
  url = {https://doi.org/10.5281/zenodo.22834060}
}

---

Contributing

We welcome contributions! Please see our CONTRIBUTING.MD for guidelines on reporting bugs, suggesting features, or contributing hardware data.

---

Community

CHANGELOG.md · SECURITY.MD

---

Author and License

Emre Ozkal — GitHub · ecotraceteam@gmail.com

MIT License — Use it however you like.

Developed for sustainable software development practices.