@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.

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:
  init            Create a .oaklean config file
  format          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
  
  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
  
  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
  
  transpile       commands to parse javascript or typescript files
     - withJest Transpiles a given javascript/typescript file with jest and stores the transpiled code into a file
     - withTS Transpiles a given javascript/typescript file with typescript and stores the transpiled code into a file
  
  backend         commands to interact with the backend
     - send Sends a given .oak report to a backend specified in the .oaklean config
  
  help [command]  display help for command

Fast Config Setup

The @oaklean/cli can be used to easily setup a .oaklean config file.

1. Install the cli: npm add --save-dev @oaklean/cli
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 config file for you:

? Select a sensor interface (recommended for your platform: perf) perf (Linux only)
{
  "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
      }
    },
    "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

⚠️ Most Sensor Interfaces need root privileges
Look into the Sensor Interface Docs to see how you can run them without root privileges

🔍 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.

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.