This is part of a series of small blog posts which will cover some of the smaller, perhaps less likely to be noticed, features of IBM MQ. Read other posts in this series.

While I've certainly captured many IBM MQ traces in my time, almost all of them have been taken with the default set of parameters on the strmqtrc command. Very occasionally I might add -t all -t detail, but that was pretty much the limit of my use of the command. I suspect this is because I was always taking traces on a fairly small system, which was already only doing what I needed to trace. There was no additional work going on in other processes, or other queue managers, and I had no concern about any performance cost or storage requirement of capturing trace that I didn't actually need.

When you have a production system showing an error and you can't replicate it on a testing system, you need to be more targeted with your tracing. IBM Service will very often assist in creating the tracing command you need, but I thought it would be interesting to take a look at all the different ways trace can be filtered down to only capture what is needed and reduce the impact, both in performance, and in storage requirement of the captured trace.

If you look in Knowledge Center there are lots of parameters on the strmqtrc command. They can be grouped into the following sections.

strmqtrc [scope] [type] [data] [size] [trigger] [end] 

Scope

You can filter the scope of tracing down to avoid tracing processes that are not relevant to your current investigation. This can include only tracing one, or a few, of your queue managers. The -m MQG1 parameter would trace only queue manager MQG1, and the -m "MQG*" parameter would capture all queue managers matching the pattern. I've quoted the string containing the asterisk because otherwise it can get processed by some shells on Unix. You can also used the '?' character as a wildcard for a single character.

Further to targeting only specific queue managers, you can also target only specific processes in those queue managers, by name, using the -p parameter. Here you specify a name or comma-separated list of names of processes to be traced.

For example, strmqtrc -m MQG1 -p amqrmppa

You can also target processes by Process ID (PID) and within that MQ Thread ID (TID) which might be useful when there are multiple processes with the same name, and you know exactly which one you want. This is done using the -i parameter.

Finally in this section, and not combinable with any of the above, you can request early tracing of all processes with the -e parameter. This makes it possible to trace the creation of startup of a queue manager. By default this flag is off and must be explicitly requested.

Type

There are a large number of types that you can select (or deselect) for tracing. You use the -t parameter (repeatedly) to select them and the -x parameter (repeatedly) to exclude them. For the most part you'll likely be guided by IBM Service to choose which types are needed to diagnose a problem, but some might be useful for your own purposes, for example strmqtrc -t api -p MyAppName if you're trying to figure out exactly what your application is doing.

In addition to the various types, there are two values for the -t parameter that aren't types but detail levels. You can use -t detail to request high-detail tracing, and omit it or specify -t parms to request default-detail tracing.

Data

You can configure how much user data is traced. This includes message data in communication trace and message buffers on MQPUT and MQGET calls. You can choose to have no user data traced at all with -d 0, trace it all with -d all or specify a number of bytes.

Size

You can control how much space your trace takes up, first by restricting the number of processes that are traced with the scope settings, and secondly by setting a maximum size of a trace file in MB using the -l parameter. This can be a number between 1 and 2048. If your trace file reaches this maximum size it will be renamed to a .TRS file and a new one created with the .TRC name. Older .TRS files of the same name will be deleted as part of this process.

Trigger

You can have tracing begin when a certain condition is reached. A "condition" is an FDC. To indicate which conditions you are interested in, you supply a comma separated, wildcarded if necessary, list of Probe IDs using the -b FDC=.

Starting trace at the time of an FDC isn't as late as it may sound, as the FDC file also contains 200 trace points that are captured leading up to the FDC which can augment what is recorded in the trace.

End

You can trigger the end of tracing just like the starting above, with a list of FDC probe ids, this time using the -c FDC= parameter. Or alternatively you can indicate you want tracing to end after a certain time interval, in seconds, has passed. You don't have to combine this with a trigger start, you could just start some tracing now, and say you want it to run for a certain time period. For example, strmqtrc -m MQG1 -c interval=30

Tracing IBM MQ doesn't have to be all or nothing. As you can see there are lots of ways to filter it down and reduce some of the impact of a necessary evil.