请求协助在z/OS Connect与CICS中启用分布式追踪（opentracing-1.0）

一、前置准备 #

• 确认环境组件版本兼容性：当前WAS Liberty 19.0.0.12、zCEE 3.0.3、CICS TS 5.6.0均支持OpenTracing集成
• 准备匹配Liberty 19.0.0.12版本的OpenTracing Zipkin追踪器适配包
• 确保z/OS系统TCP/IP连通性正常，可向WSO2 API-M的追踪收集端点发送数据

二、z/OS Connect（Liberty服务器）配置 #

1. 部署追踪器组件并启用特性 #

• 将Zipkin追踪器JAR包放入Liberty服务器的usr/shared/resources目录
• 在server.xml中启用OpenTracing特性，保留原有z/OS Connect特性：

<featureManager>
    <feature>opentracing-1.0</feature>
    <feature>zosconnect:apiRequester-2.0</feature>
    <!-- 其他已启用特性 -->
</featureManager>

2. 配置Zipkin追踪器参数 #

在server.xml中添加追踪器配置，指向WSO2 API-M的收集端点：

<opentracing:zipkinTracer serviceName="zosconnect-api-requester"
                         reporterEndpoint="http://<WSO2-API-M-地址>:<端口>/api/v2/spans"
                         samplerType="const"
                         samplerParam="1"/>

• serviceName：自定义服务标识，用于链路中区分z/OS Connect节点
• reporterEndpoint：替换为WSO2 API-M实际的Zipkin兼容接收地址
• samplerType+samplerParam：const+1表示全量采样，生产环境可调整为概率采样

3. 开启API请求者追踪上下文传递 #

在API请求者配置中启用追踪：

<zosconnect:apiRequester id="your-api-requester-id"
                        location="api/your-api-definition.yaml"
                        enableTracing="true"/>

三、CICS TS 5.6.0配置 #

1. 启用CICS分布式追踪 #

• 在CICS区域SIT中设置TRACETYPE=OPENTRACING
• 定义与Liberty追踪器通信的连接：

DEFINE CONNECTION(ZOSCONNECT-TRACER) GROUP(TRACEGRP)
       CONNTYPE(TCPIP)
       NETNAME('<Liberty服务器IP>')
       PORTNUMBER(<Liberty追踪端口>)

• 定义URIMAP用于通信路由：

DEFINE URIMAP(ZOSCONNECT-TRACER-URI) GROUP(TRACEGRP)
       USAGE(CICSCLIENT)
       SCHEME(HTTP)
       HOST('<Liberty服务器IP>')
       PORTNUMBER(<Liberty追踪端口>)
       PATH('/opentracing/api/v1/traces')

2. 配置zCEE通信存根的追踪传播 #

在zCEE配置文件中开启追踪上下文传递：

com.ibm.zosconnect.apistub.tracing.enabled=true
com.ibm.zosconnect.apistub.tracing.propagation.format=b3

• b3为Zipkin默认传播格式，需与Liberty追踪器配置一致

四、COBOL程序集成 #

1. 自动追踪（默认） #

CICS与zCEE集成后，COBOL程序调用API请求者时会自动生成根Span与子Span，无需额外代码即可获取基础链路数据

2. 自定义埋点（增强粒度） #

若需在关键步骤添加自定义Span，可调用zCEE的IZUACALL接口：

* 初始化自定义Span
CALL 'IZUACALL' USING FUNC-INIT-SPAN
                     SPAN-NAME('COBOL-业务处理步骤')
                     PARENT-SPAN-ID(WS-PARENT-SPAN-ID)
                     RETURNING WS-SPAN-ID.

* 为Span添加标签
CALL 'IZUACALL' USING FUNC-ADD-TAG
                     SPAN-ID(WS-SPAN-ID)
                     TAG-NAME('事务ID')
                     TAG-VALUE(WS-TRANS-ID).

* 结束Span
CALL 'IZUACALL' USING FUNC-FINISH-SPAN
                     SPAN-ID(WS-SPAN-ID).

• 确保程序已链接zCEE相关模块（如IZUACALL）

五、验证与调试 #

• 启动Liberty与CICS区域，触发COBOL事务调用API请求者
• 登录WSO2 API-M追踪控制台，检查是否生成包含CICS、COBOL、z/OS Connect节点的完整链路
• 排查日志：
  • Liberty日志messages.log中搜索ZipkinReporter确认数据发送状态
  • CICS日志MSGUSR中搜索TRACER关键字查看追踪初始化与传播情况

六、注意事项 #

• 确保Zipkin追踪器版本与Liberty 19.0.0.12兼容，避免类加载错误
• 配置z/OS系统权限：确保Liberty与CICS用户具备访问TCP/IP资源及WSO2端点的权限
• 生产环境调整采样策略：建议使用probabilistic类型并设置合理采样比例，避免追踪数据过载

内容的提问来源于stack exchange，提问作者Alon Amiramov