@oaklean/cli
Version:
A command-line interface that provides utilities for parsing, inspecting, and converting the .oak file format, as well as interfaces used in the @oaklean suite.
153 lines (125 loc) • 6.46 kB
Markdown
# `@oaklean/cli`
A command-line interface that provides utilities for parsing, inspecting, and converting the .oak file format, as well as interfaces used in the `@oaklean` suite.
## Table of Contents
- [Usage](#usage)
- [Fast Config Setup](#fast-config-setup)
- [Development](#development)
- [For More Information](#for-more-information)
## Usage
`$ npx oak -h`
```
Usage: oak [options] [command]
An CLI to interact with the @oaklean suite
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
config commands to interact with a config file
- resolve Resolves the given config file and outputs the resolved config (including all default values and overrides)
init Create a .oaklean config file
report commands to convert or inspect the profiler's format
- toHash Calculates the hash of given a profiler format
- toJSON Converts a profiler format that is given in binary format to a json version
- toSourceFileTree Converts a profiler format that is given in binary format to a SourceFileMetaDataTree
- check Checks wether all files in the profiler format are present
- inspect Displays an overview of the reports stats
profile commands to convert or inspect the cpu profile's format
- toCPUModel Converts a cpu profile format that is given to a cpu model format
- inspect Displays an overview of the cpu profile stats
- trace Displays the trace of the cpu profile
- anonymize Converts all paths in the cpu profile to relative paths (relative to the rootDir mentioned in the .oaklean config) to remove all user related paths
parse commands to parse javascript or typescript files
- toPST Converts a given javascript/typescript file and extracts the ProgramStructureTree from it and stores it into a file
- verify-identifiers Parses all source files (.js, .ts, .jsx, .tsx) within a given path and verifies that all identifiers are valid and unique
external-resource|er commands to interact with external resource files (.resources.json)
- verify-identifiers Parses all source files in all resource files within a given path and verifies that all identifiers are valid and unique
- extract Extract a file from a resource file and stores it into a separate file
backend commands to interact with the backend
- send Sends a given .oak report to a backend specified in the .oaklean config
jest Commands to inspect the jest profiler format. This is mostly used for debugging purposes
- verify Checks wether the accumulate report of the jest-test-environment would be generated the same way with this version
- inspect-profiles Inspects all reports and cpu profiles in the jests output directory and verifies their consistency
- verify-trees Checks all sub reports in the output directory for SourceFileMetaDataTree consistency
metrics-data|md commands to convert or inspect the metrics data collection format
- show Displays the metrics data collection as a table
help [command] display help for command
```
## Fast Config Setup
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](/docs/SensorInterfaces.md)
> :warning: **Most Sensor Interfaces need root privileges**<br>
> Look into the [Sensor Interface Docs](/docs/SensorInterfaces.md) to see how you can run them without root privileges
> :mag: **How measurements work**<br>
> 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.
## Development
To build the tool, execute npm run build.
To make the tool available on your system and enable the `oak` command, simply run `npm run setup`. This command not only builds the tool but also updates your system's version of `@oaklean/cli` to the newly built one.
## For More Information
### Website
* [Oaklean Website](https://www.oaklean.io/)
### Github Links
* [Oaklean Profiler](https://github.com/hitabisgmbh/oaklean)
* [Oaklean VS Code Extension](https://github.com/hitabisgmbh/oaklean-vscode)
### NPM Packages
* [Oaklean Packages](https://www.npmjs.com/search?q=%40oaklean)
### VS Code Extension
* [Oaklean Extension - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=HitabisGmbH.oaklean)
* [Oaklean Extension - Open VSX Registry](https://open-vsx.org/extension/HitabisGmbH/oaklean)