Capturing Traces in IIB OR ACE

 

User Trace

User trace is normally used by IIB Developers to aid debugging message flow the result of each node and ESQL/Java statement is logged to the trace.

Service Trace

Service trace is - as the name suggests - normally used by IBM service teams to analyse problems. Service trace produces very detailed output the format of which is not publicly available. You will often be asked to produce a service trace as part of the PMR process. The IIB Knowledge Centre has this to say about service trace:

"..Activate service trace only when you receive an error message that instructs you to or when directed to do so by your IBM Support Center.."

Collecting "User Level" Trace for an ACE Integration Server

This method of enabling trace requires an Integration Node.

If you are using a stand-alone Integration Server, you cannot use the mqsichangetrace command.

1. 1. Start trace:
   mqsichangetrace <Int.Node> -e <Int.Server> -u -l debug -r -c 200000 
2. 2. Re-create the runtime behavior.
3. 3. Stop trace:
   mqsichangetrace <Int.Node> -e <Int.Server> -u -l none 

Additional Information

Output location

Traces are written to the Integration Server's workdir or the multi-user work path:

 - <workdir>/config/common/log

 - /var/mqsi/common/log

Performance Impact
A "user level" trace logs a high level view of message flow processing within Int.Server and therefore can have some impact to performance.
Take care when enabling trace in production and other high throughput environments.

 

Maximum file size

ACE component traces have a maximum file size.
When the maximum file size is reached, the tracing mechanism overwrites the oldest trace data.

The '-c' flag on the mqsichangetrace command overrides the maximum size for the trace, in KB.

Collecting "Service Level" Trace for an ACE Integration Node

This method of enabling trace uses the same mqsi* commands as previous versions of IBM Integration Bus (IIB).

1. Start trace:

   mqsichangetrace <Int.Node> -b -t -l debug -r -c 200000

   
   
2. Recreate the runtime behavior.
3. Stop trace:

   mqsichangetrace <Int.Node> -b -t -l none

Additional Information

Output location

Traces are written to the Integration Server's workdir or the multi-user workpath:

 - <workdir>/config/common/log

 - /var/mqsi/common/log

Performance Impact 
A "service level" trace logs the internal function calls within Int.Node processing and therefore can have an impact to performance. 
Take care when enabling trace in production and other high throughput environments.

 

Maximum file size

ACE component traces have a maximum file size. 
When the maximum file size is reached, the tracing mechanism will begin to overwrite the oldest trace data.

The '-c' flag on the mqsichangetrace command, or the traceSize in the node.conf.yaml file, overrides the maximum size for the trace, in KB.

 

Capturing startup events

The mqsichangetrace command can be run with the Int.Node stopped. 
Updating the node.conf.yaml file requires the Int.Node to be restarted. 
Enabling trace in either of these ways will trace startup activities.

We can enable trace for JDBC, ODBC, HTTP listener, SSL, Java etc.  see below link-

https://www.ibm.com/support/pages/index-app-connect-enterprise-and-ibm-integration-bus-trace-directions

https://www.ibm.com/support/pages/tracing-and-debugging-iib-message-flows-0

Service Trace --

mqsichangetrace ACEORNG-TEST -e TGCS_HTTPS_PROXY -t -l debugTree -r -c 200000 

[aceuser@~]$ mqsichangetrace ACEORNG-TEST -e TGCS_HTTPS_PROXY -t -l debugTree -r -c 200000

BIP8071I: Successful command completion.

[aceuser@~]$ mqsireporttrace ACEORNG-TEST -e TGCS_HTTPS_PROXY

trace

  userTrace

    level='none'

    traceSizeKb=1048576

    mode='safe'

  serviceTrace

    level='debugTree'

    traceSizeKb=200000

    mode='safe'

    stopOn=''

  traceNodes

    enabled='on'

BIP8071I: Successful command completion.

[aceuser@~]$

[aceuser@~]$ mqsichangetrace ACEORNG-TEST -e TGCS_HTTPS_PROXY -t -l none

BIP8071I: Successful command completion.

[aceuser@tuat2ace01 ~]$ mqsireporttrace ACEORNG-TEST -e TGCS_HTTPS_PROXY

trace

  userTrace

    level='none'

    traceSizeKb=1048576

    mode='safe'

  serviceTrace

    level='none'

    traceSizeKb=200000

    mode='safe'

    stopOn=''

  traceNodes

    enabled='on'

BIP8071I: Successful command completion.

[aceuser@~]$

Overriding UDP - External Variable Properties in IBM IIB OR ACE

 

As we all know we have different types of variables available in ESQL which we can define, use and modify during flow processing.

But there are certain challenges with UDP - user defined properties that we also know as External Variables.

These variables holds static values and we have very limited options to modify them once the flow is deployed.

So lets explore those options -

1. First and foremost option to override them before you deploy the flow using toolkit BAR builder or using mqsiapplybaroverride command

