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:
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
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
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
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
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
# 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
module.exports = {
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME",
hostname: "web1.example.com"
};
Option 2: In start function
atatus.start({
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME",
hostname: "web1.example.com"
});
Option 3: 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"
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
module.exports = {
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME",
releaseStage: "development"
};
Option 2: In start function
atatus.start({
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME",
releaseStage: "development"
});
Option 3: In Environment
# 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
module.exports = {
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME",
analytics: true
};
Option 2: In start function
atatus.start({
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME",
analytics: true
});
Option 3: In Environment
# 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
module.exports = {
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME",
analytics: true,
logBody: 'all', // 'all' (or) 'request' (or) 'response'
};
Option 2: In start function
atatus.start({
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME",
analytics: true,
logBody: 'all', // 'all' (or) 'request' (or) 'response'
});
Option 3: 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
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
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
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
# 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
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
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
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
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
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
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
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
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
module.exports = {
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME",
tags: ['new-user', 'signup']
};
Option 2: In start function
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
module.exports = {
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME"
customData: { plan: "premium", customer: "John Doe" }
};
Option 2: In start function
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
module.exports = {
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME",
ignoreUrls: ["/v1/admin", /health/i]
};
Option 2: In start function
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
module.exports = {
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME",
ignoreUserAgents: ["curl/", /pingdom/i, /googlebot/i]
};
Option 2: In start function
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
module.exports = {
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME",
ignoreStatusCodes: [400, 404, 500]
};
Option 2: In start function
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
module.exports = {
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME",
proxy: "http://localhost:8080"
};
Option 2: In start function
atatus.start({
licenseKey: "YOUR_LICENSE_KEY",
appName: "YOUR_APP_NAME",
proxy: "http://localhost:8080"
});