IBM App Connect Enterprise （ACE）Tracerの設定

Instana のACEトレース・ユーザー・エグジットは、以下のノードタイプのみをサポートしています：

• HTTP 要求
• IBM MQ リクエスト
• Kafkaリクエスト

CICS リクエスト・サポートを IBM Cloud Pak for Integration 環境で有効にする場合は、以下の手順を実行します：

1. カスタム docker イメージを作成する ACEトレースのユーザー・エグジットが有効になっている状態で。
2. この docker のイメージに基づいて、ACEアプリケーションをデプロイします。

• Instana のACEトレース・ユーザー・エグジットは、 MQRFH2 ヘッダーのみを含む IBM MQ メッセージをサポートしています。これは、トレース情報が IBM MQ メッセージの MQRFH2 ヘッダーに書き込まれ、トレースコンテキストが伝播されるためです。 一部の IBM MQ コンシューマークライアントでは、 IBM MQ メッセージに余分なヘッダーデータが含まれていると、メッセージ処理エラーやメッセージの拒否が発生する可能性があります。

• 本番環境で有効化する前に、 非本番環境で IBM MQ のコンシューマークライアントをテストしてください。

• トレース相関のサポートを有効にした結果、 IBM MQ クライアントアプリケーションでエラーが発生した場合は、次のいずれかの操作を行ってください：

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

Instana のACEトレース・ユーザー・エグジットは、入力ノードをエントリポイントとするメッセージ・フローのみをサポートしています。

Instana のACE Tracingユーザー・エグジットをインストールおよび設定する前に、 IBM ACE をインストールおよび設定してください。

「 IBM ACE 」のトレース・ユーザー・エクジットをダウンロードするには、以下の手順を実行してください：

1. Artifactory から「 IBM ACE Tracing user exit .tgz 」ファイルをダウンロードしてください。 ファイルをダウンロードするには、ユーザー名に_を、パスワードに有効なエージェントキーを使います。

2. ダウンロードした.tgzファイルを一時的な場所に展開します。

3. 取り出した後、ディレクトリの中に、異なるプラットフォーム用の5つのユーザー終了パッケージを見つける。

4. IBM ACE ホスト上のプラットフォーム固有のユーザー・エグジット・パッケージを転送してください。

5. ユーザー終了パッケージを ACE ホストの以下のディレクトリに解凍します。

   • LinuxとAIXです：/var/mqsi/shared-classes
   • Windows: C:\ProgramData\IBM\MQSI\shared-classes

   以下のファイルをshared classesディレクトリに置いてください：

   • ACEOpenTracingUserExit.lel: このファイルには、 Instana ACEユーザー出口が含まれています。これは、 HTTP リクエスト、 IBM MQ リクエスト、および Kafka リクエストをインターセプトし、ラップされた OpenTelemetry C++ クライアントライブラリを起動してスパンを作成します。
   • tracelibrary.so: このファイルは、 OpenTelemetry C++ のラッパークライアントを定義しています。このクライアントは、スパンのライフサイクルを管理する機能を提供し、スパンをターゲットのトレースシステムに送信します。
   • acetracingexit.conf: この設定ファイルは、ログレベルとホストエージェントへの接続に関する情報を指定します。

   ACEサーバーがグローバルインストールでインストールされていない場合、 IBM ACE ホスト上に または C:\ProgramData\IBM\MQSI\shared-classes /var/mqsi/shared-classes ディレクトリは存在しません。 IBM ACE/opt/acetracingexitC:\acetracingexit ホスト上でディレクトリを手動で作成し、そのディレクトリにファイルを .tar 解凍してください。

IBM ACE のトレース機能を有効にするには、以下の手順を実行してください：

1. 統合ノードを停止します。

   mqsistop <integrationNodeName>
    

2. コマンド mqsichangeflowuserexits を使用するプロパティ UserExitPath を設定して、統合ノードにユーザー・エグジットをインストールします。

   mqsichangeflowuserexits <integrationNodeName> -o -x /var/mqsi/shared-classes
    

   IBM ACE.tar/opt/acetracingexit のトレースファイルをディレクトリに抽出する場合は、をに /var/mqsi/shared-classes 置き換えて /opt/acetracingexitください。

