IBM MQ トレース

オンプレミス IBM MQ のトレースを有効にするには、以下のセクションを参照してください：

IBM MQ Operator 2.2.0 およびそれ以降のバージョンは、Instana IBM MQ Tracing をネイティブにサポートしています。 ネイティブ・サポートを得るには、 IBM MQ キュー・マネージャー・コンテナ・イメージ 9.3.1.0-r2 またはそれ以降のバージョンを使用する。 Instana IBM MQ IBM Cloud Pak for Integration クラスタまたは Red Hat OpenShift Container Platform クラスタ上で IBM MQ オペレータ 2.2.0 またはそれ以降のバージョンを使用してデプロイされているキューマネージャのトレースを有効にするには、 IBM MQ ガイドを参照してください。 IBM MQ トレースは、 x86_64、 ppc64le、 s390x Kubernetes ノードの Linux でサポートされています。

Instana AutoTrace webhook を使用して、 IBM Cloud Pak for Integration クラスタ上の IBM MQ に対して Instana IBM MQ Tracing を有効にすることもできます。 Instana AutoTrace webhook は、 9.3.3.0 および Linux/amd64 Kubernetes ノードより前のバージョンの IBM MQ キュー・マネージャー・コンテナ・イメージのみをサポートします。 IBM Cloud Pak for Integration クラスタ上で実行される IBM MQ コンテナのトレースを有効にする方法の詳細については、 IBM MQ および ACE の Webhook インストルメンテーションを有効にするを参照してください。

IBM MQ Tracing for on-premises IBM MQ を設定するには、以下の手順を実行します。

1. exits64 ：

   • Linux と AIX については、 /var/mqm/exits64 ディレクトリにアクセスしてください。
   • Windowsの場合は、 C:\ProgramData\IBM\MQ\exits64 ディレクトリに移動します。

