Introducing Node Clinic - A Performance Toolkit for Node.js Developers

One of the problems Node.js developers have to deal with is figuring out why their app is "slow." There aren't many tools available to help dig into performance issues so we decided to create some. We're really happy to announce the open source Node Clinic toolkit and Clinic Doctor tool.

If you're at JSConf Asia today, you can see Matteo Collina presenting all the details.

In a nutshell, Clinic simplifies the process of investigating and fixing performance issues in your Node.js applications.

Developers First

Our overarching aim with the project was to create developer tools with an amazing user experience. This means the tools should not require large infrastructure to run and should be usable on developer laptops. They should generate portable outputs that can be shared between developers and they should have a progressive approach to information display where the fine detail is only provided if you want it.

To achieve this we assembled a team of of experts in Node.js Core, Data Science, Design, Front-End Development, Data Visualisation and Product, to create Clinic.

Clinic Doctor

Doctor is the first tool that we are releasing in the toolkit. It helps diagnose performance issues in your application and guides you towards more specialised tools to look deeper into your specific issues.

Symptoms such as low CPU usage, blocking garbage collection, frequent event loop delay, or chaotic number of active handles may indicate a number of potential problems. Doctor helps narrow down the possibilities by generating a recommendation based on those symptoms. Examples such as I/O issues, non-optimized garbage collection and blocked event loop are quite common. Doctor will help you with all of these.

Event loop delay has been marked in red to indicate a problem.

Once the problem is diagnosed, Doctor helps you find the right solution. It may point you to a specific profiling tool or suggest a common approach to the problem. For those who prefer more context, Doctor also provides an in-depth explanation of the issue. In situations where you have a hunch that the issue may be different than the recommendation, Doctor provides easy access to the documentation of all the other issues.

The "Read More" section helps you understand the issue in-depth.

Doctor is very easy to use — all it takes is a single command to monitor your app and generate a recommendation.

Doctor is compatible with Node.js versions 8 and 9. (Note you might hit some issues if you pick an old version of those release lines)

Explore Clinic on Github:

• https://github.com/nearform/node-clinic
• https://github.com/nearform/node-clinic-doctor
• https://github.com/nearform/node-clinic-examples

Re-Introduction to 0x

nearForm has a long history working on performance in Node.js apps and our own David Mark Clements created the 0x tool many moons before we kicked off Node Clinic.

0x helps profile your application with the use of flamegraphs and is one of the tools that Doctor will recommend in certain situations.

Flamegraphs simplify identification of hot paths in your code. Each block in a flamegraph represents a function. Its color matches how often it was observed still executing whilst not having called any other function yet (where applicable).

The darker red a block is the hotter it is - and the more likely it is a bottleneck blocking the event loop (synchronously).

Each block on top of another block represents one function that has called another.

The width of the block represents the total time a call frame was part of a stack on CPU relative to the total time sampling.

0x is very easy to use — all it takes is a single command to monitor your app and generate a flamegraph.

0x is compatible with Node.js v6+ (if you require Node.js v4 support, 0x v2 supports Node.js v4).

Explore 0x on Github: https://github.com/davidmarkclements/0x

Clinic Flame

Clinic Flame wraps 0x so that it can be used by Node Clinic. Just type clinic flame to learn how to use it.

Participate in the Community

Clinic is an open-source project, which means everyone is welcome to join us.

If you don't know where to start, please see our CONTRIBUTING.md.

Clinic is a safe environment for everyone, thanks to our Code of Conduct.

Project is licensed under Apache 2.0 license.

Please Send Us Your Data

We'd really appreciate it if you would send us your Doctor data so we can continue to improve our models and recommendations. Note this is only timing data and will not leak any information about your code or app data. Please consult the README to find out how to send the data. Be assured that the tool does not send any data automatically.

Finally

We are actively expanding our Clinic toolkit. Expect more tools very soon!