Clinic.js Documentation

Install the Clinic.js CLI globally using npm.

npm install -g clinic

Use clinic doctor to diagnose your Node.js application. The workflow involves running the doctor command, benchmarking your server with a tool like wrk or autocannon, and then shutting down the server to analyze the results.

Note: Do not exit the process forcefully (e.g., kill -9), as this can prevent the generation of log files. Use Ctrl+C to shut down the server gracefully.

If clinic doctor identifies I/O issues, use clinic bubbleprof for a more detailed asynchronous profiling of your application.

clinic bubbleprof -- node server.js

When running Clinic.js inside a Podman container via a CMD instruction, the container may exit immediately with code 0 due to an anonymous usage statistics prompt.

To resolve this, set the NO_INSIGHT environment variable to any value to suppress the prompt.

You can automate the benchmarking step by using the --autocannon flag or the --on-port flag. This ensures the benchmark starts as soon as your server is ready.

• Use --autocannon to run autocannon automatically.
• Use --on-port to run any custom script (like wrk) when the server starts listening on a specific port. Use the $PORT variable to specify the target port.

# Using autocannon automatically
clinic doctor --autocannon [ / --method POST ] -- node server.js

# Using wrk via --on-port
# $PORT is the port the server is listening on
clinic doctor --on-port 'wrk http://localhost:$PORT' -- node server.js

The following flags are available for Clinic.js commands (doctor, bubbleprof, flame, heapprofiler):

• -h | --help: Display Help
• -v | --version: Display Version
• --collect-only: Do not process data on termination
• --visualize-only <datapath>: Build or rebuild visualization from data
• --on-port <script>: Run a script when the server starts listening on a port.
• --autocannon: Run the autocannon benchmarking tool when the server starts listening on a port.
• --dest <path>: Destination for the collected data (default is .).
• --stop-delay <ms>: Add a delay to close the process when a job is done through either autocannon or on-port flag (in milliseconds).
• --name <name>: Sets a name for the output data, allowing you to replace existing reports without generating new ones (e.g., .clinic/node-19-test.clinic-flame).

The clinic flame command generates flamegraphs for CPU profiling.

Flags:

• --help, -h: Show help information.
• --version, -v: Show version.
• --collect-only: Only collect data; do not generate a report automatically.
• --open: Automatically open the generated report in your default browser (default: true).
• --debug: Enable debug mode.
• --kernel-tracing: Enable kernel tracing.
• --visualize-only <path>: Visualize an existing data file.
• --dest <path>: Specify the destination directory for output (default: .clinic).
• --stop-delay <ms>: Delay the process exit after stopping data collection.
• --name <name>: Set a name for the session.

The clinic heapprofiler command profiles memory usage.

Flags:

• --help, -h: Show help information.
• --version, -v: Show version.
• --collect-only: Only collect data; do not generate a report automatically.
• --open: Automatically open the generated report in your default browser (default: true).
• --debug: Enable debug mode.
• --visualize-only <path>: Visualize an existing data file.
• --dest <path>: Specify the destination directory for output (default: .clinic).
• --stop-delay <ms>: Delay the process exit after stopping data collection.
• --name <name>: Set a name for the session.

The clinic bubbleprof command is used for asynchronous flow visualization.

Flags:

• --help, -h: Show help information.
• --version, -v: Show version.
• --collect-only: Only collect data; do not generate a report automatically.
• --open: Automatically open the generated report in your default browser (default: true).
• --debug: Enable debug mode.
• --visualize-only <path>: Visualize an existing data file.
• --dest <path>: Specify the destination directory for output (default: .clinic).
• --stop-delay <ms>: Delay the process exit after stopping data collection.
• --name <name>: Set a name for the session.

Clinic.js provides several tools for profiling and diagnosing Node.js applications. All tools must be called with a node command.

Usage Pattern: clinic <tool> -- node <script.js> [args...]

Available Tools:

• doctor: Diagnoses performance issues by analyzing various metrics.
• bubbleprof: Visualizes the asynchronous flow of your application.
• flame: Generates flamegraphs to identify CPU bottlenecks.
• heapprofiler: Profiles memory usage to find leaks.
• clean: Removes Clinic.js output files (defaults to .clinic directory).