2. すべてのキューマネージャインスタンス用の mqtracingexit.conf ファイル、または特定のキューマネージャ用の mqtracingexit_<QMNAME>.conf ファイルを編集します。

   # configuration for IBM MQ Tracing user exit
   LOG_LEVEL="info" #Log level: info, warn, error, debug
   SPAN_FORMAT="instana" #Span Format: instana, otel
   MONITOR_LEVEL="normal" #MQ tracing level: normal, quiet, off, debug
   IBMMQ_DEST_MONITOR_LEVEL_OFF = "" Regex for message destinations with tracing level off, for example: "^TMPQ.*". An example for multiple conditions: "^SYSTEM\\.AUTH\\..*|^TEMP\\.QUEUE\\..*".
   IBMMQ_DEST_MONITOR_LEVEL_QUIET = "" #Regex for message destinations with tracing level quiet
   IBMMQ_DEST_MONITOR_LEVEL_NORMAL = "" #Regex for message destinations with tracing level normal
   IBMMQ_DEST_MONITOR_LEVEL_DEBUG = "" #Regex for message destinations with tracing level debug
   IBMMQ_PUBSUB_SUPPORT = "off" #The switch for the publish/subscribe support: on, off
   IBMMQ_RFH2_HEADERS_TO_EXPOSE = "" #A list of message headers that must be included in the `PUT` span payload, and each header is separated by commas.
   INSTANA_AGENT_HOST = "localhost" #(optional) Applies only when the SPAN_FORMAT is set to instana
   INSTANA_AGENT_PORT = 42699 #(optional) Applies only when the SPAN_FORMAT is set to instana
   INSTANA_AGENT_PROTO = "http" #(optional) Applies only when the SPAN_FORMAT is set to instana
   HOST_ALIAS="<YOUR-HOST-NAME>" #(optional) Applies only when the SPAN_FORMAT is set to instana
   LOCAL_SOURCE_ADDRESS = "" #(optional) The local source ip address for outgoing traffic
   OTLP_EXPORTER_GRPC_ENDPOINT = "" #(optional) Applies only when the SPAN_FORMAT is set to otel
   OTLP_EXPORTER_SSL_CACERT_PATH = "" #(optional) Applies only when the SPAN_FORMAT is set to otel
   OTLP_EXPORTER_HTTP_URL = "" #(optional) Applies only when the SPAN_FORMAT is set to otel
    

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

   • LOG_LEVEL このパラメータはログレベルを指定する。 ログレベルは info、 warn、 error、 debug のいずれか。 Linux と AIX では、ログファイルは /tmp/ibmmqtrace ディレクトリにあり、Windows では、ログファイルは C:\ProgramData\IBM\MQ\trace ディレクトリにある。 ログファイルのデフォルト・ディレクトリを変更するには、 「 IBM MQ トレース用ログファイル 」セクションの手順を参照してください。
   • SPAN_FORMAT このパラメータは、スパンデータを送信するトレースシステムを指定する。 この変数を instana に設定してください。 デフォルトでは、 IBM MQ トレースユーザーの終了は、ホストエージェントエンドポイント http://localhost:42699 にスパンデータを送信する。 HTTPS プロトコルを使用してスパンデータをリモートホストエージェントに送信するには、設定項目 INSTANA_AGENT_HOST と INSTANA_AGENT_PROTO を更新します。 SPAN_FORMAT の設定は、 IBM MQ のホストでも同じでなければなりません。
   • MONITOR_LEVEL このパラメータは、キューマネージャのデフォルトのトレースレベルを指定するもので、 off、 quiet、 normal、 debug のいずれかに設定することができる。 MONITOR_LEVEL が off に設定されている場合、トレースデータは収集されない。 quiet に設定された場合、トレース相関情報はすべてのメッセー ジに追加されませんが、 IBM MQ サーバーでメッセージをトレースすることができます。 これが normal に設定されている場合、トレース相関情報は、 RFH2 ヘッダーまたは名前付きプロパティを持つメッセージに追加されるが、テキストメッセージには追加されない。 これが debug に設定されている場合、トレース相関情報はトレースされているすべてのメッセージに追加されます。
   • IBMMQ_DEST_MONITOR_LEVEL_OFF このパラメータは、トレースレベル off のメッセージ宛先を指定する。 このパラメータの値は、 "^TMPQ.*" のような正規表現でなければなりません。 つまり、 TMPQ で始まる宛先に送られたメッセージはトレースされない。 トランザクションの完全性を保証するために、同じメッセージングチェーン内のメッセージ宛先のトレースレベルを同じにしておく必要があります。 メッセージの宛先が複数の正規表現にマッチする場合、有効な正規表現の優先順位は以下のようになる： IBMMQ_DEST_MONITOR_LEVEL_OFF , IBMMQ_DEST_MONITOR_LEVEL_QUIET , IBMMQ_DEST_MONITOR_LEVEL_NORMAL そして IBMMQ_DEST_MONITOR_LEVEL_DEBUG .
   • IBMMQ_DEST_MONITOR_LEVEL_QUIET このパラメータは、トレースレベル quiet のメッセージ宛先を指定する。 このパラメータの値は正規表現でなければならない。 メッセージの宛先がこの正規表現にマッチする場合、トレース相関情報は、メッセージの宛先に送信されるすべてのメッセージに追加されません。 しかし、 IBM MQ サーバーでメッセージをトレースすることはできる。
   • IBMMQ_DEST_MONITOR_LEVEL_NORMAL このパラメータは、トレースレベル normal のメッセージ宛先を指定する。 このパラメータの値は正規表現でなければならない。 メッセージの宛先がこの正規表現にマッチする場合、 RFH2 ヘッダーまたは名前付きプロパティを持つメッセージにトレース相関情報が追加されます。 しかし、トレース相関情報はテキストメッセージには追加されない。
   • IBMMQ_DEST_MONITOR_LEVEL_DEBUG このパラメータは、トレースレベル debug のメッセージ宛先を指定する。 このパラメータの値は正規表現でなければならない。 メッセージの宛先がこの正規表現にマッチする場合、トレース相関情報は、メッセージの宛先に送信されるすべてのメッセージに追加されます。 Windowsプラットフォームでは、 既知の問題のため、宛先キューのモニター・レベル（IBMMQ_DEST_MONITOR_LEVEL_* ）とグローバル・モニター・レベル（MONITOR_LEVEL ）を一緒に使用することはできません。
   • IBMMQ_PUBSUB_SUPPORT このパラメータは、パブリッシュ・メッセージとサブスクライブ・メッセージのトレースを有効にするかどうかを制御します。 サポートを有効にするには on 、無効にするには off 。
   • IBMMQ_RFH2_HEADERS_TO_EXPOSE このパラメータは、スパンペイロードに含まれなければならないメッセージヘッダーの リストを指定する。各ヘッダーはカンマで区切られる。例えば、 IBMMQ_RFH2_HEADERS_TO_EXPOSE="rfh2_folder1.header1, rfh2_folder2.header2, header3"。 256バイトより大きなサイズのメッセージ・ヘッダは、スパン・サイズが大きくなりすぎて全体のパ フォーマンスに影響を与えるのを避けるために、切り捨てられる。 また、1つのスパンで収集されるすべてのメッセージヘッダーの長さの合計は、3KBを超えてはならない。 したがって、最も重要なヘッダーのみをコレクションに設定する必要がある。
   • INSTANA_AGENT_HOST このパラメータは、Instana フォーマットのスパンデータが送信されるエージェントホストを指定します。 リモートエージェントホストを指定する場合、ホストエージェントはデフォルトでは他のホストから到達できないため、最初にリモートホストエージェント用の行 *instanaAgentDir*/etc/instana/com.instana.agent.main.config.Agent.cfg を http.listen=* に追加する必要もあります。
   • INSTANA_AGENT_PORT このパラメータは、Instana エージェントがリッスンしているポートを指定します。デフォルトでは 42699 が使用されます。 エージェントが別のポートでリッスンしている場合にのみ、ポートを変更する必要があります。
   • INSTANA_AGENT_PROTO このパラメータは、 IBM MQ Tracing exit とホストエージェント間の接続タイプを指定します。 IBM MQ センサーは HTTP と HTTPS プロトコルの両方をサポートしています。 ただし、デフォルトでは HTTP。 プロトコルを HTTPS に変更するには、まずエージェントのエンドポイントを保護する必要があります。 エージェント・エンドポイントを保護する方法の詳細については、 エージェント・エンドポイントのTLS暗号化の設定を参照してください。
   • HOST_ALIAS このパラメータは、 IBM MQ Tracing ユーザー終了によって収集されるスパンデータのホストエイリアスを指定します。 IBM MQ センサがキュー・マネージャも監視している場合、 IBM MQ へのコールをインフラストラクチャ・エンティティにリンクすることができる。 デフォルトでは MQ ホストの FQDN が使用される。 ホストエイリアス値は、ホストエージェント設定yamlで指定されている IBM MQ ホストと一致する必要がある。 IBM MQ ホストの FQDN が IBM MQ センサー構成で使用されておらず、ホストエージェントがローカルの IBM MQ ホスト上にない場合は、ホストエイリアスを指定します。 IBM MQ センサーは、ローカルのキュー・マネージャー・インスタンスの FQDN を発見することができる。
   • LOCAL_SOURCE_ADDRESS このパラメータは、 IBM MQ Tracing ユーザー出口からの発信トラフィックのローカルソースIPアドレスを指定します。 IBM MQ サーバーに複数のネットワーク・インターフェイスがあり、 IBM MQ トレース・ユーザー出口からのすべての発信トラフィックを特定のネットワーク・インターフェイスにバインドしたい場合にのみ、設定する必要があります。
   • OTLP_EXPORTER_GRPC_ENDPOINT SPAN_FORMAT が otel に設定されているとき、 OpenTelemetry スパンデータが送信される OTLP gRPC エンドポイントを指定する。 デフォルトはlocalhost:4317です。 TLSが gRPC エンドポイントで有効になっている場合は、 OTLP_EXPORTER_SSL_CACERT_PATH も設定する。 AIX プラットフォームでは、OTLP gRPC プロトコル（ OTLP_EXPORTER_GRPC_ENDPOINT を設定すると有効になる）は使用できないため、デフォルトで HTTP が使用されます。

