thetool

    0.5.1 • Public • Published

    thetool

    Build Status NPM thetool package

    thetool is a CLI tool to capture different cpu, memory and other profiles for your node app in Chrome DevTools friendly format.

    Quick start

    npx thetool -o . -t memorysampling npm run test
    # .. open DevTools frontend and do three clicks to get: 
    Screen Shot 2019-05-27 at 2 10 14 AM

    Getting Started

    thetool works only with Node >= 10.x.

    thetool interface is simple as 1-2-3.

    1. Specify output folder using -o flag, e.g. -o . to put output in current folder.
    2. Specify tool using -t, available tools: cpu, memorysampling, memoryallocation, coverage, type, heapsnapshot.
    3. Specify any command to start node, e.g. node index.js or npx thetool or npm run test.

    When report is ready, thetool will dump thetool> Report captured in ... message in terminal with a hint how to analyze it.

    Why not to use Chrome DevTools directly?

    • it can be used in environments where it is not possible to run Chrome DevTools, e.g., on the server, run thetool <yourapp> there, send report back and analyze it locally,
    • it supports child processes and workers,
    • it supports some other tools, e.g., node tracing and type profiler.

    Tool selector

    Problem Tool Insight DevTools tab
    my app is slow cpu where in code does app spend most time? Performance
    my app requires too much memory memorysampling where in code does app allocate most memory? Memory
    my app requires too much memory memoryallocation most precise version of memorysampling with much bigger overhead Memory
    my app requires too much memory heapsnapshot what is inside the heap right now? Memory
    my app package is too big coverage what code was executed and how many times?
    my app needs type annotations type what are the types of function arguments and returns?

    On-demand tooling

    You can use --ondemand flag to profile only part of your app:

    1. Add --ondemand flag to the list of thetool arguments.
    2. Call startTheTool/stopTheTool from your Node scripts (thetool will add these methods to Node context).

    startTheTool/stopTheTool methods are asynchronous, so you should await them or chain them using promise.then

    Couple examples:

    async function main() {
      await startTheTool();
      // code of your app
      await stopTheTool();
    }
    // .. or using promises..
    function main() {
      startTheTool().then(() => {
        // code of your app
      }).then(() => stopTheTool());
    }

    CPU: Profiler

    thetool -o . -t cpu npm run test

    To analyze: open Chrome DevTools, to to Performance tab, click load button, select file with data.

    Screen Shot 2019-05-27 at 2 10 14 AM

    Memory: Sampling Profiler

    thetool -o . -t memorysampling npm run test

    To analyze: open Chrome DevTools, go to Memory tab, click load button, select file with data.

    --samplingInterval option is available: average sample interval in bytes, poisson distribution is used for the intervals. The default value is 32768 bytes

    Screen Shot 2019-05-27 at 2 10 14 AM

    Memory: Allocation Profiler

    thetool -o . -t memoryallocation npm run test

    To analyze: open Chrome DevTools, go to Memory tab, click load button, select file with data.

    Screen Shot 2019-05-27 at 2 10 14 AM

    Memory: Heap Snapshot

    thetool -o . -t heapsnapshot node -e "captureTheTool.then(captureTheTool).then(captureTheTool)"

    Given command will capture three heap snapshots. To analyze: open Chrome DevTools, go to Memory tab, click load button, select file with data. You can load multiple snapshots and compare them from DevTools UI.

    Screen Shot 2019-05-27 at 2 10 14 AM

    Tracing

    thetool -o . -t tracing --recordMode recordAsMuchAsPossible --includedCategories node,v8 npm run test

    To analyze: open Chrome DevTools, go to Performance tab, click load button, select file with data.

    --recordMode controls how the trace buffer stores data (recordUntilFull, recordContinuously, recordAsMuchAsPossible) --includedCategories please take a look on different available categories on https://nodejs.org/api/tracing.html

    E.g. you can capture V8 sampling profiler using following command:

    thetool -o . -t tracing --recordMode recordAsMuchAsPossible --includedCategories v8.execute,v8.cpu_profiler,v8.cpu_profiler.hires npm run test
    Screen Shot 2019-05-27 at 2 10 14 AM

    Coverage Profiler

    thetool -o . -t coverage npm run test

    To analyze: in current folder create ./coverage/tmp folder and move files with data to this folder, run c8: npx c8 report. Please take a look at c8 README.md to see what output formats are supported.

    Screen Shot 2019-05-27 at 2 10 14 AM

    Type Profiler

    thetool -o . -t type npm run test

    To analyze: no tool yet.

    Install

    npm i thetool

    DownloadsWeekly Downloads

    1

    Version

    0.5.1

    License

    Apache-2.0

    Unpacked Size

    44.4 kB

    Total Files

    8

    Last publish

    Collaborators

    • ak239