Customizing Node.js APM Agent

This page describes the available configurations for the Atatus Node.js Agent.

Configurations

You can set following configurations in the Node.js agent.

Option	Description	Type
appName	Name of your Node.js project/app. It is mandatory.	`string`
licenseKey	APM License Key of your account. It is mandatory.	`string`
notifyHost	URL of your on-premise Atatus server, for example `YOUR_ON_PREMISE_URL`.	`string`
appVersion	Application version to identify release of your app.	`string`
hostname	Default hostname is the machine name. You can override it using this option.	`string`
environment	Environment of your Node.js app. By default, it uses the value from `NODE_ENV`. You can override it with this option.	`string`
analytics	Flag to enable or disable app analytics.	`boolean`
logBody	Flag to capture request and response bodies in analytics.	`string`
analyticsCaptureOutgoing	Flag to enable or disable capturing of outgoing requests in analytics.	`boolean`
analyticsSkip	Function to skip or ignore a request in analytics.	`function`
analyticsMask	Function to mask fields in analytics.	`function`
logBodyContentTypes	List of content types that the Atatus agent will capture.	`string` / `array`
skip	Function to skip or ignore a request in transactions.	`function`
tags	List of tags sent along with errors and performance metrics.	`array`
customData	Extra metadata for errors, failures, and traces.	`object`
ignoreUrls	List of URLs that the Atatus agent will ignore from monitoring.	`array`
ignoreUserAgents	List of User-Agents that the Atatus agent will ignore.	`array`
ignoreStatusCodes	List of status codes that should be ignored.	`array`
captureConsoleErrors	Flag to capture console errors and report them as errors.	`boolean`
performance	Flag to enable or disable performance monitoring.	`boolean`
proxy	Proxy server URL.	`string`
logLevel	Sets the verbosity of internal logs for debugging purposes.	`string` (e.g., `debug`, `info`, `warning`, `error`, `critical`, `trace`, `off`)
captureLogs	Enables log capturing.	`boolean`
excludeLogLibraries	Comma-separated list of logger libraries to exclude from log capturing.	`string`

Sample Node.js agent configurations:

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",
    notifyHost: "YOUR_ON_PREMISE_URL",

    appVersion: "1.0.0",

    hostname: "auth-server-7",

    environment: "production",

    analytics: true,
    logBody: "all",
    analyticsCaptureOutgoing: true,
    tracing: true,
    analyticsSkip: function(event) {
        return false;
    },
    analyticsMask: function (event) {
    },
    logBodyContentTypes: ["application/json", "text/plain"], // or 'text/html'

    skip: function(event) {
        return false;
    },

    tags: [
        'new-user',
        'signup'
    ],

    customData: {
        plan: "premium",
        customer: "John Doe"
    },

    ignoreUrls: [
        "/v1/admin",
        /health/i
    ],

    ignoreUserAgents: [
        "curl/",
        /pingdom/i,
        /googlebot/i
    ],

    ignoreStatusCodes: [400, 404, 500],

    captureConsole: true,
    captureConsoleErrors: true,
    performance: true,

    proxy: "http://localhost:8080",

    logLevel: "debug"
});

export default atatus;

Node.js agent configurations in the environment:

Environment	Configuration	Example
ATATUS_LICENSE_KEY	licenseKey	`YOUR_LICENSE_KEY`
ATATUS_APP_NAME	appName	`YOUR_APP_NAME`
ATATUS_NOTIFY_HOST	notifyHost	`YOUR_ON_PREMISE_URL`
ATATUS_TRACING	tracing	`true` or `false`
ATATUS_APP_VERSION	appVersion	`1.0.0`
ATATUS_HOSTNAME	hostname	`auth-server-7`
ATATUS_ENVIRONMENT	environment	`production`
ATATUS_ANALYTICS	analytics	`true` or `false`
ATATUS_LOG_BODY	logBody	`all` or `request` or `response`
ATATUS_ANALYTICS_CAPTURE_OUTGOING	analyticsCaptureOutgoing	`true` or `false`

You can pass above configurations in two ways

Environment variables
atatus.start function (in atatus.js)

Create an atatus.js file in your project root and configure the agent there. Start your application with node -r ./atatus.js ./app/server.js.

Enable/Disable Agent

If you would like to enable or disable atatus agent at runtime, you can do so by controling the enabled varilable dynamically. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    enabled: true,
    // (or) directly assign false
    // enabled: false
    // (or) control through your env
    // enabled: process.env.NODE_ENV === 'production'
});

export default atatus;

Set app version

