Configure the Java Library

The Java Library is a custom distro based on the OpenTelemetry agent. Therefore, it also supports the configuration options of the OpenTelemetry agent. This topic describes the configuration options available for the Java Library, including how to use the available properties.

How to set configuration options

All configuration options can be set as properties in the solarwinds-apm-config.json file. The JSON file can also be downloaded from https://agent-binaries.cloud.solarwinds.com/apm/java/latest/solarwinds-apm-config.json. Place this file in the same folder as the Java Library solarwinds-apm-agent.jar file.

SolarWinds recommends you place all configuration in solarwinds-apm-config.json.

Some configuration options can also be set through an environment variable or Java system property. If an environment variable or system property can be used, it is listed in the description of the configuration option.

The system properties used by the OpenTelemetry agent are prefixed with otel., while the system properties used by the custom distro have sw.apm. as a a prefix.

If the same configuration option is set in multiple places, the setting is applied with the following precedence:

System property
Environment variable
Property in solarwinds-apm-config.json configuration file
the ConfigPropertySource Service Provider Interface (SPI)

For detailed configurations supported by the OpenTelemetry agent, see Agent Configuration in the OpenTelemetry Docs.

If environment variables or system properties are not defined and the solarwinds-apm-config.json file is absent, the Java Library will use default values for all configuration options.

The Service key does not have a default value. This must be defined using one of the above methods.

It is a required configuration and should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

The service name is also called the entity's service ID in SolarWinds Observability. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability does not affect the Service key.

Complete list of configuration options

Service key

The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when adding the new service.

Config file property

agent.serviceKey

System environment variable

SW_APM_SERVICE_KEY

System property

sw.apm.service.key

Required

Yes

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

Config file property

"agent.serviceKey":"ABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123ab:ServiceName"

System property

-javaagent:/path/to/solarwinds-apm-agent.jar -Dsw.apm.service.key=ABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123ab:ServiceName

Collector

The collector is the ingestion endpoint the library connects to and exports data to. It should be defined using the format host:port. To determine the endpoint for your organization, see Data centers and endpoint URIs. Port is optional and defaults to 443.

Config file property

agent.collector

System environment variable

SW_APM_COLLECTOR

System property

sw.apm.collector

Required

Default

apm.collector.cloud.solarwinds.com:443

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

Config file property
```
"agent.collector":"YourHost:PortNumber"
```

System property

-javaagent:/path/to/solarwinds-apm-agent.jar -Dsw.apm.collector=YourHost:PortNumber

System environment variable (Linux)

export SW_APM_COLLECTOR=YourHost:PortNumber

System environment variable (Windows PowerShell)
```
$env:SW_APM_COLLECTOR="YourHost:PortNumber"
```

Trusted certificate path

The library uses the trusted CA certificates configured for the JVM to verify the TLS connection to the collector. To override the default, define the trusted certificate path configuration option with an absolute path to a specific trusted certificate file in PEM format.

System environment variable

SW_APM_TRUSTEDPATH

System property

sw.apm.trustedpath

Required

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

System property

-javaagent:/path/to/solarwinds-apm-agent.jar -Dsw.apm.trustedpath=/path/to/cacert.pem

System environment variable (Linux)

export SW_APM_TRUSTEDPATH=/path/to/cacert.pem

System environment variable (Windows PowerShell)
```
$env:SW_APM_TRUSTEDPATH="/path/to/cacert.pem"
```

Logging level

Simple configuration for setting the logging level. Messages that are warnings and more severe are written to stderr, while info messages and less severe are written to stdout. For more advanced options such as streaming logs to a separate file, see Detailed Logging Configuration and Enable OpenTelemetry debug logging.

Config file property

agent.logging

System environment variable

SW_APM_DEBUG_LEVEL

System property

sw.apm.debug.level

This property sets the log level for the custom distro portion of the library code.

Required

Possible values

Valid log levels in order of descending severity are fatal, error, warn, info, debug, trace, and off.

Default

info

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

Config file property
```
"agent.logging":"info"
```

