# Show HN: EcoTrace – Lightweight carbon footprint and energy tracker for Python

> Source: <https://github.com/Zwony/ecotrace>
> Published: 2026-07-22 15:45:55+00:00

**v1.4.0 — Feature Release.** Pausable tracking API, WebhookExporter, side-by-side CLI diff comparison, filtered CSV exporting, and log maintenance commands — all with zero new mandatory dependencies.

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

Feature Release.v1.4.0 adds pausable tracking, side-by-side run comparisons, webhook integrations, filtered CSV exporting, and log rotation capabilities.

**Pausing API**— Temporarily disable carbon tracking using`EcoTrace.pause()`

and`EcoTrace.resume()`

to exclude setup and teardown overhead.**Run Comparisons (**— Perform side-by-side carbon and execution duration comparisons between two specific runs.`ecotrace diff`

)**Webhook Integration (**— Stream carbon emissions data to Slack, Teams, Discord, or a custom API in real-time.`WebhookExporter`

)**Filtered CSV Exporting**— Export filtered subsets of measurement logs with`--csv`

format and`--run`

/`--func`

filters.**Log Maintenance Commands**— Rotate and trim logs via`ecotrace clean`

, and permanently delete logs using`ecotrace reset`

.**Multi-Run History**— Every session gets a unique`RunID`

. Use`ecotrace history`

to compare runs and`ecotrace trends`

for an ASCII carbon trend chart.— Programmatic access to all session metrics as a typed dict. Ideal for notebooks, dashboards, and CI assertions.`get_summary()`

API

```
pip install ecotrace
```

Optional extras:

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

Measure any script without changing a single line of code:

```
ecotrace run my_script.py
```

Decorate functions for granular instrumentation:

``` python
from ecotrace import EcoTrace

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

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

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 budgets in your pipeline with our official GitHub Action. Add this to your `.github/workflows/ci.yml`

:

```
- name: EcoTrace Carbon Gate
  uses: Zwony/ecotrace@v1.3.0
  with:
    budget: '10.0'
    region: 'US'
```

You can also run the gate manually:

```
ecotrace gate --budget 10.0
```

If total emissions exceed the budget, the gate fails with exit code 1 — preventing carbon-heavy code from being merged.

| Feature | EcoTrace v1.0 |
CodeCarbon | CarbonTracker |
|---|---|---|---|
Sampling Interval |
50ms |
15s | Per Epoch |
Isolation |
Process-scoped |
System-wide | System-wide |
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 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).

Full documentation is available at [ ecotrace.readthedocs.io](https://ecotrace.readthedocs.io/en/latest/).

— How the energy model and process isolation work.**Architecture and Science**— GPU tracking, AI insights, benchmarks, and comparison tables.** Advanced Usage**— Technical documentation for core classes and functions.** API Reference**— Troubleshooting, region codes, and hardware compatibility.** Support and Reference**

We welcome contributions! Please see our [ CONTRIBUTING.MD](/Zwony/ecotrace/blob/main/CONTRIBUTING.MD) for guidelines on reporting bugs, suggesting features, or contributing hardware data.

**Emre Ozkal** — [GitHub](https://github.com/Zwony) · [ecotraceteam@gmail.com](mailto:ecotraceteam@gmail.com)

MIT License — Use it however you like.

*Developed for sustainable software development practices.*