Fix Readme
Abstract
The document describes how to install and enable IBM App Connect Enterprise tracing on your IBM App Connect Enterprise hosts. The tracing data can be sent to Instana or Jaeger depending on the configurations. Current version of IBM ACE Tracing user exits is 2023.1.0.
Update Name/Fix ID: IBM-ACE-TRACING-USER-EXIT
Content
Download location
http://www.ibm.com/support/fixcentral/
Fix Download for Linux
Product / Component Name | Platform | Fix |
IBM App Connect Enterprise Tracing User Exit |
AIX pSeries
Linux x86_64 Linux ppc64le Linux s390x Windows
|
IBM-ACE-TRACING-USER-EXIT |
Prerequisites and co-requisites
This is a technical preview for enabling IBM App Connect Enterprise tracing capability. You can download user exit implementation and configure your IBM App Connect Enterprise integration server to enable tracing. The tracing data is sent to Instana or Jaeger depending on your configuration.
Platforms and prerequisites
Known limitations
Known issues
Installing
- ACEOpenTracingUserExit.lel: The IBM App Connect Enterprise User Exit, intercepting the HTTP request, IBM MQ request, and Kafka request, and invoking the wrapped OpenTelemetry C++ client library to create spans.
- tracelibrary.so: The wrapped OpenTelemetry C++ client, provides functions to manage the lifecycle of spans and sends spans to the target tracing system.
- acetracingexit.conf: The configuration file to specify the target tracing system (Jaeger or Instana) and the parameters for span generation.
Configuring
Configuring User Exit
Complete the following steps to enable tracing for IBM App Connect Enterprise.
mqsistop <integrationNodeName>
mqsichangeflowuserexits <integrationNodeName> -o -x /var/mqsi/shared-classes
- Activate the user exit for an integration node.
mqsichangeflowuserexits <integrationNodeName> -o -a ACEOpenTracingUserExit
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.
mqsistart <integrationNodeName>
- Activate the user exit for an integration server:
mqsistart <integrationNodeName>
mqsichangeflowuserexits <integrationNodeName> -e <integrationServerName> -a ACEOpenTracingUserExit
- Activate the user exit for a message flow.
mqsistart <integrationNodeName>
mqsichangeflowuserexits <integrationNodeName> -e <integrationServerName> -k <applicationName> -f <messageFlow> -a ACEOpenTracingUserExit
Configuring IBM App Connect Enterprise tracing
2. Edit acetracingexit.conf file.
Where:
LOG_LEVEL
specifies the log level, which can be eitherinfo
,warn
,error,
ordebug
. The log file is located at /tmp/trace directory.SPAN_FORMAT
specifies where the span data is sent. The SPAN format can be set toinstana
orjaeger
. IfSPAN_FORMAT
is set toinstana,
span data is sent to Instana and you can ignoreJAEGER_*
parameters in acetracingexit.conf file. IfSPAN_FORMAT
is set tojaeger
, you need to configureJAEGER_*
parameters. You must use the sameSPAN_FORMAT
setting for all IBM App Connect Enterprise instances.MONITOR_LEVEL
specifies the tracing level of IBM ACE, which can be one of the following,off
,normal
, orverbose
. IfMONITOR_LEVEL
is set tooff
, then tracing context is not appended to outgoing request. IfMONITOR_LEVEL
is set tonormal
, then tracing context will be appended only when the IBM MQ message includes the RFH2 header. IfMONITOR_LEVEL
is set toverbose
, then the tracing context will be appended to all outgoing HTTP/MQ requests.INSTANA_AGENT_HOST
specifies the agent host where the Instana format span data is sent to, localhost is used by default. If you specify a remote agent host, you also need to add a linehttp.listen=*
in<instana-agent-dir>/etc/instana/com.instana.agent.main.config.Agent.cfg
for the remote host agent first as the host agent is not reachable from other hosts by default.INSTANA_AGENT_PROTO
specifies the connection type between IBM ACE tracing user exit and the host agent, andhttps
are supported,http
is used by default. If you want to change it tohttps
, you need to follow Setup TLS Encryption for Agent Endpoint to secure the Instana agent endpoint first.HOST_ALIAS
specifies a host alias for the span data that is collected by IBM ACE Tracing user exit, so calls to IBM ACE can be linked to the infrastructure entity if the integration node or integration server is also monitored by the IBM ACE sensor. The FQDN of IBM ACE host is used by default. The host alias value must match with the IBM ACE host that is specified in host agent configuration yaml. You only need to specify a host alias if the FQDN of IBM ACE host is not used in IBM ACE sensor configuration when the host agent is not on the local IBM ACE host. The IBM ACE sensor can discover the FQDN for the local integration nodes or integration servers.
Unconfiguring
- Unconfigure user exit for an integration node.
mqsistop <integrationNodeName>
mqsichangeflowuserexits <integrationNodeName> -o -a ""
- Deactivate user exit for an integration server.
mqsichangeflowuserexits <integrationNodeName> -e <integrationServerName> -a ""
- Deactivate user exit for a message flow.
mqsichangeflowuserexits <integrationNodeName> -e <integrationServerName> -k <applicationName> -f <messageFlow> -a ""
Troubleshooting
Additional information
Document change history
Version | Date | Description of change |
1.0 | 24 Aug 2021 | Initial Version. |
1.1 | 29 Sec 2021 | Update trace library path. |
2.0 | 18 Mar 2022 | Updated IBM ACE Tracing user exits version to 2022.1.0. |
3.0 | 11 Apr 2022 | Updated IBM ACE Tracing user exits version to 2022.1.0, added support for AIX 7.2. |
4.0 | 19 May 2022 | Updated IBM ACE Tracing user exits version to 2022.2.0, added support for Linux s390x. |
4.1 | 21 Jun 2022 | Changed the sequence of msgFlowTransaction span and added MQ message RFH2 header detection. |
5.0 | 01 Aug 2022 | Updated IBM ACE Tracing user exits version to 2022.3.0, added support for Linux ppc64le and AIX 7.3. |
5.1 | 28 Oct 2022 | Fixed an issue that failed to associate with the upstream application when ACE server received a request only including W3C tracing format. |
5.2 | 1 Dec 2022 | Updated IBM ACE Tracing user exits version to 2022.4.2. Added support for Windows. Upgraded the openssl version to 1.1.1s. |
5.3 | 27 Feb 2023 |
Updated IBM ACE Tracing user exits version to 2023.1.0.
Enriched tracing call tags information for HTTP sync request/reply node.
Enhanced HTTP async request node support.
Fixed an issue that incorrect HTTPRequestHeader cause message flow execution failed.
|
5.4 | 19 May 2023 | The HTTP request header `X-INSTANA-T` and the IBM MQ message header `X_INSTANA_T`, which contain the Instana trace ID, are changed to 16 characters in length. |
Was this topic helpful?
Document Information
Modified date:
19 May 2023
UID
ibm16483297