オンプレミス環境における IBM MQ のトレース

• IBM MQ サーバーおよびキューマネージャインスタンスをインストールおよび設定してから、 IBM MQ トレース機能をインストールおよび設定してください。

• IBM MQ トレースのサポート対象オペレーティングシステムを確認し、環境との互換性を確保してください。

• お使いのプラットフォームに応じて、サポートされている OpenSSL バージョンをインストールしてください。

  • Linux および Windows : OpenSSL 3.2.3 以降
  • AIX ： OpenSSL 3.0.16.1000 以降

• • 以下のプラットフォーム固有の要件が満たされていることを確認してください：

    • Windows : Microsoft Visual C++ 再配布可能パッケージ 2019 以降をインストールしてください。 Microsoftのウェブサイトから最新のパッケージをダウンロードしてください。

    • AIX:

      1. 次のファイル セットを含む、 XL C/C++ Runtime for AIX 17.1.3.0 以降のバージョンをインストールします。 libc++.rte、 libc++abi.rte、 そして libunwind.rte。

         ファイルセットがインストールされていることを確認するには、以下を実行してください：

         lslpp -l | grep -e libc++.rte -e libc++abi.rte -e libunwind.rte
          

      2. 以下の AIX システムライブラリのバージョンがインストールされていることを確認してください：

         • pthreads 7.2.5.203 以降
         • libc バージョン 7.2.5.206 以降

         ライブラリのバージョンを確認するには、以下を実行してください：

         lslpp -l | grep -e bos.rte.libc -e bos.rte.libpthreads

オンプレミス環境の IBM MQ でトレースを有効化する前に、 IBM MQ トレースユーザーエグジットパッケージをダウンロードして設定してください。

IBM MQ トレースユーザー・エグジット・パッケージをダウンロードするには、次の手順を完了してください：

1. Art ifactoryから IBM MQ トレースユーザー退出 .tar.gz ファイルをダウンロードしてください。 ファイルをダウンロードするには、以下の認証情報を使用してください：

   • ユーザー名: アンダースコア (_)
   • パスワード: 有効なエージェントキー

2. ダウンロードした .tar.gz ファイルを一時的な場所に解凍してください。 抽出後、ディレクトリ内に異なるプラットフォーム用のユーザー・エグジット・パッケージを5つ見つける。

3. プラットフォーム固有のユーザー・エグジット・パッケージを IBM MQ サーバーに転送してください。

4. 以下のディレクトリでユーザー・エグジット・パッケージを抽出してください：

   • Linux または AIX IBM MQ サーバー: /var/mqm/exits64
   • Windows IBM MQ サーバー: C:\ProgramData\IBM\MQ\exits64

5. 以下のファイルを exits64 ディレクトリに配置してください:

   • IBM MQ ユーザー・エグジット・バイナリ・ファイル（ IBM MQ API の呼び出しをインターセプトし、ラップされた OpenTelemetry C++ クライアント・ライブラリへの呼び出しを開始してスパンを作成する）

     • Linux そして AIX : mqtracingexit_r
     • Windows: mqtracingexit.dll

   • ラッピングされた OpenTelemetryC++ クライアントバイナリファイル（スパンのライフサイクルを管理する機能を提供し、 Instana ホストエージェントにスパンを送信します）

     • Linux そして AIX : tracelibrary.so
     • Windows: tracelibrary.dll

   • mqtracingexit.conf 設定ファイル: このファイルは、 MQ サーバー上のすべてのキューマネージャインスタンスの設定ファイルです。 キューマネージャ固有の設定ファイルを作成するには、をに mqtracingexit.conf コピーします mqtracingexit_<QMNAME>.conf。

6. 以下の手順を完了し、トレースツールが実行時に OpenTelemetry クライアント共有ライブラリを解決できることを確認してください：

   • Linux/AIX

     1. ディレクトリ /opt/instana/tracing/ibmmq/lib 内のファイルを libopentelemetry_*.so コピーしてください。

   • Windows

     1. ディレクトリ C:\ProgramData\IBM\MQ\exits64 内のファイルを opentelemetry_*.dll コピーしてください。
     2. システム環境変数ダイアログを通じて、 C:\ProgramData\IBM\MQ\exits64 ディレクトリを環境変数 PATH に追加してください。
     3. ターミナルを再起動してください。
     注: これらの手順は、 IBM MQ ユーザー（ Linux mqm および AIX 上、ならびに WindowsMQ_USER 上）および MQ サービスを起動するその他のユーザーに対して実行する必要があります。

7. 必要に応じて、互換性のある OpenSSL のバージョンをインストールしてください。 トレーサーが、必要なバージョンの OpenSSL バイナリを正しく解決できることを確認してください。 システムのメインの OpenSSL インストール環境を更新できない場合は、次のいずれかの操作を行ってください：

   • Linux または AIX ：セカンダリの OpenSSL インストールをインストールするか、その /opt/instana/tracing/ibmmq/lib ディレクトリにリンクを設定します。
   • Windows ：セカンダリの OpenSSL インストールを実行するか、または C:\ProgramData\IBM\MQ\exits64 そのディレクトリにリンクを設定します。

