npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@astraload/profilers

v3.0.1

Published

CPU profiler and heap dumper for multi-instance Meteor web apps

Downloads

442

Readme

@astraload/profilers

CPU profiler and heap dumper for multi-instance Meteor web apps

Installation

npm install @astraload/profilers

Basic usage

import { Profilers } from '@astraload/profilers';
const profilers = new Profilers();

It will create an instance of the Profilers class. The Profilers is a singleton class, so there always will be just a single instance of this class. The class is made singleton to prevent overlapping of CPU profiling/taking heap snapshot tasks.

An example of creating a CPU profile:

async function createCpuProfile(duration, samplingInterval) {
  const profilers = new Profilers();
  const { fileName, filePath } = await profilers.cpu.profile(duration, samplingInterval);
  return { fileName, filePath };
};

An example of creating a heap snapshot:

async function takeHeapSnapshot() {
  const profilers = new Profilers();
  const { fileName, filePath } = await profilers.heap.takeSnapshot();
  return { fileName, filePath };
};

The resulting file is located in /tmp folder and its name consists of 12 random characters.

Advanced usage

This package allows creating CPU profiles and heap snapshots in a multi-instance Meteor web apps setup. To do so, the package utilizes an auxiliary MongoDB collection instanceTasks. Each Meteor web app instance needs to call profilers.startObserving(instanceName) method in its startup hook to start an observer of the instanceTasks collection. When a new task is added to that collection, it will trigger the corresponding creation of a CPU profile or a heap snapshot:

import { Meteor } from 'meteor/meteor';
import { Profilers, TaskEvent } from '@astraload/profilers';

Meteor.startup(() => {
  const profilers = new Profilers();
  profilers.on(TaskEvent.CpuProfileCreated, handleFileCreated);
  profilers.on(TaskEvent.HeapSnapshotCreated, handleFileCreated);
  const instanceName = getInstanceName();
  profilers.startObserving(instanceName);
});

function handleFileCreated({ instanceName, fileName, filePath }) {
  /* Do whatever you need with the created file */
}

function getInstanceName() {
  /* return a unique identifier of the web app instance */
}

Also, in the startup hook, you may want to register handlers for TaskEvent.CpuProfileCreated and TaskEvent.HeapSnapshotCreated events. In the handlers, you may want to upload the resulting files to cloud storage for later inspection or do something else.

Now, as each web app instance started the observer of the instanceTasks collection, we can trigger the creation of a CPU profile or a heap snapshot of a particular web app instance, by calling scheduleTask(instanceName) method:

function createCpuProfile(duration, samplingInterval) {
  const profilers = new Profilers();
  const instanceName = getInstanceName();
  profilers.cpu.scheduleTask(instanceName, duration, samplingInterval);
};

function takeHeapSnapshot() {
  const profilers = new Profilers();
  const instanceName = getInstanceName();
  profilers.heap.scheduleTask(instanceName);
};

function getInstanceName() {
  /* return a unique identifier of the web app instance */
}

You may want to define corresponding Meteor methods in the web app to be able to trigger the creation of a CPU profile or a heap snapshot of a particular web app instance at an arbitrary point in time. When the resulting file is created the corresponding event will fire: TaskEvent.CpuProfileCreated or TaskEvent.HeapSnapshotCreated

API

The package exports the following entities:

  • Profilers - the main singleton class which extends EventEmitter
  • TaskEvent - the events names constants: TaskEvent.CpuProfileCreated and TaskEvent.HeapSnapshotCreated
  • CpuProfileFileExt - a CPU profile file extension constant
  • HeapSnapshotFileExt - a heap snapshot file extension constant
  • logInColor(message) - a helper function that logs provided message to console in cyan color

Profilers class

Profilers class has the following public members:

cpu - an instance of the CpuProfiler class.

heap - an instance of the HeapDumper class.

startObserving(instanceName) - a method that creates an observer of the instanceTasks MongoDB collection for added documents filtered by the instanceName field. A handler of the added event then triggers the corresponding creation of a CPU profile or a heap snapshot. Each new invocation of the startObserving method stops the previous observer before creating a new one. The instanceTasks MongoDB collection is created on the first invocation of the method.

stopObserving() - a method that stops the observer of the instanceTasks MongoDB collection.


CpuProfiler class

The CpuProfile class has the following public methods:

isProfiling() - returns value of the profiling flag which indicates that CPU profiling is in progress. The profiling flag is automatically managed only in a scenario when the CPU profiling process is triggered by the scheduleTask method. To prevent the overlapping of CPU profiling triggered by the profile method as well, you need to manually set the profiling flag's value using the setProfiling method.

setProfiling(value) - sets profiling flag to the provided boolean value.

profile([duration, [samplingInterval]]) - creates a CPU profile of desired duration and with the specified samplingInterval, saves it to disk. The method returns a Promise that resolves with an object containing information about the created file: { fileName, filePath }.

scheduleTask(instanceName, [duration, [samplingInterval]]) - adds a task to the instanceTasks collection to profile CPU of a web app instance with provided instanceName for desired duration and with the specified samplingInterval.

In both the profile and the scheduleTask methods, duration and samplingInterval parameters are optional and have the following default values:
duration (in milliseconds) - 60000 milliseconds which is 1 minute.
samplingInterval (in microseconds) - 1000 microseconds which is 1 millisecond.


HeapDumper class

The HeapDumper class has the following public methods:

isDumping() - returns value of the dumping flag which indicates that heap dumping is in progress. The dumping flag is automatically managed only in a scenario when the dumping process is triggered by the scheduleTask method. To prevent overlapping of heap dumping triggered by the takeSnapshot method as well, you need to manually set the dumping flag's value using the setDumping method.

setDumping(value) - sets dumping flag to the provided boolean value.

takeSnapshot() - takes a heap snapshot, saves it to disk and returns an object containing information about the created file: { fileName, filePath }.

scheduleTask(instanceName) - adds a task to the instanceTasks collection to take a heap snapshot of a web app instance specified by the instanceName parameter.