2. if in case you have deployed the flow/bar and you do not wish to update the property and redeploy the flow, then you can use WebUI to update the UDP value - 

But you will face another challenge with this as it will not persist the updated UDP value permanently.

The update value would only be available until you redeploy the flow, or application is restarted or the integration server is restarted.

So how can we persist the updated value? 

we have to update settings/configuration for the integration server by modifying the UserVariables section in the server.conf.yaml file

UserVariables: udp-persist-global-overrides: true

Independent Integration Server in IBM ACE 12

 To work with an independent integration server in ACE 11/12, we can follow below steps-

1. First of all we need to have work directory created/configured for the integrations server where it will have all the configuration files deployed artifacts etc.

To do so we need to run - mqsicreateworkdir command which needs the work dir location/path, see in below snap shot -

2. After its successful, you can go to the dir location and can see all the required dependencies, configured in the dir, which you can modify according to your need.

3. Now to run an integration node using above created work dir, we can use below command -

IntegrationServer --name MyTestIS1 --work-dir "D:\ACE_Workspace\IS-Workspace"

you can see a directory created for the integration server in the config dir under the work dir -

4. As we have not changed the required configuration for the Integration server to start on, like http listener port, admin rest api port, debug port etc, the integration server was not able to initialize successfully.

To do so, we can either run commands or edit the server.config.yaml  file or we can run the IntegrationServer command wit these parameters - as below -

Now you can see in web browser using the rest admin port as below -

Important note :

when you run the IntegrationServer command, the terminal will be on a hault  and no further command can be run on the same terminal, is you terminate the command or the terminal it will stop the server and you will no longer be able to access it.

See below snapshots - 

Handling BLOB message(xml data as blob) in Esql

                                 Parsing XML data from a blob message




/** input of this sample is a XML message 
                 ** <XmlCollection>
                 **<Collection>3c546573743e48656c6c6f20507269796573683c2f546573743e</Collection>
                 **</XmlCollection>

Collection is a XML data in hexadecimal (BLOB) representation
Create an element of type parser

**/

CREATE LASTCHILD OF OutputRoot DOMAIN 'XMLNSC' NAME 'XMLNSC';
-- Create the root tag element of your output XML
CREATE LASTCHILD OF OutputRoot.XMLNSC NAME 'RootTag';

IF EXISTS(InputRoot.BLOB[]) THEN
------<Test>Hello Priyesh</Test>---
CREATE LASTCHILD OF OutputRoot.XMLNSC.RootTag.RecSec PARSE(CAST(InputRoot.BLOB.BLOB AS BLOB) OPTIONS FolderBitStream CCSID 1208 FORMAT 'XMLNSC');

ELSE



DECLARE ptrCollection REFERENCE TO InputRoot.XMLNSC.XmlCollection.Collection;
WHILE LASTMOVE(ptrCollection) DO
--Parse the BLOB into XML using the PARSE function
CREATE LASTCHILD OF OutputRoot.XMLNSC.RootTag.RecSec PARSE(CAST(ptrCollection AS BLOB) OPTIONS FolderBitStream CCSID 1208 FORMAT 'XMLNSC');
MOVE ptrCollection NEXTSIBLING;
END WHILE;

END IF;




 Parsing XML data into blob message



/***
****  Sample input to convert into BLOB
--------------------------
<Orders>
<Order>
<OrderDetails>
<OrderID>1234</OrderID>
<NumOfItems>2</NumOfItems>
<TotalAmount>3000</TotalAmount>
<OrderDate>07/13/2017</OrderDate>
</OrderDetails>
</Order>
<Order>
<OrderDetails>
<OrderID>1235</OrderID>
<NumOfItems>4</NumOfItems>
<TotalAmount>6000</TotalAmount>
<OrderDate>07/13/2017</OrderDate>
</OrderDetails>
</Order>
</Orders>
------------------------
****/

--- creating blob message domain

CREATE LASTCHILD OF OutputRoot DOMAIN 'BLOB' NAME 'BLOB';

--creating blob root for the message

CREATE LASTCHILD OF OutputRoot.BLOB NAME 'BLOB';

-- creating a reference to the blob message root.

DECLARE refBlob REFERENCE TO OutputRoot.BLOB.BLOB;

-- assigning message data by converting it into blob using ASBITSTREAM function-

SET refBlob = ASBITSTREAM(InputRoot.XMLNSC.*[>] OPTIONS FolderBitStream CCSID 1208);


--- Creating Environment variable to get the xml data back for verification whether previous conversion was successful
----and contains data properly.

CREATE LASTCHILD OF Environment DOMAIN 'XMLNSC' NAME 'XMLNSC';

CREATE LASTCHILD OF Environment.XMLNSC  PARSE(CAST(OutputRoot.BLOB.BLOB AS BLOB) OPTIONS FolderBitStream CCSID 1208 FORMAT 'XMLNSC');



Output :