Jump to content

KEcoLab/User Docs/User Guide: Difference between revisions

From KDE Community Wiki
Rupa-rd (talk | contribs)
53 edits
Usage Scenario Page is created and content is added
 
Rupa-rd (talk | contribs)
53 edits
User Guide content is uploaded
 
Line 1: Line 1:
<h1>What is a Usage Scenario Script? </h1>
<h1> Introduction </h1>


A usage scenario script comprises a set of shell command files designed to measure the energy and hardware consumption of software across different operational modes: idle, baseline and sus. Each of these modes will have a separate usage scenario script to emulate user input.
Welcome to KEcoLab’s User Guide!


<h1> Why is it Used? </h1>
'''KEcoLab''' project aims to provide a streamlined process for measuring software energy consumption remotely using a CI/CD pipeline. By automating the measurement process and integrating with the OSCAR tool, users can make informed decisions to improve code efficiency and obtain software eco-certification with the Blue Angel. Check out our [https://eco.kde.org/handbook/ handbook] to know more about Blue Angel certification.


The primary purpose of a usage scenario script is to characterize software performance under various conditions. This involves analyzing how resource consumption (CPU, memory, disk I/O, network), response times, and other key metrics vary depending on the software's state (idle, baseline, sus).
<h1> Getting Started </h1>
This guide will provide you with step-by-step instructions on how you can measure your software’s energy consumption through KEcoLab.  


These scripts serve to automate user actions. By using these scripts in conjunction with the power meter, developers can efficiently gather comprehensive performance characteristics. This process is crucial for assessing the software's overall efficiency and identifying areas for optimization, which directly correlates with reducing its environmental footprint.
If you have any trouble while performing any of the below steps, refer to this tutorial video for help:


<h1> Script Creation </h1>
<i>[Video Tutorial Will be Placed Here]</i>


<ol>
Let’s start with preparing the necessary documentation for energy measurements.
<li> Create a folder and name it in the format reflective of its flatpak name as available on flathub. For eg for okular, it is <code>org.kde.okular</code> </li>


<li> The folder name and the Merge Request title should be the same. </li>
<h1> Pre-requisites </h1>
Before measuring your software’s energy consumption, make sure to prepare usage scenario script for the software.


<li> The folder should contain the following files.
<h2> Usage Scenario Scripts </h2>
<ul>
<li> log_baseline.sh </li>
<li> log_idle.sh </li>
<li> log_sus.sh </li>
<li> configuration.sh </li>
</ul>
</li>


</ol>
Usage scenario scripts are a set of shell command files designed to measure the energy and hardware consumption of software across different operational modes: idle, baseline and sus.


NOTE:- every application has a different naming scheme, <code> org.kde.<software_name> </code> is usually for kde applications, for non kde applications the naming scheme would be different.
During the '''idle mode''' your software will be opened but no action is performed, in '''baseline mode''' only operating system will be running, and in '''SUS mode''' your software will be opened and perform certain actions.


<h1> Files in the Folder </h1>
You need to prepare three files written in shell commands: idle.sh, baseline.sh, and sus.sh. Additionally, if you want to write any configurations for the software, you can add that in configuration.sh and attach with other files.


<ul>
If you need guidelines on creating these scripts, you can refer to the **[https://community.kde.org/KEcoLab/User_Docs/Usage_Scenario_Script Usage Scenario Script]** page.


<li> '''log_baseline.sh (Operating System only)'''</li>
<h1> Usage </h1>
<ul>
In this section, you will execute and measure the energy consumption for your software.
<li>  This is a baseline scenario script. To establish the baseline, a scenario is measured in which the Operating System is running but no actions are taken. </li>
<li>  For the baseline scenario script template, check this [https://invent.kde.org/sdk/kecolab/-/blob/master/templates/test_scripts/log_baseline.sh link]. </li>
</ul>


<li> '''log_idle.sh (OS + Application while Idle)''' </li>
<h2> Create a Fork </h2>
<ul>
As a first step, you need to fork the KEcoLab repository. Navigate to [https://invent.kde.org/teams/eco/remote-eco-lab this] link and click the <code>Fork</code> button in the right corner.
<li>  This is an idle mode scenario script. To establish the energy consumption and hardware performance data of the application while idle, a scenario is measured in which the application under consideration is opened but no action is taken. </li>
<li>  For the idle scenario script template, follow this [https://invent.kde.org/sdk/kecolab/-/blob/master/templates/test_scripts/log_idle.sh link]. </li>


</ul>
[[File:Kecolab-fork.png|center]]


'''Important'''
Do not change the project name and project slug. Under the <code> select a namespace</code>, select your <code>username</code> and click <code>create fork</code>.


The baseline and idle mode must be run for the same time needed to carry out the standard usage scenario. Since the power consumption for the baseline and idle scenario is relatively uniform, 10 repetitions for each is considered sufficient to obtain a representative sample.
[[File:Kecolab-fork-2.png|center]]


<li> '''log_sus.sh (OS + Application in Use)'''  </li>
You can either use WebIDE or your local machine.  
<ul>
<li>  This file is for standard usage scenarios. To measure the energy consumption and hardware performance data of the application in use, the standard usage scenario should be run.  </li>
<li>  The measurement of the standard usage scenario should be repeated 30 times, which will take several hours to complete. The higher number of repetitions is necessary to obtain a representative sample as the energy consumption and performance data may vary across measurements.  </li>
<li>  Follow this [https://invent.kde.org/sdk/kecolab/-/blob/master/templates/test_scripts/log_sus.sh link]for the standard usage scenario script template. </li>
</ul>


<li> '''configuration.sh (Optional)''' </li>
<h3> Using Local Machine</h3>
<ul>
If you choose to use your local machine, click code > copy the link under clone with HTTPS.
<li> This script adds the option to add user configurations such as shortcuts, which might be used to make the automation process easier. </li>
 
<li> Check out this [https://invent.kde.org/sdk/kecolab/-/blob/master/templates/test_scripts/configuration.sh link] for the configuration script template. </li>
[[File:Kecolab-url.png|center]]
</ul>
 
</ul>
Open a terminal on your local machine and copy and paste the command below to clone the repository on your local machine. Replace the <code><copied_link></code> with the actual link you copied before.
 
<center>
<code>git clone <copied_link></code>
</center>
 
[[File:Kecolab-cli-clone.jpg|center]]
 
The next step is to create a new branch for your software. Copy the command below to create a new branch and replace <code><branch_name></code> with your software name. Eg: '''org.kde.kate''', '''org.kde.okular'''.
 
<center>
<code>git checkout <branch_name></code>
</center>
 
[[File:Kecolab-cli-new-branch.jpg|center]]
 
 
<h3> Using WebIDE </h3>
Click <code>edit fork in WebIDE</code> which is present next to the code.
 
[[File:Kecolab-weide-link.jpg|center]]
 
Once the IDE is opened, click <code>master</code> in the bottom left corner of the IDE and choose <code>create new branch</code>.
 
Provide a name to the new branch (prefavorably the name of the software) and <code>enter</code>. You will switch to the new branch. Eg: '''org.kde.kate''', '''org.kde.okular'''.
 
[[File:Kecolab-weide-new-branch.jpg |center]]
 
<h2> Upload files </h2>
The next step is to organize the scripts you created and add them to a folder. Navigate to this location: <code>scripts</code> > <code>test_scripts</code>. Inside the <code>test_scripts</code> folder, create a new folder for your software.
 
The name of the folder should be strictly in this format only: ''org.kde.kate'''
 
Replace kate with your software name and upload all the scripts (i.e., baseline.sh, idle.sh, sus.sh and configuration.sh).
 
[[File:Kecolab-webide-upload.png|center]]
 
<h2> Push Changes </h2>
After uploading the files, create a commit with a message. Follow the instructions below to create a commit.
 
<h3> Using Local Machine </h3>
Before committing your changes, you need to stage the changes using the git command
 
<center>
<code>git add .</code>
</center>
 
This will add all the unstaged files.
 
To create a commit on your local machine, paste the below command in your terminal. Replace <code><software_name></code> with your software name.
 
<center>
<code>git commit -m “Uploaded files for <software_name> energy measurement.”</code>
</center>
 
[[File:Kecolab-cli-commit.jpg|center]]
 
Once you committed the changes in your local machine, it’s time to push the changes to the forked repository. Paste the command in your terminal and do not forget to replace `<branch_name>` with your new branch name.
 
<center>
<code>git push origin <branch_name></code>
</center>
 
[[File:Kecolab-cli-push.jpg|center]]
 
<h3> Using WebIDE </h3>
To stage the changes in WebIDE, go to <code>source control</code> that is present in the left navbar.  
 
[[File:Kecolab-weide-source-control.jpg|center]]
 
Enter a commit message similar to this ''''‘Uploaded files for kate software energy measurement’'''' and click <code>commit and push to new_branch</code> button. This will push the changes to your new branch you created.
 
[[File:Kecolab-webide-commit.jpg|center]]
 
<h2> Create a merge request</h2>
After pushing the changes to the new branch, go to the forked repository page. You will see a notification to create a merge request. Click <code>create merge request</code> button.
 
[[File:Kecolab-create-mr.jpg|center]]
 
Add the title of the merge request similar to the folder name you created i.e., if the folder name is <i>‘org.kde.kate’</i> then the title of the merge request is also <i>‘org.kde.kate’</i>. Failing to do so, you will encounter errors in the measurement process.
 
[[File:Kecolab-create-mr-detail.png|center]]
 
<h2> Review and Approval </h2>
After creating a merge request, wait for some time to review the merge request before running the measurement process. During this step, if you made any error creating a folder, uploading files or any errors in the usage scenario script will be notified.
 
<h2> CI/CD pipeline execution </h2>
The next step is pipeline execution. Successfully creating a merge request will trigger the pipeline defined for measuring the energy consumption of a software. During the execution of the pipeline, three jobs will run.
 
[[File:Kecolab-jobs.jpg|center]]
 
The first job is '''build'''. In the build job process, the pipeline will define and prepare all the necessary files and environments required for the measurement process.
 
[[File:Kecolab-job-1.jpg|center]]
 
The second job is '''measurement'''. In this job, the actual measurement of the energy consumption will take place. The measurement process will execute for each mode of the software, i.e., idle, baseline, and sus. The measurement will approximately execute for 30 iterations to get the most accurate results for each mode.
 
[[File:Kecolab-job-2.jpg|center]]
 
The last job is '''result'''. During this job, the results will be generated in the pdf format with the help of the R script and Oscular we defined already.
 
[[File:Kecolab-job-3.png|center]]
 
<h1> Access the result </h1>
Upon successfully executing all the jobs, you can download the results it generated.
 
<h2> Downloading Artifacts and Reports </h2>
As a result of the pipeline, you will be able to download the artifacts and reports from the merge request page you created.
 
In the artifacts folder, you can see two reports. '''Idle_Report''' report is for idle mode, and '''Sus_Report''' is for sus mode. You can find the measurement details inside the reports. Other folders includes the artifacts used to create the reports. Check out the Accessing Reports page for detailed report analysis.
 
[[File:Kecolab-artifact-folder.png|center]]
 
<h1> Conclusion </h1>
By automating the energy measurement process and providing remote access, we make it possible for developers to measure the energy consumption of their software from any location in the world. The increased access to the lab will enable data-driven decision-making for efficiency improvements in code and software eco-certification with agencies like the Blue Angel.

Latest revision as of 11:56, 1 April 2025

Introduction

Welcome to KEcoLab’s User Guide!

KEcoLab project aims to provide a streamlined process for measuring software energy consumption remotely using a CI/CD pipeline. By automating the measurement process and integrating with the OSCAR tool, users can make informed decisions to improve code efficiency and obtain software eco-certification with the Blue Angel. Check out our handbook to know more about Blue Angel certification.

Getting Started

This guide will provide you with step-by-step instructions on how you can measure your software’s energy consumption through KEcoLab.

If you have any trouble while performing any of the below steps, refer to this tutorial video for help:

[Video Tutorial Will be Placed Here]

Let’s start with preparing the necessary documentation for energy measurements.

Pre-requisites

Before measuring your software’s energy consumption, make sure to prepare usage scenario script for the software.

Usage Scenario Scripts

Usage scenario scripts are a set of shell command files designed to measure the energy and hardware consumption of software across different operational modes: idle, baseline and sus.

During the idle mode your software will be opened but no action is performed, in baseline mode only operating system will be running, and in SUS mode your software will be opened and perform certain actions.

You need to prepare three files written in shell commands: idle.sh, baseline.sh, and sus.sh. Additionally, if you want to write any configurations for the software, you can add that in configuration.sh and attach with other files.

If you need guidelines on creating these scripts, you can refer to the **Usage Scenario Script** page.

Usage

In this section, you will execute and measure the energy consumption for your software.

Create a Fork

As a first step, you need to fork the KEcoLab repository. Navigate to this link and click the Fork button in the right corner.

Do not change the project name and project slug. Under the select a namespace, select your username and click create fork.

You can either use WebIDE or your local machine.

Using Local Machine

If you choose to use your local machine, click code > copy the link under clone with HTTPS.

Open a terminal on your local machine and copy and paste the command below to clone the repository on your local machine. Replace the <copied_link> with the actual link you copied before.

git clone <copied_link>

The next step is to create a new branch for your software. Copy the command below to create a new branch and replace <branch_name> with your software name. Eg: org.kde.kate, org.kde.okular.

git checkout <branch_name>


Using WebIDE

Click edit fork in WebIDE which is present next to the code.

Once the IDE is opened, click master in the bottom left corner of the IDE and choose create new branch.

Provide a name to the new branch (prefavorably the name of the software) and enter. You will switch to the new branch. Eg: org.kde.kate, org.kde.okular.

Upload files

The next step is to organize the scripts you created and add them to a folder. Navigate to this location: scripts > test_scripts. Inside the test_scripts folder, create a new folder for your software.

The name of the folder should be strictly in this format only: org.kde.kate'

Replace kate with your software name and upload all the scripts (i.e., baseline.sh, idle.sh, sus.sh and configuration.sh).

Push Changes

After uploading the files, create a commit with a message. Follow the instructions below to create a commit.

Using Local Machine

Before committing your changes, you need to stage the changes using the git command

git add .

This will add all the unstaged files.

To create a commit on your local machine, paste the below command in your terminal. Replace <software_name> with your software name.

git commit -m “Uploaded files for <software_name> energy measurement.”

Once you committed the changes in your local machine, it’s time to push the changes to the forked repository. Paste the command in your terminal and do not forget to replace `<branch_name>` with your new branch name.

git push origin <branch_name>

Using WebIDE

To stage the changes in WebIDE, go to source control that is present in the left navbar.

Enter a commit message similar to this '‘Uploaded files for kate software energy measurement’' and click commit and push to new_branch button. This will push the changes to your new branch you created.

Create a merge request

After pushing the changes to the new branch, go to the forked repository page. You will see a notification to create a merge request. Click create merge request button.

Add the title of the merge request similar to the folder name you created i.e., if the folder name is ‘org.kde.kate’ then the title of the merge request is also ‘org.kde.kate’. Failing to do so, you will encounter errors in the measurement process.

Review and Approval

After creating a merge request, wait for some time to review the merge request before running the measurement process. During this step, if you made any error creating a folder, uploading files or any errors in the usage scenario script will be notified.

CI/CD pipeline execution

The next step is pipeline execution. Successfully creating a merge request will trigger the pipeline defined for measuring the energy consumption of a software. During the execution of the pipeline, three jobs will run.

The first job is build. In the build job process, the pipeline will define and prepare all the necessary files and environments required for the measurement process.

The second job is measurement. In this job, the actual measurement of the energy consumption will take place. The measurement process will execute for each mode of the software, i.e., idle, baseline, and sus. The measurement will approximately execute for 30 iterations to get the most accurate results for each mode.

The last job is result. During this job, the results will be generated in the pdf format with the help of the R script and Oscular we defined already.

Access the result

Upon successfully executing all the jobs, you can download the results it generated.

Downloading Artifacts and Reports

As a result of the pipeline, you will be able to download the artifacts and reports from the merge request page you created.

In the artifacts folder, you can see two reports. Idle_Report report is for idle mode, and Sus_Report is for sus mode. You can find the measurement details inside the reports. Other folders includes the artifacts used to create the reports. Check out the Accessing Reports page for detailed report analysis.

Conclusion

By automating the energy measurement process and providing remote access, we make it possible for developers to measure the energy consumption of their software from any location in the world. The increased access to the lab will enable data-driven decision-making for efficiency improvements in code and software eco-certification with agencies like the Blue Angel.

Retrieved from "https://community.kde.org/index.php?title=KEcoLab/User_Docs/User_Guide&oldid=103160"