3. ファイルを保存します。

4. キュー・マネージャ・インスタンスを再起動する。

Red Hat OpenShift クラスタ上で稼働しているキューマネージャの IBM MQ Tracing の設定を変更するには、キューマネージャポッドに新しい環境変数を追加します。 環境変数名は、 Configuring IBM MQ Tracing for on-premises IBM MQ セクションに記載されている設定項目名と一致する必要があります。 キュー・マネージャ・ポッドの環境変数を追加するには、以下の手順を実行します：

1. Red Hat OpenShift クラスター Web コンソールにログインします。

2. ナビゲーション・パネルで、[ Operators ] > [ Installed Operators] をクリックします。 指定したプロジェクトにインストールされているすべてのオペレーターが表示されます。

3. IBM MQ Operatorを選択。 IBM MQ Operator ウィンドウが表示されます。

4. キュー・マネージャー・タブに行く。 キューマネージャの詳細ウィンドウが表示されます。

5. トレース設定を変更したいキューマネージャを選択します。

6. 「YAML」タブに移動します。

7. spec > template > pod > containers > env セクションに環境変数を追加する。 例えば、 IBM MQ Tracingのログレベルをdebugに変更するには、以下のスニペットを使用します：

   template:
    pod:
      containers:
        - env:
            - name: LOG_LEVEL
              value: debug
    

