配置 IBM App Connect Enterprise （ACE）跟踪器

Instana 的ACE Tracing用户退出仅支持以下节点类型：

• HTTP 请求
• IBM MQ 请求
• Kafka 请求

如果要在 IBM Cloud Pak for Integration 环境中启用 CICS 请求支持，请完成以下步骤：

1. 构建一个已启用 ACE 跟踪用户退出功能的定制版 docker 镜像。
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. 提取后，在目录中找到五个不同平台的用户退出软件包。

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 服务器未通过全局安装方式安装，则您的 /var/mqsi/shared-classesIBM ACE 主机上不存在 或 C:\ProgramData\IBM\MQSI\shared-classes 目录。 在您的 IBM ACE 主机上手动创建该 C:\acetracingexit 目录 /opt/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. Go 到该 /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_PROTO 字段 INSTANA_AGENT_HOST 和。 所有 IBM ACE 实例的设置必须 SPAN_FORMAT 保持一致。
   • CICS_SUPPORT 此参数用于控制是否启用对 CICS 请求的跟踪支持。 将其设置为 on 以启用该功能，设置为 off 以禁用该功能。
   • MONITOR_LEVEL 指定 IBM ACE 的跟踪级别，可选值包括： normaloff、或 verbose。 如果 MONITOR_LEVEL 设置为 off，则不会在发出的请求中附加任何跟踪上下文。 如果将 MONITOR_LEVEL 设置为 normal，则只有当 IBM MQ 消息包含 RFH2 标头时，才会追加跟踪上下文。 如果将 MONITOR_LEVEL 设置为 verbose，则所有发出的 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 Tracing用户退出程序收集的跨段数据的主机别名。 因此，如果集成节点或集成服务器也由“ IBM ACE ”传感器进行监控，那么对 IBM ACE 的调用即可与基础设施实体建立关联。 默认情况下，将使用 IBM ACE 主机的完全合格域名 (FQDN)。 主机别名值必须与主机代理配置 YAML 文件中指定的 IBM ACE 传感器主机相匹配。 仅当“ IBM ACE ”主机的完全合格域名（FQDN）未在“ Instana ”ACE传感器配置中使用，且主机代理未位于本地“ IBM ACE ”主机上时，才需指定主机别名。 IBM ACE 传感器可以发现用于本地集成节点或集成服务器的 FQDN。

3. 保存文件并重新启动集成节点或集成服务器。

在要对其启用跟踪的其他 IBM ACE 主机上重复这些安装和配置步骤。

您可以在 Instana 用户界面中查看 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 considerations and limitations。

ACE 用户退出跟踪方法仅支持单节点环境。 不支持高可用性（HA）配置和集群环境。 对于 HA 部署或集群环境，请使用原生的 OpenTelemetry 追踪支持，而非用户退出方法。