Configuration

Initialization

Initialize Germain UX monitoring in your main application javascript file (e.g. server.js). In the simplest integration only the Germain UX server URL (where the monitoring data will be sent - contact the germain Team if you don't know it) must be provided and the rest will be autoconfigured.

Integration example using RequireJS:

JS

const GermainAPM = require('@germainapm/nodejs-monitoring');

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
const apm = new GermainAPM(config);
apm.start();

Integration example using ES6:

JS

import GermainAPM from '@germainapm/nodejs-monitoring';

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
const apm = new GermainAPM(config);
apm.start();

Configure

Monitoring Frequency

Some monitoring components such as Node.js process resource monitoring run periodically. By default they run every 60 seconds but you can be customized as follows

JS

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
config.monitoring.frequencySeconds = 60;

Asynchronous Correlation

By default Germain UX performs correlation between incoming HTTP requests and asynchronous outgoing HTTP requests. This feature has a minor performance overhead and can be disabled as follows.

JS

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
config.monitoring.asyncCorrelation = false;

Distribution Frequency

By default Germain UX monitoring sends data back to the Germain UX Server every 30 seconds. You can update this frequency by setting maxFlushTimeSeconds:

JS

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
config.datapoints.maxFlushTimeSeconds = 60;

Application

You can associate an application name with all collected data. The simplest way to provide an application name is by passing it as the second (optional) argument, when creating the default settings:

JS

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/', 'APP_NAME');

Alternatively you can provide the application name and application component by providing a configuration object:

JS

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
config.defaults.application = { name: 'APP_NAME', component: 'APP_COMPONENT' };

Logging output

By default, logging (info level and above) is enabled when Germain UX monitoring gets initiated. You can change this configuration through GermainAPMConfiguration:

JS

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
config.logging.level = 'debug';
config.logging.filename = 'GermainAPM_custom.log';
config.logging.maxFiles = 20;
config.logging.maxSize = 20000000; // in bytes

Data Exclusion

By default all captured data is sent to the APM server, however it may be necessary to exclude or anonymize some data due to security concerns. The exclusions section of the GermainAPMConfiguration allows to configure which fields (per fact type or globally) should be excluded or anonymized.

Masking - The string will be replaced with * characters.
Anonymization - The string will be hashed so the original string cannot be read. This allows the same value to be hashed globally so it can be used to anonymously associate data.
Exclusion - The string will be replaced with an empty string.

JS

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
config.exclusions = [{
  fieldName: 'sessionId',				// The field that will be anonymized
  factType: '',							// The fact type that this exclusion applies to, if empty it will apply to all facts
  type: 'MASK',                         // The type of exclusion to apply, one of 'MASK', 'ANONYMIZE' or 'EXCLUDE'
  name: 'SessionId Anonymization',		// A readable name for this exclusion
  pattern: '',							// A regexp to allow anonymization/exclusion of matching groups within a string
  preserveLength: true,					// If true (and type is 'MASK') the length of the excluded string will be preserved
  preserveWhitespace: true,				// If true (and type is 'MASK') the whitespaces within the excluded string will be preserved
  enabled: true							// Allows to enable/disable this exclusion
}, {
  fieldName: 'requestBody',
  factType: 'NodeJS:Outbound',
  type: 'ANONYMIZE',
  name: 'Request Body Exclusion',
  pattern: '',
  preserveLength: true,
  preserveWhitespace: false,
  enabled: true
}];

Exit Monitoring

By default Germain UX monitors Node.js process exit events. You can disable this monitoring through GermainAPMConfiguration:

JS

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
config.monitoring.exit = false;

Event Loop Latency Monitoring

By default Germain UX monitors Node.js event loop latency. You can disable this monitoring through GermainAPMConfiguration:

JS

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
config.monitoring.eventLoopLatency = false;

Startup Monitoring

By default Germain UX monitors Node.js startup duration as time between the current Node.js process startup and Germain UX initialization. You can disable this automatic feature and call it explicitly when you think the startup has been fully completed:

JS

GermainAPM.collectStartup();

You can disable this monitoring through GermainAPMConfiguration:

JS

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
config.monitoring.startup = false;

Transaction Monitoring

Germain UX allows you to monitor all kinds of transactions in your Node.js application. To enable this monitoring you need to programmatically set the start of a transaction (GermainAPM.startTransaction()) and the end of a transaction (GermainAPM.endTransaction()).

Start a transaction:

JS

GermainAPM.startTransaction('UNIQUE_TRANSACTION_NAME', 'AdditionalInformation'); // AdditionalInformation is optional, you can pass in null value

End started transaction:

JS

GermainAPM.endTransaction('UNIQUE_TRANSACTION_NAME');

Process resources Monitoring

By default Germain UX monitors CPU, Memory Usage, Heap Size and Heap Usage of your Node.js process. You can disable this monitoring through GermainAPMConfiguration:

JS

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
config.monitoring.pid = false;

OS resources Monitoring

By default Germain UX monitors CPU and Memory Usage of the server on which your Node.js application runs. You can disable this monitoring through GermainAPMConfiguration:

JS

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
config.monitoring.os = false;

Disk Monitoring

By default Germain UX monitors Disk Usage of the server on which your Node.js application runs. You can disable this monitoring through GermainAPMConfiguration:

JS

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
config.monitoring.disk = false;

Multiple Promise Resolve/Rejection Monitoring

By default Germain UX monitors when a promise has been resolved or rejected multiple times. You can disable this monitoring through GermainAPMConfiguration:

JS

const config = GermainAPM.getDefaultConfiguration('http://GERMAIN_APM_SERVER/');
config.monitoring.multiplePromiseResolves = false;

Advanced Configuration

In addition to the initialization and auto-configuration we allow customers to define custom configuration and enable/disable monitoring components. Please review GermainAPMConfiguration documentation for the complete list of options and setters.

Type definition for GermainAPMConfiguration object:

TYPESCRIPT

type GermainAPMConfiguration = {
    /** Germain UX environment URL (e.g. http://localhost:8080). */
    servicesUrl: string;
    /** Config to enable/disable/customize what is monitored */
    monitoring: {
        /** How often periodic monitoring should be collected. Default: 60 */
        frequencySeconds: number;
        /** Whether to enable correlation of data across async callbacks. Default: true */
        asyncCorrelation: boolean;
        /** Unhandled Exception monitoring */
        unhandledExceptions: {
            /** Enable monitoring. Default: true */
            enabled: boolean;
            /** Whether to exit the Node process on error. Default: true */
            exitOnError: boolean;
            /** Callback to be fired when an error occurs. */
            callbackOnError?: (error: Error) => void;
        },
        /** Incoming HTTP monitoring */
        httpIncoming: {
            /** Enable monitoring. Default: true */
            enabled: boolean;
            /** Function to extract a sessionId from an incoming request */
            sessionExtractor?: (request: IncomingMessage) => string;
        },
        /** Outgoing HTTP monitoring */
        httpOutgoing: {
            /** Enable monitoring. Default: true */
            enabled: boolean;
            /** Function to extract a sessionId from an incoming request */
            sessionExtractor?: (response: ClientRequest) => string;
        },
        /** Node Startup time monitoring. Default: true */
        startup: true,
        /** Node Process monitoring. Default: true */
        pid: boolean;
        /** OS monitoring (CPU, Memory). Default: true */
        os: boolean;
        /** Disk monitoring. Default: true */
        disk: boolean;
        /** Node Warning monitoring. Default: true */
        warning: boolean;
        /** Unhandled Promise Rejection count monitoring. Default: true */
        unhandledPromiseRejection: boolean;
        /** Event Loop Latency monitoring. Default: true */
        eventLoopLatency: boolean;
        /** Exit monitoring - when Node shuts down. Default: true */
        exit: boolean;
        /** Multiple Promise Resolve monitoring. Default: true */
        multiplePromiseResolves: boolean;
    },
    /** Logging configuration */
    logging: {
        /** Level of logging to enable. Default: 'info' */
        level: 'error' | 'warn' | 'info' | 'verbose' | 'debug',
        /** Filename to log to. Default: 'GermainAPM.log' */
        filename: string;
        /** Max number of rolling files to keep. Default: 10 */
        maxFiles: number;
        /** Max size of a single rolling log file. Default: 10Mb */
        maxSize: number;
    },
    /** Data sending settings */
    datapoints: {
        /** Whether to send data to the server or just discard. This is a debug setting as should always be set true. Default: true */
        sendData: boolean;
        /** Whether outgoing data should be compressed to reduce network overhead. Default: true */
        compress: boolean;
        /** Max number of datapoints to keep in-memory before sending to the server. Default: 250 */
        maxNumInMemory: number;
        /** Max time to wait between sending data to server. Default: 60 */
        maxFlushTimeSeconds: number;
    },
    /** Default data to be added to datapoints */
    defaults: {
        /** Default user */
        user?: UserDimension;
        /** Default system */
        system?: SystemDimension;
        /** Default application */
        application?: ApplicationDimension;
        /** Default pid */
        pid?: string;
    }
    /** Exclusions to be applied to collected datapoints */
    exclusions: FieldExclusionConfig[]
}

Component: Code Profiler

Feature Availability: 8.6.0 or later