Instrument a Java application

Instrument a Java application for Secure Application.

Follow the steps that correspond to your Java application's environment:

Instrument a Java application in a non-Kubernetes environment

Instrument a Java application with the Secure Application JVM extension.

Secure Application integrates runtime security detection into your Java application through a JVM extension (splunk-otel-javaagent-csa) that works with the Splunk Distribution of OpenTelemetry Java. This extension sends the OpenTelemetry events and logs that Secure Application needs to Splunk Observability Cloud. Follow these steps to add this extension to your Java application.

Important:

To monitor attacks your applications must be running on Java versions 8 - 23. Java 24+ is not universally supported.

  1. Find the JAR file you need for the type of monitoring you want:
    Vulnerability monitoring
    Secure Application JVM extension version 2.25.1
    Attack monitoring
    Secure Application JVM extension version 2.25.1
  2. Download the JAR file:

    For example:

    CODE 
    curl -L https://repo1.maven.org/maven2/com/splunk/splunk-otel-javaagent-csa/version/splunk-otel-javaagent-csa-<version>.jar -o splunk-otel-javaagent-csa.jar
  3. Start your application with the Secure Application JVM extension.

    On the command line, configure the agent using system properties or environment variables. System properties override environment variables.

    Table 1. Secure Application JVM extension parameters
    System property Environment variable Description
    argento.allow.security.events None Activates the JVM agent to start collecting attack events so that those events can be sent to the back end for analysis. You must include this flag to populate the Attacks page.
    otel.exporter.otlp.endpoint OTEL_EXPORTER_OTLP_ENDPOINT FQDN and gRPC port of your OpenTelemetry collector.

    Example: http://otel-collector:4318
    otel.resource.attributes OTEL_RESOURCE_ATTRIBUTES

    Resource attributes to associate with your Java application.

    Required:

    • service.name (set to same value as otel.service.name)

    Recommended:

    • deployment.environment.name
    • service.namespace
    otel.service.name OTEL_SERVICE_NAME Service name of your Java application.
    Tip: service.namespace is now an optional parameter in otel.resource.attributes. For information about this parameter, see Service Attributes. For help with the JVM agent, see Instrument Java applications for Splunk Observability Cloud.
    Syntax
    Note: To populate the Attacks page, add the JVM startup flag argento.allow.security.events=true to your java command as shown below.
    BASH 
    java -javaagent:./splunk-otel-javaagent-csa.jar \  
-Dotel.service.name=<service-name> \ 
-Dotel.resource.attributes=deployment.environment.name=<environment-name>,service.name=<service-name>,service.namespace=<namespace-name> \
-Dotel.exporter.otlp.endpoint=http://<collector-endpoint>:<collector-port> \
-Dargento.allow.security.events=true \
-jar <application-name>.jar

    For the meaning of these flags, see the JVM agent parameters table above.

    Substitute placeholders with values specific to your environment.

    Example
    BASH 
    java -javaagent:./splunk-otel-javaagent-csa.jar \ 
-Dotel.service.name=myService \ 
-Dotel.resource.attributes=deployment.environment.name=us0,service.name=myService,service.namespace=myServiceNamespace \
-Dotel.exporter.otlp.endpoint=http://otel-collector:4318 \
-Dargento.allow.security.events=true \
-jar myapp.jar

Your Java application launches with the JVM agent enabled. The JVM agent does the following:

  • Collects a list of runtime libraries and sends the data to the Splunk Observability Cloud back end.

  • Collects potential attack events at runtime.

  • Reports library data once at application startup and then every 24 hours thereafter.

Instrument a Java application in a Kubernetes environment

Use zero-code instrumentation to send Java application security telemetry to Secure Application from a Kubernetes environment.

Before you begin, make sure that your Kubernetes environment meets the following requirements:

  • You deploy the Splunk Distribution of OpenTelemetry Collector by using the Splunk OpenTelemetry Collector Helm chart.
  • The Splunk OpenTelemetry Collector Helm chart has the OpenTelemetry Operator activated with operator.enabled=true.
  • Your Java application runs in a Kubernetes namespace that you can annotate.
  • You don't override instrumentation.spec.java.image in the OpenTelemetry Operator instrumentation resource. Let the Helm chart manage the Java instrumentation image.

Follow this Kubernetes workflow when you already use, or plan to use, the OpenTelemetry Operator to inject Java instrumentation. In this workflow, the Helm chart configures the Secure Application Java instrumentation image, the namespace annotation triggers injection for Java pods, and a JVM startup flag activates security event collection.

Note: These steps are for Java applications in Kubernetes. For Java applications that don't run in Kubernetes, see Instrument a Java application in a non-Kubernetes environment.
  1. Activate Secure Application in the Splunk OpenTelemetry Collector Helm chart.

    If you already installed the chart, run helm upgrade and keep the values that your deployment already requires, such as realm, access token, and cluster name.

    SHELL 
    helm upgrade <release> splunk-otel-collector-chart/splunk-otel-collector \
  --set splunkObservability.secureAppEnabled=true
  2. Annotate the Kubernetes namespace that contains your Java application.

    Use the Helm release name as the annotation value. If you use the example release name from the Splunk OpenTelemetry Collector Helm chart docs, the value is splunk-otel-collector.

    SHELL 
    kubectl annotate namespace <your-namespace> \
  instrumentation.opentelemetry.io/inject-java=splunk-otel-collector
  3. Add the Secure Application activation flag to the JVM arguments for your Java application.

    For example, add the flag by using the JAVA_TOOL_OPTIONS environment variable in the Kubernetes deployment for your application.

    YAML 
    env:
  - name: JAVA_TOOL_OPTIONS
    value: "-Dargento.allow.security.events=true"
  4. Restart the pods for your Java application.

    The OpenTelemetry Operator injects the Java instrumentation when Kubernetes creates the pods.

    SHELL 
    kubectl rollout restart deployment/<your-deployment> -n <your-namespace>

After the pods restart, Secure Application receives security events from your Java application. Attack events appear on the Attacks page within a few minutes of pod start.

Upgrade Java instrumentation in a Kubernetes environment

Add Secure Application to an existing Java zero-code instrumentation deployment in Kubernetes.

If you already use the OpenTelemetry Operator to inject Java instrumentation for Splunk APM, you can add Secure Application without changing your application image. Activate splunkObservability.secureAppEnabled=true in the Splunk OpenTelemetry Collector Helm chart, annotate the namespace, and restart your Java application pods.

Use the following guardrails when you add Secure Application to an existing Kubernetes instrumentation deployment:

  • Let the Helm chart manage the Java instrumentation image. If you previously set a custom instrumentation.spec.java.image value, remove that override before you activate Secure Application.

  • Use the namespace annotation value for your Splunk OpenTelemetry Collector Helm release, such as instrumentation.opentelemetry.io/inject-java=splunk-otel-collector. Don't use true as the annotation value for this workflow.

  • Keep the Secure Application activation flag, -Dargento.allow.security.events=true, in the JVM arguments for your Java application. Without this flag, Splunk APM traces can continue to appear while Secure Application attack events don't appear.

  • Restart your Java application pods after you change Helm values, annotations, or JVM arguments. The OpenTelemetry Operator injects instrumentation when Kubernetes creates the pods.

When the Helm chart manages the Java instrumentation image, existing Splunk APM trace collection continues and Secure Application receives the additional security telemetry it needs.