Java センサーの設定

Instana エージェントをインストールすると、 Java センサーとトレーサーが自動的に設定されます。 追加の設定を一切行わなくても、メトリクスと分散トレーシングを提供します。 ただし、以下のセクションで説明するように、設定をカスタマイズすることは可能です。

JVM の監視に関する詳細については、 「 Java 仮想マシンの監視 ( JVM )」 を参照してください。

アプリケーション名のカスタマイズ

このアプリケーション名は、 Instana 内の「 Java 」アプリケーションを識別するものです。 アプリケーション名は、自動設定と手動設定の2つの方法で設定できます。

自動命名

通常、 Instana は以下の情報源からアプリケーション名を自動的に取得します:

  • アプリケーション .jar ファイル:この .jar ファイル内では、以下の標準属性が利用可能です META-INF/Manifest.MF

    Implementation-Title=Demo App
    Implementation-Version=1.0.0
     

    ビルドツールを使用すれば、アプリケーションをビルドする際に両方の属性を設定できます。 詳細については、『 Oracle 』のドキュメントを参照してください。

  • コマンドライン:名前が利用できない場合、 Java ツールがJVMを表示するのと同じ方法で、コマンドラインを使用して名前を検索します。

  • システムプロパティ:ファイル .jar から名前が取得できない場合、 Instana は、Tomcatコンテナなど -Dcatalina.home 、さまざまなシステムプロパティを調べます。

手動での命名

アプリケーション名を変更するには、次のいずれかの方法を使用してください:

  • JVM の初期化時に名前を設定する:アプリケーション名を明示的に設定するには、 JVM を起動する際に `name` -Dcom.instana.agent.jvm.name="My Custom Name" 属性を指定してください。

  • 既存のシステムプロパティを使用する:エージェントが既存のカスタムシステムプロパティを使用するように設定するには、エージェント configuration.yaml ファイルにプロパティのリストを指定します。 現存する最初の物件は、 JVM と名付けられています:

com.instana.plugin.java:
  name-properties:
    - 'acme.app'
    - 'DEPLOYMENT'
 

ポーリング間隔のカスタマイズ

エージェントの ` configuration.yaml ` ファイルにある `poll_rate` パラメータを使用することで、 Instana がデータやメトリクスを収集するために JVM をポーリングする頻度を設定できます。

ポーリング間隔の設定

com.instana.plugin.java:
   poll_rate: 1 # Value is in seconds. Default value is 1 second.
 

JMX のカスタムメトリクスの設定

監視する JMX のメトリクスを設定するには、次の例に示す configuration.yaml ようにagentファイルを編集します

com.instana.plugin.java:
  jmx:
    # JMX is NOT hot-reloaded and needs to be set before a JVM is discovered.
    # Supported attribute types are Number and Boolean
    # delta calculation is only supported for Number
    - object_name: 'java.lang:type=Compilation'
      metrics:
        - attributes: 'TotalCompilationTime'
          type: 'delta' # delta will report the change to the previous second
    - object_name: 'java.lang:type=ClassLoading'
      metrics:
        - attributes: 'LoadedClassCount'
          type: 'absolute' # absolute will report the value as-is
 

前の例では、以下の種類のメトリクスが指定されています:

  • delta: カウンターなど、時間の経過とともに値が増加し、その相対的な変化が注目される場合に使用されます。
  • absolute: メトリクスにアクセスするたびに実際の値を表示するために使用されます。

指定された属性は、 Number (または や などのそのサブ Doubleクラスの Integer いずれか)であるか、数値 String を表す でなければなりません。

ワイルドカードパターンを使用した JMX メトリクスの設定

には、 Java ObjectName APIobject_name のドキュメントで指定されているワイルドカードパターンが含まれている場合があります。

次の例は、ワイルドカードパターンを使用した設定を示しています:

com.instana.plugin.java:
  jmx:
    - object_name: 'kafka.*:type=*-metrics,client-id=*,*'
      metrics:
        - attributes: 'incoming-byte-rate'
          type: 'absolute'
        - attributes: 'incoming-byte-total'
          type: 'absolute'
        - attributes: 'outgoing-byte-rate'
          type: 'absolute'
        - attributes: 'outgoing-byte-total'
          type: 'absolute'
 

JMX のカスタムメトリクスの表示

JVM のダッシュボードでは、「 JMX 」のメトリクスが、「 JMX のカスタムメトリクス 」の下に表示されます。

Java のトレース計測の設定

Instana ホストエージェントをインストールすると、デフォルトの(SDK非対応の) Java トレース計測機能はデフォルトで有効になりますが、 OpenTracing 計測機能および Java トレースSDK は有効になりません。

Java のトレース計測機能を無効にする

デフォルトでは、すべての Java プロセスに対して Java のトレース機能が無効になっています。 すべてのプロセスに対して、または特定のプロセスに対して無効にすることができます。

すべての Java プロセスで無効にする

すべてのプロセスに対して、デフォルトの Java トレース機能無効化するには、エージェント configuration.yaml ファイルを次のように設定してください:

com.instana.plugin.javatrace:
   instrumentation:
     enabled: false
 
注:Java アプリケーションを再起動し、計測が無効になっていることを確認してください。

Java のトレース機能を手動で有効にするには、 を に enabled: false 設定してください true

単一の Java プロセスに対して無効にする

Java デフォルトでは、すべての Java プロセスでトレース機能が無効になっています。

Java プロセスのトレース機能無効化には、次のいずれかのオプションを使用してください:

  • Java 仮想マシン( JVM )の引数として、 -Dinstana.java.tracer.enabled=false システムプロパティを追加します。
  • **INSTANA_JAVA_TRACER_ENABLED=false **システム環境変数を追加します。