8. 更新されたキューマネージャの YAML ファイルを保存します。

1. Instana エージェントが IBM MQ サーバで実行されている場合は、キューマネージャーインスタンスと Instana エージェントを停止します。
2. IBM MQ Tracing ユーザー終了の設定ファイルを IBM MQ サーバーの /var/mqm/exits64 ディレクトリにバックアップする。
3. ダウンロードした IBM MQ Tracing user exit ファイルを解凍し、 /var/mqm/exits64 ディレクトリの対応するファイルを置き換える。
4. ステップ 1 で Instana エージェントが停止していた場合は、キューマネージャーインスタンスと Instana エージェントを起動します。

1. Instana エージェントが IBM MQ サーバで実行されている場合は、キューマネージャインスタンス、 MQ エクスプローラ、および Instana エージェントを停止します。
2. IBM MQ Tracing ユーザー終了の設定ファイルを IBM MQ サーバーの C:\ProgramData\IBM\MQ\exits64 ディレクトリにバックアップする。
3. ダウンロードした IBM MQ Tracing user exit ファイルを解凍し、 C:\ProgramData\IBM\MQ\exits64 ディレクトリの対応するファイルを置き換える。
4. ステップ 1 で Instana エージェントが停止していた場合は、キュー・マネージャ・インスタンス、 MQ エクスプローラ、および Instana エージェントを起動します。

Red Hat OpenShift クラスタ上で IBM MQ Tracing をアップグレードするには、次のいずれかの手順を実行します：

• IBM MQ IBM MQ オペレータ 2.2.0 またはそれ以降のバージョンを使用してトレースが有効になっている場合は、 IBM MQ キュー・マネージャをアップグレードしてください。
• Instana AutoTrace webhook を使用して IBM MQ Tracing が有効になっている場合は、Instana AutoTrace webhook を再度デプロイし、キューマネージャーポッドを再起動します。

IBM MQ でトレースデータの収集を無効にするには、 mqtracingexit.con ファイルで MONITOR_LEVEL を off に設定する。

IBM MQ ユーザー終了のトレースを無効にするには、 IBM MQ ホストで以下の手順を実行します：

1. /var/mqm/mqs.ini または C:\ProgramData\IBM\MQ\mqs.ini ファイルで設定した ApiExitCommon と ApiExitLocal スタンザを削除し、 IBM MQ トレースが有効になっている IBM MQ ホストから /var/mqm/qmgrs/<QMNAME>/qm.ini または C:\ProgramData\IBM\MQ\qmgrs\<QMNAME>\qm.ini ファイルを削除する。
2. Instana エージェントが IBM MQ サーバで実行されている場合は、キューマネージャーインスタンス、 MQ Explorer、および Instana エージェントを再起動します。

Red Hat OpenShift クラスタで IBM MQ Tracing を無効にするには、次のいずれかの手順を実行します：

• IBM MQ IBM MQ オペレータバージョン 2.2.0 以降を使用してトレースが有効になっている場合は、 IBM Cloud Pak for Integration Platform UI または OpenShift ウェブコンソールで Enable Instana tracing トグルを false に設定します。 IBM MQ ガイドを参照。

