構成ベースの Java トレース SDK

構成ベースの SDK は、アプリケーションの変更に対して不安定です。 クラスまたはメソッドの名前を変更すると、突然構成が一致しなくなり、トレース・データが失われることがあります。 可能な限り、 Java Trace SDK を使用することをお勧めします。この SDK はコードの変更に対する耐性がはるかに高く、目的を達成するための機能も豊富に備えています。

設定ベースの Java トレースSDKを使用するには、 「 Java トレースSDKの有効化」 の手順に従って、 Java トレースSDKを有効にする必要があります。

注:

• 設定ベースの Java Trace SDKの設定変更は、 Instana エージェントによって自動的に反映されます。 変更された構成を使用するには、既にインスツルメントされているアプリケーションを再始動する必要があります。

• 設定ベースの Java トレースSDKは、 Java1.2.351 トレースセンサーのバージョン以降で利用可能です。

以下のリストは、構成の一般的なフォーマットを示しています。

# Java Tracing
com.instana.plugin.javatrace:
  instrumentation:
    sdk:
      targets:
        - match:
            type: 'interface'|'class'|'baseclass'
            name: '<type-name>'
            method: '<method-name>'
            [argumentTypes:
              - '<argument-type-index0>'
              - '<argument-type-indexn>']
            [returnType: '<return-type-name>']
          span:
            name: '<span-name>'
            [type: '<span-type>']
            [stackDepth: <depth>]
            [tags:
              - kind: 'argument'
                name: 'name'
                index: 0
              - kind: 'return'
                name: 'name'
              - kind: 'constant'
                name: 'name'
                value: 'constant-value']
 

targets キー内に複数のターゲットを定義できます。各ターゲットでは、作成するスパンを 1 つ指定します。 1 つの target の match オブジェクトは、インスツルメンテーションの適用先のメソッドを指定します。 span オブジェクトは、スパンの作成方法を指定します。これには、スパンの名前 (call.name フィルターの無制限分析などで使用される) および設定するタグが含まれます。

Throwableがインスツルメンテーションされたメソッドの外部に伝搬されると、スパンには自動的にエラーのマークが付けられ、Throwable#getMessage()の値がエラー・メッセージとして設定されます。このエラー・メッセージは、call.error.messageタグを使用して 無制限分析 で検索できます。

1. 設定が正常に解析されたことを確認してください。 エージェントのログで、次のようなメッセージを探してください：

   Parsed configuration file /instana-agent/etc/instana/configuration.yaml 

2. 計測設定が適用されたことを確認してください。 解析後、エージェントはSDKの計測処理を実行したことを示すメッセージをログに記録します：

   ... Spent XX ms and XXX KiB of Metaspace for instrumentation [sdk] ... 

3. SDKのスパン・トレース・ログを有効にし、確認します。 スパンが実際に作成されていることを確認するには、次の YAML を追加してトレースログを有効にしてください：

   com.instana.plugin.javatrace: instrumentation: log: type: trace file: /tmp/trace.log 

インストルメンテーションが有効になり、インストルメンテーションが適用されたコードが実行されると、SDKスパンが出力されるはずです。 トレースログのフォーマット例：

 -|EN|052d6bf37f16034c7:0:52d6bf37f16034c7|sdk:sdk.quarkus-hello|*com.instana.agent.instrumentation.sdk.SdkPlugin:start:789:SdkPlugin.java
    

以下のスニペットは、バッチ・ジョブを処理するアプリケーションをトレースする方法の構成例を示しています。

com.instana.plugin.javatrace:
  instrumentation:
    sdk:
      targets:
        - match:
            type: class
            name: com.instana.java.sdk.BatchApplication
            method: processBatch
          span:
            name: Job
            type: ENTRY
            stackDepth: 2
            tags:
              - kind: constant
                name: endpoint
                value: BatchJob
              - kind: argument
                name: batch.job
                index: 0
        - match:
            type: class
            name: com.instana.java.sdk.BatchApplication
            method: updateDatabase
          span:
            name: DatabaseCall
            type: EXIT
            stackDepth: 2
            tags:
              - kind: constant
                name: db.connection_string
                value: jdbc:mysql://127.0.0.1:3306/jobs
              - kind: argument
                name: db.statement
                index: 0
 

最初に、クラス com.instana.java.sdk.BatchApplication 内のメソッド processBatch がインスツルメントされて、Job という名前のエントリー・スパン、定数値 BatchJob を持つ注釈 endpoint、および値として最初の引数を持つ注釈 batch.job が作成されます。

さらに、バッチ処理中の発信 DB 呼び出し (つまり、同じクラス内のメソッド updateDatabase の呼び出し) で、DatabaseCall という名前のエグジット・スパン、定数値 jdbc:mysql://127.0.0.1:3306/jobs を持つ注釈 db.connection_string、およびメソッド呼び出しの最初の引数を持つ注釈db.statement が作成されます。

processBatch を使用して新規バッチを処理すると、新しいトレースが開始され、updateDatabase による後続の DB 更新がその中に子スパンとしてリストされます。 無制限分析と同様、すべての Instana 機能は、Instana AutoTrace で作成されたトレースに同じように使用できます。

構成ベースの Java トレース SDK には、以下の制約事項が適用されます。

• コンストラクターのインスツルメントはサポートされていません。
• あるメソッドでスパンを開始して別のメソッドでそれを閉じることはサポートされていません。このため、構成ベースの SDK には @Span.Start 注釈および @Span.End 注釈に相当するものはありません。
• tag を明示的に作成せずにすべての引数または戻り値をキャプチャーする処理はサポートされていません。
• 重要でない引数やそれ以外のすべての引数に対して、引数リスト内でプレースホルダーを指定することはサポートされていません。引数に基づくマッチングは厳密に実行されます。
• クラスやメソッドの名前パターンの指定はサポートされていません。
• スパンを作成する前にトレース・コンテキストを復元することはサポートされていません。つまり、構成ベースの SDK には、SpanSupport.inheritNext() に相当する機能はありません。
• 設定ベースのSDKは、JDKクラスのインストルメンテーションをサポートしていません。