energytrackr.pipeline.core_stages package

Submodules

energytrackr.pipeline.core_stages.build_stage module

Module to build the project if in ‘benchmarks’ mode or skip if in ‘tests’ mode.

class energytrackr.pipeline.core_stages.build_stage.BuildStage

Bases: PipelineStage

Builds the project if in ‘benchmarks’ mode, or skip if ‘tests’ mode has no build commands.

run(context: dict[str, Any]) → None

Executes the build stage of the pipeline based on the provided context and configuration.

This method handles two primary modes of operation:

1. Benchmarks Mode: Executes a series of build commands specified in the configuration. If any command fails, the pipeline may be aborted based on the configuration.

2. Batch Mode: Creates multiple copies of the repository, runs build commands in each copy, and handles failures similarly to benchmarks mode.

Parameters:

• context (dict[str, Any]) – A dictionary to store the state of the pipeline execution.

• used (Keys) –

  • “build_failed” (bool): Indicates if any build command failed.

  • ”abort_pipeline” (bool): Indicates if the pipeline should be aborted.

Notes

• The behavior of the pipeline is influenced by the configuration, specifically:

• config.execution_plan.mode: Determines if the pipeline is in benchmarks mode.

• config.execution_plan.batch_size: Specifies the number of repository copies to create in batch mode.

• config.execution_plan.compile_commands: The list of build commands to execute.

• config.execution_plan.ignore_failures: If True, the pipeline will not abort on build failures.

• The repository path is derived from config.repo_path.

energytrackr.pipeline.core_stages.checkout_stage module

Module to checkout a specific commit in a git repository.

class energytrackr.pipeline.core_stages.checkout_stage.CheckoutStage

Bases: PipelineStage

Checks out the commit specified in context[“current_commit”].

run(context: dict[str, Any]) → None

Checks out the commit specified in context[“current_commit”].

Retrieves the commit specified in context[“current_commit”] and the repository path from the configuration. It then checks out the commit using GitPython. If the checkout fails for any reason, it logs an exception and aborts the pipeline by setting context[“abort_pipeline”] = True.

Parameters:

context – A dictionary containing the current execution context, including the commit to checkout.

energytrackr.pipeline.core_stages.copy_directory_stage module

Pipeline stage to copy a directory to a target location.

class energytrackr.pipeline.core_stages.copy_directory_stage.CopyDirectoryStage

Bases: PipelineStage

Pipeline stage to copy a directory to a target location.

run(context: dict[str, Any]) → None

Executes the logic to copy a directory from source to target.

Parameters:

• context (dict[str, Any]) – A dictionary containing contextual information.

• keys (Expected) –

  • ‘source_dir’: str | Path — path to the source directory

  • ’target_dir’: str | Path — path to the destination directory

Raises:

• MissingContextKeyError – If the required keys are missing in the context.

• SourceDirectoryNotFoundError – If the source directory does not exist.

energytrackr.pipeline.core_stages.filter_and_regression_stage module

Module to filter commits and add regression context based on configuration.

This merged stage first applies filtering criteria to the commit list, then uses the original commit order along with the configuration parameters (min_commits_before and min_commits_after) to ensure that each candidate commit has a previous and/or a next commit for comparison. If a neighboring commit was removed during filtering, it is added back from the original list.

class energytrackr.pipeline.core_stages.filter_and_regression_stage.FilterAndRegressionStage

Bases: PipelineStage

Stage to filter commits and augment them with regression context.

Combined stage to filter commits and augment them with regression context based on the commit order and configuration parameters.

run(context: dict[str, Any]) → None

Executes the filter and regression augmentation stage of the pipeline.

This method processes the list of commits provided in the context, applying filtering criteria and augmenting the list for regression detection. It updates the context in place with the filtered and augmented list of commits, and may set the ‘abort_pipeline’ flag in the context if no commits remain after filtering.

Parameters:

context (dict[str, Any]) – The pipeline context containing at least a “commits” key with a list of Commit objects. The context is modified in place.

Side Effects:

• Logs information and warnings about the commit processing steps.

• Modifies the “commits” list in the context in place.

• Sets “abort_pipeline” in the context to True if no commits are available for further processing.

energytrackr.pipeline.core_stages.measure_stage module

Module for measuring energy consumption using perf.

class energytrackr.pipeline.core_stages.measure_stage.MeasureEnergyStage

Bases: PipelineStage

Uses perf to measure energy consumption. Appends the data to a results file.

static extract_energy_value(perf_output: str, event_name: str) → str | None

Extracts the value of the specified event from perf output.

Parameters:

• perf_output (str) – The output from the perf command.

• event_name (str) – The name of the event to extract, e.g. “power/energy-pkg/”.

Returns:

The value of the event as a string, or None if not found.

Return type:

str | None

run(context: dict[str, Any]) → None

Runs the energy measurement and appends the data to a results file.

If the build failed, or if there is no test command, or if the perf command fails, it will abort the pipeline unless ignore_failures is set.

Parameters:

context (dict) – The context dictionary containing the current commit and other configuration.

energytrackr.pipeline.core_stages.post_test_stage module

Module to run any post-test command (cleanup or teardown).

class energytrackr.pipeline.core_stages.post_test_stage.PostTestStage

Bases: PipelineStage

Runs any post-test command (cleanup or teardown).

run(context: dict[str, Any]) → None

Runs any post-test command (cleanup or teardown).

Retrieves the post-test command from the configuration and executes it within the specified working directory. If the command fails and failures are not ignored, the pipeline is aborted.

Parameters:

context (dict) – The shared context dictionary for the pipeline.

energytrackr.pipeline.core_stages.pre_build_stage module

Module to run pre-build commands (e.g., setting up environment).

class energytrackr.pipeline.core_stages.pre_build_stage.PreBuildStage

Bases: PipelineStage

Runs any pre-build commands (e.g., setting up environment).

Optionally only runs if certain files changed, etc.

run(context: dict[str, Any]) → None

Executes pre-build commands as defined in the configuration.

This method retrieves a pre-build command from the configuration and executes it within the specified repository path. If no pre-build command is defined, the stage is skipped. Optionally, the execution can be conditioned on changes in specific files, though such logic is not implemented here.

If the pre-build command fails and failures are not ignored, the pipeline is aborted.

Parameters:

context – A dictionary containing the current execution context, including flags for build failure and pipeline abortion.

energytrackr.pipeline.core_stages.set_directory_stage module

SetDirectoryStage: A pipeline stage to change the working directory to a commit-specific directory.

class energytrackr.pipeline.core_stages.set_directory_stage.SetDirectoryStage

Bases: PipelineStage

Pipeline stage to change the working directory to a commit-specific directory.

run(context: dict[str, Any]) → None

Executes the logic to change the current working directory to the commit-specific directory.

Parameters:

context (dict[str, Any]) – A dictionary containing contextual information. Expected to include a ‘commit’ key with the commit identifier.

Raises:

• MissingContextKeyError – If the ‘commit’ key is not found in the context.

• TargetDirectoryNotFoundError – If the target directory does not exist.

energytrackr.pipeline.core_stages.stability_check_stage module

Module to check the stability of the system before running the pipeline.

class energytrackr.pipeline.core_stages.stability_check_stage.StabilityCheckStage

Bases: PipelineStage

Runs a stability test on power usage before running the pipeline.

run(context: dict[str, Any]) → None

Runs a stability test on power usage before running the pipeline.

If the system is not stable, the pipeline is aborted by setting context[“abort_pipeline”] = True. Otherwise, the pipeline is allowed to proceed.

Parameters:

context (dict[str, Any]) – The pipeline context containing the

energytrackr.pipeline.core_stages.temperature_check_stage module

Stage to check CPU temperature before proceeding with the pipeline.

class energytrackr.pipeline.core_stages.temperature_check_stage.TemperatureCheckStage

Bases: PipelineStage

Ensures that the CPU is not too hot before starting the next stage.

run(context: dict[str, Any]) → None

Monitors the CPU temperature and waits until it is below a safe limit before proceeding.

Parameters:

• self (TemperatureCheckStage) – The instance of the stage.

• context (dict) – The shared context dictionary for the pipeline.

The function repeatedly checks the CPU temperature by reading from the thermal file specified in the configuration. If the temperature is above the safe limit, it logs a warning and waits for 2 seconds before checking again. If the temperature is below the safe limit, or if there is an issue reading the temperature, it logs the information and exits the loop, allowing the pipeline to proceed.

energytrackr.pipeline.core_stages.verify_perf_stage module

Module to check if user is allowed to use perf without sudo.

class energytrackr.pipeline.core_stages.verify_perf_stage.VerifyPerfStage

Bases: PipelineStage

Runs any pre-build commands (e.g., setting up environment).

Optionally only runs if certain files changed, etc.

run(context: dict[str, Any]) → None

Check if user is allowed to use perf without sudo.

Parameters:

• context (dict[str, Any]) – The pipeline context.

• keys (Expected) –

  • “abort_pipeline”: bool — indicates if the pipeline should be aborted.

Module contents

Core stages of the pipeline.