@ghadautopia/express-profiler v1.0.2

Ghada Express Profiler

Ghada Express Profiler is inspired by Symfony Profiler. Its main target is to make debugging easier for applications built using Express Node.js framework.

Works with

• Express version 4

Dependencies

"ejs": "^3.1.6",
"express": "^4.17.1",
"on-finished": "^2.3.0",
"response-time": "^2.3.2",
"sqlite3": "^5.0.2",
"uuid": "^8.3.2"

Installation

Using npm

npm install @ghadautopia/express-profiler

Or using yarn

yarn add @ghadautopia/express-profiler

Usage

Import @ghadautopia/express-profiler in your project. Instantiate it directly after mounting all the routes in the Express app and before the 404 and Error handlers. As shown in the below example:

// import express
const express = require('express');
// import profiler
const { profiler } = require('@ghadautopia/express-profiler');

// instantiating express app
const app = express();

// app routes
app.use('/', indexRouter);

// instantiating profiler - directly after mounting app routes
profiler(app);

// catch 404 and forward to error handler
app.use(function(req, res, next) {
  next(createError(404));
});

// error handler
app.use(function(err, req, res, next) {
  // set locals, only providing error in development
  res.locals.message = err.message;
  res.locals.error = req.app.get('env') === 'development' ? err : {};

  // render the error page
  res.status(err.status || 500);
  res.render('error');
});

How it works

Ghada Express Profiler mainly depends on 2 concepts:

• Streams: responsible for logging the helpful data related to each request
• Scopes: responible for using the logged data by streams to render friendly views to be helpful in debugging the request and its response

Ghada Express Profiler uses sqlite to log the Streams data. The sqlite file is created in the project itself in the path .cache/ghada/profiler.sqlite.

In order to avoid logging collision between concurrent requests. Ghada Express Profiler forces the requests to be handled one by one. If a request is being processed, any other coming request will wait for the current one to finish.

To activate Ghada Express Profiler debugging on a current request, you should prefix the path being called with /_debug. For example,

• http://localhost:3000 should be http://localhost:3000/_debug
• http://localhost:3000/error should be http://localhost:3000/_debug/error

If your app returns HTML content in the response to this request, Ghada Express Profiler will render a Toolbar element sticking to the end of the rendered page. As shown below

For Ghada Express Profiler to distinguish between requests, it injects 2 headers in the response:

• The X-Profiler-Link header: holds the URL of the current request profiler scopes view
• The X-Profiler-Token header: holds the profiler token identifier of the current request

By heading to the URL of the X-Profiler-Link, You will be able to see something like the below view. This is called the s view. On the left hand side navigation, you can check your scopes. Here you can see only the req-res scope which is auto imported by the profiler. In the req-res, you can check the data about the server request and its response.

To check all the logged requests. Click on the logo anchor on the top left of the page. You should see something like the below view

Configuration

You can configure Ghada Express Profiler by passing a second argument with the configuration object, as follows:

profiler(app, {
  debugRoute: '_myDebugRoute',
  rootRoute: '_myRootRoute'
})

Available configuration props

More Scopes

You can import more scopes from the following:

• axios-scope
• mongoose-scope

Demo

Demo

Code base

Known Issues

Version Mismatch

Error: The scope {"name":"mongoose","hasToolbarSlot":true,"hasPageView":true} is not instance of ProfilerScope

When facing an issue like the above. This means that the failing scope package is not using the same @ghadautopia/express-profiler which is installed in your project. Please make sure to install the scope package which aligns to the same version of @ghadautopia/express-profiler used in you project. You can debug the failing scope package via going into the project's node_modules. Then search for the scope package directory and in its package.json, you can see the version of the required @ghadautopia/express-profiler under the dependencies field.

Advanced

• Create your own scope

License

MIT