Skip to content

Agent Configuration

Tuning agent configurations

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

Agent properties

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

require('lightrun').start({
     company: 'YOUR_COMPANY_NAME',
     lightrunSecret: 'YOUR_COMPANY_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({
    company: 'YOUR_COMPANY_NAME',
    lightrunSecret: 'YOUR_COMPANY_SECRET',
    metadata: {
    filename: './agent.metadata.json'
    }
});

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

If no agent properties are specified by the user, the default values listed in the table below, are supplied during the agent's installation, are used.

An alternative method for configuring agent properties is by entering 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.

When an application is run with a Lightrun agent, properties are defined according to the following precedence:

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

Important

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 in the application's start method.

Property name Environment variable Default value Description
company LIGHTRUN_COMPANY No default value The user's company name. This value is mandatory
lightrunSecret COMPANY_SECRET No default value The company's secret API key, to connect to Lightrun
apiEndpoint LIGHTRUN_API_ENDPOINT 'app.lightrun.com' 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

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 How much time to wait (in milliseconds) between log collection requests from the server
maxLogFileBytes - 1024 * 1024 The maximum volume of log data to send to the server upon log collection request

Metadata:

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

Log:

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)

Capture:

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

Quota:

Property name Environment variable Default value Description
maxConditionCost - 0.01 Maximum cost in percentage of CPU consumption of condition evaluation
maxCPUCost - 0.03 Maximum cost of dynamic logging in percentage of CPU consumption
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

Last update: October 27, 2021