NodeJS

Monitor code execution in NodeJS applications.

Install

To install the latest version, use the following npm command:

npm install @palzin-apm/palzin-nodejs --save

Configure the Ingestion Key and URL

You need an Ingestion Key and URL to create a Palzin Monitor (APM) instance. Obtain a new key by creating a project in your Palzin Monitor (APM) dashboard.

If you use dotenv, you can configure the Palzin Ingestion Key in your environment file:

PALZIN_APM_INGESTION_KEY=[ingestion key]
PALZIN_APM_URL=[your palzin domain]

Initialization

It's important that Palzin is required in the first line of the script, before you require any other modules - i.e., before http, mysql, etc.

This means that you should require Palzin in your application's main file (usually index.js, server.js, or app.js). Here's an example of how Palzin Monitor (APM) is normally initialized in a NodeJS script:

const palzin = require('@palzin-apm/palzin-nodejs')({
    url: 'xxxxxxxxx',
    ingestionKey: 'xxxxxxxxxxxxx'
});

// Continue with the rest of the script...

Autowiring

The Palzin Monitor (APM) Node.js module has the ability to automatically detect the modules you require in your application and instrument them for monitoring during transaction execution.

To take advantage of autowiring, you need to require the palzin apm module at the first line of your script, before requiring any other modules.

The following modules are autowired by default:

• mysql2
• mssql
• pg
• knex
• mongodb

If you use other modules that are not listed here, please let us know by sending an email to hello@palzin.app, and we will consider adding them to the autowiring list.

HTTP Request Monitoring

Palzin wraps incoming HTTP requests in an entity called "Transaction." To get a complete picture of what happens in your application during an HTTP request, you should start the transaction as soon as possible in the web server.

Here's an example where a custom web server uses patterns to route requests to handlers:

const palzin = require('@palzin-apm/palzin-nodejs')({
    ingestionKey: 'xxxxxxxxxxxxx682eedcce097b64b',
    url: 'xxxxxxxxx',
});

var http = require('http');
var patterns = require('patterns')();

// Setup routes and their respective route handlers
patterns.add('GET /posts/{id}', require('./routes/posts').show);

// Start web server
http.createServer(function (req, res) {
    // Check if we have a route matching the incoming request
    var match = patterns.match(req.method + ' ' + req.url);

    // If no match is found, respond with a 404.
    // Palzin Monitor (APM) will use the default transaction name "unknown route"
    if (!match) {
        res.writeHead(404);
        res.end();
        return;
    }

    // Start the transaction
    palzin.startTransaction(match.pattern);

    req.params = match.params;
    match.value(req, res);
}).listen(3000);

If the transaction is started correctly, Palzin Monitor (APM) will automatically monitor other tasks based on supported modules like mysql2, pg, mongodb, etc.

If you are using the Express framework, transactions are automatically labeled based on the names of your routes. Follow the specific Express documentation for more details.

Instrument a CLI Script

A NodeJS application that runs from the command line can start the transaction immediately after initialization:

const palzin = require('@palzin-apm/palzin-nodejs')({
    ingestionKey: 'xxxxxxxxxxxxx',
    url: 'xxxxxxxxx',
});

// Start the transaction
palzin.startTransaction(__filename);

// Continue with the rest of the script...

Custom Segments

By default, Palzin Monitor (APM) reports many different tasks based on the application's dependencies. However, you can "wrap" specific parts of your code that you consider relevant to create a more complete picture of the executed statements during an execution cycle and their performance.

Learn more about custom segments.