注: システムプロパティとシステム環境変数の両方が指定されている場合、システムプロパティが優先されます。

計測プラグインの無効化

特定の計測プラグインを無効にすることで、オーバーヘッドを軽減したり、特定の技術をトレース対象から除外したりすることができます。 詳細については、 「計測プラグインの無効化」 を参照してください。

OpenTracing の計測機能を有効にする

「 Java Trace」の OpenTracing による計測を有効にするには、エージェント configuration.yaml ファイルを次のように設定してください:

com.instana.plugin.javatrace:
   instrumentation:
     opentracing: true
 

OpenTracing の計測機能を無効にするには、 を opentracing: false に設定してください false

Java トレースSDKの有効化

Java Trace SDK を有効にするには、SDK アノテーションのスキャン対象となるパッケージのリストを以下のように指定して、エージェント configuration.yaml 設定ファイルを構成してください。 デフォルトでは、SDK アノテーションについてスキャンされるパッケージはありません。

com.instana.plugin.javatrace:
   instrumentation:
     sdk:
       packages:
         - 'com.instana.backend'
         - 'com.instana.frontend'
 

Java Trace SDK を無効にするには、セクション packages 全体をコメントアウトしてください。

中間スパンを捕捉する

Instana Kafka Streamsおよび WebMethods Integration Serverにおいて、 Java アプリケーションの中間スパンをキャプチャできます。 ただし、この機能はデフォルトでは無効になっています。

注: 中間スパンを有効にすると、スパンの数が大幅に増加し、トレースデータの量が膨大になり、アプリケーションのパフォーマンスに影響を与える可能性があります。

この機能を有効にするには、以下のセクションを参照してください:

Kafka ストリームの中間スパンを有効にする

Kafka Streams では、すべてのストリーム・オペレーターが中間スパンとしてキャプチャーされます。 この機能は、大量のデータが流入する場合に、アプリケーションのパフォーマンスに影響を与えます。 実稼働環境ではこの機能を使用 しないでください

Kafka ストリームの中間スパンをキャプチャできるようにするには、 エージェント configuration.yaml ファイルに以下の行を追加してください:

com.instana.plugin.javatrace:
   instrumentation:
    plugins:
     Kafka011StreamIntermediate: true
 

WebMethods Integration Server での内部サービス呼び出しを有効にする

WebMethods Integration Server では、すべてのサービス呼び出しを中間スパンとしてキャプチャする機能を有効にできます。 しかし、サーバーが重いワークロードを処理する場合、この機能はアプリケーションのパフォーマンスに影響を与える可能性がある。

WebMethods Integration Server で内部サービス呼び出しのキャプチャを有効にするには、 エージェント設定ファイル ` YAML ` に以下の行を追加してください:

com.instana.plugin.javatrace:
   instrumentation:
     plugins:
       WebmethodsIntermediate: true
 

webMethods Integration サーバーで内部サービス呼び出しがキャプチャされる際に、中間スパンが生成されることによるパフォーマンスの低下を防ぐため、内部サービス呼び出しのキャプチャを有効にする設定に加えて、 エージェントの設定ファイル( YAML ) に以下の行を追加してください

com.instana.plugin.javatrace:
   instrumentation:
     enableIntermediateSpanOpt: true
     plugins:
       WebmethodsIntermediate: true
       enableIntermediateSpanOpt: true
注: 設定を追加した後、 webMethods Integration サーバーを再起動してください。

スタックトレースの取得を無効にする

Java Tracerは、終了スパンおよび中間スパンのスタックトレースをキャプチャします。 ただし、エントリスパンに対するスタックトレースは、デフォルトでは無効になっています。 アプリケーションのスタックが深かったり、1つのリクエストで複数のスパンが発生したりする場合、スタックトレースの取得はアプリケーションのパフォーマンスに影響を与える可能性があります。 パフォーマンスの問題が発生している場合は、スタックトレースを無効にすることでパフォーマンスを最適化できます。

スタックトレースの取得を無効にするには、 JVM を次のプロパティを指定して起動してください:

-Dinstana.tracing.stack.exit=-1 -Dinstana.tracing.stack.log=-1
 

次の例は、スタックトレースの取得を無効にする方法を示しています:

$ java -Dinstana.tracing.stack.exit=-1 -Dinstana.tracing.stack.log=-1 -jar application.jar
 
注: この設定では、中間スパンを無効にすることはできません。

スパン相関の設定

デフォルトでは、コンシューマーがメッセージを取得する際、受信操作全体を表す単一のスパンが生成され、すべてのメッセージが1つのスパンにまとめられます。 トレースの粒度を高めるために、メッセージ単位での相関分析を有効にする設定オプションが用意されています。

可観測性の向上のための Kafka スパン相関の設定

Kafka のユーザーがメッセージを取得する際、 Instana は通常、ポーリング操作全体を表す単一のspanを生成します。 つまり、1回のポーリングで取得されたすべてのメッセージは単一のPOLLスパンにまとめられるため、個々のメッセージがどのように処理されているかを把握しにくくなる可能性があります。

トレースの粒度を高めるため、 Instana には、メッセージがバッチ処理で消費される場合でも、個々の送信および受信操作ごとに相関付けを有効にする設定オプションが用意されています。 これにより、メッセージごとに個別のスパンを作成できるようになり、メッセージ単位の処理についてより詳細な分析が可能になります。

この instana.kafka.correlate.send.receive フラグを有効にすると、レコードが個別に処理される際に実行される操作を確認できるようになります。

そのフラグが役立つ場合

個別のレコード処理:

