HelidonでのAPMトレーサの使用

HelidonでAPMトレーサを使用するには、次を行います:

APMトレーサをMavenプロジェクトに追加します。詳細は、MavenプロジェクトへのAPMトレーサの追加を参照してください。

Helidonバージョンを確認し、対応する依存性を追加します。

Helidon 2に対して、次の依存性を追加します:

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

Helidon 3 SEに対して、次の依存性を追加します:

<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>

Helidon 3 MPの場合は、次の依存性を追加します:

<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>

Helidon 4 SEの場合は、次の依存関係を追加します:

<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>

ノート

Helidon 4 MPを含むHelidon 4については、Helidon 4のOpentelemetryサポートを参照してください。

Helidonの構成。

APMトレーサは、Helidon構成ファイルで次のプロパティを使用します:

プロパティ	デフォルト	必須	説明
name		×	トレーサの名前。このプロパティはnullにできません。
service		○	サービスの名前。このプロパティはnullにできません。
private-data-key		○	Oracle APMサービス・クラウド通信に必要なAPMデータ・アップロード・キー。
data-upload-endpoint		○	Oracle APMサービス・クラウド通信に必要なAPMデータ・アップロード・エンドポイント。
daemon-channel		×	APMデーモン・チャネルは、トレーサとデーモン間のソケット接続です。このプロパティ値のフォーマットは、<host>:<port>です。このプロパティが設定された状態でデーモンが起動されると、デーモンはソケット接続を受け入れ、指定されたこのチャネルでデータをリスニングします。これが設定された状態でトレーサが起動されると、データ・アップロード・エンドポイントは無視されます。データはこのソケット・チャネルを使用してのみデーモンに送信されます。
collect-metrics	true	×	サーバー・メトリックを収集し、OCI APMサービス・クラウドにレポートします。デフォルトはtrueです。ユーザーは、OCI Telemetryからすべての収集済サーバー・メトリックにアクセスできます。
collect-resources	true	×	サーバー・リソースを収集し、OCI APMサービス・クラウドにレポートします。収集されたすべてのリソースは、データ問合せのディメンションとして使用されます。
log-directory	JVM作業ディレクトリ内のapm-tracer-log	×	すべてのAPMトレーサ・ログが書き込まれるログ・ディレクトリのフル・パス。これが設定されていない場合、デフォルトのログ・ディレクトリ`(apm-tracer-log)`がJVMの作業ディレクトリ内に作成されます。
tags		×	すべてのトレース・スパンに含める静的タグ。
properties		×	追加のAPMトレーサ・プロパティ。これにより、APMトレーサの起動時にプログラムによってプロパティを設定できます。キーまたは値がnullの場合、プロパティは無視されます。

例:

Helidon SE: YAML形式で指定する必要があります。デフォルトの名前はapplication.yamlです。次の例を参照してください:

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

前述の書式では、propertiesセクションに優先書式を使用します。また、次の形式もサポートされています。

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

Helidon MP: PROPERTIES (key= value)形式で指定する必要があります。デフォルト名はmicroprofile-config.properties.です次の例を参照してください:

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

前述の書式はpropertiesセクションで推奨されますが、次の書式もサポートされています。

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 MPをお持ちの場合は、この手順をスキップします。
アプリケーションMain.javaなどのHelidon SEのトレーサを起動および構成するには、次の手順を実行します。
```
Tracer tracer = TracerBuilder.create(Config.create()).build();
```
上のコードを使用すると、確実にHelidonプロジェクトにTracerBuilderパラメータが追加されます。構成オブジェクトを作成し、同じ構成オブジェクトを使用して、TracerBuilderをMain.java内に作成します。

TracerBuilderは、APMトレーサをオープントレース・トレーサとして起動しており、オープントレースGlobalTracerに登録されています。

Helidon 4のOpentelemetryサポート

Helidon 4アプリケーションの場合は、「OpenTelemetryと連携するためのAPM Javaエージェントの構成」の「APMエージェントでのOpenTelemetryの有効化」セクションに記載されている手順に従います。

ノート

Opentracingのサポートは、Helidon 4 MPでは非推奨です。Opentelemetryサポートを構成する必要がある場合は、OpenTelemetryと連携するためのAPM Javaエージェントの構成のAPMエージェントでのOpenTelemetryの有効化を参照してください。

Oracle Cloud Infrastructureドキュメント

HelidonでのAPMトレーサの使用