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 a 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 uses 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 SaaS. 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 SaaS does not affect the Service key.

When the configuration file is checked

The solarwinds-apm-config.json configuration file is read at startup. You can use the agent.configFileWatchPeriod property to specify the interval for checking the configuration file after startup. The default value is 0, which means that the configuration file is not checked for changes by default.

If the agent.configFileWatchPeriod property is set, the configuration file is checked for changes at the specified interval. If the values of any of the following properties have changed, the updated value is used:

agent.configFileWatchPeriod
agent.logging
agent.tracingMode
agent.hostnameAlias
agent.transactionNameSchemes
agent.transactionSettings
agent.hostnameAlias
agent.sqlQueryMaxLength
transaction.prependDomain
agent.triggerTrace

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 you add 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.na-01.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 the 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 key-value pairs for logging to a separate file. This is an optional key and by default is not defined. If it is 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 is 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 are generated when debug logging is enabled.

System environment variable

OTEL_JAVAAGENT_DEBUG

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

Enable or disable log exports

Logs are automatically exported when a supported logging framework is used by an instrumented service. This property can be used to enable or disable log export.

Config file property

agent.exportLogsEnabled

System environment variable

SW_APM_EXPORT_LOGS_ENABLED

System property

sw.apm.export.logs.enabled

Required

Possible values

true or false

Default

false

History

Examples

Config file property
```
"agent.exportLogsEnabled":true
```

Introduced with version 2.4.1 of the Java Instrumentation Library.

Trace context in queries

This option enables or disables injecting trace context as a comment into the beginning of a SQL statement for sampled requests. See Java trace context in queries for details and the support matrix.

The trace context injected for prepared statements is likely to be incorrect. SolarWinds recommends enabling injection only for non-prepared statements by using the config file property agent.sqlTag or the system environment variable SW_APM_SQL_TAG.

When agent.sqlTag or agent.sqlTagPrepared is enabled, the agent.sqlTagDatabases option can be used to restrict the feature to specific database drivers.

Config file properties and corresponding system properties and environment variables

agent.sqlTag: Enables trace context injection for non-prepared statements

System property: SW_APM_SQL_TAG
System environment variable: sw.apm.sql.tag

agent.sqlTagPrepared: Enables trace context injection for prepared statements

System property: SW_APM_SQL_TAG_PREPARED
System environment variable: sw.apm.sql.tag.prepared

agent.sqlTagDatabases: Restricts this feature to the specified comma-separated list of the JDBC driver names

System property: SW_APM_SQL_TAG_DATABASES
System environment variable: sw.apm.sql.tag.databases

Required

Possible scope values

`agent.sqlTag`	`true` or `false`
`agent.sqlTagPrepared`	`true` or `false`
`agent.sqlTagDatabases`	`mysql`, `postgresql`

Default

agent.sqlTag: false

agent.sqlTagPrepared: false

agent.sqlTagDatabases: mysql

History

The config file property agent.sqlTag and the corresponding environment variable and system property were introduced with version 0.7.1 of the Java instrumentation Library.

The config file property agent.sqlTagPrepared and the corresponding environment variable and system property were introduced with version 0.17.4 of the Java instrumentation Library.

The config file property agent.sqlTagDatabases and the corresponding environment variable and system property were introduced with version 2.4.0 of the Java instrumentation Library.

Examples

Config file property

"agent.sqlTag":true
"agent.sqlTagDatabases": "mysql,postgresql"

System environment variable (Linux)

export SW_APM_SQL_TAG=true
export SW_APM_SQL_TAG_DATABASES=postgresql

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 the Java Library

Disables 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)

