@mmarchini/observe
Version:
Inspector Protocol made easy
65 lines (46 loc) • 2.97 kB
Markdown
# Observe 🕵♀
[](https://github.com/mmarchini-oss/node-observe/actions?query=branch%3Adevelop)
[](https://codecov.io/github/mmarchini-oss/node-observe)
[](https://www.npmjs.com/package/@mmarchini/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`](https://nodejs.org/api/inspector.html) 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`](https://github.com/nodejs/node-inspect) can connect to
external processes, but since it's a REPL which doesn't allow for automation.
[chrome-remote-interface](https://github.com/cyrus-and/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
```console
$ npm install @mmarchini/observe
```
Or, use npx to get insights with a single command:
```console
$ 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.