!oaklean-header

@oaklean/profiler

A library to measure the energy consumption of your javascript/typescript code

Table of Contents

- Usage
- Setup
- Measure your code
- Interpret the measurements
- For More Information

Usage

$3

The CLI can be used to easily setup a .oaklean config file.
1. Install oaklean: npm add @oaklean/profiler
2. Run the init script: npx oak init
3. It will ask you which sensor interface should be used for energy measurements:
``
Select a sensor interface (recommended for your platform: perf)
None (pure cpu time measurements)
powermetrics (macOS only)
❯ perf (Linux only)
windows (Windows only)
energy measurements on Linux (Intel & AMD CPUs only)
`
4. The cli asks you to confirm your choice and generates a valid .oaklean and .oaklean.local config file for you:
`
✔ Select a sensor interface (recommended for your platform: powermetrics) perf (Linux only)
[Oaklean] [Main Config]
{
"extends": ".oaklean.local",
"exportOptions": {
"outDir": "profiles/",
"outHistoryDir": "profiles_history/",
"rootDir": "./",
"exportV8Profile": false,
"exportReport": true,
"exportSensorInterfaceData": false
},
"projectOptions": {
"identifier": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
},
"runtimeOptions": {
"seeds": {},
"v8": {
"cpu": {
"sampleInterval": 1
}
}
}
}
[Oaklean] [Local Config]
{
"runtimeOptions": {
"sensorInterface": {
"type": "perf",
"options": {
"outputFilePath": "energy-measurements.txt",
"sampleInterval": 100
}
}
}
}
? Is this OK? (yes) (Y/n)
`

##### Available Sensor Interfaces
| SensorInterface | Operating System |
| --------------- | ---------------- |
| powermetrics | macOS |
| perf | linux |
| windows | windows |

If you want to how to setup the Sensor Interfaces and how to make them work with Docker you can read more about it here

> :warning: Most Sensor Interfaces need root privileges

> Look into the Sensor Interface Docs to see how you can run them without root privileges

> :mag: How measurements work

> During the test execution measurements are collected with a sample based approach. So for every n - microseconds it collects a v8 cpu profile and energy measurements of the sensor interface. You can adjust the sampling rate with the sampleInterval options in the .oaklean config file above.

$3

- Option 1 (Code Injection):
> :warning: On Windows, this feature is not fully supported yet.
`typescript
import { Profiler } from '@oaklean/profiler'
async function main() {
await Profiler.inject("") // IMPORTANT: need the await
// run the code to measure
}
main()

// profiler stops and exports profile when applications stops or gets killed
// If the resp. exports are enabled the profiler will automatically
// export the measurements into the output directory (defined via the .oaklean config) ///
`

- Option 2 (Code wrapping):
`typescript
import { Profiler } from '@oaklean/profiler'
const profile = new Profiler('profile-name')

async function main() {
await profile.start("")
// run the code to profile
await profile.finish("")
}
main()

// If the resp. exports are enabled the profiler will automatically
// export the measurements into the output directory (defined via the .oaklean config) ///
`

$3

The Oaklean` VSCode Extension lets you to interpret the measurements. It integrates the energy measurements directly into your IDE.

You can find it here:
- Github
- VS Code Extension

It provides code highlighting to point out which source code locations consume the most energy:


!vscode-code-highlighting-img


It also provides multiple features to determine the components that consume the most energy, including node modules:


!vscode-explorer-img

For More Information

$3

* Oaklean Website

$3

* Oaklean Profiler
* Oaklean VS Code Extension

$3

* Oaklean Packages

$3

* Oaklean Extension - Visual Studio Marketplace
* Oaklean Extension - Open VSX Registry