@KafkaListener(topics = "topicName", containerFactory = "kafkaListenerContainerFactory")
public void listen(ConsumerRecord<?, ?> record)
{
    // Process single record
    // DB operations, Kafka sends, etc.
}

この場合、このフラグを有効にすると、個々のレコードの処理中に実行されるデータベースへの書き込み操作や Kafka への送信操作を確認できるようになります。

このフラグの使用が推奨されない場合

一括操作によるバッチ処理:

@KafkaListener(topics = "topicName")
public void receive(List<ConsumerRecord<?, ?>> consumerRecords) {
    // Direct bulk operations without iterating through individual records
}

レコードがバッチ処理として消費され、一括操作(データベースへの一括書き込みなど)が直接実行される場合、このフラグは有用ではなく、POLLスパン内の下流の呼び出しが隠れてしまう可能性があります。

バッチ処理に関する推奨事項

バッチ処理のユースケースでは、アプリケーションの起動時に特定の JVM を除外するようにシステムプロパティを設定することで、このフラグを無効にできます。 この設定により、下流の呼び出しが引き続き可視化されます。

java -jar -Dcom.instana.kafka.correlate.send.receive=false app.jar

混合処理モデルに関する重要な考慮事項

アプリケーションで、 Kafka のバッチ・リスナー(バッチ処理)と標準の Kafka リスナー(単一レコード処理)の両方を使用している場合は、この instana.kafka.correlate.send.receive フラグに関する以下の制限事項に注意してください。

フラグが無効になっている場合、単一レコードの Kafka リスナーは、処理を個別のPOLLスパンとして表示しなくなります。 その代わりに、アプリケーションではレコードを個別に処理しているにもかかわらず、すべてのダウンストリーム呼び出しがそのスパン下にグループ化された単一のPOLLスパンとして表示されます。

注: このフラグでは、両方の処理モデルを同時に完全にサポートすることはできないため、バッチ処理と単一レコード処理の両方の Kafka リスナーを使用するアプリケーションでは、単一レコード処理におけるメッセージレベルの可視性を妥協する必要がある場合があります。
注:Kafka のスパン相関は、デフォルトで無効になっています(値はfalseに設定されています)。

Kafka のスパン相関を有効にするには、以下のいずれかの設定を使用してください:

  • エージェントの設定:エージェント configuration.yaml 設定ファイルを構成します。
    com.instana.tracing:  
      kafka:  
        correlateEverySendReceive: true # possible values: true or false
    注:

    エージェント configuration.yaml ファイルを編集した後、エージェントまたはアプリケーションを再起動してください。

  • 環境変数の設定:以下の例のように環境変数を設定してください:
    INSTANA_KAFKA_CORRELATE_SEND_RECEIVE=true # possible values: true or false
  • システムプロパティの設定: JVM を起動する際に、以下のプロパティを設定してください:
    -Dcom.instana.kafka.correlate.send.receive=true # possible values: true or false 

以下の画像は、この設定を有効にした場合と無効にした場合で、スパン相関がどのように動作するかを示しています。

図 1. 設定が無効な場合のスパン相関
設定が無効な場合のスパン相関

図 2. 構成を有効にしたスパン相関
構成を有効にしたスパン相関

Instana で「 Kafka 」のスパン相関機能を完全に無効にするには、以下のいずれかの設定を使用してください:

  • エージェント構成:
    com.instana.tracing: 
      kafka: 
        correlateEverySendReceive: false 
  • 環境変数の設定:環境変数を設定します。
    INSTANA_KAFKA_CORRELATE_SEND_RECEIVE=false
  • システムプロパティの設定: JVM を起動する際に -Dcom.instana.kafka.correlate.send.receive=false 、このオプションを指定してください。

不要なデータの取り込みを防ぐため、この instana.kafka.correlate.send.receive フラグはデフォルトで無効になっています。

トレースの相関設定

Instana IBM Db2、 WebLogic、 T3、 IBM MQ、および Kafka などのテクノロジーでは、トレースに Java Tracerを使用しているため、トレースの相関関係機能はデフォルトで無効になっています。 これらのテクノロジーでトレースの相関関係を有効にするには、以下のセクションを参照してください:

IBM Db2 のトレース相関の設定

IBM Db2 のトレース相関を設定するには、以下の設定オプションのいずれかを使用してください:

  • エージェントの設定:エージェント configuration.yaml 設定ファイルを次のように設定してください:

      com.instana.tracing:
        db2:
          trace-correlation: true
          db2CorrelationMode: dont-override
          db2CorrelationDelimiter: '|'
          db2CorrelationField: ClientHostname
     
  • 環境変数の設定:以下の環境変数を設定してください:

     INSTANA_DB2_TRACE_CORRELATION=true
     INSTANA_DB2_TRACE_CORRELATION_MODE=dont-override
     INSTANA_DB2_TRACE_CORRELATION_DELIMITER='|'
     INSTANA_DB2_TRACE_CORRELATION_FIELD=ClientHostname
     
  • システムプロパティの設定: JVM のインストルメンテーション設定で、以下のシステムプロパティを設定してください:

     -Djdbc.db2.correlation.enable=true
     -Djdbc.db2.correlation.mod=dont-override
     -Djdbc.db2.correlation.delimiter=|
     -Djdbc.db2.correlation.field=ClientHostname
     
注: デフォルトでは、相関(および TraceId その伝播 SpanId)は無効になっています。 伝播は、 Db2 のクライアント情報プロパティを使用して行われます。 相関フィールドは、デフォルトでフィールド ClientHostname 名を に設定します。 デフォルトの区切り文字は. です |。 相関モードが (デフォルト override )に設定されている場合、相関データは既存の値を上書きします。 ただし、この設定が「」になっていない override場合、相関データは既存の値に追加されます。

