Performance Profiler

Stayed tuned for speed!

Installation

npm install --save performance-profiler

Usage

const Profiler = require('performance-profiler');

// Get a new task object and give it a friendly name.
let myTask = new Profiler("Stuff that happens");

// Start the clock on your task whenever you're ready.
myTask.start();
/* 
 * DO YOUR THING
 * The code you're trying to profile goes here.
 * It can be synchronous or asynchronous, doesn't matter.
 * Just make sure that you keep track of that `myTask` object.
 */

// You can check to see how long it's been since the task started.
if (myTask.seconds > 10) console.log('This is taking a while, huh?');

// Stop the clock on the task when you're done.
myTask.finish();

// At any time, you can get a collated report of all your tasks.
console.log(Profiler.csv());

For more details, see the API documentation.

Development

Made sure to review our contributing guidelines before you get started.

Running Tests

You can run the full suite of tests with npm test.

To run only the basic tests, and skip the longer ones, you can use npm test -- --quickly instead. (Please be aware that all tests must pass before a pull request will be accepted.)

CI/CD

The build pipeline will automatically test all branches and PRs. A successful test is required before any changes will be accepted into master.

When a branch or commit is merged into the master branch, semantic-release will automatically determine an appropriate version number and publish it if required.

Remember: Because version numbers are automatically determined by semantic-release, it's important that you use the appropriate commit format. If you fail to do this, then your commits may need to be squashed into a new one before your PR can be merged.

API Documentation

(The following documentation is generated automatically.)

Classes

Members

Profiler

Tracks high-resolution timing data for multiple tasks in order to identify slow operations.

Kind: global class

• Profiler
  • new Profiler(name)
  • instance
    • .name ⇒ string
    • .state ⇒ string
    • .hrtime ⇒ Array
    • .seconds ⇒ number
    • .milliseconds ⇒ number
    • .nanoseconds ⇒ number
    • .start() ⇒ Profiler
    • .finish() ⇒ Profiler
    • .track() ⇒ Profiler
  • static
    • .tasks ⇒ Array.<Profiler>
    • .csv(scale)
    • .reset()

new Profiler(name)

Create a new instance, usually called a "task". Tasks start in the "Pending" state and are automatically added to global tracking.

| Param | Type | Description | | --- | --- | --- | | name | string | a friendly name to be used in reports |

Example

// Import the module.
const Profiler = require('performance-profiler');

// Get a task instance, with a friendly name.
let myTask = new Profiler("Just Some Stuff");

// PREPARE YOUR STUFF

// Start the task.
myTask.start();

// DO STUFF

// Finish the task.
myTask.finish();

// Print the csv report.
console.log(Profiler.csv());

Example

// Most instance methods return the instance and can be chained together, for example:
let myTask = new Profiler("Create and Start").start().untrack();

profiler.name ⇒ string

Kind: instance property of Profiler
Returns: string - the tasks's friendly name as set in the constructor

profiler.state ⇒ string

Kind: instance property of Profiler
Returns: string - the task's current state: either "Pending", "Started", or "Finished"

profiler.hrtime ⇒ Array

Returns the raw high-resolution elapsed time for the task. "Pending" tasks always return zero time spent. "Started" tasks return the amount of time passed since calling Profiler.start(). "Finished" tasks return the elapsed time between calling profiler.start() and Profiler.finish().

Kind: instance property of Profiler
Returns: Array - [seconds, nanoseconds] - an array similar to process.hrtime()

profiler.seconds ⇒ number

Returns the value of Profiler.hrtime expressed in seconds.

Kind: instance property of Profiler
Returns: number - - decimal number of seconds elapsed for the task

profiler.milliseconds ⇒ number

Returns the value of Profiler.hrtime expressed in milliseconds.

Kind: instance property of Profiler
Returns: number - - decimal number of milliseconds elapsed for the task

profiler.nanoseconds ⇒ number

Returns the value of Profiler.hrtime expressed in nanoseconds.

Kind: instance property of Profiler
Returns: number - - integer number of milliseconds elapsed for the task

profiler.start() ⇒ Profiler

Start the clock on the task. The task must be in the "Pending" state and is immediately changed to "Started".

Kind: instance method of Profiler
Returns: Profiler - the instance

profiler.finish() ⇒ Profiler

Stop the clock on the task. The task must be in the "Started" state and is immediately changed to "Finished". Finished tasks cannot be restarted.

Kind: instance method of Profiler
Returns: Profiler - the instance

profiler.track() ⇒ Profiler

Add this task to global tracking.

Kind: instance method of Profiler
Returns: Profiler - the instance

Profiler.tasks ⇒ Array.<Profiler>

Returns a list of all currently tracked tasks, in no particular order. This array is a shallow copy and is not backed by the underlying list.

Kind: static property of Profiler
Returns: Array.<Profiler> - a list of all currently-tracked tasks

Profiler.csv(scale)

Generate a csv report detailing all currently tracked tasks.

Kind: static method of Profiler

| Param | Type | Default | Description | | --- | --- | --- | --- | | scale | string | "milliseconds" | timing scale for the csv: 'nanoseconds', 'milliseconds', or 'seconds' |

Profiler.reset()

Delete all existing tasks from global tracking. Any such tasks can still be used individually, but they won't be included in the csv.

Kind: static method of Profiler

trackedTasks : Set.<Profiler>

All currently tracked tasks.

Kind: global variable