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

構成ベースの SDK は、アプリケーションの変更に対して不安定です。 クラス名やメソッド名を変更すると、突然コンフィギュレーションが一致しなくなり、トレースデータが失われることがあります。 可能な限り、コード変更に対する耐性がはるかに高く、目標達成に役立つ機能がより多く備わった Java Trace SDK を使用することをお勧めします。

設定ベースのJava Trace SDKを使用するには、 Java Trace SDKの有効化で説明するように、Java Trace SDKを有効にする必要があります。

注:

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

• 設定ベースの Java Trace SDK は、Java Trace Sensor バージョン 1.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() に相当する機能はありません。