Instrumenting Node.js Internals


When troubleshooting complex Node.js applications recollecting information about the network, filesystem or external dependencies is always useful. Even when working with a new codebase insights on how the application is built, which asynchronous calls are being used or how often. In this talk I want to introduce "instrument", a tool I've created for this which is also Open Source.


Hey everyone, before we continue, I wanted first to thank all the organizers and volunteers that made this happen, dedicated their time, and also gave me the opportunity to be presenting to you today. My talk is about troubleshooting node.js applications. Before that, a little introduction about myself. I'm Alejandro. I'm from Buenos Aires, Argentina. I work as the backend engineer at Xteam, and I also contribute with a couple of communities, both locally and some other that are international.

So into the topic of this talk, say you have a node.js application that is running, but something is not working. There is no exception. You don't have locks. Where would you start? What I would try to do is to tear apart the parts of the application so it's easier to pinpoint where exactly a problem is. Say it's a server, I would check the bootstrap part of the process, a breakpoint right after it initializes to see if the error happens before that or after that. Oftentimes I would be in the process of troubleshooting an application, and I would think I have no idea why that is happening. I would be just like this dog. So a lot of times this would also happen on my development environment where I have full control, full access, and also should have a good observability about what is happening. This last part was one of the motivations that I had to work on a tool that would practically no changes to your application could allow improved visibility and potentially turn yourself into Ironman like in this scene. Viewing a lot of useful information at once. I will go over a few specific examples that I could think of on a short demo. On the scenario number one, imagine you have a script or an application that is running through Node, we want to be able to tell if it's going over the network and if that's the case, to collect more information about what URLs it's using and possibly more information on that. So we will go on to my demo. For this, let's say we want to try to do that with npm. And we will try to retrieve the latest version for a package, in this case, Mocha. We get the result 802.1. Say we wanted to do that with this tool, with npm. We can require instrument pass the same arguments that we were passing before. And first of all, we will see the same output that before 802.1.

And after that, a short summary for the tool. In this case, for these two native modules that are enabled, HTTP and HTTPS. Those two are specifically configured here in the modules list. You can add another ones like FS, require, and others as well. And this configuration is added on the instrument.config.js part. So we can see that this is going to We see that the method is get. And the headers is region, npm, NCI, and whatnot. So, all I had to do to require that tool is to add as a development dependency. For another example, say you're a refactoring HTTP server and you want to identify which files are importing module A.js. The module is only being loaded dynamically by a specific route in your server. And in this case, it would be practically impossible to do this task with the static analysis. You would have to instrument your application or your server to get that information. So by adding the require module in the list we previously saw, you could get that information using this tool as well. A little caveat on this and a recommendation if you should be running these on other environments that are not your local environments, and the answer is no, definitely no. There is a performance overhead on adding this instrumentation. And I'm sure there are a few bugs that you will find if you test this on your own. So it's not recommended to do so. You can find this tool on GitHub and see the code. See an open issue, pull request. And if you have further questions on how this is being done or other technical questions, we will be holding a Q&A session or feel free to send them over via social media, Twitter. That's everything that I have for you today. Thank you very much.

7 min
24 Jun, 2021

Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

Workshops on related topic