3. ユーザー出口をアクティブ化します。

   ユーザー出口はアクティブまたは非アクティブにすることができ、デフォルトでは非アクティブです。 統合ノード、統合サーバー、または特定のメッセージフローのユーザー終了を有効にできます。

   1. 統合ノードのユーザー出口をアクティブにします。

      1. ユーザー終了を有効にする：

         mqsichangeflowuserexits <integrationNodeName> -o -a ACEOpenTracingUserExit
          

      2. ユーザーの退出を確認する：

         mqsireportflowuserexits <integrationNodeName> -o
          

         次の出力例を参照してください。

         # mqsireportflowuserexits BK3 -o
         BIP8854I: User Exits active for integration server 'BK3': ACEOpenTracingUserExit.
         BIP8855I: User Exits inactive for integration server 'BK3': .
         BIP8741I: User Exit path for integration server 'BK3': /var/mqsi/shared-classes.
         BIP8071I: Successful command completion.
          

      3. 統合ノードを起動します：

         mqsistart <integrationNodeName>
          

   2. 統合サーバーのユーザー出口をアクティブ化します。

      1. 統合ノードを起動します：

         mqsistart <integrationNodeName>
          

      2. ユーザー終了を有効にする：

         mqsichangeflowuserexits <integrationNodeName> -e <integrationServerName> -a ACEOpenTracingUserExit
          

   3. メッセージ・フローのユーザー出口をアクティブ化します。

      1. 統合ノードを起動します：

         mqsistart <integrationNodeName>
          

      2. メッセージフローのユーザー終了を有効にする：

         mqsichangeflowuserexits <integrationNodeName> -e <integrationServerName> -k <applicationName> -f <messageFlow> -a ACEOpenTracingUserExit
          

   4. ユーザー終了を有効にする他の統合ノード、統合サーバー、またはメッセージフローについて、手順を繰り返します。

詳しくは、以下のリンクを参照してください。

• IBM ACE ： ユーザー・エグジットのデプロイ
• IBM ACE ： mqsichangeflowuserexits コマンド - Windows、 Linux、および AIX システム

1. /var/mqsi/shared-classes ディレクトリーに移動します。