WebLogic の構成 T3 トレースの相関付け

エンタープライズ・ Java ・Bean(EJB)の呼び出しでは、 WebLogic および T3 との相関関係がサポートされています。

WebLogics T3 のトレース相関を設定するには、以下の設定オプションのいずれかを使用してください:

  • エージェントの設定:エージェント configuration.yaml 設定ファイルを次のように設定してください:

      # General Tracing Settings
      com.instana.tracing:
        weblogic:
          trace-correlation: true
     
  • 環境変数の設定:以下の環境変数を設定してください:

    INSTANA_WEBLOGIC_EJB_TRACE_CORRELATION=true
     
  • システムプロパティの設定: JVM のインストルメンテーション設定で、以下のシステムプロパティを設定してください:

    -Dcom.instana.weblogic.ejb.trace.correlation=true
     

    この設定は、 T3 間の通信が WebLogic サーバー間で行われる場合にのみ機能します。 ただし、 WebLogic クライアントを WebLogic サーバー以外で使用する場合、相関分析は行えません。

  • WeblogicRpcIntermediate: WebLogic の RPC コールトレースにおいて、リモートプロシージャコール( RPC )の中間コールスパンを有効にするには、エージェント configuration.yaml ファイルを次のように設定する必要があります。 「 RPC 」の中間コールスパンを有効にすると、同じ WebLogic Server内の RPC コールを確認できるようになります。
     com.instana.plugin.javatrace:
       instrumentation:
         enableIntermediateSpanOpt: true
         plugins:
           WeblogicRpcIntermediate: true

    WeblogicRpcIntermediate 不要なデータの取り込みを防ぐため、デフォルトでは無効になっています。

    システムが中間スパンを作成する際に発生するパフォーマンス低下の問題を回避するには、 enableIntermediateSpanOptを有効にすることができます。

IBM MQ のトレース相関機能を有効にする

一部の IBM MQ コンシューマークライアントでは、 IBM MQ メッセージに余分なヘッダーデータが含まれていると、メッセージ処理エラーやメッセージの拒否が発生する可能性があります。 したがって、 IBM MQ Java アプリケーションでは、デフォルトで Instana トレースヘッダーの相関機能は有効になっていません。

本番環境で IBM MQ のトレース相関機能を有効にする前に、 本番環境でテストを行う必要があります。 トレースの相関関係を有効にした後、 IBM MQ クライアントアプリケーションでエラーが発生した場合は、以下の手順でトラブルシューティングを行ってください

  • アプリケーションを変更できる場合は、 Instana によって追加される IBM MQ ヘッダーデータを無視するように、アプリケーションを更新してください。 IBM MQ クライアントの設定変更に関するサポートが必要な場合は、 IBM MQ のサポートまでお問い合わせください。
  • アプリケーションを変更できない場合は、 IBM MQ のトレース相関機能を有効にしないでください。

IBM MQ でトレースの相関機能を有効にするには、次のいずれかの設定オプションを使用してください:

  • エージェントの設定:以下の例に示すように、エージェント configuration.yaml ファイルを編集してください:

    # General Tracing Settings
    com.instana.tracing:
      ibm-mq:
        trace-correlation: true
        ibmmq-optin-queues-regexp: '^QueueName.*'
     

    トレースの相関を有効にしたいキュー名をフィルタリングするために、正規表現 ibmmq-optin-queues-regexp の値を設定します。 正規表現値はオプションであり、欠落している場合、トレース相関はすべてのキューに適用されます。

    この構成は、以下のいずれかのシナリオで選出されます。

    • JVMが起動するとき
    • Java Tracerが更新されたとき
    • Instana エージェントが約15分間停止した後

    実行時にホット・リロードされません。 この機能は最適化されているため、エージェントを素早く再始動してもこの構成変更が反映されない可能性があります。 構成変更には、完全な再インスツルメンテーションが必要です。

  • システムプロパティの設定:あるいは、次の例に示すように、 IBM MQ クライアントを含むアプリケーションJVMでシステムプロパティを指定することもできます

    -Dinstana.ibm.mq.trace.correlation.enable=true -Dcom.instana.ibm.mq.trace.optin.queues="^QueueName.*"
     

IBM MQ センサーは、ユーザー・エクジット( IBM MQ 向けのサーバーサイド・トレーシング)を使用して、トレース機能も提供します。 IBM MQ センサーについて詳しくは、IBM MQ のモニターを参照してください。

Kafka のトレース相関ヘッダーの設定

Java Tracer で使用される Kafka トレース相関ヘッダーのヘッダー形式を有効にするには、次のいずれかの設定オプションを使用してください:

  • エージェントの設定:エージェント configuration.yaml 設定ファイルを構成します。 詳細については、「 Instana 」ホストエージェントを参照してください。

  • 環境変数の設定:以下の例のように環境変数を設定してください:

    INSTANA_KAFKA_HEADER_FORMAT= both # possible values: binary, both, string
     

    有効な値は、 string、、または binary です both

  • システムプロパティの設定: JVM を起動する際に、以下のプロパティを設定してください:

    -Dcom.instana.kafka.trace.header.format=binary # possible values: binary, both, string
     

Kafka のトレース相関機能を完全に無効にするには、以下の設定オプションのいずれかを使用してください:

  • エージェントの設定: Instana host-agent を参照してください。
  • 環境変数の設定:環境変数を設定しますが INSTANA_KAFKA_TRACE_CORRELATION=false、このオプションの使用は推奨されません。
  • システムプロパティの設定: JVM を起動する際に -Dcom.instana.kafka.trace.correlation=false 、このオプションを指定してください。