Disables tracing for the service. When disabled, requests are no longer monitored and do not send traces or metrics. The trace context is still injected in the HTTP request and response headers, and JMX metrics are still 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 do 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, double backslashes are needed for Java regex escapes. The first backslash ensures the second backslash is retained as a Java escape character, for example, the JSON string \\. would become the regular expression \. that matches on a literal . instead of any character.
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"
    },
    {
        "regex": ".*/ping",
        "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 three 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 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. The 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 are omitted. By default, some Java basic method calls are excluded. To have no exclusions and show all operations, use an empty array as the 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 later.

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.

SolarWinds encourages defining this library proxy configuration even if the process level jvm arguments https.proxyHost and https.proxyPort are defined, because those arguments would only work for proxy servers that require no authentication.

Agent traffic cannot be authenticated with java.net.Authenticator#setDefault. For proxy servers that require 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 affect various SolarWinds Observability features and should be used only 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

Configurable transaction naming scheme

You can use the configurable transaction naming scheme functionality to specify one or more span attributes to be used to form the transaction name for a given request. This functionality complements the automatic and custom SDK transaction naming provided by the SolarWinds APM libraries.

The span attributes can be configured in the agent’s configuration in an array format. Each entry in the array represents a scheme with its associated properties. The order of schemes in the array specifies their precedence for generating a transaction name. Exactly one scheme will generate a name. Configuring multiple schemes ensures that at least one of them returns a name if some of the attributes are missing. The following example shows the configuration, the span, and the resulting transaction name.

Currently the span attributes available are limited to those set on the entry span of the service. Note that the final transaction name is still subject to cardinality limiting and transformations such as truncation, lowercasing, and invalid character replacement.

Config file property

agent.transactionNameSchemes

Required

Default

None.

History

Introduced with version 0.17.0 of the Java Instrumentation Library.

Example

Configuration

{
  "agent.transactionNameSchemes": [
   {
      "scheme": "spanAttribute",
      "delimiter": "-",
      "attributes": ["http.method"]
    },
    {
      "scheme": "spanAttribute",
      "delimiter": ":",
      "attributes": ["http.route","HandlerName"]
    },
  ]
}

Span

{
  "trace_id": "7bba9f33312b3dbb8b2c2c62bb7abe2d",
  "parent_id": "",
  "span_id": "086e83747d0e381e",
  "name": "/v1/sys/health",
  "start_time": "2021-10-22 16:04:01.209458162 +0000 UTC",
  "end_time": "2021-10-22 16:04:01.209514132 +0000 UTC",
  "status_code": "STATUS_CODE_OK",
  "status_message": "",
  "attributes": {
    "net.transport": "IP.TCP",
    "net.peer.ip": "172.17.0.1",
    "net.peer.port": "51820",
    "net.host.ip": "10.177.2.152",
    "net.host.port": "26040",
    "http.method": "GET",
    "http.target": "/v1/sys/health",
    "http.server_name": "mortar-gateway",
    "http.route": "/v1/sys/health",
    "http.user_agent": "Consul Health Check",
    "http.scheme": "http",
    "http.host": "10.177.2.152:26040",
    "http.flavor": "1.1"
  },
  "events": [
    {
      "name": "",
      "message": "OK",
      "timestamp": "2021-10-22 16:04:01.209512872 +0000 UTC"
    }
  ]
}

Transaction name = get

In the example above, the transaction name is get only if there is no name set using the custom SDK. The first configured scheme’s span attribute http.method exists in the span attribute list. Therefore, the second scheme will not be considered. The transaction name is normalized to lowercase characters.

In the example configuration above, a scheme is represented as an object with three properties: scheme, delimiter, and attributes.

scheme (string): Specifies the scheme. Currently only spanAttribute is supported.
attributes (array): Specifies the names of the span attribute to be used for the transaction name derivation.
delimiter (string): Specifies the delimiter used to join the values of the attributes specified.

Configure additional exporters

The Java Library sets an OpenTelemetry exporter for SolarWinds Observability SaaS 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 SaaS.

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.

Events flush interval

Specifies the amount of time (in seconds) to batch events before sending them to the collector. A long flush interval may cause the internal buffer to fill up faster than it is flushed, resulting in events being dropped. A long interval might also result in a noticeable increase in memory usage.

System environment variable

SW_APM_EVENTS_FLUSH_INTERVAL

System property

sw.apm.events.flush.interval

Required

Default

2 seconds

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

System environment variable (Linux)
```
export SW_APM_EVENTS_FLUSH_INTERVAL=2
```
System environment variable (Windows PowerShell)
```
$env:SW_APM_EVENTS_FLUSH_INTERVAL=2
```

System property

-javaagent:</path/to/solarwinds-apm-agent.jar> -Dsw.apm.events.flush.interval=2

Metrics flush interval

Specifies the amount of time (in seconds) to batch metrics before sending them to the collector.

System environment variable

SW_APM_METRICS_FLUSH_INTERVAL

System property

sw.apm.metrics.flush.interval

Required

Default

60 seconds

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

System environment variable (Linux)
```
export SW_APM_METRICS_FLUSH_INTERVAL=60
```
System environment variable (Windows PowerShell)
```
$env:SW_APM_METRICS_FLUSH_INTERVAL=60
```

System property

-javaagent:</path/to/solarwinds-apm-agent.jar> -Dsw.apm.metrics.flush.interval=60

Azure IMDS timeout

Specifies the amount of time (in seconds) to wait for the Azure instance metadata service to respond. A long timeout may increase the agent start-up time.

Config file property

agent.azureVmMetadataTimeout

System environment variable

SW_APM_AZURE_VM_METADATA_TIMEOUT

System property

sw.apm.azure.vm.metadata.timeout

Required

Default

1 second

History

Introduced with version 0.15.5 of the Java Instrumentation Library.

Examples

Config file property
```
"agent.azureVmMetadataTimeout":3
```

System environment variable (Linux)

export SW_APM_AZURE_VM_METADATA_TIMEOUT=3

System environment variable (Windows PowerShell)
```
$env:SW_APM_AZURE_VM_METADATA_TIMEOUT=3
```

System property

-javaagent:</path/to/solarwinds-apm-agent.jar> -Dsw.apm.azure.vm.metadata.timeout=3

Configuration watch period

Specifies the interval (in seconds) for checking the configuration file for changes.

Config file property

agent.configFileWatchPeriod

Required

Default

0 seconds (don't watch)

History

Introduced with version 0.17.1 of the Java Instrumentation Library.

Example

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

Collector timeout

Specifies the amount of time (in seconds) to wait for the collector to respond to requests.

Config file property

agent.collectorTimeout

System environment variable

SW_APM_COLLECTOR_TIMEOUT

System property

sw.apm.collector.timeout

Required

Default

10 seconds

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

Config file property
```
"agent.collectorTimeout":10
```
System environment variable (Linux)
```
export SW_APM_COLLECTOR_TIMEOUT=10
```
System environment variable (Windows PowerShell)
```
$env:SW_APM_COLLECTOR_TIMEOUT=10
```

System property

-javaagent:</path/to/solarwinds-apm-agent.jar> -Dsw.apm.collector.timeout=10

Azure IMDS version

Specifies the Azure instance metadata service version to use for retrieving instance metadata.

Config file property

agent.azureVmMetadataVersion

System environment variable

SW_APM_AZURE_VM_METADATA_VERSION

System property

sw.apm.azure.vm.metadata.version

Required

Default

2021-12-13

History

Introduced with version 0.15.5 of the Java Instrumentation Library.

Examples

Config file property

"agent.azureVmMetadataVersion":"2021-12-13"

System environment variable (Linux)

export SW_APM_AZURE_VM_METADATA_VERSION="2021-12-13"

System environment variable (Windows PowerShell)

$env:SW_APM_AZURE_VM_METADATA_VERSION="2021-12-13"

System property

-javaagent:</path/to/solarwinds-apm-agent.jar> -Dsw.apm.azure.vm.metadata.version="2021-12-13"

Transaction name pattern

Specifies a comma separated pattern based on URL path elements that should be used to form the transaction name.

Config file property

transaction.namePattern

Required

Default

None

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Example

Config file property
```
"transaction.namePattern":"host,p2,p3"
```

In the example above:

The URL http://something.com/v1/store/item?id=123 is mapped to the transaction name something.com.store.item.
The URL http://something.com/v1/welcome is mapped to the transaction name something.com.welcome.

Capture Database statement length

Specifies the maximum length of db.statement span attribute value allowed before it is truncated.

Config file property

agent.sqlQueryMaxLength

System environment variable

SW_APM_MAX_SQL_QUERY_LENGTH

System property

sw.apm.max.sql.query.length

Required

Default

2¹⁷

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Examples

Config file property
```
"agent.sqlQueryMaxLength":100
```
System environment variable (Linux)
```
export SW_APM_MAX_SQL_QUERY_LENGTH=100
```
System environment variable (Windows PowerShell)
```
$env:SW_APM_MAX_SQL_QUERY_LENGTH=100
```

System property

-javaagent:</path/to/solarwinds-apm-agent.jar> -Dsw.apm.max.sql.query.length=60

Time drift adjustment interval

Specifies the period for time adjustment to help minimize time drift effects on events timing.

Config file property

agent.timeAdjustInterval

Required

Default

600 seconds

History

Introduced with version 0.7.1 of the Java Instrumentation Library.

Example

Config file property
```
"agent.timeAdjustInterval":1000
```

Enable or disable metrics exports

This configuration is a convenience to set up OTLP metrics export from the instrumented application. When enabled, OTel-originated metrics from the application will be exported to SolarWinds Observability SaaS based on the configured service key and collector endpoint.

Config file property

agent.exportMetricsEnabled

System environment variable

SW_APM_EXPORT_METRICS_ENABLED

System property

sw.apm.export.metrics.enabled

Required

Possible values

true or false

Default

false

History

Introduced with version 2.8.0 of the Java Instrumentation Library.

Examples

Config file property
```
"agent.exportMetricsEnabled":true
```

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

When the configuration file is checked

Complete list of configuration options

Service key

Collector

Trusted certificate path

Logging level

Detailed logging configuration

Enable OpenTelemetry debug logging

Enable or disable log exports

Trace context in queries

Config file location

Disable the 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

Configurable transaction naming scheme

Configure additional exporters

Events flush interval

Metrics flush interval

Azure IMDS timeout

Configuration watch period

Collector timeout

Azure IMDS version

Transaction name pattern

Capture Database statement length

Time drift adjustment interval

Enable or disable metrics exports