@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
• Fast Config Setup
• Development
• 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

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

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

Github Links

• Oaklean Profiler
• Oaklean VS Code Extension

NPM Packages

• Oaklean Packages

VS Code Extension

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