> ## Documentation Index
> Fetch the complete documentation index at: https://docs.germainux.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Monitoring for Node.js

> Configure GermainUX Node.js monitoring to control telemetry, HTTP monitoring, asynchronous correlation, errors, transactions, privacy, and alerts.

Components
[`Engine`](https://docs.germainux.com/main/germain-ux-engine)
[`JS Profiler`](https://docs.germainux.com/main/germain-ux-js-profiler)
[`RPA Bot Recorder`](https://docs.germainux.com/main/germain-ux-rpa-bot-recorder)
[`RUM JS`](https://docs.germainux.com/main/germain-ux-rum-js)

Availability
2017.1 or later

> [card] [Configure the Application](#configure-the-application)
>
> Consistent naming across systems

> [card] [Configure Data Privacy & Exclusions](#configure-data-privacy-%26-exclusions)
>
> Filtering sensitive values

> [card] [Validate the Configuration](#validate-the-configuration)
>
> Checking telemetry after changes

> [card] [Advanced Configuration](#advanced-configuration)
>
> Tuning monitoring behavior

**Configure Monitoring for Node.js**

Configure GermainUX Node.js monitoring to control application telemetry, HTTP monitoring, asynchronous correlation, errors, warnings, Promise behavior, transactions, resource monitoring, privacy, analytics, alerts, dashboards, and automation.

This guide assumes the `@germainapm/nodejs-monitoring` package is already installed and initialized.

## Configure the Node.js Data Source

Enable and configure the Node.js data source that GermainUX will monitor.

Depending on the environment, the data source can identify information such as:

* File path
* Host
* URI
* Application endpoint
* Monitored runtime

Enable only the Node.js data sources that GermainUX should collect or analyze data from.

![Configure Monitoring for Node.js: Configure the Node.js Data Source](https://mintcdn.com/germain-ux/ARpsBmsSl-QLchOO/images/main/node-js-monitoring-configuration/image-20260907-211133.png?fit=max\&auto=format\&n=ARpsBmsSl-QLchOO\&q=85\&s=163b59b37fa301880f92b92cbecc2a3c)

## Configure the Application

Configure the Node.js application in GermainUX so collected telemetry is associated with the correct application.

Use consistent application naming across:

* Production
* Staging
* Development
* Application components
* Services

Application identity can also be configured programmatically:

```javascript theme={null}
const config = GermainAPM.getDefaultConfiguration(
    'https://GERMAIN_APM_SERVER/',
    'APP_NAME'
);
```

Application and component can also be specified separately:

```text theme={null}
config.defaults.application = {
    name: 'APP_NAME',
    component: 'APP_COMPONENT'
};
```

![Configure Monitoring for Node.js: Configure the Application](https://mintcdn.com/germain-ux/ARpsBmsSl-QLchOO/images/main/node-js-monitoring-configuration/image-20260907-211150.png?fit=max\&auto=format\&n=ARpsBmsSl-QLchOO\&q=85\&s=3d752c6d52510b66f318abc7e74105ce)

## Configure Monitoring Frequency

Some Node.js monitoring components execute periodically.

The default frequency is **60 seconds**.

Configure it using:

```text theme={null}
config.monitoring.frequencySeconds = 60;
```

Choose a frequency appropriate for the required visibility and monitoring overhead.

## Configure Asynchronous Correlation

By default, GermainUX correlates incoming HTTP requests with asynchronous outgoing HTTP requests.

This supports tracing such as:

Incoming HTTP Request
Node.js Processing
Outgoing HTTP Request
Downstream Service

Disable asynchronous correlation when required:

```text theme={null}
config.monitoring.asyncCorrelation = false;
```

Correlation introduces a small performance overhead, so enable it where transaction tracing is valuable.

## Configure Data Distribution

GermainUX periodically sends collected telemetry to the GermainUX Server.

Configure the maximum interval between transmissions using:

```text theme={null}
config.datapoints.maxFlushTimeSeconds = 60;
```

The data transport configuration also supports controls for:

* Sending or discarding telemetry
* Compression
* Maximum datapoints retained in memory
* Maximum flush interval

Available settings include:

```text theme={null}
config.datapoints.sendData
config.datapoints.compress
config.datapoints.maxNumInMemory
config.datapoints.maxFlushTimeSeconds
```

Compression is enabled by default.

## Configure Incoming HTTP Monitoring

Incoming HTTP monitoring is enabled by default.

Control it using:

```text theme={null}
config.monitoring.httpIncoming.enabled = true;
```

A custom session extractor can also be configured when the application needs application-specific session correlation.

This is useful when an incoming request contains a session identifier that GermainUX should associate with downstream activity.

## Configure Outgoing HTTP Monitoring

Outgoing HTTP monitoring is enabled by default.

Control it using:

```text theme={null}
config.monitoring.httpOutgoing.enabled = true;
```

Outgoing HTTP telemetry can be correlated with the incoming transaction to provide visibility into downstream service calls.

## Configure Unhandled Exception Monitoring

Unhandled exception monitoring is enabled by default.

Configuration supports:

* Enable / disable monitoring
* Whether the Node.js process exits after an error
* Application callback when an error occurs

Available configuration includes:

```text theme={null}
config.monitoring.unhandledExceptions.enabled
config.monitoring.unhandledExceptions.exitOnError
config.monitoring.unhandledExceptions.callbackOnError
```

Review `exitOnError` carefully because changing it can affect normal Node.js error-handling behavior.

## Configure Node.js Warning Monitoring

Node.js warning monitoring is enabled by default.

Warnings generated by the Node.js process can be collected and analyzed by GermainUX.

Control this capability using:

```text theme={null}
config.monitoring.warning = true;
```

Warnings can be used in:

* KPIs
* Dashboards
* Reports
* Alerts
* Trend analysis

## Configure Unhandled Promise Rejection Monitoring

Unhandled Promise rejection monitoring is enabled by default.

Control it using:

```text theme={null}
config.monitoring.unhandledPromiseRejection = true;
```

This allows GermainUX to identify asynchronous errors that are not properly handled by the application.

## Configure Multiple Promise Resolve / Rejection Monitoring

GermainUX also monitors when a Promise is resolved or rejected multiple times.

This monitoring is enabled by default.

Disable it using:

```text theme={null}
config.monitoring.multiplePromiseResolves = false;
```

## Configure Event Loop Latency Monitoring

Event-loop latency monitoring is enabled by default.

Disable it using:

```text theme={null}
config.monitoring.eventLoopLatency = false;
```

High event-loop latency can indicate blocking or resource-intensive application processing.

## Configure Startup Monitoring

GermainUX automatically monitors Node.js startup duration.

By default, startup duration is measured between the Node.js process startup and GermainUX initialization.

Disable automatic startup monitoring using:

```text theme={null}
config.monitoring.startup = false;
```

For applications with a more complex initialization process, explicitly indicate when startup has completed:

```text theme={null}
GermainAPM.collectStartup();
```

This allows startup duration to reflect the point at which the application is actually ready.

## Configure Exit Monitoring

Node.js process-exit monitoring is enabled by default.

Disable it using:

```text theme={null}
config.monitoring.exit = false;
```

Exit monitoring provides useful context when analyzing unexpected application termination or availability issues.

## Configure Custom Transaction Monitoring

Use custom transactions to monitor important business or application operations.

Start a transaction:

```text theme={null}
GermainAPM.startTransaction(
    'UNIQUE_TRANSACTION_NAME',
    'AdditionalInformation'
);
```

End the transaction:

```text theme={null}
GermainAPM.endTransaction(
    'UNIQUE_TRANSACTION_NAME'
);
```

Examples of useful transaction names include:

* `ProcessOrder`
* `CustomerLookup`
* `GenerateInvoice`
* `PaymentRequest`
* `SubmitClaim`

Custom transactions can then be analyzed for duration, failure, correlation, and application impact.

## Configure Node.js Process Monitoring

By default, GermainUX monitors the Node.js process for:

* CPU
* Memory usage
* Heap size
* Heap usage

Disable process-resource monitoring using:

```text theme={null}
config.monitoring.pid = false;
```

## Configure OS Resource Monitoring

GermainUX monitors CPU and memory usage of the server hosting the Node.js application.

Disable it using:

```text theme={null}
config.monitoring.os = false;
```

## Configure Disk Monitoring

GermainUX monitors disk usage of the server hosting the Node.js application.

Disable it using:

```text theme={null}
config.monitoring.disk = false;
```

## Configure Default Context

Default context can be added to collected datapoints.

Supported default dimensions include:

```text theme={null}
config.defaults.user
config.defaults.system
config.defaults.application
config.defaults.pid
```

Use default dimensions when telemetry should consistently be associated with a particular:

* User
* System
* Application
* Application component
* Process

Avoid attaching sensitive or unnecessary identifying information.

## Configure GermainUX Logging

Logging is enabled at `info` level and above by default.

Configure logging using:

```text theme={null}
config.logging.level = 'debug';
config.logging.filename = 'GermainAPM_custom.log';
config.logging.maxFiles = 20;
config.logging.maxSize = 20000000;
```

Available logging levels are:

* `error`
* `warn`
* `info`
* `verbose`
* `debug`

Default behavior includes rolling log files.

Use verbose and debug logging selectively in production.

## Configure Data Privacy & Exclusions

By default, captured telemetry is sent to GermainUX.

Use field exclusions when data must be protected for security or privacy reasons.

GermainUX supports:

**Mask** \
 Replace characters while optionally preserving length and whitespace.

**Anonymize** \
 Hash the original value so it can still be correlated without retaining the original value.

**Exclude** \
 Remove the captured value.

Example:

```text theme={null}
config.exclusions = [{
    fieldName: 'sessionId',
    factType: '',
    type: 'MASK',
    name: 'SessionId Anonymization',
    pattern: '',
    preserveLength: true,
    preserveWhitespace: true,
    enabled: true
}, {
    fieldName: 'requestBody',
    factType: 'NodeJS:Outbound',
    type: 'ANONYMIZE',
    name: 'Request Body Exclusion',
    pattern: '',
    preserveLength: true,
    preserveWhitespace: false,
    enabled: true
}];
```

Review sensitive fields such as:

* Session identifiers
* Request bodies
* Authentication information
* Tokens
* User information
* Personal information
* Application-specific confidential data

before production deployment.

## Configure KPIs

GermainUX provides preconfigured Node.js KPIs and supports custom KPIs.

Examples include:

* NodeJS Unhandled Promise Rejections
* NodeJS Warning
* HTTP response time
* Transaction duration
* Event-loop latency
* CPU usage

> [accordion] Show all 9
>
> * Memory usage
> * Heap usage
> * Application exits

Enable the KPIs relevant to the application and create custom KPIs where required.

![Configure Monitoring for Node.js: Configure KPIs](https://mintcdn.com/germain-ux/ARpsBmsSl-QLchOO/images/main/node-js-monitoring-configuration/image-20260907-211217.png?fit=max\&auto=format\&n=ARpsBmsSl-QLchOO\&q=85\&s=4667b009c612c1be8dd2e3d1a1b5f7f7)

## Configure SLAs

Define SLAs for Node.js KPIs requiring threshold-based monitoring.

For example:

**HTTP Response Time > Threshold**

**Event Loop Latency > Threshold**

**Unhandled Promise Rejections > 0**

**CPU Usage > Threshold**

**Transaction Duration > Threshold**

SLAs should reflect expected application behavior rather than using the same thresholds for every Node.js service.

![Configure Monitoring for Node.js: Configure SLAs](https://mintcdn.com/germain-ux/ARpsBmsSl-QLchOO/images/main/node-js-monitoring-configuration/image-20260907-211228.png?fit=max\&auto=format\&n=ARpsBmsSl-QLchOO\&q=85\&s=254eb940018805a864382ab9b787c4a6)

## Configure Categorization

Configure categorization rules to group Node.js telemetry into meaningful operational categories.

Categorization can be used for:

* Errors
* Warnings
* Transactions
* Application components
* Services
* Failure types

This helps consolidate similar events and simplify dashboards, reports, and alerts.

## Configure Correlation

In addition to built-in asynchronous HTTP correlation, configure GermainUX correlation where Node.js telemetry should be associated with other monitored technologies.

Examples:

Browser
Node.js
API

MarkoJS
Node.js
MySQL

Node.js
MuleSoft
Downstream Service

Correlation allows teams to move across application layers during troubleshooting.

## Configure Analytics Data Privacy

In addition to the Node.js collector-side exclusion rules, configure GermainUX privacy controls where collected telemetry needs additional handling within analytics.

Privacy policies should remain consistent across Node.js and any correlated frontend, API, or database monitoring.

## Configure Alerts

Create alerts for Node.js conditions requiring operational attention.

Examples include:

* Unhandled exception
* Unhandled Promise rejection
* Node.js warning
* Unexpected process exit
* Slow HTTP request
* Slow transaction
* High event-loop latency
* CPU or memory threshold exceeded

Configure appropriate:

* Conditions
* Thresholds
* Time windows
* Recipients
* Escalation behavior

![Configure Monitoring for Node.js: Configure Alerts](https://mintcdn.com/germain-ux/A5V4ExbdsH-e9Odt/images/main/node-js-monitoring-configuration/image-20260907-211250.png?fit=max\&auto=format\&n=A5V4ExbdsH-e9Odt\&q=85\&s=0508eeefa4489a668e136b9e02398b92)

## Configure Automation

Node.js conditions can trigger GermainUX automation.

For example:

Node.js Condition
KPI
SLA
Alert / Action

Automation can include:

* Notifications
* Reports
* Scripts
* HTTP actions
* Incident workflows
* Other configured operational actions
* Remediation actions where appropriate

## Configure Dashboards

Use an existing Node.js dashboard or create a custom dashboard.

Dashboards can present:

* Application health
* Errors and warnings
* HTTP performance
* Transaction performance
* Event-loop latency
* Promise-related problems

> [accordion] Show all 11
>
> * CPU and memory
> * Heap utilization
> * OS resources
> * Disk utilization
> * SLA status

Combine Node.js telemetry with frontend, API, database, and infrastructure data where useful.

## Configure Automated Reports

Enable an existing report or create a Node.js-specific automated report.

Reports can summarize:

* Availability
* Errors
* Application performance
* Transaction performance
* Resource utilization
* SLA violations
* Trends over time

Configure the appropriate schedule and recipients for each operational or management audience.

## Validate the Configuration

After changing Node.js configuration, execute representative application activity and verify:

* Application and data source association
* Incoming HTTP monitoring
* Outgoing HTTP monitoring
* Async correlation
* Unhandled exceptions
* Node.js warnings

> [accordion] Show all 21
>
> * Promise rejections
> * Event-loop latency
> * Startup and exit events
> * Custom transactions
> * Process CPU and memory
> * Heap telemetry
> * OS resources
> * Disk usage
> * Privacy and exclusion rules
> * KPIs
> * SLA evaluation
> * Categorization
> * Correlation
> * Alerts and automation
> * Dashboards and reports

Also verify that monitoring introduces acceptable overhead for the application.

## Advanced Configuration

`GermainAPMConfiguration` exposes additional controls for Node.js monitoring.

The main configuration areas include:

* `servicesUrl`
* `monitoring`
* `logging`
* `datapoints`
* `defaults`
* `exclusions`

The monitoring configuration includes controls for:

* Monitoring frequency
* Asynchronous correlation
* Unhandled exceptions
* Incoming HTTP
* Outgoing HTTP
* Startup

> [accordion] Show all 14
>
> * Process resources
> * OS resources
> * Disk
> * Node.js warnings
> * Unhandled Promise rejections
> * Event-loop latency
> * Process exit
> * Multiple Promise resolutions

Use the default automatic configuration where possible and customize only the capabilities required by the application.

```typescript theme={null}
type GermainAPMConfiguration = {
    /** GermainUX 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[]
}
```

## Get More Information

Magento environments can vary significantly depending on storefront customization, extensions, integrations, infrastructure, and security requirements.

The GermainUX team can help configure the appropriate monitoring scope, privacy controls, analytics, alerts, and automation for your Magento environment.

Please contact us [for any help.](https://docs.germainux.com/main/support.md)

## Get Help

> [card] [Contact GermainUX Support](https://docs.germainux.com/main/support.md)
>
> The GermainUX team helps you get up and running faster, empower your team, turn data into actionable insights, and optimize performance to deliver measurable business outcomes.

> [card] Can't find what you need?
>
> Search all GermainUX docs with **Ctrl + K**, or use the feedback buttons at the bottom of this page to tell us what is missing.

The content of this document is proprietary to GERMAIN SOFTWARE.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.