System property

-javaagent:/path/to/solarwinds-apm-agent.jar -Dsw.apm.debug.level=debug

Detailed logging configuration

The Java Library prints logs to the streams stderr (for warn or more severe levels) and stdout (for info or less severe levels). Most application servers then redirect stderr and stdout to their own log files. The library logs can be redirected to a separate log file using the following settings.

Config file property

agent.logging.file.location

System environment variable

SW_APM_JAVA_LOG_FILE

System property

sw.apm.java.log.file

If the sw.apm.java.log.file system property is not set, the library looks for the io.opentelemetry.javaagent.slf4j.simpleLogger.logFile system property. This property defines the log file path of the built-in Otel agent. If the Otel agent log file path is defined, the Java Library will redirect logs to the same path.

Required

Additional logging configurations

The config file supports the additional logging configurations for the logging JSON object.

level

The logging level. Valid log levels in order of descending severity are fatal, error, warn, info, debug, trace, and off. This is a mandatory key with a default value of info.

stdout

Valid values are enabled or disabled. The stdout key determines if Java Library info level (or below) logs are printed to the stdout stream. This is an optional key with a default value of enabled. This is only available in the JSON config file and can only be set to disabled if the file key is defined.

stderr

Valid values are enabled or disabled. The stderr key determines if library warning level (or above) logs are printed to the stderr stream or not. This is an optional key with a default value of enabled. This is only available in the JSON config file and can only be disabled if the file key is defined.

file

The value is an object containing various keys-value pairs for logging to a separate file. This is an optional key and by default is not defined; if left undefined no logs are written to a separate file. The child keys are:

location

The location of the log file. If a relative path is provided, it is relative to the folder containing the library .jar. The folders in the path must already exist and the application user must have sufficient permission to write to the location. This is a mandatory parameter if the file key is defined.

maxSize

The maximum size (in megabytes) of the current log file before rolling to a backup. This is an optional key with a default of 10.

maxBackup

The maximum number of backup files. If this limit is reached, the oldest backup file will be discarded next time. This is an optional key with a default of 5.

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

Config file property

"agent.logging": {
  "level": "info",
  "stderr": "enabled",
  "stdout": "enabled",
  "file": {
    "location": "solarwinds-apm-agent.log",
    "maxSize": 10,
    "maxBackup": 5
  }
}

System property

 -javaagent:</path/to/solarwinds-apm-agent.jar> -Dio.opentelemetry.javaagent.slf4j.simpleLogger.logFile="solarwinds-apm-agent.log"

System environment variable (Linux)

export SW_APM_JAVA_LOG_FILE=solarwinds-apm-agent.log

System environment variable (Windows PowerShell)

$env:SW_APM_JAVA_LOG_FILE="solarwinds-apm-agent.log"

Enable OpenTelemetry debug logging

This property enables or disables debug logging in the OpenTelemetry portion of the library. See Logging level for information about setting the log level of the custom distro portion of the library.

More verbose logs will be generated by enabling the debug logging.

System property

otel.javaagent.debug

Required

Possible values

true or false

Default

false

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Example

System property

-javaagent:/path/to/solarwinds-apm-agent.jar -Dotel.javaagent.debug=true

Trace context in queries

Trace context as a string identifier can be added as a comment to the start of the SQL statement for sampled requests to identify the query statements executed for a traced request.

Trace context in queries is only supported for the MySQL driver under JDBC. This setting has no effect for other database drivers.

Config file property

agent.sqlTag

System environment variable

SW_APM_SQL_TAG

Required

Default

false

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

Config file property
```
"agent.sqlTag":true
```
System environment variable (Linux)
```
export SW_APM_SQL_TAG=true
```
System environment variable (Windows PowerShell)
```
$env:SW_APM_SQL_TAG="true"
```

Config file location

Specify the location of the Java Library config file.

System environment variable

SW_APM_CONFIG_FILE

System property

sw.apm.config.file

Required

Default

./solarwinds-apm-config.json

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Example

System property

