Skip to content

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.7.1] - 2026-10-20

Fixed

  • Terminal ASCII Table Bounds Guard (ecotrace analyze --table): Fixed an IndexError: tuple index out of range crash triggered when terminal width is narrower than 28 columns by strictly aligning data cells to rendered header columns. Added automated matrix unit tests covering 20 to 100 column widths.
  • In-Memory CPU Specification Caching: Added functools.lru_cache(maxsize=1) to load_tdp_database in cpu.py, eliminating redundant disk I/O and parsing of cpu_data.csv (6,980+ rows) across successive EcoTrace() and EmissionsTracker() instances.
  • Defensive LangChain Tracking Isolation: Protected _begin and _finish lifecycle hooks in EcoTraceLangChainCallback with exception guards to ensure telemetry anomalies never crash host LLM inference or RAG workflows.
  • Container Environment Safeguards: Guaranteed non-null logical CPU core resolution (psutil.cpu_count() or 1) for restricted Docker/LXC container environments.
  • Hardware Configuration Completeness: Added explicit "nvidia": 150.0 default entry to GPU_TDP_DEFAULTS in constants.json.

[1.7.0] - 2026-09-30

Added

  • LangChain Integration (EcoTraceLangChainCallback): Native callback handler (ecotrace.callbacks.langchain) that measures process-scoped energy and carbon for every LLM and chat model call made through LangChain, including chains and agents. Concurrent calls are tracked independently per run_id, failed calls are cleaned up via on_llm_error, and provider token usage is recorded when available. LangChain is lazy-imported and remains an optional dependency. Includes examples/langchain_tracking.py and tests/test_langchain_callback.py (contributed by @Gthejesraj in #198).
  • Global Grid Database Expansion (200+ Countries/Zones): Upgraded CARBON_INTENSITY_MAP in constants.json with verified country-level generation intensity data from the Ember Climate 2025/2026 dataset, providing offline local carbon intensity resolution across 209 countries and territories with zero configuration.
  • Terminal ASCII Analysis Table (ecotrace analyze --table): Added bordered per-function breakdown table with responsive terminal width auto-scaling, column totals, and zero new third-party dependencies (contributed by @hajar-benhadj in #197 / #199).

Changed

  • Unified Hardware Specification Resolution: Cleaned up legacy hardcoded TDP_MAP in constants.json and cpu.py, unifying x86 and Apple Silicon processor resolution directly against the verified 6,980+ CPU specification dataset (cpu_data.csv).
  • OpenSSF Security & Dependency Pinning: Enforced GitHub branch protection status checks, established .github/CODEOWNERS, configured codecov.yml exclusion boundaries, and pinned continuous integration dependencies across Python 3.8 through 3.14-dev matrix jobs.

[1.6.1] - 2026-09-18

Added

  • HuggingFace Transformers Integration (EcoTraceHuggingFaceCallback): Native callback module (ecotrace.callbacks.huggingface) providing seamless integration with HuggingFace Trainer. Delivers automatic per-step carbon logging into state.log_history, per-epoch metric evaluation, and consolidated emissions reporting upon training completion.
  • CodeCarbon-Compatible API (ecotrace.tracker): Compatibility module exporting EmissionsTracker, OfflineEmissionsTracker, and track_emissions from top-level ecotrace, enabling projects already using the CodeCarbon API surface to adopt EcoTrace with minimal migration effort.
  • Case 08 Instrumentation Overhead Benchmark: Added empirical benchmark (benchmarks/08_ecotrace_vs_codecarbon.py) and academic article (benchmarks/articles/08_ecotrace_vs_codecarbon.md) comparing design tradeoffs between high-frequency process-scoped sampling (50ms) and periodic system-wide polling (15s) in carbon tracking libraries.
  • Zenodo DOI Archival Metadata (.zenodo.json): Added standardized Zenodo metadata configuration for automated citable DOI minting upon GitHub release tagging.

Changed

  • Benchmark Suite Harmonization: Renamed initial benchmark to benchmarks/01_pandas_vs_polars.py and updated suite registry in benchmarks/README.md to cleanly index Studies 01 through 08.
  • Strict IDE Diagnostic & Type Integrity: Resolved all 21 type checker diagnostics (Pyrefly / Pylance) across benchmark runners, whitepaper PDF generator (enforcing integer font sizes), and report dispatcher.
  • Repository Cleanliness: Enhanced .gitignore to automatically filter all generated CSV run logs across benchmarks and workspaces.

[1.6.0] - 2026-09-13

Added

  • Multi-GPU Automatic Tracking & Aggregation: Automated discovery of all available NVIDIA GPUs via NVML device enumeration (get_all_gpu_info) with continuous 50ms multi-GPU power measurement and aggregation (get_all_gpu_power_w).
  • Telemetry Hardware Reporting: Added multi-device GPU array reporting (GPU count, device models, combined TDP) to startup logs, session summaries, and exported JSON/CSV artifacts.
  • DDR3 RAM Speed Detection: Added memory clock frequency evaluation (800–2133 MHz) via dmidecode and WMI with calibrated DDR3 power factor (0.500 W/GB) for legacy enterprise architectures.
  • Cloud Exporter Offline Disk Retry Queue: Persistent local disk queue (~/.ecotrace/retry_queue) with automatic chronological FIFO queue flushing (50-entry ceiling) on network recovery.
  • Security Policy Update: Added v1.6.x to the active supported versions table in SECURITY.MD.

Changed

  • Deprecated Single gpu_index Parameter: Standardized multi-device monitoring across all GPUs; supplying gpu_index > 0 emits a backward-compatible DeprecationWarning.
  • Static Type Safety & Diagnostics Overhaul: Eliminated # type: ignore pragmas in favor of explicit TYPE_CHECKING imports and runtime type narrowing, achieving clean IDE diagnostics under Pyright and Pylance.

[1.5.1] - 2026-08-15

Fixed

  • Windows COM Initialization in Exporters: Added COM library initialization (CoInitialize/CoUninitialize) guards to worker threads in ThreadPoolExecutor to prevent Windows fatal exception (0x800401f0) during metric exports.
  • CloudExporter Parameter Forwarding: Updated exporter dispatch mechanism in core.py to forward run_id and run_label to registered exporters, enabling full session filtering on the web dashboard.
  • Exporter Signature Consistency: Added **kwargs support to all exporter signatures (CloudExporter, OTelExporter, WebhookExporter) to ensure forward and backward compatibility.
  • Logger Default Level: Restored logging.WARNING as default package log level across ecotrace.logger.
  • Dynamic Exporter Lazy Loading: Implemented module __getattr__ in ecotrace.exporters to prevent eager imports and potential circular import dependencies.

[1.5.0] - 2026-07-31

Added

  • CloudExporter & Native EcoTrace(api_key="eco_usr_...") Integration: Direct, zero-config telemetry streaming from Python applications to the EcoTrace Hosted Web Dashboard using private ingestion keys.
  • CLI Authentication & Credential Management: Added ecotrace login --key eco_usr_..., ecotrace logout, and ecotrace status terminal subcommands to securely manage credentials in ~/.ecotrace/config.json.
  • Automatic CLI Telemetry Streaming: ecotrace run <script.py> now automatically attaches saved credentials and streams execution runs to the user's web dashboard.
  • Web Backend WebSocket Live Channel: Implemented /api/ws/live WebSocket channel on FastAPI backend for real-time metric streaming to active web dashboard sessions.
  • 6,980+ Unique CPU TDP Database Expansion: Expanded cpu_data.csv to 6,983 unique CPU models with 100% valid TDP ratings, increasing laptop/mobile CPU coverage by +760% (1,520+ mobile CPUs including Intel 10th-14th Gen H/U/P/HX, Core Ultra, AMD Ryzen 3000-8000 mobile, and Apple Silicon M1-M4).
  • Expanded Python Version Compatibility: Extended Python compatibility from Python 3.9-3.12 to Python 3.8 → 3.14+ across pyproject.toml, documentation, marketplace manifests, and landing page metrics.

[1.4.3] - 2026-07-28

Fixed

  • CPU TDP Database Path Resolution: Fixed invalid file path in core.py targeting non-existent boaviztapi/data/crowdsourcing/ path. Redirected to cpu_data.csv (7,390+ CPU dataset, 100% verified TDP coverage) to ensure TDP database is actually loaded into memory instead of silently falling back to generic 65W for all x86 chips.
  • Enhanced CPU Model Matching Algorithm: Upgraded string resolution in cpu.py to support bidirectional containment checks, noise word stripping (cpu, processor), and length-descending model sorting so specific chips (e.g. i7-10700K, EPYC 7B12, i7-13700H) match their exact TDP boundaries.

Changed

  • Repository Cleanup: Removed 164 unused BoaviztAPI documentation, test, and build artifacts from git index, updating .gitignore to prevent tracking non-runtime assets.

[1.4.2] - 2026-07-21

Fixed

  • ram_info null safety: Guarded _compute_carbon against NoneType ram_info returns to prevent crash loops.
  • nvmlShutdown global scope isolation: Removed pynvml.nvmlShutdown() from instance __del__ destructor to preserve global NVML state for concurrent instances.
  • Exception propagation in measure() & measure_async(): Fixed exception handling in measurement teardown to prevent user function exceptions from being masked.
  • Dashboard Stored XSS: Sanitized user inputs before DOM rendering in live web dashboard.
  • Dashboard CORS origin restriction: Restricted Access-Control-Allow-Origin from wildcard * to localhost origin.
  • GitHub Action CLI integration: Added --region flag support to ecotrace gate subcommand required by action.yml.
  • Updater fallback logic: Replaced naive string inequality with integer tuple parsing for version comparison when packaging is absent.
  • Middleware lazy loading: Implemented module __getattr__ in middleware/__init__.py to avoid eager imports of web frameworks.
  • RAM power modeling: Added watt factors for DDR3, LPDDR4, LPDDR5 and UNKNOWN RAM types.
  • PDF Report log path parameter: Added configurable log_file parameter to generate_pdf_report.

[1.4.1] - 2026-07-18

Fixed

  • track_block() exception safety: Restructured with try/finally so carbon is always logged even when user code raises exceptions inside the block, matching the behavior of measure() and track_gpu().
  • GPU chart 3-tuple crash: Normalized GPU samples to 2-tuples (timestamp, utilization) in generate_pdf_report() before passing to chart functions, preventing data format mismatches with the core engine's 3-tuple (timestamp, utilization, power) samples.
  • Django middleware naming: Renamed EcoTraceMiddleware in middleware/django.py to EcoTraceDjangoMiddleware as documented in the v1.1.2 changelog. A backward-compatible alias is preserved for migration.
  • plistlib top-level import: Moved the plistlib import from top-level in hardware.py into the macOS-only methods where it is actually used, following the project's established lazy-import pattern.
  • Dashboard stale version: The live dashboard footer now dynamically resolves version from ecotrace.__version__ instead of displaying a hardcoded v1.3.0.
  • CSV export default filename: ecotrace export --csv now defaults output to ecotrace_export.csv instead of the format-mismatched ecotrace_report.json.
  • ML energy accumulation: Added total_energy_kwh attribute to EcoTrace.__init__ so EcoTraceML can correctly accumulate GPU energy across sessions.

[1.4.0] - 2026-07-01

Added

  • Pausable Tracking API (pause() / resume()): Temporarily disable carbon tracking during setup, teardown, or data loading phases. The paused duration is excluded from the session summary automatically.
  • ecotrace diff command: Side-by-side carbon footprint comparison of any two runs. Shows per-function call count, duration, and gCO2 deltas. Supports --latest shortcut for CI/CD pipelines.
  • WebhookExporter: Push carbon metrics to any webhook in real-time (Slack, MS Teams, Discord, custom APIs). Integrates with the existing add_exporter() API.
  • Filtered CSV Export: Extended ecotrace export with --csv format and --run/--func filter options for targeted data extraction.
  • ecotrace clean command: Rotate the CSV audit log by run count (--keep-runs) or date (--before). Creates an automatic .bak backup before trimming.
  • ecotrace reset command: Delete the CSV log file entirely with a confirmation prompt (--yes flag for non-interactive use).

Fixed

  • Duplicate Carbon Calculations: Removed duplicate and fragile carbon formulas in Keras and PyTorch callbacks — now delegates cleanly to EcoTraceML.log_epoch().
  • Empty GPU monitoring crash: Guarded EcoTraceML shutdown sequence against empty GPU monitor histories to prevent IndexError on CPU-only machines.
  • Async Metadata propagation: Propagated source file paths and line numbers correctly in measure_async(), restoring hotspot tracking for async functions.
  • CPU Cache Optimization: Eliminated duplicate cpuinfo.get_cpu_info() calls in get_cpu_info by reusing the cached fetch_raw_cpu_info() result.

[1.3.0] - 2026-06-13

Added

  • Multi-Run History (ecotrace history / ecotrace trends): Every EcoTrace session now gets a unique RunID and optional run_label. The ecotrace history CLI command groups the CSV audit log by run and prints a per-run carbon summary. ecotrace trends renders an ASCII bar chart of emissions across the last N runs, making it easy to see whether code is getting greener over time.
  • --label flag for ecotrace run: Tag any CLI session with a human-readable label (e.g. ecotrace run my_script.py --label nightly-build) that is stored in every CSV row of that run.
  • get_summary() API: New EcoTrace.get_summary() -> dict method returns all session metrics — run ID, duration, total carbon, budget status, hardware info, and carbon equivalence — as a structured dictionary. Enables integration with notebooks, dashboards, and custom reporting pipelines without parsing stdout or CSV.
  • Apple Silicon powermetrics Support: HardwareMonitor now detects Apple Silicon (M-series) Macs and reads exact CPU package energy via sudo -n powermetrics. Falls back to Boavizta estimation silently if powermetrics is unavailable — consistent with the existing RAPL fallback pattern.
  • ML Framework Callbacks (ecotrace.callbacks): New EcoTracePyTorchCallback and EcoTraceKerasCallback classes provide per-epoch carbon breakdowns for training loops. Both use lazy imports — neither PyTorch nor TensorFlow is required at install time. Install optionally with pip install ecotrace[ml] or pip install ecotrace[keras].
  • Live Dashboard (ecotrace dashboard): New ecotrace dashboard [--port 8585] CLI command starts a lightweight localhost HTTP server (zero external dependencies — stdlib only) serving a real-time browser dashboard. Features: carbon timeline chart, per-function emissions bar chart, run history table, run filter dropdown, and carbon equivalence display. Auto-refreshes every 5 seconds.
  • EcoTraceML.snapshot_energy(): New method for reading intermediate GPU energy values during training without stopping the monitoring thread.
  • EcoTraceML.log_epoch(): Logs per-epoch energy/carbon to the CSV audit log, used internally by the ML callbacks.

Changed

  • Session summary now displays the RunID (and label if set).
  • _print_session_summary() refactored to delegate to get_summary(), eliminating duplicated logic.
  • CSV audit log headers updated: RunID and RunLabel columns appended at the end for full backward compatibility with existing log files.
  • export_json() now includes run_id and run_label in the meta block.

[1.2.1] - 2026-06-03

Fixed

  • Windows RAM detection: Replaced deprecated wmic with PowerShell Get-CimInstance for Windows RAM speed detection, preventing compatibility issues on Windows 11 24H2.
  • ML CSV alignment: Aligned ML tracking CSV headers with the core engine's format to prevent parse mismatches.
  • ML constructor parameters: Added missing project_name, epochs, batch_size, and dataset_size parameters to the EcoTraceML constructor and decorator.
  • API security: Switched ip-api.com endpoint to HTTPS to protect against MITM attacks.
  • Dynamic User Agent: Resolved dynamic package version in USER_AGENT to prevent stale version reports.
  • GPU naming: Renamed misleading WATTS_PER_KILOWATT to MILLIWATTS_PER_WATT for Milliseconds to Watts NVML conversions.
  • Class-level atexit: Implemented class-level exit handler using a WeakSet to prevent duplicate per-instance exit summaries.
  • Security Policy: Updated supported versions in SECURITY.MD to include v1.2.x and v1.1.x.

[1.2.0] - 2026-05-31

Added

  • EcoTraceML tracking engine: A context manager (EcoTraceML) and decorator (@ecotrace_ml) designed to track carbon footprint and energy consumption of machine learning model training.
  • Continuous hardware sampling: Implemented multi-threaded background sampling for high-frequency hardware metrics polling.
  • ML test suite & example: Added tests/test_ml.py and example_ml.py to demonstrate and verify ML tracking functionality.

Fixed

  • NVIDIA NVML Windows compatibility: Dynamic search and injection of Windows PATH for NVML DLLs, resolving import issues on Windows.
  • NVIDIA driver decode: Safe fallback UTF-8 decoding for newer NVIDIA driver queries returning binary GPU names.
  • FPDF keyword issue: Removed txt keyword argument from PDF cell generation to resolve strict Pylance/Type warnings.
  • Lazy imports: Moved google-generativeai import inside get_gemini_insights to avoid startup ModuleNotFoundError when the [ai] extra is not installed.

[1.1.2] - 2026-05-21

Fixed

  • Session atexit: Class-level atexit handler with WeakSet instances replaces per-instance registration.
  • measure / measure_async: User exceptions propagate after measurement teardown; measurement errors no longer mask failures.
  • PDF / CSV: generate_pdf_report accepts log_path; report CSV parsing uses DictReader column names.
  • Gemini import: Lazy-load google.generativeai inside get_gemini_insights only.
  • Windows RAM: PowerShell Get-CimInstance replaces deprecated wmic.
  • Linux RAM: dmidecode without sudo first, then sudo -n when output is empty.
  • CPU info: Reuses cached fetch_raw_cpu_info() instead of duplicate cpuinfo calls.
  • USER_AGENT: Resolved from installed package version with fallbacks.
  • Update checker: _is_newer_version returns False on parse failure.

Changed

  • Breaking: Django middleware renamed to EcoTraceDjangoMiddleware (ecotrace.middleware.django). FastAPI EcoTraceMiddleware unchanged.
  • Logger default level restored to WARNING.

Updated

  • Version bumped to 1.1.2 across package metadata.

[1.1.0] - 2026-05-19

Added

  • OpenTelemetry Exporter: Added OTelExporter for non-blocking export of carbon metrics to OpenTelemetry-compatible platforms such as Grafana, Datadog, New Relic, and Prometheus.
  • Django Middleware: Added WSGI/ASGI request tracking with X-Eco-Carbon-Emitted and X-Eco-Duration response headers.
  • Celery Plugin: Added task-level carbon tracking through Celery worker signals, including retry and revoke cleanup handling.
  • Exporter API: Added EcoTrace.add_exporter(exporter) for registering custom exporter objects.

Fixed

  • GPU TDP Resolution: Runtime power limits are now used instead of factory default limits, improving estimates on power-capped GPUs.

Updated

  • Exporter dispatch now runs through a dedicated thread pool and flushes pending export tasks during process shutdown.
  • Version bumped to 1.1.0 across package metadata.

[1.0.1] - 2026-05-05

Added

  • Carbon Budget Enforcement: carbon_limit parameter now actively enforces budget with two-tier alerts (80% warning + 100% exceeded) and optional on_budget_exceeded callback.
  • Differential Tracking: Idle baseline measurement is now subtracted from all CPU utilization readings, reporting only the energy cost of YOUR code — not OS background noise.
  • Session Summary: Automatic atexit hook prints a formatted session summary (duration, functions tracked, total carbon, budget status) when the process exits.
  • Carbon Equivalences: New equivalence(gco2) method converts abstract gCO2 values into human-readable comparisons (Google searches, LED bulb minutes, smartphone charges, Netflix streaming, car km).
  • CI/CD Carbon Gate: New ecotrace gate --budget 10.0 CLI command returns exit code 1 if accumulated emissions exceed the carbon budget. Designed for GitHub Actions / GitLab CI integration.
  • remaining_budget Property: Programmatic access to remaining carbon budget for external consumers (IDE, dashboards).

Fixed

  • Exception Swallowing: measure() and measure_async() now properly re-raise user exceptions instead of silently returning None.
  • GPU track_block Crash: Fixed tuple unpacking error when computing GPU carbon in track_block().
  • GPU Chart Crash: Fixed 3-tuple unpacking in report.py GPU chart generation.
  • Packaging: Added ecotrace.middleware and ecotrace.plugins to distribution packages.
  • Optional Dependencies: Moved nvidia-ml-py, google-generativeai, and wmi to optional extras (pip install ecotrace[gpu], [ai], [all]).

Updated

  • Logger default level changed from WARNING to INFO (initialization banner now visible).
  • Version bumped to 1.0.1 across pyproject.toml, __init__.py, and config.py.

[0.9.0] - 2026-04-30

Added

  • Exact Mode (RAPL): Support for direct hardware energy counter monitoring on Linux (0% deviation).
  • Advanced Power Modeling: Implementation of non-linear Boavizta load curves for precise estimation on Windows/macOS.
  • Hybrid Energy Engine: Automatic hardware detection that selects the most accurate measurement method available.

[0.8.0] - 2026-04-24

Added

  • Unified CLI Tool: Introduced the ecotrace command-line interface with run, analyze, export, and benchmark subcommands.
  • JSON Export API: Added export_json(path) to the EcoTrace core to support VS Code extension integration.
  • python -m ecotrace Support: Package-level __main__.py module for direct module invocation.

Updated

  • Bumped version to 0.8.0 across pyproject.toml, __init__.py, and config.py.
  • Added [project.scripts] entry point for system-wide ecotrace command availability after pip install.

[0.7.1] - 2026-04-18

Added

  • Hotspot Highlighting: Added support for capturing source file paths and line numbers during instrumentation.

Updated

  • Optimized CSV logging performance to ensure stability during high-throughput monitoring.
  • Scaled up the versioning for both the core library (0.7.1) and VS Code extension (0.8.0).

[0.7.0] - 2026-04-09

Added

  • GPU Carbon Monitoring: Real-time utilization tracking for NVIDIA GPUs via NVML.
  • Grid Carbon Intensity Fallback: Automatic selection of static carbon data when Live Grid API is unavailable.
  • Memory Consumption Tracking: Process-scoped RSS monitoring integrated into total emission calculation.