EcoTrace

High-Precision Energy and Emissions Instrumentation

---

v1.8.0 — Community & Hardware Expansion Release. Slack and Discord rich card webhook exporters, CLI run CSV session exports, FastAPI middleware reference, expanded TDP coverage for Apple M4, Intel Core Ultra, and AMD Ryzen 9000 processors, plus official LangChain and HuggingFace integration guides.

EcoTrace is a lightweight, zero-configuration hardware profiler for Python applications, AI training pipelines, and LLM workloads. Measure exact process-scoped energy consumption (Joules/kWh), runtime latency, and operational carbon footprint ($gCO_2$) without background daemons.

Hardware-Level Telemetry (RAPL / NVML / Apple Silicon) • Process-Scoped Isolation • Native LLM & LangChain Callbacks • 100% Offline & Local-First

Function-level energy and carbon measurement with real-time monitoring

Core Features in v1.8.0

Latest Release. v1.8.0 brings community-driven webhook enhancements (Slack and Discord rich cards), CLI run CSV session export, reference FastAPI middleware integration, and broadened next-generation hardware profiles.

• Slack Block Kit & Discord Embed Exporters (WebhookExporter) — Export real-time emissions to Slack channels and Discord servers with budget-aware embed color coding based on carbon_limit thresholds.
• CLI Session CSV Export (ecotrace run -o session.csv) — Persist run-level metrics directly into CSV tables without stdout redirection, complete with structured hardware metadata serialization.
• Next-Gen Hardware Specification Coverage — Added architecture and TDP profiles for Apple Silicon M4 (Base, Pro, Max), Intel Core Ultra (Arrow Lake and Meteor Lake), and AMD Ryzen 9000 Zen 5 processors.
• FastAPI Reference Integration (examples/fastapi_tracking.py) — Production reference demonstrating EcoTraceMiddleware attachment and request-level carbon telemetry headers (X-Eco-*).
• Native LangChain & HuggingFace Callbacks — End-to-end process-scoped carbon and token profiling for LLMs, RAG pipelines, and model training workflows.

Quick Install

pip install ecotrace

Optional extras:

pip install ecotrace[gpu]   # NVIDIA GPU (NVML) support
pip install ecotrace[ai]    # Gemini AI code optimization insights
pip install ecotrace[all]   # Full dependencies (GPU + AI + Report generation)

Quick Start (100% Local & Offline)

EcoTrace works entirely on your local machine with zero configuration, zero API keys, and no required accounts.

Option 1: 3-Line Function Profiler

Decorate any synchronous or asynchronous function to immediately inspect its runtime energy draw and carbon impact:

from ecotrace import EcoTrace

eco = EcoTrace()

@eco.track
def process_data():
    # Your heavy compute, batch job, or inference logic
    return sum(i * i for i in range(10_000_000))

process_data()

When your script exits, EcoTrace automatically prints an accurate hardware breakdown (Joules, Wh, execution latency, and $gCO_2$).

Option 2: Zero-Code CLI Profiler

Profile any standalone Python script or training run without changing a single line of source code:

# Run script with terminal ASCII breakdown table
ecotrace run my_script.py --table

Option 3: LangChain & AI Agent Callback (LLM Profiling)

Officially listed in the LangChain Provider Directory. Measure the exact hardware energy footprint and token consumption of every LLM call, RAG pipeline, or autonomous agent:

from ecotrace.callbacks import EcoTraceLangChainCallback

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

print(f"Total Emissions: {cb.total_emissions_g:.6f} gCO2")
print(cb.records)  # per-call breakdown: model, duration, token usage, emissions

Option 4: A/B Implementation Comparison

Directly compare the energy efficiency and execution speed of two alternative algorithms or libraries (e.g., Pandas vs. Polars):

from ecotrace import EcoTrace

eco = EcoTrace()

# Compares runtime, CPU utilization, Joules, and carbon side-by-side
eco.compare(pandas_pipeline, polars_pipeline)

Option 5: Carbon Budget & Guardrail Mode

Set an operational budget and trigger alerts when your workload exceeds thresholds:

eco = EcoTrace(
    region_code="TR",
    carbon_limit=5.0,  # 5 gCO2 budget
    on_budget_exceeded=lambda total, limit: print(f"Budget exceeded: {total:.4f}/{limit:.4f} gCO2")
)

@eco.track
def training_pipeline():
    ...

training_pipeline()
print(f"Remaining budget: {eco.remaining_budget} gCO2")

Option 6: HuggingFace Transformers Integration

Log step-by-step training emissions directly inside HuggingFace Trainer:

from transformers import Trainer
from ecotrace.callbacks import EcoTraceHuggingFaceCallback

trainer = Trainer(
    model=model,
    args=training_args,
    callbacks=[EcoTraceHuggingFaceCallback()],
)
trainer.train()

Option 7: Drop-in CodeCarbon Compatibility

Migrate legacy codebases with zero refactoring — just change your import statement:

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

Optional: Live Web Observatory & Cloud Dashboard

If you want live streaming dashboards, team collaboration, or persistent audit history across cloud clusters, connect your local runs to our hosted platform at ecotracelibrary.com:

# 1. Login with your personal ingestion key from https://ecotracelibrary.com
ecotrace login --key eco_usr_abc123...

# 2. Run your script — telemetry automatically streams to your web dashboard!
ecotrace run my_script.py

Or connect programmatically via Python:

eco = EcoTrace(api_key="eco_usr_abc123...", region_code="US")

Save a CLI run report

Place --output (or -o) before the script path to save a report while keeping the console summary:

ecotrace run --output report.json my_script.py
ecotrace run -o session.csv my_script.py

A .csv extension (case insensitive) writes one row from get_summary() for the current session. Nested objects, including hardware and a configured budget, use JSON inside their CSV cells. Other extensions use the existing JSON report format, including hardware metadata, audit-log measurements and totals.

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?

• 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

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.8.0},
  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.