Docs » Instrument back-end applications to send spans to Splunk APM » Instrument Java applications for Splunk Observability Cloud » Splunk OpenTelemetry Zero Configuration Auto Instrumentation for Java

Splunk OpenTelemetry Zero Configuration Auto Instrumentation for Java πŸ”—

Splunk OpenTelemetry Zero Configuration Auto Instrumentation for Java provides a package that automatically instruments your local Java applications to capture and report distributed traces to the Splunk Distribution of OpenTelemetry Collector, and then on to Splunk APM.

Splunk OpenTelemetry Zero Configuration Auto Instrumentation for Java provides the following benefits:

  • You can start streaming traces and monitor distributed applications with Splunk APM in minutes.

  • You don’t need to configure or instrument your Java back-end services or applications before deployment.

Install the package πŸ”—

You can install the package in two ways:

Install using the Collector installer script πŸ”—

By default, the installer script only installs the Collector. If the --with-instrumentation option is specified, the installer script also installs the agent from the Splunk Distribution of OpenTelemetry Java, which is then loaded automatically when a Java application starts on the local machine.

Run the installer script with the --with-instrumentation option, as shown in the following example:

curl -sSL https://dl.signalfx.com/splunk-otel-collector.sh > /tmp/splunk-otel-collector.sh && \
sudo sh /tmp/splunk-otel-collector.sh --with-instrumentation --realm <SPLUNK_REALM> -- <SPLUNK_ACCESS_TOKEN>

To automatically define the optional deployment.environment resource attribute at installation time, run the installer script with the --deployment-environment <VALUE> option. Replace <VALUE> with the desired attribute value, for example, prod, as shown in the following example:

curl -sSL https://dl.signalfx.com/splunk-otel-collector.sh > /tmp/splunk-otel-collector.sh && \
sudo sh /tmp/splunk-otel-collector.sh --with-instrumentation --deployment-environment prod --realm <SPLUNK_REALM> -- <SPLUNK_ACCESS_TOKEN>

See Supported parameters for the supported configuration parameters.

After successful installation, the Java applications on the host need to be manually started or restarted for automatic instrumentation to take effect.

Install using Debian or RPM packages πŸ”—

Follow these steps to install the package using the Debian or RPM repositories with root privileges:

  1. Download the splunk-otel-auto-instrumentation Debian or RPM package for the target system from the GitHub Releases page.

  2. Run the following commands to install the package. Replace <path to splunk-otel-auto-instrumentation deb/rpm> with the local path to the downloaded package.

dpkg -i <path to splunk-otel-auto-instrumentation deb>
  1. See Supported parameters for additional details.

You can also install the splunk-otel-auto-instrumentation package using the same package repositories as the Collector. See Debian or RPM packages for more information.

Configuration file of the package πŸ”—

The package includes the /usr/lib/splunk-instrumentation/instrumentation.conf configuration file, which is read by the shared object library libsplunk.so when applications are started. The .so library, which is installed with the configuration file and the JAR file, is a set of files used by multiple applications.

By default, the configuration file looks like the following example:

java_agent_jar=/usr/lib/splunk-instrumentation/splunk-otel-javaagent.jar

The java_agent_jar parameter points to the default location of the JAR file. See Supported parameters for more information on the supported parameters.

Supported parameters πŸ”—

The following table shows the supported parameters for the /usr/lib/splunk-instrumentation/instrumentation.conf file:

Parameter

Description

Required

java_agent_jar

The full path to the JAR file provided by the installer.

Yes

service_name

Optional override for the service name that is generated by the shared object before Java startup. By default, this line is commented out, but can be uncommented to override the generated name. If this parameter is set, all instrumented Java applications on the host have their service name set using the OTEL_SERVICE_NAME environment variable.

No

resource_attributes

