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	APM License Key of your account. It is mandatory.	`string`
licenseKey	Name of your Node.js project/app. It is mandatory.	`string`
appVersion	Application version to identify release of your app.	`string`
hostname	Default hostname is machine name. You can override it by this option.	`string`
releaseStage	Environment of your Node.js app. By default, the value will be taken from `NODE_ENV`. If you want to override it, you can set this option.	`string`
analytics	Flag to enable/disable app analytics.	`boolean`
logBody	Flag to capture request body and response body in analytics.	`string`
analyticsCaptureOutgoing	Flag to enable/disable capture outgoing request in analytics.	`boolean`
analyticsSkip	Function to skip/ignore a request in analytics.	`function`
analyticsMask	Function to mask field in analytics.	`function`
logBodyContentTypes	List of content types that the Atatus agent will capture.	`string/array`
skip	Function to skip/ignore a request in transactions.	`function`
tags	List of tags send along with the errors and performance metrics.	`array`
customData	Extra meta data for errors, failures and traces.	`object`
ignoreUrls	List of URLs that Atatus agent will ignore from monitoring.	`array`
ignoreUserAgents	List of User-Agents that Atatus agent will ignore.	`array`
ignoreStatusCodes	List of status code should be ignored.	`array`
proxy	Proxy server URL.	`string`

Sample Node.js agent configurations:

copy

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

    appVersion: "1.0.0",

    hostname: "web1.example.com",

    releaseStage: "development",

    analytics: true,
    logBody: 'all',
    analyticsCaptureOutgoing: 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],

    proxy: "http://localhost:8080"

};

You can pass above configurations in two ways

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

Setting 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"

Setting release stage

By default, Atatus looks at the NODE_ENV environment variable to see what releaseStage 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 releaseStage options.

Option 1: In atatus-config.js

copy

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

    releaseStage: "development"
};

Option 2: In start function

copy

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

    releaseStage: "development"
});

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"

Setting 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

Setting 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

Setting 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

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

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

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

    }
});

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

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

Configurations

Enable/Disable Agent

Setting app version

​Configure a custom host name

Setting release stage

Setting analytics

Setting logBody

Setting analytics outgoing request

Setting skip function

Setting analytics skip function

Setting analytics mask function

Setting log body content types

Add tags

Add custom data

Ignore URL

Ignore User Agents

Ignore Error Status Codes

Setting proxy configuration

Configure a custom host name