オンプレミス版 IBM MQ でユーザー・エグジットを有効にするには、ホスト上のすべてのキュー・マネージャ・インスタンスをトレースする場合は`/etc/cpu_trace.conf mqs.ini `を qm.ini 、特定のキュー・マネージャをトレースする場合は`/etc/cpu_trace.conf`を編集します。

ファイルは、 IBM MQ サーバーのプラットフォームに応じて以下のディレクトリに配置されています：

• Linux および AIX

  • mqs.ini: /var/mqm
  • qm.ini: /var/mqm/qmgrs/<QMNAME>

• Windows

  • mqs.ini: C:\ProgramData\IBM\MQ
  • qm.ini: C:\ProgramData\IBM\MQ\qmgrs\<QMNAME>

<QMNAME> はキューマネージャの名前です。

オンプレミス版 IBM MQ のトレース設定を行うには、次の手順を完了してください:

1. Go exits64 ディレクトリへ:

   • Linux そして AIX : /var/mqm/exits64
   • Windows: C:\ProgramData\IBM\MQ\exits64

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

    # The configuration items for IBM MQ Tracing user exit 2026.1.3
    LOG_LEVEL="error"                      # The log level of the tracing user exit, which can be set to error, warn, info, or debug. The default value is error.
    SPAN_FORMAT="instana"                  # The trace system to which the span data is sent. The default value is "instana", but you can also change it to "otel" to send the span data to an OpenTelemetry collector.
    MONITOR_LEVEL="normal"                 # The tracing level of the queue manager(s), which can be set to off, quiet, normal, or debug. The default value is normal.
    IBMMQ_FF_SEND_METRICS = "off"         # Feature flag to include message backout count metrics in trace spans. Set to "on" or "off" (default: off).
    #IBMMQ_DEST_MONITOR_LEVEL_OFF = ""     # The regex for message destinations with MONITOR_LEVEL(tracing level) off, for example: "^TMPQ.*". An example for multiple conditions: "^SYSTEM\\.AUTH\\..*|^TEMP\\.QUEUE\\..*".
    #IBMMQ_DEST_MONITOR_LEVEL_QUIET = ""   # The regex for message destinations with MONITOR_LEVEL(tracing level) quiet.
    #IBMMQ_DEST_MONITOR_LEVEL_NORMAL = ""  # The regex for message destinations with MONITOR_LEVEL(tracing level) normal. 
    #IBMMQ_DEST_MONITOR_LEVEL_DEBUG = ""   # The regex for message destinations with MONITOR_LEVEL(tracing level) debug.
    #IBMMQ_PUBSUB_SUPPORT = "off"          # The switch for the pubsub support, which can be set to on or off. The default value is off.
    #IBMMQ_RFH2_HEADERS_TO_EXPOSE = ""     # A list of message headers that should be included in the span payload, with each header separated by commas.
    #INSTANA_AGENT_HOST = "localhost"      # The Instana agent host, localhost will be used by default.
    #INSTANA_AGENT_PORT = 42699            # The Instana agent port, 42699 will be used by default.
    #INSTANA_AGENT_PROTO = "http"          # The connection type between mq tracing exit and instana agent; http and https are supported; http will be used by default.
    #HOST_ALIAS="<YOUR-HOST-NAME>"         # The host name to match with instana agent configuration.yaml.
    #LOCAL_SOURCE_ADDRESS = ""             # The local source ip address for outgoing traffic; if not specified, a local address will be automatically allocated by default.
   
    #The following three configuration items only apply when the SPAN_FORMAT is set to "otel".
    #OTLP_EXPORTER_GRPC_ENDPOINT = ""      # The grpc endpoint to which the span data is sent. The default value is "localhost:4317".
    #OTLP_EXPORTER_SSL_CACERT_PATH = ""    # The path of the CA certificate file to verify the certificate of the target OpenTelemetry collector. Used only for GRPC exporter.
    #OTLP_EXPORTER_HTTP_URL = ""           # The http url to which the span data span data is sent. For example, "http://localhost:4318:/v1/traces".
    #OTEL_EXPORTER_OTLP_HEADERS=""         # Custom headers to include in OTLP requests, formatted as key-value pairs separated by commas. For example: "api-key=secret,custom-header=value".
    #OTEL_RESOURCE_ATTRIBUTES=""           # Resource attributes to attach to all telemetry data, formatted as key-value pairs separated by commas. For example: "service.name=my-service,deployment.environment=production".

   設定パラメータの詳細については、 「設定パラメータ」 を参照してください。

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

4. キューマネージャのインスタンスを再起動します。

IBM MQ Tracing user exit の新バージョンがリリースされた場合、以下の手順でアップグレードできます:

IBM MQ でのトレースデータの収集を無効にするには、設定 mqtracingexit.con ファイルで `` を `` off に MONITOR_LEVEL 設定します。 IBM MQ トレースの設定を参照してください。

IBM MQ トレースユーザー終了を無効化するには、 IBM MQ ホストで次の手順を完了してください：

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