詳しくは、 Kafka ヘッダー・マイグレーションを参照してください。

スパンのバッチ処理の設定

スパン・バッチ処理とは、複数のスパンを結合し、それらを個別に送信するのではなく、バッチ単位でエージェントに送信する機能です。 スパンバッチ処理が有効になっている場合、名前、タイプ、および継続時間(10ミリ秒未満)が同じスパンは集約されます。 通常、データベースへの呼び出しなど、高頻度かつ短時間の処理はまとめて実行されます。

次の図は、spanのバッチ処理の実装を示しています。 ダッシュボードには5つのサブコールが表示されており、そのうち3つはバッチ処理され、「コール」セクションに一覧表示されています。

図 3. スパン・バッチ処理
スパン・バッチ処理
注: スパンバッチ処理はデフォルトで有効になっています。 スパンバッチ処理を明示的に有効にするには、 パラメータ INSTANA_SPANBATCHING_ENABLED を に設定してください true

以下のアプリケーションでは、スパンバッチ処理が自動的に有効になります:Aerospike、Amazon s3、 Cassandra、Data Grid、 DynamoDB,、 Elasticsearch、FTP、 Google Cloud、Bigtable、 Google Cloud storage、HBase、 Hazelcast、 IMS、 JavaMail,、Kinesis、 LDAP、 Memcached、 MongoDB,、 Neo4j、および Redis。

Data Gridおよび JDBC については、特定のスパン結合戦略が採用されています。 詳細については、 「スパン・バッチ処理戦略」 を参照してください。

スパンバッチ処理を無効にする

スパンバッチ処理を無効にすると、送信される個々のスパンの数が増え、データ量が増加します。

スパンバッチ処理を無効にするには、以下の設定オプションのいずれかを使用してください:

  • エージェントの設定: エージェントの設定ファイルを次のように設定してください:

      com.instana.plugin.javatrace:
        instrumentation:
          spanBatchingEnabled: false
     
  • 環境変数の設定:環境変数を次のように設定してください:

    INSTANA_SPANBATCHING_ENABLED=false
     
  • システムプロパティの設定: JVM の計測対象環境において、システムプロパティを次のように設定してください:

    -DspanBatchingEnabled=false
     

WebLogic の RPC 中間スパンにおけるスパンバッチ処理を無効にする

中間スパンのバッチ処理を行うと、親スパンがマージされ、親子関係が切断されるため、子スパンが孤立した状態になります。 RPC の-intermediateスパンに対するバッチ処理を無効にすると、この問題は発生せず、トレース構造も正しく維持されます。 WebLogic RPC の中間スパンに対するスパンバッチ処理を無効にするには、以下の設定オプションのいずれかを使用してください:

  • エージェントの設定: エージェントの設定ファイル<agent_install_dir>/etc/instana/configuration.yaml)を次のように設定してください:

     com.instana.tracing:
       batching:
         disabled:
           - rpc-intermediate
  • 環境変数の設定:環境変数を次のように設定してください:

    INSTANA_TRACING_BATCHING_DISABLED=rpc-intermediate
注: 設定または環境変数を追加した後、WebLogic Serverを再起動してください。

Data Gridおよび JDBC のスパンに対するスパン・バッチ処理戦略

Data Gridや JDBC などのアプリケーションでは、スパン・バッチ処理に対して以下のカスタム・バッチ処理戦略を実装しています:

  • データグリッド:連続するスパンにおいて、および datagrid.operation の両方が datagrid.cacheName 同じ値を持つ場合にのみ、スパンは結合されます。 この条件が満たされた場合にのみ、スパンバッチ処理が有効になります。

  • JDBC :以下の種類のスパンバッチ処理戦略がサポートされています:

    • デフォルトのバッチ処理 (デフォルトで有効)

      JDBC のspan属性の値にかかわらず、スパンは結合されます。

    • カスタムバッチ処理 (オプション)

      連続するスパンにおいての値が同一 JDBC.statement である場合にのみ、スパンは結合されます。

JDBC のスパンに対するカスタムバッチ処理を有効にする

JDBC のスパンでカスタムバッチ処理を有効にすると、取り込まれるデータのサイズが増加します。

JDBC のスパンでカスタムバッチ処理を有効にするには、以下の設定オプションのいずれかを使用してください:

  • エージェントの設定: エージェントの設定ファイルを次のように設定してください:

      com.instana.plugin.javatrace:
        instrumentation:
          customJDBCSpanBatchingEnabled: true
     
  • 環境変数の設定:環境変数を次のように設定してください:

    INSTANA_CUSTOM_JDBC_SPANBATCHING_ENABLED=true
     
  • システムプロパティの設定: JVM の計測対象環境において、システムプロパティを次のように設定してください:

    -DcustomJDBCSpanBatchingEnabled=true
     

スパン抑制の設定

Instana Java Tracer には、高負荷時にスパンを抑制し、リソースの過剰な消費を防ぐためのメカニズムが組み込まれています。 デフォルトでは、トレース機能は、1秒あたりの発生率が240スパンを超える場合、終了スパンおよび中間スパンの表示を抑制します。 この動作はシステムの安定性を維持するのに役立ちますが、次のような問題を引き起こす可能性があります:

  • トレース内の欠落したスパン
  • 孤立スパン(親を持たないスパン)
    図 4. 孤立したスパン
    孤立したスパン

スパン抑制が発生すると、エージェントは次の例に示すようなメッセージをログに記録します:

Suppressed span(s) due to high number of short (< 4 ms) spans (SpanMonitor rate: 0.870 (last span: spring-rest 0-2486541141927097937:7078946718854091545:-2486541141927097937, duration: 3941 ms, erroneous: false, http.method: GET, http.host: example.com, http.url: http://example.com/api/testB, 
http.size: 11, http.status: 200)

スパン抑制制御パラメータ

スパン抑制は、以下の設定パラメータを使用して設定できます:

  • minspanduration: このパラメータは、スパン期間の最小値を指定します(デフォルト:4 ms)。 この値より短いスパンは省略されます。
    com.instana.plugin.javatrace:
      instrumentation:
        minspanduration: 1
  • span-suppression-start: このパラメータは、抑制が開始されるスパンレートの閾値を設定します。 この値より低い場合、スパンは抑制されません。 ただし、レートがこの値を超えると、抑制は徐々に強まり、最大で毎秒5000スパン(すべてのスパンが抑制される状態)に達します。 たとえば、このパラメータが に設定されている 3000場合、スパンレートが 1 秒あたり 3000 スパンを超えたときにのみ、抑制が開始されます。
    com.instana.plugin.javatrace:
      instrumentation:
        span-suppression-start: 3000
注: 高い値に設定すると、データの span-suppression-start 取り込み量が増える可能性があります。

ロギングレベルの設定

Instana で、ロギングレベルを有効または無効にできます。 Instana 以下のロギングレベルに対応しています:

  • OFF
  • ERROR
  • WARN

ロギングレベルが設定されると、それより優先順位の高いすべてのロギングレベルがトレースに含まれます。 たとえば、が設定されている ERROR 場合、ログレベル ERROR とが FATAL トレースされます。

ユーザー定義のログレベルを有効にする

ロギングレベルを設定するには、以下の設定オプションのいずれかを使用してください:

  • システムプロパティの設定: を ERROR または に instana_log_level_capture 設定 WARNします。
  • 環境変数の設定:を または ERRORINSTANA_LOG_LEVEL_CAPTURE 設定してください WARN

無効なロギングレベル(たとえば、 INFOTRACE)を指定した場合、エージェントのログに以下の警告が記録され、デフォルトのロギングレベル WARN が使用されます。

The value 'INFO' for 'INSTANA_LOG_LEVEL_CAPTURE' is not valid. Valid values are 'WARN', 'ERROR' and 'OFF'.
 

ロギングプラグインの無効化

すべてのロギングプラグインのロギングを無効にするには、以下の設定オプションのいずれかを使用できます:

  • エージェントの設定: Java のトレース設定を行い、エージェントの configuration.yaml ファイル内のすべてのロギングプラグインを無効にします:

        com.instana.plugin.javatrace:
          instrumentation:
            plugins:
              Logging: false
     
  • システムプロパティの設定:設定する instana_log_level_capture="OFF"

  • 環境変数の設定:設定する INSTANA_LOG_LEVEL_CAPTURE="OFF"
    注: エージェントの ` configuration.yaml ` ファイルを編集した後は、エージェントまたはアプリケーションを再起動する必要があります。

互換性のないエージェントを実行しているJVM向けに Java Tracerを設定する

Instana エージェントは、以下のいずれかのエージェントも実行しているJVMを自動的に監視しません:

  • AppDynamics
  • DataDog
  • Dynatrace
  • Glow Root
  • Kanela、Kamon インスツルメンテーション・エージェント
  • ManageEngine APM Insight Java エージェント
  • New Relic
  • Oracle Java Flight Recorder
  • Java 用の OpenTelemetry インスツルメンテーション
  • Riverbed AppInternals
  • Spring Loaded
  • Wily Introscope (CA Application Performance Management および Broadcom DX Application Performance Management とも呼ばれる)

これらのエージェントのいずれかを実行しているJVMを監視するには、エージェント configuration.yaml 設定ファイルを次のように設定してください:

com.instana.plugin.javatrace:
  trace-jvms-with-problematic-agents: true
 

クラスを無視する

パッケージ内の特定のクラスまたは複数のクラスに対するインストルメンテーションを無効にするには、次の設定オプションのいずれかを使用できます:

  • エージェントの設定:エージェント configuration.yaml ファイルで、 Java トレースセンサーが特定のパッケージ内の1つまたは複数のクラスの計測を無視するように、次のように設定します:

        com.instana.plugin.javatrace:
          instrumentation:
             ignoredClass: "^ClassName or PackageName"
     

    たとえば、パッケージ org.apache.derby 内のすべてのクラスの計測機能を無効にするには、次の設定を使用します:

           com.instana.plugin.javatrace:
             instrumentation:
                ignoredClass: org.apache.derby.
     
    注: エージェント configuration.yaml ファイルを編集した後は、エージェントまたはアプリケーションを再起動してください。
  • システムプロパティの設定:以下の例のように ignoredClass="^ClassName or PackageName" 設定してください:

    -DignoredClass=org.postgresql
     
  • 環境変数の設定:設定する IGNORED_CLASS_NAME="^ClassName or PackageName"

エンドポイントを無視する

この機能により、特定のトレースや呼び出しを除外することで、不要なデータの取り込みを減らすことができます。 このフィルタリング方法により、トレースの収集が絞り込まれます。 トレースを無効にするには、以下の Java のTracer設定のいずれかでこのパラメータを定義してください:

この機能は、以下の技術で利用可能です:

  • DynamoDB
  • Redis
  • Kafka

エンドポイントを無視する際の考慮事項

「エンドポイントの無視」機能を設定する前に、スパンのフィルタリングに関する以下のルールを確認してください:

  • あるトレースが無視されると、それに続くすべての下流のトレースも同様に無視されます。
  • を使用して * 、すべてのエンドポイント、メソッド、またはコマンドを無視します。
  • エンドポイントの値( Kafka のトピック名や Redis のコマンドなど)は、サービス間で一貫しています。
  • メソッド名は、プログラミング言語や技術によって異なる場合があります。 サービスの適切なメソッドとエンドポイントを確認するには、 Instana のUIを参照してください。

以下の Instana のUIスクリーンショットは、設定に適切なメソッドとエンドポイントを特定するための視覚的な参考資料となります:

図 5. Instana UIにおける手法とエンドポイント
方法と評価項目

「エンドポイントの無視」機能は、メソッド名が完全に一致する場合にのみ動作します。 フィルタリング対象として、正しいメソッド名を使用していることを確認してください。

エージェントの構成

エージェントを通じて設定を行うことで、すべてのサービスのエンドポイントをグローバルに無視することができます。

無視するエンドポイントを設定するには、次の例に示すように、エージェント設定ファイルの セクション com.instana.tracing.ignore-endpoints で、監視対象から除外するエンドポイントを指定します

com.instana.tracing:
  ignore-endpoints:

    # Filtering by Method Name
    redis:
      - 'get'
      - 'type'
    dynamodb:
      - 'query'

    # Filtering by Method Name and Endpoint for Kafka
    kafka:
      - methods: ["consume"]
        endpoints: ["topic1", "topic2"]  # Exclude consume calls for topic1 and topic2
      - methods: ["consume", "publish"]
        endpoints: ["topic3"]  # Exclude both consume and send calls for topic3
      - methods: ["*"]
        endpoints: ["topic4"]  # Exclude all methods for topic4
      - methods: ["consume"]
        endpoints: ["*"]  # Exclude consume method for all topics

前の例では、記載されたフィルタリングオプションに対して、以下のトレースは無視されます:

  • メソッドによるフィルタリング( Redis および DynamoDB )

    • GET および TYPERedis 内のコマンド
    • QUERY DynamoDB 内のコマンド
  • メソッドとエンドポイントによるフィルタリング( Kafka のみ)

    • CONSUME Kafkatopic2 およびすべての下流トレースにおける および topic1 に対するメソッド
    • CONSUME および PUBLISHtopic3Kafka およびすべての下流トレースにおける手法
    • Kafka 内のすべてのメソッド topic4*)およびすべての下流のトレース
    • CONSUME すべてのトピック (*) およびすべてのダウンストリーム・トレースに対するメソッド