Contains a list of name-value pairs, separated by =s, that the shared object sets to the RESOURCE_ATTRIBUTES environment variable. The RESOURCE_ATTRIBUTES environment variable is then picked up by the Java instrumentation JAR file. The installer script sets this to something like resource_attributes=deployment.environment=test, which defines the deployment environment.

No

Keep the following information in mind after the installation:

  • The /etc/ld.so.preload file is automatically created or updated with the default path to the installed instrumentation library, which is /usr/lib/splunk-instrumentation/libsplunk.so. If necessary, custom library paths can be manually added to this file.

  • The /usr/lib/splunk-instrumentation/instrumentation.conf configuration file can be manually configured for resource attributes and other parameters. By default, this file contains the java_agent_jar parameter set to the path of the installed Java Instrumentation Agent, which is /usr/lib/splunk-instrumentation/splunk-otel-javaagent.jar. If the --deployment-environment VALUE installer script option is specified, the deployment.environment=VALUE resource attribute is automatically added to this file.

After any configuration changes, the Java applications on the host need to be manually started or restarted to source the updated values from the configuration file.

Upgrade the package πŸ”—

You can upgrade the package in two ways:

Upgrade using the package repository πŸ”—

If you installed the package using the installer script, or if you configured the Debian or RPM package repositories manually, run the following commands according to your platform. Upgrading the package requires root privileges.

Debian πŸ”—

Run the following commands:

sudo apt-get update
sudo apt-get --only-upgrade splunk-otel-auto-instrumentation

You might be prompted to keep or overwrite the configuration file at /usr/lib/splunk-instrumentation/instrumentation.conf. If you choose to overwrite, the configuration file reverts to the default file provided by the upgraded package.

RPM πŸ”—

For the RPM package management system, run the following commands:

yum πŸ”—
sudo yum upgrade splunk-otel-auto-instrumentation
dnf πŸ”—
sudo dnf upgrade splunk-otel-auto-instrumentation
zypper πŸ”—
sudo zypper refresh
sudo zypper update splunk-otel-auto-instrumentation

After you’ve upgraded the packages, manually start or restart the Java applications on the host for the changes to take effect.

Upgrade using Debian or RPM packages πŸ”—

To manually upgrade the package:

  1. Download the splunk-auto-auto-instrumentation Debian or RPM package for the target system from the GitHub Releases page.

  2. Run the following commands to install the package. Replace <path to splunk-otel-auto-instrumentation deb/rpm> with the local path to the downloaded package:

    sudo dpkg -i <path to splunk-otel-auto-instrumentation deb>
    

After upgrading the Debian package, you might be prompted to keep or overwrite the configuration file at /usr/lib/splunk-instrumentation/instrumentation.conf. If you choose to overwrite, the configuration file reverts to the default file provided by the upgraded package.

You can also upgrade using the same package repositories as the Collector. See Debian or RPM packages for more information.

Disable automatic instrumentation πŸ”—

Use one of the following options to disable automatic instrumentation:

  • Uninstall the package by running curl -sSL https://dl.signalfx.com/splunk-otel-collector.sh > /tmp/splunk-otel-collector.sh && \sudo sh /tmp/splunk-otel-collector.sh --uninstall. See Uninstall on Linux for more information on the files deleted by the uninstall.

  • Set DISABLE_SPLUNK_AUTOINSTRUMENTATION to any non-empty value other than false, FALSE, or 0.

  • Set the JAVA_TOOL_OPTIONS environment variable to some value that you want the JVM to pick up.

  • Delete or move the instrumentation.conf configuration file.

Report an issue πŸ”—

Before you create an issue or open a support request, try gathering the following information:

  • What happened and the impact of the issue.

  • All the steps you’ve followed until the issue appeared.

  • What was the expected outcome.

  • Your attempts to solve the issue, including workarounds.

  • The operating system, runtime or compiler version, libraries, frameworks, and application servers of your environment, including your instrumentation settings.

  • Debug logs and other logs that might help troubleshoot the issue.

To get help, see Splunk Observability Cloud support.