2. acetracingexit.conf ファイルを編集します:

   # configuration for ace tracing exit
   LOG_LEVEL="info" #Log level: info, warn, error, debug
   SPAN_FORMAT="instana"
   CICS_SUPPORT="off" #Propagate trace context for CICS request: off, on
   MONITOR_LEVEL="verbose" #ACE tracing level: off, normal, verbose
   INSTANA_AGENT_HOST="localhost" #(optional)
   INSTANA_AGENT_PROTO="http" #(optional)
   HOST_ALIAS="<YOUR-HOST-NAME>" #(optional)
   
    

   ここで、それぞれ以下のとおりです。

   • LOG_LEVEL ログレベルを指定します。ログレベルは、次のいずれかのタイプに設定できます： info、 warn error、、または debug。 ログファイルは /tmp/trace ディレクトリにあります。
   • SPAN_FORMAT は、スパン・データの送信先を指定します。 この変数を instana に設定してください。 Instana ACEトレースのユーザー・エグジットは、デフォルトでスパンデータをホスト http://localhost:42699 ・エージェントのエンドポイントに送信します。 HTTPS プロトコルを使用するリモートホストエージェントにスパンデータを送信する場合は、設定フィールド INSTANA_AGENT_HOSTINSTANA_AGENT_PROTO および を更新してください。 すべての IBM ACE インスタンスで、同じ SPAN_FORMAT 設定にする必要があります。
   • CICS_SUPPORT このパラメータは、 CICS リクエストのトレース機能を有効にするかどうかを制御します。 この設定を「オン on 」にすると機能が有効になり、「オフ」にすると off 無効になります。
   • MONITOR_LEVEL IBM ACE のトレースレベルを指定します。指定できる値は、, normaloff, または の verboseいずれかです。 が に設定されている MONITOR_LEVELoff 場合、送信されるリクエストにはトレースコンテキストが追加されません。 が に設定されている MONITOR_LEVELnormal 場合、 IBM MQ メッセージに RFH2 ヘッダーが含まれているときのみ、トレースコンテキストが追加されます。 が に設定されている MONITOR_LEVELverbose 場合、トレースコンテキストは、送信されるすべての HTTP または IBM MQ リクエストに追加されます。
   • INSTANA_AGENT_HOST Instana 形式のスパンデータが送信されるエージェントホストを指定します。 デフォルトでは、 localhost が使用されます。 リモートエージェントのホストを指定する場合は、デフォルトではホストエージェントが他のホストからアクセスできないため、まずリモートホストのエージェント *instanaAgentDir*/etc/instana/com.instana.agent.main.config.Agent.cfg 用に に http.listen=* 一行を追加する必要があります。
   • INSTANA_AGENT_PROTO IBM ACE のトレーシング・ユーザー・エグジットとホスト・エージェント間の接続タイプを指定します。 デフォルトでは、 http が使用されます。 ただし、 もサポート https されています。 これをに変更する場合は https、まず 「エージェント・エンドポイントの TLS 暗号化の設定」 の手順に従って、 Instana エージェント・エンドポイントを保護する必要があります。
   • HOST_ALIAS Instana のACEトレース・ユーザー・エグジットによって収集されるスパンデータのホストエイリアスを指定します。 したがって、統合ノードまたは統合サーバーが「 IBM ACE 」センサーによって監視されている場合、 IBM ACE への呼び出しをインフラストラクチャ・エンティティに関連付けることができます。 デフォルトでは、 IBM ACE ホストの FQDN が使用されます。 ホストエイリアスの値は、ホストエージェントの設定YAMLファイルで指定されている IBM ACE センサーのホストと一致している必要があります。 「 IBM ACE 」ホストのFQDNが「 Instana 」ACEセンサーの設定で使用されていない場合、かつホストエージェントがローカルの「 IBM ACE 」ホスト上にない場合にのみ、ホストエイリアスを指定する必要があります。 IBM ACE センサーは、ローカル統合ノードまたは統合サーバーの FQDN をディスカバーできます。

3. ファイルを保存し、統合ノードまたは統合サーバーを再始動します。

トレースを有効にする他の IBM ACE ホストで、上記のインストール・ステップと構成ステップを繰り返します。

「 Instana 」のUIで、 Instana のACEトレースデータを表示できます。

1. ユーザー出口を構成解除します。

   1. 統合ノードのユーザー終了の設定を解除します：

      1. 統合ノードを停止します：

         mqsistop <integrationNodeName>
          

      2. ユーザー終了を無効にする：

         mqsichangeflowuserexits <integrationNodeName> -o -a ""
          

      3. 統合ノードを再始動します。

   2. 統合サーバーのユーザー終了を無効にします：

      mqsichangeflowuserexits <integrationNodeName> -e <integrationServerName> -a ""
       

   3. メッセージフローのユーザー終了を無効にする：

      mqsichangeflowuserexits <integrationNodeName> -e <integrationServerName> -k <applicationName> -f <messageFlow> -a ""
       

2. 他の統合ノードでもこの手順を繰り返します。

IBM ACE で OpenTelemetry のトレースを有効にするには、以下の手順に従ってください：

1. Instana 向けに、 OpenTelemetry のデータ取り込みを設定します。 詳細については、 「 OpenTelemetry のデータ取り込みの設定」 を参照してください。

2. ACEの OpenTelemetry トレースを有効にする。 詳細については、 「統合サーバーの OpenTelemetry トレースの設定」 を参照してください。

3. エンティティ間のインフラストラクチャの相関関係を正しく機能させるために、正しいホスト名を設定してください。

注意事項および制限事項の詳細については、 OpenTelemetry の注意事項および制限事項を参照してください。

ACEユーザー・エグジットのトレース機能は、シングルノード構成でのみサポートされています。 高可用性（HA）構成およびクラスタ環境はサポートされていません。 HA展開やクラスタ環境では、ユーザー・エグジット方式の代わりに、 OpenTelemetry のネイティブトレース機能を使用してください。