Use APM Tracer in Helidon

To use APM Tracer with Helidon, do the following:

  1. Add the APM Tracer to Maven project. For details, see Add APM Tracer to Maven Project.
  2. 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.

  3. 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
  4. 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.