package
HTTP middleware for CPU and heap profiling with flamegraph visualization
npm install flamegraph-middlewareGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Node.js HTTP middleware for on-demand CPU and heap profiling with interactive flamegraph visualization.
http, Express, Fastify, and other frameworksnpm install Qard/flamegraph-middlewareimport http from 'http'
import { createFlamegraphMiddleware } from 'flamegraph-middleware'
import express from 'express'
import { createFlamegraphMiddleware } from 'flamegraph-middleware'
const app = express()
app.use(createFlamegraphMiddleware({
basePath: '/flamegraph',
defaultDuration: 10000
}))
app.get('/', (req, res) => {
res.send('Hello World')
})
app.listen(3000)import Fastify from 'fastify'
import middie from '@fastify/middie'
import { createFlamegraphMiddleware } from 'flamegraph-middleware'
const fastify = Fastify({ logger: true })
await fastify.register(middie)
fastify.use(createFlamegraphMiddleware({
logger: fastify.log // Use Fastify's pino logger
}))
fastify.get('/', async (request, reply) => {
return { hello: 'world' }
})
await fastify.listen({ port: 3000 })Navigate to /flamegraph?duration=10000 to start a 10-second profile:
curl http://localhost:3000/flamegraph?duration=10000The page will show a "Profiling in Progress" message and automatically refresh when complete.
After profiling completes, you'll see two interactive flamegraphs:
Each flamegraph is interactive:
createFlamegraphMiddleware({
basePath: '/flamegraph', // Route prefix (default: '/flamegraph')
maxDuration: 60000, // Maximum profile duration in ms (default: 60000)
defaultDuration: 10000, // Default duration when not specified (default: 10000)
heapSamplingInterval: 524288, // Heap sampling interval in bytes (default: 512*1024)
maxProfiles: 10, // Max profiles to keep in memory (default: 10)
profileTTL: 300000, // Profile expiration time in ms (default: 300000)
colors: {
primary: '#ff4444', // Primary flamegraph color (default: '#ff4444')
secondary: '#ffcc66' // Secondary flamegraph color (default: '#ffcc66')
},
logger: pinoLogger // Pino logger instance (optional, no logging if not provided)
})The middleware supports pino for structured logging. By default, if no logger is provided, the middleware will not log. You can pass your own pino logger instance to enable logging and integrate with your application's logging:
import pino from 'pino'
import { createFlamegraphMiddleware } from 'flamegraph-middleware'
// Custom logger configuration
const logger = pino({
level: 'debug',
transport: {
target: 'pino-pretty'
}
})
const flamegraph = createFlamegraphMiddleware({ logger })The middleware logs at different levels:
All logs include structured data with relevant context like profileId, duration, component, etc.
createFlamegraphMiddleware(options)Creates a middleware function for profiling.
Parameters:
options (Object) - Configuration options
basePath (string) - Base URL path for the middlewaremaxDuration (number) - Maximum allowed profile duration in millisecondsdefaultDuration (number) - Default profile duration when not specifiedheapSamplingInterval (number) - Heap profiling sampling interval in bytesmaxProfiles (number) - Maximum number of profiles to store in memoryprofileTTL (number) - Time in milliseconds before profiles expirecolors (Object) - Color customization
primary (string) - Primary color for flamegraphs (hex format)secondary (string) - Secondary color for flamegraphs (hex format)logger (Object) - Pino logger instance (optional, no logging if not provided)Returns: Function - Middleware function with signature (req, res, next)
GET /flamegraph?duration=<ms>Start a new profiling session.
Query Parameters:
duration (optional) - Profile duration in milliseconds (must be ≤ maxDuration)Response: HTML page showing "Profiling in Progress" with auto-refresh
GET /flamegraph/result/<id>View profiling results for a specific session.
Response: HTML page with interactive CPU and heap flamegraphs
/flamegraph?duration=10000⚠️ Important: This middleware exposes profiling capabilities that can:
Recommendations:
import { createFlamegraphMiddleware } from 'flamegraph-middleware'
const flamegraph = createFlamegraphMiddleware()
function requireAuth (req, res, next) {
// Your authentication logic here
if (!isAuthorized(req)) {
res.writeHead(401)
res.end('Unauthorized')
return
}
next()
}
app.use('/flamegraph', requireAuth, flamegraph)Profiling has minimal overhead on your application:
A complete TODO CRUD application example is available in the example/ directory:
cd example
npm install
npm startVisit http://localhost:3000 to:
See example/README.md for more details.
curl http://localhost:3000/flamegraph?duration=30000curl http://localhost:3000/flamegraphcreateFlamegraphMiddleware({
colors: {
primary: '#2563eb', // Blue
secondary: '#7dd3fc' // Light blue
}
})Apache-2.0
Estimated unpacked size across 26 packages.
30.6 MB
Includes dependencies.
4 direct dependencies.