Websphere® MQ Workflow Tracing - the essentials

Technote (troubleshooting)

Problem(Abstract)

When reporting a problem customers may be asked to run a workflow trace on part of the setup. This document provides the information necessary to understand tracing, and to successfully obtain a workflow trace of workflow components in the majority of cases.

Resolving the problem

1.0 Concepts.

System trace is the process of recording statements and instructions that are executed within a system in the sequence in which they occur.

The two main concept that need to be understood are the trace mode and the trace level. Trace mode determines the way in which trace information is captured, whereas the trace level determines how much information is captured (through progressive levels of importance).

1.1 Trace modes

There are two different trace modes:

Extended trace
Simple trace

1.1.1 Extended Trace Mode.
This is the default trace mode for workflow servers (NOTE: servers can be switched to simple trace mode if required).
With extended trace information is written to buffers in memory. This can be written out to files using the extended trace writer.

1.1.2 Simple Trace Mode
This trace mode needs to be activated.
In this mode, trace is written directly to a file (or multiple files if some further options are enabled).

1.2 Trace levels

Trace level specifies the type of trace information that is captured. Each trace statement has a level associated with it relating to the relative importance of the trace information.

1.2.1 Range

The range is from 0 for essential information to 99 the least important trace information.
0 is the default trace level.

1.2.2. Allowing trace level greater than 3
When activating traces with the checker utility (fmczchk), the -d option has to be used to allow a level higher than 3.

1.2.3 Performance

The higher the level of trace the greater the impact on performance
In order to collect useful tracing for problem determination a high trace level is usually required.
If a lower trace level is used, vital information is sometimes missing making it necessary to run trace a second time with a higher level.
In some circumstances, if the support team has already narrowed down the potential area in which the problem is occurring, they may be able to recommend further options to limit trace if is has to be run again. (dependant on individual situations)

2.0 Some tracing settings

Trace setting allow you to enable the trace mode and specify the trace level. There are also trace variables controlling the trace files produced, some of these are only available in simple trace mode.

FMC_TRACE_CRITERIA	- specifies the level of tracing - basic syntax: ,, - use 99,FFFF,FFFFFFFF unless directed to do otherwise by support.
FMC_SIMPLE_TRACE_ONLY	- used to switch to Simple trace mode
FMC_TRACE_FILE	- specifies (partial) name and the location for trace file(s). - the trace file produced will have an extension automatically added - in addition when using split tracing the process id and executable name are added to the trace file name.
FMC_SPLIT_TRACES	- this specifies that a separate trace file should be written for each OS process. - only in combination with simple trace mode - process name and ID get automatically included in trace file name.
FMC_FLIP_FLOP_TRACES	- allows to operate with 2 trace files - the backup and current trace file. The 'bak' extension is added to the backup file. - only in combination with simple trace mode - once the 'current' is full it is saved as the bak file, overwriting the previous bak file if there is one, and a new current trace file is started.
FMC_TRACE_FILE_SIZE	- this limits the trace file size. - input values will be taken as MB

3.0 Enabling tracing

Each Workflow component (executable) only checks at startup whether trace variables are set. So, even if tracing variables are set, tracing will only take place if a component is newly started.

There are two ways to enable tracing:

Using the checker utility, fmczchk

By setting appropriate environment variables.

If trace environment variables are present they take precedence over the config profile values, However using the fmczchk utility is the preferred method.

NOTE: for the new 'native' Java API (3.5 with additional support pack) tracing is only possible via the fmcrc configuration profile - this also applies to windows. There is also an initialization tracing ability for tracing startup. See this technote for details.

3.1 Setting tracing with fmczchk

3.1.1 You can set variables individually with:

fmczchk -c inst:m,, -y

examples:
fmczchk -c inst:m,FMC_TRACE_CRITERIA,99,FFFF,FFFFFFFF
fmczchk -c inst:m,FMC_SIMPLE_TRACE_ONLY,YES
fmczchk -c inst:m,FMC_TRACE_FILE,d:\tmp\workflow\fmctrc
fmczchk -c inst:m,FMC_SPLIT_TRACES,1
fmczchk -c inst:m,FMC_FLIP_FLOP_TRACES,1
fmczchk -c inst:m,FMC_TRACE_FILE_SIZE,10

3.1.2 Alternatively you can use a single 'shorthand' command for all except the simple trace.

fmczchk -dc trc:level[,file][,split][,flipflop][,filesize] -y

examples:
fmczchk -dc trc:99
fmczchk -dc trc:99,d:\tmp\workflow\fmctrc,1,1,10 -y

3.2 Setting tracing via environment variables.

Each of the tracing options (trace variables) defined in section 2.0 can be set as an environment variable.

Example for Unix:
export FMC_SIMPLE_TRACE_ONLY=YES
Example for Windows:
set FMC_TRACE_CRITERIA=99,FFFF,FFFFFFF

4.0 Disabling trace

To disable trace simply unset/remove the setting in the environment or in the configuration profile (depending on where they were set) processes need to be restarted in order for the changes to take effect.

This can be achieved in several ways

1. Explicitly set tracing to the default value:

e.g. fmczchk -c trc:0 -y
NOTE: this does not effect the trace mode.

2. Individual variables set in the profile can be removed with the checker using:

fmczchk -c inst:m, -y
Note the missing variable value
e.g. fmczchk -c inst:m,FMC_SIMPLE_TRACE_ONLY

3. Unset environment variables
e.g. (Windows) set FMC_SIMPLE_TRACE_ONLY=
e.g (AIX) unset FMC_SIMPLE_TRACE_ONLY

5.0 Tracing the configuration utility - fmczutil

During the creation of a configuration the configuration profile will not exist until all configuration parameters have been entered. Therefore if you experience a problem in fmczutil that needs to be traced you must set environment variables to enable tracing.

6.0 Trouble shooting

If you do not get a trace when expected the following should be checked:

Did you set tracing in the correct configuration? Consider the following scenario:
You are trying to obtain a client API trace. You have two configurations on the same machine, FMCSRV as the server configuration and FMCCLI as a client configuration. FMCSRV is the default configuration. You set the trace variables with the checker utility but did not specify the option -y FMCCLI. Result - tracing was enable only for the server.
Ensure the trace variables are set in the profile where the component is configured using the -y option with the checker.

Are the environment variables set in the environment where the Workflow executable/script. was started (UNIX - echo $Variable', Windows - echo %Variable%).

Did you restart the executable/script?

Is there enough space in the file system where the trace file is to be written?

Does the user under which you start workflow executables/scripts have appropriate permission's to write to the directory specified for the trace file?

7.0 Tracing - quick setup

Note: this section can be used as a quick way to obtain a trace with a very simple setup. For more complex setups and special tracing requirements please read the rest of this technote or follow directions given from the support organization.

Sequence of steps needed to trace a re-creatable problem:

1. fmczchk -c inst:m,FMC_SIMPLE_TRACE_ONLY,YES -y
2. fmczchk -dc trc:99 -y
3. Stop workflow executable/script.
4. Re-start workflow executable/script.
5. Recreate problem.
6. fmczchk -c inst:m,FMC_SIMPLE_TRACE_ONLY, -y
7. fmczchk -c trc:0 -y
8. Stop the workflow executable/script.
9. Restart the workflow executable/script.
10. Send the fmctrc.log file to us for analysis (fmctrc.log is the default trace file name)

转:http://www-01.ibm.com/support/docview.wss?uid=swg21143823

ITPub博客

Websphere® MQ Workflow Tracing - the essentials

Websphere® MQ Workflow Tracing - the essentials

最新文章