• IBM MQ トレースが Instana AutoTrace Webhook を使用して有効になっている場合は、次のいずれかの手順を実行します：

  • Instana AutoTrace Webhook をアンインストールし、キューマネージャーポッドを再起動します。
  • Instana AutoTrace webhook をアンインストールし、 autotrace.ibmmq.enabled を false に設定してから、Instana AutoTrace webhook を再度デプロイします。 変更を有効にするには、キュー・マネージャ・ポッドを再起動します。 AutoTrace webhookのインストールを参照してください。

トレース相関情報を伝播するために、 IBM MQ トレースユーザー終了は、メッセージにすでに MQRFH2 ヘッダーが含まれている場合、またはメッセージ送信先のモニターレベルが debug に設定されている場合、トレース対象のメッセージに追加の MQRFH2 ヘッダー (X_INSTANA_T, X_INSTANA_S, X_INSTANA_L, traceparent, tracestate) を追加します。 しかし、メッセージに追加ヘッダーデータが存在すると、 IBM MQ コンシューマーアプリケーションによっては、メッセージ処理エラーやメッセージ拒否の原因になることがある。 追加の MQRFH2 ヘッダーが、 IBM MQ クライアント・アプリケーションでエラーを引き起こす場合は、以下のいずれかの対処を行ってください：

• IBM MQ クライアント アプリケーションを変更して、Instana が追加したトレース相関情報を持つ追加の MQRFH2 ヘッダーを無視するようにします。
• IBM MQ Tracing ユーザー終了設定パラメータにメッセージングチェーン内のキューを追加することで、トレース相関伝搬を無効にします。 IBMMQ_DEST_MONITOR_LEVEL_QUIET .
• IBM MQ クライアント・アプリケーションによって接続されたキューについて、 PROPCTL プロパティの値を NONE に変更する。

デフォルトでは、トレース相関情報は、 MQRFH2 ヘッダーまたはメッセージ・プロパティを含む IBM MQ メッセージに自動的に追加されます。 IBM MQ クライアント・アプリケーションを壊さないように、 IBM MQ ユーザー終了のトレースでは、プレーン・テキスト・メッセージにトレース相関情報を追加しません。 それでもなお、メッセージにトレース相関情報を追加したい場合は、 IBM MQ Tracing ユーザー終了設定パラメータにメッセージ送信先を追加することができます。 IBMMQ_DEST_MONITOR_LEVEL_DEBUG . しかし、 IBM MQ クライアント・アプリケーションが、追加の MQRFH2 ヘッダーを持つメッセージを解析できるようにする必要があります。

IBM MQ Tracing ユーザー出口によって生成されるコールを、 IBM MQ キューマネージャの監視対象インフラストラクチャ エンティティにリンクできます。このエンティティは、Instana UI の Instana IBM MQ センサーによって収集されます。 Instana IBM MQ センサーが収集するキュー・マネージャーのエンティティIDには、アクティブ・ノードとスタンバイ・ノード IBM MQ の両方のホストが含まれているため、 IBM MQ の高可用性シナリオではインフラリンクが利用できない場合があります。 これは、 IBM MQ Tracingユーザー終了によって生成されるエンティティIDとは対照的で、アクティブな IBM MQ ノードのホストのみを含む。 不一致は、呼の詳細とキュー・エンティティ間のリンクを破壊する。 この問題を解決するには、次のような対処が可能です：

1. Instana UI のインフラストラクチャビュー内の高可用性キューマネージャダッシュボードに移動します。
2. キュー・マネージャ・ダッシュボードのサイドバーにある Name 属性を見つけて、キュー・マネージャのホスト情報を抽出してください。 高可用性キューマネージャのホストは、 Name 文字列のうち、 @ シンボルの後に来る部分である。 例えば、キューマネージャ名が haqm1@ibmmqnode1.ibm.com-ibmmqnode2.ibm.com-ibmmqnode3.ibm.com と表示される場合、キューマネージャホストは ibmmqnode1.ibm.com-ibmmqnode2.ibm.com-ibmmqnode3.ibm.com となります。
3. IBM MQ サーバーにアクセスし、 IBM MQ ユーザー終了をトレースするための mqtracingexit.conf 設定ファイルを開く。
4. HOST_ALIAS フィールドに、手順2で取得したキュー・マネージャ・ホスト名を設定します。
5. 構成ファイルを保存します。
6. 変更を適用するために高可用性キューマネージャを再起動します。