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:
The above is the preferred format for thetracing.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
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
- Helidon SE: You need to specify it in YAML format. The default name
is
- 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
Theopentelemetry-exporter-otlp
andopentelemetry-exporter-otlp-common
artifacts are not present in thetarget/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.