@mmarchini/observe

Observe 🕵‍♀

CLI tool to run common Inspector Protocol tasks on remote Node.js processes.

Why

There are several tools to interact with the Inspector Protocol. The Inspector API on Node.js core allows users to automate inspector protocol tasks, but it only interacts with the protocol within a Node.js process (it doesn't connect to external processes). node-inspect can connect to external processes, but since it's a REPL which doesn't allow for automation.

chrome-remote-interface addresses both issues, but users need to know how to use the inspector protocol to interact with it. Observe addresses that by providing shortcuts to common tasks used in production, such as taking snapshots or profiles. This allows users to get insights on their running applications without need to redeploy.

Install

$ npm install @mmarchini/observe

Or, use npx to get insights with a single command:

$ npx -q @mmarchini/observe ...

Note: since the result of observe is redirected to stdout, it's recommended to pass -q to npx to prevent unwanted lines in the output.

Usage

To execute a command, run npx -q @mmarchini/observe [command] [options]. For a full list of commands and options, run npx -q @mmarchini/observe -h. Available commands are:

• heap-profile will take a Heap Profile
• heap-snapshot will take a Heap Snapshot
• cpu-profile will take a CPU Snapshot

By default the result will be outputted to stdout, so it can be piped to another process if needed without touching the filesystem (encryption, upload to another server, compression, etc.). --file will save the result to the filesystem instead.

All commands require at least one option: -p <pid> or -h <host>/-P <port>.

• -p: will start the inspector protocol on the remote process <pid> by sending a SIGUSR1 signal to the process.
• -h/-P: will attach to the inspector protocol on this remote or local host. Important, the app should already start debugger listening on the expected port.

Each command might also have their own options. For example, heap-profile accepts a -d <duration> option to determine for how long(in seconds) the profiler should run. npx -q @mmarchini/observe command -h will show all available options for the command.

Changelog

3.1.0 (2025-06-07)

Features

• custom-script: allow passing arguments to custom scripts (327e816)