メソッドのオプション

Kafka メソッドでは、以下のオプションを使用できます:

  • 消費者 consume : そして poll
  • プロデューサー publish : および send

Kafka のエンドポイント数に制限はありません。 したがって、エンドポイントの数が多すぎると、パフォーマンスに影響を及ぼす可能性があります。 したがって、 Kafka のエンドポイントサイズの設定については、慎重に検討してください。 Redis また、 DynamoDB のエンドポイント一覧の表示件数は10件までに制限されています。

Kafka 「エンドポイントを無視する」には、の使用状況に基づいて設定を統合できる *という重要な機能があります。 次の例はこの特徴を示しています:

  ignore-endpoints:
    kafka:
      - methods: [ "consume", "publish" ]
        endpoints: [ "topic1", "topic2" ]
      - methods: [ "consume" ]
        endpoints: [ "topic3" ]
      - methods: [ "*" ] # Applied to all methods
        endpoints: [ "topic4" ]
      - methods: [ "consume", "publish" ]
        endpoints: [ "*" ] # Applied to all topics

前の例では、記載されたフィルタリングオプションに対して、以下のトレースは無視されます:

  • 最後のエントリで および publish * メソッド consume に対して が適用されているため、すべてのトピックが無視されます。 この場合、他のすべてのエントリは上書きされます。
  • 以前の設定はすべて無効になります。

環境変数

サービスごとにエンドポイントをフィルタリングするには、環境 INSTANA_IGNORE_ENDPOINTS 変数を使用して無視するエンドポイントを設定できます。

この環境変数を使用すると、メソッドやエンドポイントに基づいてトレースを除外することができます。

INSTANA_IGNORE_ENDPOINTS=redis:get,type;dynamodb:query,scan;kafka:publish,consume

この設定では、以下のトレースがフィルタリングされます:

  • GET および TYPERedis 内のコマンド
  • QUERY および SCANDynamoDB 内のコマンド
  • PUBLISH および、すべてのエンドポイントに対する KafkaCONSUME 内のメソッド

Kafka では、エンドポイントを無視するための環境変数を適用できますが、一度に指定できるのはエンドポイント1つとメソッド1つだけです。

INSTANA_IGNORE_ENDPOINTS=kafka:topic1,topic2,topic3,topic4,topic5,topic6,topic7,topic8,topic9,topic10,topic11

Kafka では、 Redis や DynamoDB, とは異なり、エンドポイントの数は 10 に制限されません。 したがって、リストのサイズがパフォーマンスに影響を与える可能性があるため、慎重に検討する必要があります。

Kafka のメソッドオプションを使用して、環境変数を次のように設定します:

INSTANA_IGNORE_ENDPOINTS=kafka:consume,publish
OR
INSTANA_IGNORE_ENDPOINTS=kafka:poll,send
OR
INSTANA_IGNORE_ENDPOINTS=kafka:*

システム・プロパティー

また、 Java システムプロパティを使用して、無視するエンドポイントを設定することもできます。 次の例は、システムプロパティを使用して無視するエンドポイントを設定する方法を示しています:

java -Dinstana.ignore-endpoints="redis:get,type;dynamodb:query,scan;kafka:publish,consume" -jar application-jar

