No-code instrumentation for Java in Splunk Observability Cloud

No‑code instrumentation enables custom tracing for Java applications without modifying source code.

No‑code instrumentation enables adding custom OpenTelemetry instrumentation to Java applications without modifying the application source code. It can be used to create spans and attributes for specific Java methods when built‑in automatic instrumentation doesn't provide the required visibility. No‑code instrumentation for Java is implemented by the Splunk Distribution of OpenTelemetry Java agent and configured using an external configuration file.

Prerequisites

Before using no‑code instrumentation for Java, make sure that:

  • The application is already instrumented with the Splunk Distribution of OpenTelemetry Java agent (version 2.x).
  • The application runs on Java 8 or later.
  • The application is started with the Java agent using the -javaagent option.
  • Built‑in Java automatic instrumentation doesn't provide the required visibility for the methods you want to trace.
Note:

If the Java application isn't instrumented yet, see Instrument your Java application for Splunk Observability Cloud.

Usage guidelines

No‑code instrumentation provides additional flexibility when standard Java instrumentation options don't fully meet your needs. The guidelines below help you apply no‑code rules effectively and in a maintainable way, with a focus on targeted use cases.

When to use no‑code instrumentation

Use no‑code instrumentation when:

  • Automatic Java instrumentation doesn't provide the required visibility.
  • The application source code can't be modified.
  • You need to instrument specific, narrowly scoped methods.

If you can change the application code, use code‑based (manual) instrumentation instead.

Usage recommendations

  • Keep rules as narrow as possible.

  • Prefer simpler expressions and matchers when possible.

  • Write expressions defensively and assume values may be null.

  • Introduce rules incrementally and observe application behavior.

  • Validate configurations in a non‑production environment before wider rollout.

Configuration file location

No‑code instrumentation for Java is configured using an external YAML configuration file.

Specify the location of the configuration file by setting the following environment variable:
CODE 
SPLUNK_OTEL_INSTRUMENTATION_NOCODE_YML_FILE=/path/to/nocode.yml
The Splunk OpenTelemetry Java agent reads the configuration file during application startup.
Note: To apply any changes to the configuration, restart the Java process

Configuration file structure

The no‑code configuration file is a YAML file that defines one or more instrumentation rules evaluated by the Splunk OpenTelemetry Java agent at runtime.

Each rule describes how specific Java methods are instrumented, including span creation behavior, span properties, and optional attributes derived from the method execution context.

Example configuration

The following example illustrates the structure of a no‑code configuration file and shows how rules can be defined to instrument individual Java methods.
CODE 
- class: foo.Foo
  method: foo
  span_name: this.getName()
  attributes:
    - key: "business.context"
      value: this.getDetails().get("context")

- class: foo.Foo
  method: doStuff
  span_kind: CLIENT
  span_status: 'returnValue.code() > 3 ? "OK" : "ERROR"'
  attributes:
    - key: "special.header"
      value: 'param0.headers().get("special-header").substring(5)'
Warning: No‑code instrumentation modifies application behavior at runtime.

Expression variables

Expressions used in no‑code instrumentation rules (such as those shown in the example above) are written using the JEXL and are evaluated at runtime.

The table below lists the variables that can be referenced in expressions.
Variable Available in Description
this span_name, attributes Reference to the current object instance. May be null when instrumenting a static method.
param0 … paramN span_name, attributes Method prameters, where param0 corresponds to the first method parameter.
returnValue span_status Value returned by the method. May be null if the method returns void or exits with an exception.
error span_status The Throwable thrown by the method, or null if the method completes normally.

Example of complex class and method matching

No‑code instrumentation rules support advanced matching logic for selecting classes and methods to instrument. Logical operators and matchers can be combined to precisely target specific code paths.

The following example demonstrates how to combine multiple matchers to control class and method selection:
CODE 
- class:
    and:
      - or:
        - name: some.specific.Name
        - name_regex: some.*Regex.*
      - super_type: some.superclass.or.Interface
  method:
    and:
      - name_regex: methodName.*Regex.*
      - not:
          name: specificMethodNameToNotMatch
      - parameter_count: 2
      - parameter:
          index: 0
          type: int

Selection matchers

The following table describes the logical operators and matchers that can be used to select classes and methods for no‑code instrumentation.
Matcher / Operator Applies to Description
and, or,not, name, name_regex Class, Method Requires all nested matchers to match.
super_type Class Matches the specified type exactly, or any class that directly or indirectly extends or implements it.
parameter_count Method Requires an exact number of method parameters. Can be combined with logical operators to express more complex conditions.
parameter Method Matches a method parameter at a specific position using a zero‑based index and requires an exact type match.

Related content