Java zero-code instrumentation¶

Beacon Java ships as one agent JAR. It requires a JDK-supported runtime; profiling requires JDK 11 or later. The same JAR contains the optional Security capability.

Before starting, enable the DataKit OpenTelemetry input as described in Common configuration. The commands use a Linux/macOS shell and assume that the application and DataKit run on the same host. Replace 127.0.0.1 and adjust the listening address for remote or container deployments.

Install¶

Download the complete Agent JAR from the Beacon Java releases page and save it as beacon-javaagent.jar in the current directory.

Run¶

export OTEL_SERVICE_NAME=my-java-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4317
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
java -javaagent:./beacon-javaagent.jar -jar app.jar

Put -javaagent before -jar or the application's main class. Keep all existing JVM and application arguments unchanged.

Debugging and diagnostics¶

Keep the service name and OTLP settings above. Temporarily enable Agent debug logging and capture the output:

OTEL_JAVAAGENT_DEBUG=true \
  java -javaagent:./beacon-javaagent.jar -jar app.jar \
  > beacon-java-debug.log 2>&1

Alternatively, add -Dotel.javaagent.debug=true before -jar. The JVM system property takes precedence over the environment variable. Use these logs to inspect Agent loading, instrumentation matching, and export errors.

Return to the normal launch command after troubleshooting. If the variable or JVM property was added to service configuration, remove it and restart the application.

Profile¶

Enable the DataKit Profile input, then set the variables below and retain the launch configuration above. Profiles use a separate HTTP upload endpoint, independent of the OTLP traces endpoint.

Beacon Java profiling is experimental, disabled by default, and requires Java 11 or later with JFR available. Keep using the same -javaagent command from the Java zero-code guide.

Upload over HTTP¶

Use the compatibility HTTP exporter to send a JFR snapshot and its metadata as multipart/form-data:

export OTEL_SERVICE_NAME=my-java-service
export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_EXPORTER=datakit
export OTEL_PROFILING_ENDPOINT=http://127.0.0.1:9529/profiling/v1/input
java -javaagent:./beacon-javaagent.jar -jar app.jar

The value datakit is the current compatibility exporter identifier. The configured receiver must accept main.jfr and event.json multipart fields. The default snapshot interval is one minute.

Write JFR files locally¶

Use the file exporter for receiver-independent validation:

mkdir -p profiles
export OTEL_PROFILING_ENABLED=true
export OTEL_PROFILING_EXPORTER=file
export OTEL_PROFILING_EXPERIMENTAL_FILE_EXPORT_PATH="$PWD/profiles"
java -javaagent:./beacon-javaagent.jar -jar app.jar

Confirm that .jfr files appear in profiles/. Plan disk retention and validate overhead under application load before enabling profiling in production.

Optional memory events¶

export OTEL_PROFILING_MEMORY_ENABLED=true

This applies memory-focused JFR settings on top of the standard profile template.

Configuration reference¶

Environment-variable names are case-sensitive. Duration values accept a number followed by ns, us, ms, s, m, h, or d.

Environment variable	Type / accepted values	Default	Description
`OTEL_PROFILING_ENABLED`	Boolean	`false`	Enables the JFR profiler.
`OTEL_PROFILING_INTERVAL`	Positive duration	`1m`	Time between JFR snapshots.
`OTEL_PROFILING_STARTUP_DELAY`	Non-negative duration	`0s`	Delay before profiling starts.
`OTEL_PROFILING_MAX_AGE`	Positive duration	`5m`	Maximum age retained in the active JFR recording.
`OTEL_PROFILING_STACK_DEPTH`	Positive integer	`64`	Maximum recorded stack depth.
`OTEL_PROFILING_MAX_SIZE`	Non-negative integer, bytes	`0`	Maximum active JFR recording size; `0` keeps the JFR default.
`OTEL_PROFILING_TEMP_DIR`	Directory path	Unset	Directory for temporary JFR data; unset uses the runtime temporary directory behavior.
`OTEL_PROFILING_MEMORY_ENABLED`	Boolean	`false`	Enables the memory-focused JFR settings.
`OTEL_PROFILING_MEMORY_ALLOCATION_SAMPLING`	Boolean	Unset	Overrides JFR allocation sampling when set.
`OTEL_PROFILING_MEMORY_OLD_OBJECT_SAMPLING`	Boolean	Unset	Overrides JFR old-object sampling when set.
`OTEL_PROFILING_EXPORTER`	`none`, `file`, `datakit`	`none`	Selects no export, local JFR files, or the compatibility HTTP multipart exporter.
`OTEL_PROFILING_ENDPOINT`	HTTP(S) URL	`http://localhost:9529/profiling/v1/input`	Upload endpoint used by the `datakit` exporter.
`OTEL_PROFILING_DATAKIT_TIMEOUT`	Positive duration	`10s`	HTTP upload timeout used by the compatibility exporter.
`OTEL_PROFILING_EXPERIMENTAL_FILE_EXPORT_PATH`	Directory path	`${java.io.tmpdir}/otel-profiles`	Output directory used by the `file` exporter.

The datakit value and timeout variable are compatibility identifiers required by the current Java agent.

Security¶

The same Agent can export opt-in security findings and a runtime SBOM through OpenTelemetry Logs. See the Java Security guide.

Verify¶

Send a request through a supported framework or library, then open APM > Traces in Guance and filter by the configured service name. See Common configuration for verification steps and Troubleshooting if no data appears.