Kafka では、エンドポイントを無視するためのシステムプロパティを適用できますが、一度に指定できるメソッドとエンドポイントはそれぞれ1つだけです。

java -Dinstana.ignore-endpoints="kafka:topic1,topic2,topic3,topic4,topic5,topic6,topic7,topic8,topic9,topic10,topic11" -jar application-jar

Kafka では、 Redis や DynamoDB, とは異なり、エンドポイントの数は 10 に制限されません。 したがって、リストのサイズがパフォーマンスに影響を与える可能性があるため、慎重に検討する必要があります。

Kafka のメソッドオプションを使用して、システムプロパティを次のように設定します

java -Dinstana.ignore-endpoints="kafka:consume,publish" -jar application-jar
OR
java -Dinstana.ignore-endpoints="kafka:poll,send" -jar application-jar
OR
java -Dinstana.ignore-endpoints="kafka:*" -jar application-jar

スパン注釈の制限

デフォルトでは、1つのSpanに対して最大10個の注釈を追加し、 Instana のUIに表示することができます。

注釈の上限を増やす

Instana SDK を使用中に、Span に注釈をさらに追加する必要がある場合は、監視対象の JVM で以下のシステムプロパティを設定することで、この制限を引き上げることができます:

-Dinstana.tracing.annotation.size=<desired_limit>

たとえば、制限を20に増やすには、アプリケーションを次のように起動します:

java -Dinstana.tracing.annotation.size=20 -jar application.jar
注:
  • アノテーションの上限を増やすと、監視対象アプリケーションのメモリ使用量が増加します。 利用可能なシステムリソースに応じて値を調整してください
  • システムプロパティを設定した後、変更を反映させるには JVM を再起動してください。

Java Tracer によって取得されたすべてのアノテーションの完全な一覧については、 「 Java のトレースアノテーション」 を参照してください。

誤ったスタックトレースの取得

トランザクション処理量が多いアプリケーションでは、スタックトレースの取得が重大なパフォーマンス上のオーバーヘッドとなる可能性があります。特に、操作の大部分が正常に完了し、スタックトレース情報が不要な場合には、その傾向が顕著です。 そのような場合、誤ったスタックトレースを取得する代わりに、関連する情報を得られるように最適化された手法を用いてスタックトレースを取得します。

以下の設定オプションのいずれかを使用することで、エラーが発生したスパンについてのみスタックトレースの取得を有効にすることができます。 エラーが発生したスパンについてのみスタックトレースを取得することで、正常に完了したスパンのスタックトレースをスキップし、パフォーマンスを向上させるとともにデータ取り込み量を削減できます。

エージェントの構成

エージェントの設定ファイルに以下の設定を行ってください:

com.instana.tracing:
  stack.capture.timing: error
注: エージェントの設定変更を行う際、アプリケーションの再起動は必要ありません。

動作 :エラーが発生したスパン(メタデータにエラーが含まれるスパン )についてのみスタックトレースをキャプチャします。これにより、正常に完了したスパンのスタックトレースを除外することで、パフォーマンスが向上し、取り込まれるデータ量が削減されます。

環境変数

お使いの INSTANA_TRACING_STACK_CAPTURE_TIMING 環境で、環境変数を次のように設定し、エクスポートしてください:

export INSTANA_TRACING_STACK_CAPTURE_TIMING=error
注:
  • この変数を、アプリケーションが実行される環境で定義してください。
  • アプリケーションを再始動して、変更を有効にします。

システム・プロパティー

以下のプロパティーを設定します。

-Dcom.instana.tracing.stack.capture.timing=error 

このシステムプロパティを使用するには、アプリケーションの起動時に次の引数を指定する必要があります:

java -Dcom.instana.tracing.stack.capture.timing=error -jar application.jar

フィルタリングの設定

属性に基づいて特定のスパンを除外することで、トレースデータの量を削減できます。 この機能により、データ取り込みのコストを最適化し、アプリケーション監視のニーズに最も関連性の高いトレースに焦点を当てることができます。

HTTP および JDBC のスパンに対してフィルタリングが可能です。 エージェント configuration.yaml 設定ファイルを通じてフィルタリングルールを設定し、URL、SQL文、 HTTP メソッドなどの属性に基づいてスパンを除外することができます。

主な特長:

  • HTTP エンドポイントのフィルタリング : HTTP のスパンを除外し、子スパンおよび下流のトレースを自動的に非表示にします。
  • JDBC スパンフィルタリング :下流のトレースを抑制することなく、データベースのスパンを除外します。
  • 柔軟な一致 :完全一致、先頭一致、末尾一致、部分一致、およびワイルドカード('*'*)パターンをサポートしています。
  • 動的設定 :初期設定後は、アプリケーションを再起動することなく変更が反映されます。

フィルタリングの設定に関する詳細情報(設定構文、スパン属性、例、制限事項など)については、 「フィルタリングの設定」 を参照してください。

Open Liberty の誤ったスパンキャプチャを有効にする

Open Liberty Server では、エラーのあるスパンのキャプチャを有効にすることで、無効なコンテキストを持つリクエストをキャプチャできます。 この機能により、無効なコンテキストを含むリクエストが大量に発生した場合でも、アプリケーションからのデータ取り込み量を増加させることができます。 本番環境でこの機能を有効にする際は、十分にご注意ください。

Open Liberty で、無効なコンテキストを持つリクエストエントリのスパンをキャプチャできるようにするには、エージェント configuration.yaml ファイル(*instanaAgentDir*/etc/instana/configuration.yaml)に以下の行を追加してください:

com.instana.plugin.javatrace:
   instrumentation:
    plugins:
      LibertyHttpChannelEntry: true