Configuration (legacy agent)

The following content pertains to configuration for the legacy AppOptics Nodejs Agent.

The Node.js agent provides many settings that can be used to modify how it behaves, control security options, or even disable individual instrumentation.

Service key is the only required configuration, everything else is optional.

• System environment variable – certain configuration must be in set in the system environment variable such as APPOPTICS_DEBUG_LEVEL.

• JSON configuration – the agent also supports JSON configuration that applies to the agent and/or to each "probe", or the sub-component instrumentation, so that you can disable instrumentation or disable collecting backtraces on a per-probe basis. You can store the JSON configuration data in a file named either appoptics-apm-config.json or appoptics-apm-config.js at the root of your app, and it will get loaded when the appoptics-apm module starts up. An example is included in the agent package, and you can see the full probe options in the probe-default.js file that is distributed with the agent.

  See the Node.js readme for more information.

• Programmatic configuration – you can apply certain settings programmatically by modifying the object returned when requiring appoptics-apm, this can be in addition to having a JSON config file. For example:

  var ao = require('appoptics-apm')
  ao.hostnameAlias = 'apm-host-east'

Take note that if the same configuration is set in more than one of the above places, configuration is taken using this precedence:

System Environment Variable > JSON config file > Programmatic configuration > Default

Commonly used config options

The following is a list of the commonly used instrumentation configuration options. For more details, please refer to the agent's configuration guide.

Service Key

Service key used to identify your account and the service being instrumented. It should be in the form of <account key>:<service name>

• Config File Property: serviceKey
• System Environment Variable: APPOPTICS_SERVICE_KEY
• Required: Yes
• Examples: export APPOPTICS_SERVICE_KEY="0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:my-service" or in the configuration file "serviceKey": "0123456789abcde0123456789abcde0123456789abcde0123456789abcde1234:my-service"

Hostname Alias

An optional logical/readable hostname that can be used to easily identify the host.

• Config File Property: hostnameAlias
• System Environment Variable: APPOPTICS_HOSTNAME_ALIAS
• Default: Unset
• Examples: export APPOPTICS_HOSTNAME_ALIAS=apm-host-east or ao.hostnameAlias = 'apm-host-east'

Automatic Insertion of Trace ID into Logs

Enables the automatic insertion of the trace ID into supported log packages. Valid settings are: false - never insert, true or 'traced' - insert when traced, 'sampledOnly' - insert only when the trace is sampled, 'always' - insert an all-zeroes dummy value if not tracing. There are two options which enable the feature for different loggers:

bunyan, pino and winston

The object {ao: {traceId: '...'}} will be inserted into the logger’s metadata. The way that appears in the log varies with the logging package and version of the package.

• Config File Property: insertTraceIdsIntoLogs
• Default: false
• Example: "insertTraceIdsIntoLogs": true

morgan

The string ao.traceId=... will be appended to logged messages. The agent achieves this by modifying the morgan log format to include a Trace ID token, see the configuration option createTraceIdsToken for a less invasive approach.

• Config File Property: insertTraceIdsIntoMorgan
• Default: false
• Example: "insertTraceIdsIntoMorgan": true

Automatic Creation of Trace ID Log Attribute

Enables the creation of a logger attribute/token that can be used in the format string to include the Trace ID. Currently the only valid setting is 'morgan', which will create a token that can be referenced in morgan format strings as :ao-auto-trace-id.

• Config File Property: createTraceIdsToken
• Default: Unset
• Example: "createTraceIdsToken": "morgan"

Agent Log Level

Configure the level(s) at which the agent writes log messages, these are normally seen in the webserver logs and will be prefixed with the log level issuing the message, e.g., "appoptics:error". The log levels are not strictly levels - they are individual settings (see https://github.com/visionmedia/debug). They can be set via the environment variable APPOPTICS_LOG_SETTINGS or in the code using logLevel. If the APPOPTICS_LOG_SETTINGS environment variable is not set it will default to enabling "error" and "warn"; if APPOPTICS_LOG_SETTINGS is set to empty it will suppress all agent log messages.

• Config File Property: logLevel
• System Environment Variable: APPOPTICS_LOG_SETTINGS
• Default: "error,warn"
• Example: export APPOPTICS_LOG_SETTINGS=error,warn,info or ao.logLevel = 'error,warn,info'

Addon Log Level

Increase or decrease the log level of the C++ addon used by the agent. It takes the following values: 0 fatal, 1 error, 2 warning, 3 info (the default), 4 debug low, 5 debug medium, 6 debug high. Increase the logging verbosity to one of the debug levels to get more detailed information sent to stderr.

• Config File Property: None. The addon’s debug level can only be specified by environment variable.
• System Environment Variable: APPOPTICS_DEBUG_LEVEL
• Default: 3
• Example: export APPOPTICS_DEBUG_LEVEL = 6

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.