Use APM Tracer in Helidon

To use APM Tracer with Helidon, do the following:

Add the APM Tracer to Maven project. For details, see Add APM Tracer to Maven Project.

Check the Helidon version and add its corresponding dependency.

For Helidon 2, add the following dependency:

<dependency>
    <groupId>com.oracle.apm.agent.java</groupId>
    <artifactId>apm-java-agent-helidon</artifactId>
    <version>[1.0.1389,)</version>
</dependency>

For Helidon 3 SE, add the following dependency:

<dependency>
    <groupId>io.helidon.tracing</groupId>
    <artifactId>helidon-tracing-opentracing</artifactId>
</dependency>         
<dependency>
    <groupId>com.oracle.apm.agent.java</groupId>
    <artifactId>apm-java-agent-helidon3</artifactId>
    <version>[1.8.3326,)</version>
</dependency>

For Helidon 3 MP, add the following dependency:

<dependency>
    <groupId>io.helidon.tracing</groupId>
    <artifactId>helidon-tracing-opentracing</artifactId>
</dependency>         
<dependency> 
    <groupId>io.helidon.microprofile.tracing</groupId> 
    <artifactId>helidon-microprofile-tracing</artifactId> 
</dependency>
<dependency>
    <groupId>com.oracle.apm.agent.java</groupId>
    <artifactId>apm-java-agent-helidon3</artifactId>
    <version>[1.8.3326,)</version>
</dependency>

For Helidon 4 SE, add the following dependency:

<dependency>
    <groupId>io.helidon.tracing</groupId>
    <artifactId>helidon-tracing-opentracing</artifactId>
</dependency>
<dependency>
    <groupId>io.helidon.tracing.providers</groupId>
    <artifactId>helidon-tracing-providers-opentracing</artifactId>
</dependency>        
<dependency>
    <groupId>com.oracle.apm.agent.java</groupId>
    <artifactId>apm-java-agent-helidon4</artifactId>
    <version>[1.15.0.516,)</version>
</dependency>

Note

For Helidon 4 MP, the Opentracing support is deprecated. If you need to configure Opentelemetry support, see Opentelemetry Support for Helidon 4.

Configuration for Helidon.

APM Tracer uses the following properties in Helidon configuration file:

Property	Default	Required	Description
name		No	Name of the tracer. This property cannot be null.
service		Yes	Name of the service. This property cannot be null.
private-data-key		Yes	APM data upload key required for Oracle APM service cloud communication.
data-upload-endpoint		Yes	APM data upload endpoint required for Oracle APM service cloud communication.
daemon-channel		No	APM Daemon channel is a socket connection between Tracer and Daemon. Format of this property value is <host>:<port>. When Daemon is started with this property set, Daemon accept socket connection and listen data on this specified channel. When Tracer is started with this set, data upload endpoint is ignored, and data is only sent to Daemon using this socket channel.
collect-metrics	true	No	Collects server metrics and report to OCI APM service cloud. Default is true. User can access all collected server metrics from OCI Telemetry.
collect-resources	true	No	Collects server resources and report to OCI APM service cloud. All collected resources are used as dimension for data query.
log-directory	apm-tracer-log in JVM working directory	No	Full path of log directory where all APM Tracer logs are written to. If this is not set then the default log directory `(apm-tracer-log`) is created in the working directory of JVM.
tags		No	Static tags to be included in all tracing spans.
properties		No	Additional APM tracer properties. This allows properties be set programmatically at APM Tracer startup time. Properties are ignored if either key or value is null.

Examples:

Helidon SE: You need to specify it in YAML format. The default name is application.yaml. See the following example:

tracing:
    service: "helidon-http"
    data-upload-endpoint: <data upload endpoint of your OCI domain>
    private-data-key: <privatedata key of your OCI domain>
    collect-metrics: true
    collect-resources: true
    log-directory: "/user/apm/log"
    tags:
        tag1: true
        tag2: 1234
        tag3: "hello"
    properties:
        com.oracle.apm.agent.logging.level: DEBUG
        com.oracle.apm.agent.key1: value123

The above uses the preferred format for the properties section. The following format is also supported:

tracing:
    ...
    ...
    ...
    properties:
        - key: com.oracle.apm.agent.logging.level
          value: DEBUG
        - key: com.oracle.apm.agent.key1
          value: value123

Helidon MP: You need to specify it in the PROPERTIES (key=value) format. Default name is microprofile-config.properties. See the following example:

tracing.service=my-helidon-service
tracing.data-upload-endpoint=<data upload endpoint of your OCI domain>
tracing.private-data-key=<private data key of your OCI domain>
tracing.collect-metrics=true
tracing.collect-resources=true
tracing.log-directory=/user/apm/log
tracing.tags.tag1=true
tracing.tags.tag2=1234
tracing.tags.tag3=hello
tracing.properties.com.oracle.apm.agent.data.upload.file=stdout
tracing.properties.com.oracle.apm.agent.json.pretty=true

The above is the preferred format for the properties section, but it also supports the following format:

tracing.service=my-helidon-service
...
...
...
tracing.properties.0.key=com.oracle.apm.agent.data.upload.file
tracing.properties.0.value=stdout
tracing.properties.1.key=com.oracle.apm.agent.json.pretty
tracing.properties.1.value=true

If you have Helidon MP, skip this step.
Start and configure tracer of Helidon SE, such as the application Main.java, by doing the following:
```
Tracer tracer = TracerBuilder.create(Config.create()).build();
```
When you use the above code, you are ensuring the TracerBuilder parameter is being added in the Helidon project. You create a config object and use the same config object to create a TracerBuilder in Main.java.

The TracerBuilder is starting the APM Tracer as an opentracing tracer and it's being registered in opentracing GlobalTracer.

Opentelemetry Support for Helidon 4

For Helidon 4 applications, do the following:

Copy Opentelemetry artifacts to APM Agent/Tracer
Copy the Opentelemetry artifacts bundled by the Helidon 4 application (located under target/libs) to the APM Agent installed location by following the steps described in Configure APM Java Agent to Work with OpenTelemetry.

Note

The opentelemetry-exporter-otlp and opentelemetry-exporter-otlp-common artifacts are not present in the target/libs. Ensure to copy them separately to the APM Agent installed location.
Configure Opentelemetry hybrid mode
For instructions, see Configure APM Java Agent Hybrid Mode.

Oracle Cloud Infrastructure Documentation