OpenProfiling is a toolkit for collecting profiling data from production workload safely.
The project's goal is to empower developers to understand how they applications is behaving in production with minimal performance impact and without vendor lock-in.
The library is in alpha stage and the API is subject to change.
I expect that the library will not match everyone use-cases, so i'm asking to everyone in this case to open an issue so we can discuss how the toolkit could meet yours.
Use cases
An application have a memory leak
The recommend profiler is the Heap Sampling Profiler which has the lowest impact in terms of performance, here the instructions on how to use it.
After getting the exported file, you can go to speedscope to analyse it.
If we load a example heap profile and head to Sandwich
panel, we can see a list of functions listed by how much memory it allocated.
Note that the top function in the view should be automatically considerated as leak, when you receive a http request for example, nodejs allocate memory for it but it will be cleaned up after it finish. The view will only show where memory is allocated, not where it leaks.
A application is using too much CPU
The recommend profiler is the CPU JS Sampling Profiler which is made for production profiling (low overhead), checkout the instructions to get it running.
After getting the exported file, you can go to speedscope to analyse it.
If we load a example cpu profile and head to Sandwich
panel again, we can see a list of functions sorted by how much cpu they used.
Note that there is two concepts of "time used":
self
: which is the time the cpu took in the function itself, without considering calling other functions.total
: the opposite ofself
, it represent both the time used by the function and all functions that it called.
You should then look for functions that have a high self
time, which means that their inner code take a lot of time to execute.
Installation
Install OpenProfiling for NodeJS with:
yarn add @openprofiling/nodejs
or
npm install @openprofiling/nodejs
Configure
Before running your application with @openprofiling/nodejs
, you will need choose 3 different things:
- What do you want to profile: an
profiler
- How to start this profiler: an
trigger
- Where to send the profiling data: an
exporter
Typescript Example
import { ProfilingAgent } from '@openprofiling/nodejs'
import { FileExporter } from '@openprofiling/exporter-file'
import { InspectorHeapProfiler } from '@openprofiling/inspector-heap-profiler'
import { InspectorCPUProfiler } from '@openprofiling/inspector-cpu-profiler'
import { SignalTrigger } from '@openprofiling/trigger-signal'
const profilingAgent = new ProfilingAgent()
/**
* Register a profiler for a specific trigger
* ex: we want to collect cpu profile when the application receive a SIGUSR2 signal
*/
profilingAgent.register(new SignalTrigger({ signal: 'SIGUSR2' }), new InspectorCPUProfiler({}))
/**
* Start the agent (which will tell the trigger to start listening) and
* configure where to output the profiling data
* ex: the file exporter will output on the disk, by default in /tmp
*/
profilingAgent.start({ exporter: new FileExporter() })
Javascript Example
const { ProfilingAgent } = require('@openprofiling/nodejs')
const { FileExporter } = require('@openprofiling/exporter-file')
const { InspectorCPUProfiler } = require('@openprofiling/inspector-cpu-profiler')
const { SignalTrigger } = require('@openprofiling/trigger-signal')
const profilingAgent = new ProfilingAgent()
/**
* Register a profiler for a specific trigger
* ex: we want to collect cpu profile when the application receive a SIGUSR2 signal
*/
profilingAgent.register(new SignalTrigger({ signal: 'SIGUSR1' }), new InspectorCPUProfiler({}))
/**
* Start the agent (which will tell the trigger to start listening) and
* configure where to output the profiling data
* ex: the file exporter will output on the disk, by default in /tmp
*/
profilingAgent.start({ exporter: new FileExporter(), logLevel: 4 })
Triggers
A trigger is simply a way to start collecting data, you can choose between those:
Profilers
Profilers are the implementation that collect profiling data from different sources, current available profilers:
Exporters
OpenProfiling aim to be vendor-neutral and can push profiling data to any backend with different exporter implementations. Currently, it supports:
Versioning
This library follows Semantic Versioning.
Note that before the 1.0.0 release, any minor update can have breaking changes.
LICENSE
Apache License 2.0