ecotrace 0.8.0

EcoTrace: High-precision carbon tracking engine for production Python. Function-level CPU/GPU emission measurement with 50ms continuous sampling, Boavizta TDP database, and audit-ready PDF reporting.

EcoTrace

High-Precision Energy and Emissions Instrumentation

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] VS Code Extension: Monitor application carbon footprint in real-time during development. Download here.

Function-level carbon measurement with real-time monitoring

---

Quick Install

pip install ecotrace

---

Quick Start

Option 1: Zero-Code Profiling (CLI)

Measure any script without changing a single line of code:

ecotrace run my_script.py

Option 2: Programmatic Tracking (Library)

Decorate functions for granular instrumentation:

from ecotrace import EcoTrace

# region_code: Use ISO 3166-1 alpha-2 (e.g., US, TR, DE). See docs/SUPPORT.md for full list.
eco = EcoTrace(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")

Expected Output

When initialized, EcoTrace performs automated hardware detection:

---------------------------------
--- EcoTrace v0.8.0 Initialized ---
Region  : US (367 gCO2/kWh)
CPU     : 13th Gen Intel Core i9-13900K
TDP     : 125.0W
Monitoring: Active (50ms sampling)
---------------------------------

---

Why EcoTrace?

Feature	EcoTrace	CodeCarbon	CarbonTracker
Sampling Interval	50ms	15s	Per Epoch
Isolation	Process-scoped	System-wide	System-wide
Dependencies	Zero (Core)	10+ (Pandas, etc.)	5+
Async Support	Native	Limited	No

• Deep Transparency: Derived from 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).

---

Documentation

• Architecture and Science — How the energy model and process isolation work.
• Advanced Usage — GPU tracking, AI insights, benchmarks, and comparison tables.
• Support and Reference — Troubleshooting, region codes, and hardware compatibility.

---

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 · [e-mail]

MIT License — Use it however you like.

Developed for sustainable software development practices.