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`
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`
errorLimit	Maximum number of errors to capture before throttling.	`number`
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:

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    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,
    errorLimit: 20,

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

    logLevel: "debug"
};

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_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 three ways

Environment variables
atatus.start function
atatus-config.js file

You can create atatus-config.js file in the root directory of your app. If agent could not find atatus-config.js file, you can set config file path in the environment variable ATATUS_CONFIG_FILE.

export ATATUS_CONFIG_FILE="/path/to/atatus-config.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.

Option 1: In atatus-config.js

copy

module.exports = {
    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'
};

Option 2: In start function

copy

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'
});

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.

Option 1: In atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

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

Option 2: In start function

copy

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

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

Option 3: In Environment

copy

# 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:

Option 1: In atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    hostname: "web1.example.com"
};

Option 2: In start function

copy

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

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

Option 3: In Environment

copy

# 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.

Option 1: In atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    environment: "production"
};

Option 2: In start function

copy

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

    environment: "production"
});

Option 3: In Environment

copy

# 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.

Option 1: In atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    analytics: true
};

Option 2: In start function

copy

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

    analytics: true
});

Option 3: In Environment

copy

# 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.

Option 1: In atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

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

Option 2: In start function

copy

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

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

Option 3: In Environment

copy

# 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.

Option 1: In atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

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

Option 2: In start function

copy

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

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

Option 3: In Environment

copy

# 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.

Option 1: In atatus-config.js

copy

module.exports = {
    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;
    }
};

Option 2: In start function

copy

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;
    }
});

Set analytics skip function

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

Option 1: In atatus-config.js

copy

module.exports = {
    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;
    }
};

Option 2: In start function

copy

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;
    }
});

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.

Option 1: In atatus-config.js

copy

module.exports = {
    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)
      }

    }
};

Option 2: In start function

copy

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)
      }

    }
});

Set log body content types

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

Option 1: In atatus-config.js

copy

module.exports = {
    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'
};

Option 2: In start function

copy

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'
});

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:

Option 1: In atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

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

Option 2: In start function

copy

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

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

Add custom data

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

Option 1: In atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME"

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

Option 2: In start function

copy

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

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

Ignore URL

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

Option 1: In atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

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

Option 2: In start function

copy

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

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

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.

Option 1: In atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

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

Option 2: In start function

copy

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

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

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.

Option 1: In atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    ignoreStatusCodes: [400, 404, 500]
};

Option 2: In start function

copy

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

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

Set proxy configuration

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

Option 1: In atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

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

Option 2: In start function

copy

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

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

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.

Option 1: Using atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    logLevel: "debug"
};

Option 2: Using atatus.start()

copy

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

    logLevel: "debug"
});

Option 3: Using Environment Variables

copy

# 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.

Option 1: In atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    analytics: true,
    captureLogs: true
};

Option 2: In start function

copy

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

    analytics: true,
    captureLogs: true
});

Option 3: In Environment

copy

# 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.

Option 1: In atatus-config.js

copy

module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

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

Option 2: In start function

copy

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

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

Option 3: In Environment

copy

# 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

Customizing Node.js APM Agent

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

Configure a custom host name