javaagent:/path/to/solarwinds-apm-agent.jar -Dsw.apm.config.file=/path/to/solarwinds-apm-config.json

Disable Java Library

Disable the Java Library by setting the standard OpenTelemetry otel.javaagent.enabled config file property or OTEL_JAVAAGENT_ENABLED environment variable to false. See Disabling the agent entirely in the OpenTelemetry documentation.

Tracing mode (disable tracing)

Disable tracing for the service. When disabled, requests will no longer be monitored or send traces or metrics. The trace context will still be injected in the HTTP request and response headers, and JMX metrics will still be reported.

To completely disable the library, remove the library. See Uninstall the Java Library.

Config file property

agent.tracingMode

Required

Possible values

`disabled`	Does not continue existing traces or start new ones, and does not report metrics for requests.
`enabled`	(Default) Create or continue traces (subject to sampling and rate limits), and always report metrics for requests.

Default

enabled

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Example

Config file property
```
"agent.tracingMode":"disabled"
```

Tracing mode per transaction (Enable or disable tracing for specific requests)

Defines the tracing mode for requests at a granular level, based on whether the requests match a specified criteria. Tracing is enabled or disabled for requests based on the tracing property of the matching criteria, superseding tracing mode settings applied at the service level. Requests with "tracing" : "disabled" are not monitored, and will not create traces or send metrics. Requests with "tracing" : "enabled" define the requests that are monitored even when tracing is disabled at the service level.

Config file property

agent.transactionSettings

Possible values

Config value should be an array of JSON entries where each entry must contain a matcher and the desired tracing mode:

regex (required) - value should be a Java regular expression (see Java.util.regex Pattern class in the Oracle Java™ Platform API Specification). Since the regular expression is defined in a JSON string, use double backslashes to escape your Java regular expressions. The first backslash ensures the second backslash is retained as a Java escape character in the regular expression and still escapes whatever follows in the regex pattern.
tracing (required) - value should either be enabled or disabled.

Entries are applied in the order defined in the JSON array. To find a match, each entry is first compared against the request's URL (constructed with the format scheme://host/target using the Span attributes http.scheme, net.host.name, and http.target), and then compared against the Span kind and name (concatenated with a colon, for example CLIENT:SELECT). The first matching entry for a request is taken.

Required

Default

None. No transaction-specific tracing mode.

History

Introduced with version 0.15.3 of the Java Instrumentation Library.

Example

Config file property

"agent.transactionSettings": [
    {
        "regex": "CLIENT:GET",
        "tracing": "disabled"
    },
    {
        "regex": "INTERNAL:Task\\.run",
        "tracing": "disabled"
    },
    {
        "regex": "http://localhost.*",
        "tracing": "disabled"
    }
]

Set hostname alias

An optional descriptive host name that can be used to easily identify the host. If configured, the host name alias is displayed and can be used as a filter in the Traces Explorer.

Config file property

agent.hostnameAlias

System environment variable

SW_APM_HOSTNAME_ALIAS

System property

sw.apm.hostname.alias

Required

Default

Not present

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

Config file property

"agent.hostnameAlias":"my-service-host"

System property

-javaagent:/path/to/solarwinds-apm-agent.jar -Dsw.apm.hostname.alias=my-service-host

Prepend domain to transaction name

An optional boolean parameter to prepend the domain to the transaction name.

Config file property

transaction.prependDomain

Required

Default

Not present

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Example

Config file property
```
"transaction.prependDomain":true
```

JMX metrics

By default, the Java Library reports several core JVM health metrics using JMX MBeans. The list of JMX MBeans can be customized to allow each Java application to export more specific metrics.

There are 3 configuration properties for JMX: monitor.jmx.enable (enable or disable library JMX reporting), monitor.jmx.scopes (defines the attributes used to locate metrics), and monitor.jmx.maxEntry (maximum number of JMX metrics reported per cycle).

Enable or disable JMX metrics

Boolean value to enable or disable library JMX reporting.

Config file property

monitor.jmx.enable

Required

Default

true

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Example

