why-is-node-running

What is why-is-node-running?

The why-is-node-running package is a Node.js module that helps developers diagnose why a Node.js process hasn't exited on its own. It provides insights into what operations are keeping the event loop busy, such as open handles, active timers, and other system tasks that may prevent the process from exiting.

What are why-is-node-running's main functionalities?

Logging active handles

This feature allows you to log all active handles that are currently preventing Node.js from exiting. It's useful for identifying potential sources of memory leaks or unintended behavior.

const log = require('why-is-node-running');

// somewhere in your long-running program
log(); // logs out active handles that are keeping node running

Logging with a delay

This feature is similar to the previous one, but it allows you to set a delay before logging the active handles. This can be useful when you want to give your application some time to settle before checking what is still running.

const log = require('why-is-node-running');

setTimeout(function () {
  log(); // logs out active handles after a delay
}, 10000);

Other packages similar to why-is-node-running

wtfnode

WTFNode is similar to why-is-node-running in that it helps to diagnose what is keeping a Node.js process running. It provides detailed output about timers, sockets, and other resources. It differs in its output format and the level of detail provided.

node-report

Node-report is an npm package that provides a diagnostic report on demand or when certain events occur. It's more comprehensive than why-is-node-running, offering information about the system, resource usage, and JavaScript stack trace, but it's not as focused on the reasons why a Node.js process is still running.

README

why-is-node-running

Node is running but you don't know why? why-is-node-running is here to help you.

Installation

Node 8 and above:

npm i why-is-node-running -g

Earlier Node versions (no longer supported):

npm i why-is-node-running@v1.x -g

Usage

const log = require('why-is-node-running') // should be your first require
const net = require('net')

function createServer () {
  const server = net.createServer()
  setInterval(function () {}, 1000)
  server.listen(0)
}

createServer()
createServer()

setTimeout(function () {
  log() // logs out active handles that are keeping node running
}, 100)

Save the file as example.js, then execute:

node ./example.js

Here's the output:

There are 5 handle(s) keeping the process running

# Timeout
/home/maf/dev/node_modules/why-is-node-running/example.js:6  - setInterval(function () {}, 1000)
/home/maf/dev/node_modules/why-is-node-running/example.js:10 - createServer()

# TCPSERVERWRAP
/home/maf/dev/node_modules/why-is-node-running/example.js:7  - server.listen(0)
/home/maf/dev/node_modules/why-is-node-running/example.js:10 - createServer()

# Timeout
/home/maf/dev/node_modules/why-is-node-running/example.js:6  - setInterval(function () {}, 1000)
/home/maf/dev/node_modules/why-is-node-running/example.js:11 - createServer()

# TCPSERVERWRAP
/home/maf/dev/node_modules/why-is-node-running/example.js:7  - server.listen(0)
/home/maf/dev/node_modules/why-is-node-running/example.js:11 - createServer()

# Timeout
/home/maf/dev/node_modules/why-is-node-running/example.js:13 - setTimeout(function () {

Important Note! unrefed timers do not prevent the Node process from exiting. If you are running with Node v11.0.0 and above, unrefed timers will not be listed in the above list. Unfortunately, this is not supported in node versions below v11.0.0.

CLI

You can also run why-is-node-running as a standalone if you don't want to include it inside your code. Sending SIGUSR1/SIGINFO signal to the process will produce the log. (Ctrl + T on macOS and BSD systems)

why-is-node-running /path/to/some/file.js

probing module /path/to/some/file.js
kill -SIGUSR1 31115 for logging

To trigger the log:

kill -SIGUSR1 31115

Require CLI Option

You can also use the node -r option to include why-is-node-running:

node -r why-is-node-running/include /path/to/some/file.js

The steps are otherwise the same as the above CLI section

License

MIT