Last week I wrote about the IBM i Job Trace capabilities. In that article, I briefly mentioned that you can instrument your own application so you can collect your own trace data as part of a job trace.
A more recent article on this same topic was published in the IT Jungle; Application Tracing with the QTRC APIs.
The secret to this support is something called the “QTRC APIs,” which were introduced with the 6.1 release. These APIs are documented under the “Problem Management” category of APIs in the IBM i Knowledge Center. The QTRC API documentation section has much more information than just the programming interfaces; it discusses how you use these APIs and covers the related information you need to know to fully utilize these programming interfaces.
An important concept in how the QTRC APIs work is something called the “component.” The component is a parameter you specify on each of the QTRC APIs to identify the trace collection, and the component is the parameter on the STRTRC command that will turn trace on or off for your component. Below is the documentation taken from the Knowledge Center on a QTRC Component:
A 10-byte character string which names the application component. Each Trace Point has an associated component that is specified on the QTRC Trace APIs. The component name is also shown in the trace output for each Trace Record that is written. A component is defined to the QTRC Trace environment when specified on the Start Trace (STRTRC) CL command. Component names should only contain characters in the invariant character set. Avoid using lowercase a through z. Application component names should contain an abbreviated company name along with the application name. Component names starting with an asterisk (*) are reserved for the operating system. Component names starting with Q are reserved for IBM licensed programs.
There are three basic steps to collect diagnostic data from your application as part of a job trace:
1. Instrument your application to collect the desired diagnostic information.
This is the step that will require the most thought. What kind of data will you need for diagnostic purposes? What are the performance implications of collecting additional data? Do you have different types of data you would need for different kinds of problems?
You use the QTRC APIs to collect the data you need.
- Use the Get Active Trace Level API to determine the trace level that has been set for your component trace. This check will determine whether trace has been turned on for your component; if the required trace is not active, you can easily bypass the data collection logic in your application and avoid adding overhead to your application when trace has not been turned on.
- Based upon the trace level, you then write trace records; you can collect text data, hexadecimal data, and the call stack. The QTRC API documentation in the IBM i Knowledge Center describes how to use these APIs.
2. Collect your trace data using the STRTRC command.
The magic to using the STRTRC command to collect your own trace data is on the TRCTYPE parameter. While IBM has defined special values to start trace collection for components within the operating system, the TRCTYPE keyword is not restricted to just these special values; you can specify your own component name on the TRCTYPE parameter.
The operating system components that you can trace with the TRCTYPE parameter are using the QTRC APIs as well – the QTRC APIs allow you to instrument your applications in the exact same way that IBM developers have instrumented the operating system.
3. Interpret the collected data by printing out the trace with the PRTTRC command.
There will be trace information included automatically by the system in addition to the component-specific data you add by using the APIs.
Traces can be large so you want to ensure that you clean up after yourself. Once you have completed diagnostics with the trace data, be sure to delete the trace data with the DLTTRC command. You should also delete any spooled trace files when you are done with them as well.
Adding diagnostic information to an application can be time-consuming, but the improved diagnostic capabilities provided by having trace data can ultimately save you a lot of time when problems arise. IBM i has significant tracing capabilities built into the operating system and you can be sure that every developer thinks about how they are going to debug problems that may arise. And with the QTRC APIs, you can do the same thing with your application.
This blog post was edited for currency on February 14, 2020.
This blog post was originally published on IBMSystemsMag.com and is reproduced here by permission of IBM Systems Media.