Config file property
```
"monitor.jmx.enable":true
```

JMX Metrics collection scope

An array of JMX MBean/attribute entries used to locate metrics. Each entry consists of an object name and an attribute list in the form of <Object Name>:[<Attribute 1>, <Attribute2>...].

Config file property

monitor.jmx.scopes

Valid values

Each scope entry consists of an object name and an attribute list in the form of <Object Name>:[<Attribute 1>, <Attribute2>...].

Object name

The object name is the pattern for JMX MBean look-up. A single object name can match multiple MBeans. The following example matches all MBeans exposed by domain "Catalina" with type "Manager":

"Catalina:type=Manager,*"

More information on Object Name can be found in Java Management Extensions (JMX) - Best Practices - Oracle.

Attribute list

List of attributes within the JMX MBean that matches the object name in the scope.

For example, to report the attributes HeapMemoryUsage and NonHeapMemoryUsage from the Memory MBean, use this scope:

"java.lang:type=Memory":["HeapMemoryUsage", "NonHeapMemoryUsage"]

Wildcards can be used to report all attributes, however this is may result in a large number of metric entries.

"java.lang:type=Memory":"*"

Wildcards are not recommended: the use of wildcards may result in a large number of metric entries and a higher cost.

Required

Default

Config file property

{
  "java.lang:type=MemoryPool,":["Usage"],
  "java.lang:type=Memory":["HeapMemoryUsage","NonHeapMemoryUsage"],
  "java.lang:type=GarbageCollector,":["CollectionTime"],
  "java.lang:type=Threading":["ThreadCount"],
  "java.lang:type=OperatingSystem":["ProcessCpuTime","AvailableProcessors","ProcessCpuLoad"],
  "java.lang:type=Runtime,*":["Uptime"]
}

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

JMX max entries

An integer value that defines the maximum number of JMX metrics reported per cycle.

Config file property

monitor.jmx.maxEntry

Required

Default

100

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Enable or disable code profiling

The Java Library's code profiling is currently only applicable to Servlet processing and SDK-initiated traces.

Code profiling is defined using a combination of configuration options. When set using the solarwinds-apm-config.json config file, the profiler option is defined using a JSON object. When set using environment variables, the configuration options are defined in different environment variables.

Config file property

profiler

profiler child object properties

`enabled`	Boolean value to enable or disable code profiling; default is `false`. This can also be set using the `SW_APM_PROFILER_ENABLED` environment variable.
`interval`	The interval in milliseconds that determines how often the profiler obtains information about the method execution from the JVM. A shorter interval results in more frequent sampling, which could lead to extra overhead. The default interval is `20` and the minimum is `10`. This can also be set using the `SW_APM_PROFILER_INTERVAL` environment variable.
`excludePackages`	A list of Java packages the code profiler excludes from its data reporting. Classes with package names that start with any entry in the list will be omitted. By default, some Java basic method calls are excluded. To have no exclusions and show all operations, use an empty array as value.

System environment variables

SW_APM_PROFILER_ENABLED, SW_APM_PROFILER_INTERVAL

System properites

sw.apm.profiler.enabled

sw.apm.profiler.interval

Required

Default

Code profiling disabled (false)

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

Config file property

"profiler":
{
  "enabled" : true,
  "excludePackages" : ["java", "javax", "com.sun", "sun", "sunw"],
  "interval" : 20
}

System environment variable (Linux): enabling the profiler
```
export SW_APM_PROFILER_ENABLED=true
```
System environment variable (Windows PowerShell): enabling the profiler
```
$env:SW_APM_PROFILER_ENABLED="true"
```
System environment variable (Linux): setting the profiler interval
```
export SW_APM_PROFILER_INTERVAL=100
```
System environment variable (Windows PowerShell): setting the profiler interval
```
$env:SW_APM_PROFILER_INTERVAL="100"
```

Proxy

Configure traffic between the library and the SolarWinds APM collector to go through a proxy server.

This feature requires Java 8u252 or newer.

