Customize the Lightrun Node.js agent¶

According to the Lightrun actions you specify, the agent dynamically inserts logs and snapshots in the target environment. The agent's behavior when performing these tasks is governed by a set of user-configurable properties.

Agent properties¶

You can specify the agent properties within the code, by using environment variables, or using the config file.

Specifying agent properties within the code¶

You specify agent properties in the start method of your application file as JSON comma-separated parameter-value pairs. For example:

require('lightrun').start({
     lightrunSecret: '<LIGHTRUN_SECRET>',
     propertyName1: 'value' ,
     propertyName2: 'value',
     .....
});

Optional metadata properties can be imported from a metadata file referenced in the start method. For example:

require('lightrun').start({
    lightrunSecret: '<LIGHTRUN_SECRET>',
    metadata: {
        filename: './agent.metadata.json'
    }
});

For more information about metadata, see the metadata and tagging article.

When specified in the start method, the agent configuration persists between application runs.

Specifying agent properties using environment variables¶

An alternative method for configuring agent properties is to enter them as environment variables when running the agent from the command line. A disadvantage of this method is that agent properties do not persist between runs and are required to be input at the command line each time the application is run.

For example, you can configure the Lightrun secret of your application by setting the <LIGHTRUN_SECRET> environment variable.

See the table below for all supported environment variables.

Specifying agent properties using a config file¶

You can also specify the agent properties using an agent config file agent.config, specify the path to the config file using agentConfigFile parameter or LIGHTRUN_AGENT_CONFIG environment parameter.

For example:

require('lightrun').start({
    agentConfigFile: '<PATH-TO-CONFIG>'
});

Order of precedence¶

When an application is run with a Lightrun agent, properties are defined in the following order of precedence:

1. Environment variables
2. Start configuration
3. Default configuration

Configuration properties supported by the Node.js agent¶

The following table lists agent configuration properties that can be configured either in the application's start method, or through environment variables when available.

Agent log¶

Metadata¶

Log¶

Capture¶

Quota¶

ExtraPaths¶

The Lightrun Node.js agent does not scan external files and third-party modules, i.e., node_modules, for Lightrun actions by default. To execute Lightrun actions in these files and modules, you have to specify the path to the files/modules using the extra_path parameter in your agent configuration.

TO specify extra_paths with the start method.¶

You can specify the path to the external files/third-party modules in your start method using the extraPathparameter.

require('lightrun').start({
    lightrunSecret: '<LIGHTRUN_SECRET>',
    extraPaths: ['path/to/file']
});

require('lightrun').start({
    lightrunSecret: '<LIGHTRUN_SECRET>',
    extraPaths: ['path/to/file', 'path/to/module']
});

To specify extra_paths in your agent.config file.¶

You can specify the path to the external files/third-party modules in your agent.config file using the extra_path parameter.

extra_paths = path/to/file, path/to/module

HTTP-Proxy configuration¶

A custom HTTP proxy server can be configured for the agent traffic.

The proxy server should support the CONNECT method.

proxy_host and proxy_port are mandatory settings, and should be provided together.

When specifying proxy_host, provide it as host.com without a protocol (e.g., https://host.com or http://host.com should not be used).

Manage Lightrun Node.js agent initialization in asynchronous startup¶

For performance-sensitive applications, Lightrun provides an asynchronous startup method, Lightrun.asyncStart(), allowing applications to continue execution while the agent initializes in the background. This reduces performance impact while enabling real-time observability.

When using Lightrun.asyncStart(), the Lightrun Node.js agent starts in a non-blocking manner, ensuring the application's main thread remains unblocked and runs without delays.

Using Lightrun.asyncStart()¶

For Node.js applications, the following example shows how to start Lightrun asynchronously while specifying a wait time:

await lightrun.asyncStart({
   lightrunWaitForInit: true,
   lightrunInitWaitTimeMs: 10000, 
});