How flipflop133/energytrackr works
Project Type & Purpose
• Type: A command-line tool / open-source library (Python)
• Purpose: Orchestrates a pluggable pipeline of “stages” to measure energy consumption (via Intel RAPL or perf) across Git commits, then outputs CSV data and automated plots.
Main Components
A. CLI & Command Dispatcher
– main.py → Parses args (via utils/args_parser.py) → Delegates to commands/dispatcher.py
B. Configuration Subsystem
– config/loader.py loads JSON/YAML → config/config_model.py (pydantic) → config/config_store.py
C. Pipeline Orchestrator
– pipeline/pipeline.py: Pipeline class reads execution_plan → instantiates PipelineStage objects → coordinates execution
– stage_interface.py: Defines the interface for all stages
D. Core & Custom Stages (Plugin Points)
– Core stages (pipeline/core_stages/…): checkout, pre-build, build, measure, regression check, post-test, etc.
– Custom stages (pipeline/custom_stages/…): e.g. java_setup_stage.py
E. Measurement Engine
– Under the measure stage: invokes external tools (GitPython, perf, Intel RAPL); writes raw energy readings
F. Data Persistence
– CSV writer (built into pipeline stages) → sorted.csv, metadata
G. Plotting Subsystem
– plot/pipeline.py loads CSV → passes through:
• Data transforms (plot/builtin_data_transforms/…)
• Plot object registry & renderers (plot/builtin_plot_objects/…)
• Page sections & templates (plot/builtin_page_sections/…)
• Core loader & context (plot/core/…)
– Outputs PNG/HTML via matplotlib + JS assets
H. Utilities
– utils/logger.py, git_utils.py, sort.py, generic helpers
I. External Dependencies & Tools
– Git (GitPython), Python (≥3.13), perf or RAPL, matplotlib, ruptures, pydantic
Component Relationships & Data Flow
• CLI → Dispatcher → Config Loader → Pipeline Orchestrator
• Pipeline → executes sequence of Stage instances → each stage may invoke Git, build tools, measure tools → writes intermediate results (CSV)
• Once pipeline completes → Plotting Subsystem ingests CSV → runs transforms → assembles page → dumps plots
• Utilities provide cross-cutting support (logging, error handling, sorting)
Architectural Patterns & Design Principles
• Modular “PipelineStage” interface (Strategy/Plugin pattern)
• Registry pattern for plot types
• Layered: CLI → Core engine → Plugins → I/O (CSV/plots)
• Single Responsibility: each stage does one thing (checkout, build, measure, etc.)
• Configuration-driven execution plan (Pydantic models enforce schema)