The config value should either be http://<proxyHost>:<proxyPort> for a proxy server that does not require authentication, or http://<username>:<password>@<proxyHost>:<proxyPort> for a proxy server that requires Basic authentication.

While HTTP is the only type of connection supported between the Java Library and the proxy, the Java Library's traffic to the SolarWinds APM collector is still encrypted using SSL/TLS.

It is encouraged to define this library proxy configuration even if the process level jvm arguments https.proxyHost and https.proxyPort are defined, as those arguments would only work for proxy server that requires no authentication.

Agent traffic cannot be authenticated with java.net.Authenticator#setDefault. For proxy servers that requires authentication, the Java Library proxy configuration must be used.

Config file property

agent.proxy

System environment variable

SW_APM_PROXY

System property

sw.apm.proxy

Required

Default

Not present; no proxy

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

Config file property

"agent.proxy":"http://my-proxy-user:password123@my-proxy-server:8080"

System property

-javaagent:/path/to/solarwinds-apm-agent.jar -Dsw.apm.proxy="http://my-proxy-user:password123@my-proxy-server:8080"

Disable or set timeout on EC2 instance check

Optional configuration. On library startup, the Java Library checks to determine if the server is an AWS EC2 or OpenStack instance. The ec2MetadataTimeout configuration can be used to adjust the timeout length of this check. If the library is not running on an AWS EC2 or OpenStack instance, it is safe to set this value to 0. A valid value is an integer between 0 and 3000. The EC2 metadata timeout is in milliseconds.

Config file property

agent.ec2MetadataTimeout

System environment variable

SW_APM_EC2_METADATA_TIMEOUT

System property

sw.apm.ec2.metadata.timeout

Required

Default

1000

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

Config file property
```
"agent.ec2MetadataTimeout":0
```

System property

-javaagent:/path/to/solarwinds-apm-agent.jar -Dsw.apm.ec2.metadata.timeout=0

Enable or disable trigger trace

Config file property

agent.triggerTrace

System environment variable

SW_APM_TRIGGER_TRACE

System property

sw.apm.trigger.trace

Required

Default

enabled

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

Config file property
```
"agent.triggerTrace":"disabled"
```

System property

-javaagent:/path/to/solarwinds-apm-agent.jar -Dsw.apm.trigger.trace=disabled

Disable instrumentation components

Many instrumentation components can be disabled for troubleshooting purposes. To disable options for our custom distro, see below. To disable the standard OpenTelemetry instrumentation using otel.instrumentation.* properties, see Suppressing specific agent instrumentation in OpenTelemetry Docs

Disable customization of JDBC instrumentation

Disables our customization of the JDBC instrumentation. This may impact various SolarWinds Observability features and should only be used for troubleshooting.

System properties

otel.instrumentation.sw-jdbc.enabled

Required

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Example

System property

-javaagent:/path/to/solarwinds-apm-agent.jar -Dotel.instrumentation.sw-jdbc.enabled=false

Configure additional exporters

The Java Library sets an OpenTelemetry exporter for SolarWinds Observability by default. If you want to configure additional exporters, follow the instructions in the OpenTelemetry SDK Autoconfigure documentation's Exporters section. Include solarwinds in your list of exporters to continue exporting to SolarWinds Observability.

If you want to use an exporter that is not packaged with the library, see Components supported by the Java Library for details about extending the Java Library.

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.

Search SolarWinds Support

Configure the Java Library

How to set configuration options

Complete list of configuration options

Service key

Collector

Trusted certificate path

Logging level

Detailed logging configuration

Enable OpenTelemetry debug logging

Trace context in queries

Config file location

Disable Java Library

Tracing mode (disable tracing)

Tracing mode per transaction (Enable or disable tracing for specific requests)

Set hostname alias

Prepend domain to transaction name

JMX metrics

Enable or disable JMX metrics

JMX Metrics collection scope

JMX max entries

Enable or disable code profiling

Proxy

Disable or set timeout on EC2 instance check

Enable or disable trigger trace

Disable instrumentation components

Disable customization of JDBC instrumentation

Configure additional exporters