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
icon/buttons/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

  1. atatus.start function
  2. 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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/copy
module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    hostname: "web1.example.com"
};

Option 2: In start function

copy
icon/buttons/copy
atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

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

Option 3: In Environment

copy
icon/buttons/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
icon/buttons/copy
module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    releaseStage: "development"
};

Option 2: In start function

copy
icon/buttons/copy
atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    releaseStage: "development"
});

Option 3: In Environment

copy
icon/buttons/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
icon/buttons/copy
module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    analytics: true
};

Option 2: In start function

copy
icon/buttons/copy
atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    analytics: true
});

Option 3: In Environment

copy
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/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
icon/buttons/copy
module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

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

Option 2: In start function

copy
icon/buttons/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
icon/buttons/copy
module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME"

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

Option 2: In start function

copy
icon/buttons/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
icon/buttons/copy
module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

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

Option 2: In start function

copy
icon/buttons/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
icon/buttons/copy
module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

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

Option 2: In start function

copy
icon/buttons/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
icon/buttons/copy
module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

    ignoreStatusCodes: [400, 404, 500]
};

Option 2: In start function

copy
icon/buttons/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
icon/buttons/copy
module.exports = {
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

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

Option 2: In start function

copy
icon/buttons/copy
atatus.start({
    licenseKey: "YOUR_LICENSE_KEY",
    appName: "YOUR_APP_NAME",

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