If you use an appVersion to identify releases of your app, you can send it to Atatus. It is highly recommended to set appVersion. In atatus.js

import atatus from 'atatus-nodejs';
import pkg from './package.json' assert { type: 'json' };

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    // From your app package.json
    appVersion: pkg.version,
    // (or) directly assign
    // appVersion: "1.0.0"
});

export default atatus;

Option 2: In Environment

# set to env file
export ATATUS_LICENSE_KEY="YOUR_LICENSE_KEY"
export ATATUS_APP_NAME="YOUR_APP_NAME"

export ATATUS_APP_VERSION="1.0.1"

Configure a custom host name

By default, we will fetch the host name using node.js os.hostname(), but you can override this as follows: In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    hostname: "web1.example.com"
});

export default atatus;

Option 2: In Environment

# set to env file
export ATATUS_LICENSE_KEY="YOUR_LICENSE_KEY"
export ATATUS_APP_NAME="YOUR_APP_NAME"

export ATATUS_HOSTNAME="web1.example.com"

Set environment

By default, Atatus looks at the NODE_ENV environment variable to see what environment the script is running in. If that is not set, Atatus assumes you are running in production. If you want to override this, you can set the environment options. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    environment: "production"
});

export default atatus;

Option 2: In Environment

# set to env file
export ATATUS_LICENSE_KEY="YOUR_LICENSE_KEY"
export ATATUS_APP_NAME="YOUR_APP_NAME"

export ATATUS_ENVIRONMENT="development"

Set analytics

App Analytics collects all requests individually with contextual data. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    analytics: true
});

export default atatus;

Option 2: In Environment

# set to env file
export ATATUS_LICENSE_KEY="YOUR_LICENSE_KEY"
export ATATUS_APP_NAME="YOUR_APP_NAME"

export ATATUS_ANALYTICS=true

Set logBody

By default, Atatus Analytics does not capture request and response bodies. However, if you want to capture them, you can enable the appropriate options during Atatus initialization. Please note that this option is only applicable to Analytics and not to APM.

request - Only the request body is captured in analytics.
response - Only the response body is captured in analytics.
all - Both the request and response bodies are captured in analytics.

In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    analytics: true,
    logBody: 'all',       // 'all' (or) 'request' (or) 'response'
});

export default atatus;

Option 2: In Environment

# set to env file
export ATATUS_LICENSE_KEY="YOUR_LICENSE_KEY"
export ATATUS_APP_NAME="YOUR_APP_NAME"

export ATATUS_ANALYTICS=true
export ATATUS_LOG_BODY=all

Set analytics outgoing request

By default, Atatus Analytics does not capture outgoing requests. However, if you want to capture them, you can enable the appropriate options during Atatus initialization. Please note that this option is only applicable to Analytics and not to APM. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    analytics: true,
    logBody: 'all',                 // 'all' (or) 'request' (or) 'response',
    analyticsCaptureOutgoing: true,
});

export default atatus;

Option 2: In Environment

# set to env file
export ATATUS_LICENSE_KEY="YOUR_LICENSE_KEY"
export ATATUS_APP_NAME="YOUR_APP_NAME"

export ATATUS_ANALYTICS=true
export ATATUS_LOG_BODY=all
export ATATUS_ANALYTICS_CAPTURE_OUTGOING=true

Set skip function

The skip function helps you exclude specific API requests (such as health-related requests) from being sent to Atatus. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    analytics: true,
    logBody: 'all',                 // 'all' (or) 'request' (or) 'response'

    skip: function(event) {
      // Skip certain transactions
      if (event.name === 'GET /health' || event.name === 'POST /cron/report') {
        return true;
      }

      return false;
    }
});

export default atatus;

Set analytics skip function

The analyticsSkip function helps you exclude specific API requests (such as health-related requests) from being sent to Atatus. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    analytics: true,
    logBody: 'all',                 // 'all' (or) 'request' (or) 'response'
    analyticsSkip: function(event) {
      // Skip certain transactions
      if (event.name === 'GET /health' || event.name === 'POST /cron/report') {
        return true;
      }
      // Skip content type text/html
      if (event.responseHeaders['content-type'].includes('text/html')) {
        return true;
      }
      return false;
    }
});

export default atatus;

Set analytics mask function

