Skip to content

Tuning the agent configuration

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:

     lightrunSecret: '<LIGHTRUN_SECRET>',
     propertyName1: 'value' ,
     propertyName2: 'value',

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

    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:

    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


Whenever changing agent configurations, save the changes and restart the application to apply the new 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.

Property name Environment variable Default value Description
lightrunSecret LIGHTRUN_SECRET No default value The company's secret API key, to connect to Lightrun
apiEndpoint LIGHTRUN_API_ENDPOINT '' The endpoint URI, with which the agent communicates
noCheckCertificate - false If set to true, the agent will not perform certificate pinning when communicating with the API endpoint
caPath - 'node_modules/lightrun/build/src/resources/lightrun-self-signed.pem' Path to the pem file of the CA signing the server's certificate (useful for self-signed certificates)
transmissionBulkMaxSize - 10 The maximum size of updates to transmit in a single batch to the server
pinnedCerts - ['515a630cfd1fb908e30087bcc20b7413ad146b9bf2b23d3aaa72c28e45b24fb2','ee80811b38e7e6c2dc4cc372cbea86bd86b446b012e427f2e19bf094afba5d12'] List of sha256 certificate public keys for pinning
agentLog - See table below Configuration related to the internal logs of the agent (not to be confused with the dynamic logs the user adds with the help of the agent)
metadata - See table below Agent metadata (such as tags and display name)
log - See table below Configuration related to the log action
capture - See table below Configuration related to the Capture (snapshot) action
quota - See table below Configuration related to the quotas on the agent's performance
extraPaths - - Paths to external files and third-party modules to be scanned for Lightrun actions.
lightrunWaitForInit - false Block the application until the first time breakpoints are fetched from the server. This option is intended for short-running applications like serverless functions, and it ensures that the Lightrun agent has time to communicate with the Lightrun server before the short-running application disconnects.

Note - using lightrun_wait_for_init in a cloud environment will likely incur additional costs from the cloud provider due to a longer application runtime.
lightrunInitWaitTimeMs - - Timeout in milliseconds for wait if lightrun_wait_for_init is set.

Agent log

Property name Environment variable Default value Description
logsPath - '/tmp' The directory in which internal agent logs file are stored. If the value is empty (undefined or empty string), the logs are transmitted to the console
level - 'info' The log level of the internal agent logger
collectCooldownMs - 1000 * 60 The time to wait before resuming logging activity when logging is paused due to CPU throttling in milliseconds.
maxLogFileBytes - 1024 * 1024 The maximum volume of log data to send to the server upon log collection request


Property name Environment variable Default value Description
filename LIGHTRUN_METADATA_FILE No default value Path to file containing json with the metadata
registration - {tags: ['Production']} Metadata registration:
- tags: array of strings with the tags to register the agent with. Can also be assigned with the Environment variableiable LIGHTRUN_TAGS that should contain a string of the tags, separated by commas with no spaces
-displayName: the name of the agent that will be displayed by Lightrun


Property name Environment variable Default value Description
maxLogsPerSecond - 50 Maximum number of logs to record per second per log action
logDelaySeconds - 1 Number of seconds to wait, before resuming, after the maxLogsPerSecond rate is reached
logger - console Object that implements info(msg), error(msg), warn(msg)


Property name Environment variable Default value Description
includeNodeModules - false Whether to include details about stack frames belonging to node-core
maxFrames - 20 Maximum number of stack frames for which to capture data in a single snapshot
maxExpandFrames - 5 The maximum number of top frames for which to collect full data for (locals and arguments)
maxProperties - 10 Number of properties gathered on a captured object. Value of 0 disables the limit
maxDataSize - 20000 Total 'size' of data to gather. This is a coarse approximation based on the length of names and values of the properties. Value of 0 disables the limit
maxStringLength - 100 Maximum length of captured strings. Value of 0 disables the limit


Property name Environment variable Default value Description
maxConditionCost - 1.0 Maximum cost in percentage of CPU consumption of condition evaluation (value between 0.1 and 1.0).
maxCPUCost - 1.0 Maximum cost of dynamic logging in percentage of CPU consumption (value between 0.1 and 1.0).
maxDynamicLogRate - 30 Maximum rate of dynamic log entries in this process
maxDynamicLogByteRate - 20480 Maximum rate of dynamic log bytes in this process
ignoreQuota - false Determines whether quota need to be ignored or not


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.

    lightrunSecret: '<LIGHTRUN_SECRET>',
    extraPaths: ['path/to/file']


You can add more than one path to the extraPath parameter.

    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


When specifying extraPaths, it is better to use the complete path to the file/module. i.e., node_modules/module_name instead of just node_modules to prevent duplicate file errors.

Last update: May 29, 2023