The analyticsMask function allows you to modify the request/response headers, body, or query parameters before they are sent to Atatus. You can utilize this function to make alterations such as removing specific header or body fields. It will give you the flexibility to customize the request data that is ultimately sent to Atatus. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    analytics: true,
    logBody: 'all',                 // 'all' (or) 'request' (or) 'response'
    analyticsMask: function (event) {
      event.responseHeaders['x-powered-by'] = '';

      try {
        if (event.name === 'POST /login') {
          if (event.requestBody) {
            let requestBody = JSON.parse(event.requestBody);
            if (requestBody.password) {
              requestBody.password = '****';
            }
            event.requestBody = JSON.stringify(requestBody);
          }
        }

        if (event.name === 'GET /api/token') {
          if (event.responseBody) {
            let responseBody = JSON.parse(event.responseBody);
            if (responseBody.token) {
              responseBody.token = '****';
            }
            event.responseBody = JSON.stringify(responseBody);
          }
        }

      } catch (e) {
        console.error('Error in mask event ', e)
      }

    }
});

export default atatus;

Set log body content types

The logBodyContentTypes option allows capturing the response body for specific content types in API analytics. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    analytics: true,
    logBody: 'all',                 // 'all' (or) 'request' (or) 'response',
    logBodyContentTypes: ["application/json", "text/plain"], // or 'text/html'
});

export default atatus;

Add tags

It is often very useful to send some extra information along with the errors and performance metrics so that you can filter them in the Atatus dashboard. To do this, you can set the tags: In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    tags: ['new-user', 'signup']
});

export default atatus;

Add custom data

To debug errors effectively, you can send some meta data along with errors. To do this, you can set the customData: In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    customData: { plan: "premium", customer: "John Doe" }
});

export default atatus;

Ignore URL

Using this option, you can define list of URLs that Atatus agent will ignore. Ignore URLs accepts array of string or Regex. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    ignoreUrls: ["/v1/admin", /health/i]
});

export default atatus;

Ignore User Agents

Using this option, you can define list of User-Agents that Atatus agent will ignore. Ignore user agents accepts array of string or Regex. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    ignoreUserAgents: ["curl/", /pingdom/i, /googlebot/i]
});

export default atatus;

Ignore Error Status Codes

If you want to ignore certain status codes from HTTP failures, you can use this option. Ignore status codes accepts array of integer. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    ignoreStatusCodes: [400, 404, 500]
});

export default atatus;

Set proxy configuration

You can use a proxy server by configuring a proxy URL when starting with Atatus. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    proxy: "http://localhost:8080"
});

export default atatus;

Set Log Level

You can enable detailed logging in Atatus by setting the log level to debug. This helps in troubleshooting by printing internal logs to the console. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    logLevel: "debug"
});

export default atatus;

Option 2: Using Environment Variables

# Set in .env file or export in your shell
export ATATUS_LICENSE_KEY="YOUR_LICENSE_KEY"
export ATATUS_APP_NAME="YOUR_APP_NAME"

export ATATUS_LOG_LEVEL=debug

Set capture Logs

Enables automatic log collection from supported logging libraries. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    analytics: true,
    captureLogs: true
});

export default atatus;

Option 2: In Environment

# set to env file
export ATATUS_LICENSE_KEY="YOUR_LICENSE_KEY"
export ATATUS_APP_NAME="YOUR_APP_NAME"

export ATATUS_ANALYTICS=true
export ATATUS_CAPTURE_LOGS=true

Set Excluded Log Libraries

Specifies which log libraries should be excluded from automatic log capturing. In atatus.js

import atatus from 'atatus-nodejs';

atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    analytics: true,
    captureLogs: true,
    excludeLogLibraries: "console,winston"
});

export default atatus;

Option 2: In Environment

# set to env file
export ATATUS_LICENSE_KEY="YOUR_LICENSE_KEY"
export ATATUS_APP_NAME="YOUR_APP_NAME"

export ATATUS_ANALYTICS=true
export ATATUS_CAPTURE_LOGS=true
export ATATUS_EXCLUDE_LOG_LIBRARIES=console,winston

​Configurations

​Enable/Disable Agent

​Set app version

​​Configure a custom host name

​Set environment

​Set analytics

​Set logBody

​Set analytics outgoing request

​Set skip function

​Set analytics skip function

​Set analytics mask function

​Set log body content types

​Add tags

​Add custom data

​Ignore URL

​Ignore User Agents

​Ignore Error Status Codes

​Set proxy configuration

​Set Log Level

​Set capture Logs

​Set Excluded Log Libraries

Configurations

Enable/Disable Agent

Set app version

Configure a custom host name

Set environment

Set analytics

Set logBody

Set analytics outgoing request

Set skip function

Set analytics skip function

Set analytics mask function

Set log body content types

Add tags

Add custom data

Ignore URL

Ignore User Agents

Ignore Error Status Codes

Set proxy configuration

Set Log Level

Set capture Logs

Set Excluded Log Libraries