Starting the global trace

The Db2 global trace can be started automatically at startup (by parameters that are specified during the installation action or migration process) or with the -START TRACE(GLOBAL) command.

Begin program-specific programming interface information.

The global trace provides data related to the major functional and exceptional events that are taking place within Db2. When a trace is started, Db2 assigns it a trace number (TNO) from 1 to 32. This number mask is displayed in the standard trace record header externalized to SMF or GTF.

Specify GLOBAL when starting a trace to distinguish the Db2 global trace from other trace types, as displayed in the following example:

-START TRACE(GLOBAL)

When you install or migrate Db2, start a collection of global serviceability data. The events recorded by a Db2 global trace are identified by event identifiers (EIDs). EIDs appear in the global trace records that Db2 externalizes.

Limiting the scope of the global trace

Several keywords can be specified to limit the scope of the global trace to aid in diagnosis.

CLASS
Class or classes of events that the trace monitors
DEST
Destination or destinations to which trace data is sent
PLAN
Specific Db2 plan or plans that the trace monitors
AUTHID
Specific authorization ID or IDs that the trace monitors
RMID
Specific resource manager or managers that the trace monitors
IFCID
Instrumentation facility component identifier (IFCID) that the trace monitors
LOCATION
Specific location that the trace monitors

The COMMENT keyword does not limit the trace scope but rather defines its purpose. The TDATA keyword specifies which headers are to placed on each record (unless the record destination is RES).

Multiple traces

One -START TRACE command can invoke several traces, depending on the keywords and parameters used.

  • Multiple parameters specified for PLAN or AUTHID invoke multiple traces. The following command invokes three traces:
    -START TRACE(GLOBAL) AUTHID(USER1,USER2,USER3)

    These traces can be displayed and stopped individually or collectively.

  • Multiple parameters specified for CLASS, DEST, or RMID invoke only one trace. The following command invokes one trace:
    -START TRACE(GLOBAL) DEST(SMF,GTF)

    An individual class or destination that was started by this command cannot be displayed or stopped.

Specifying a class

The CLASS keyword specifies a particular class or type of trace events for global trace.

  • Class 1. Reserved for major functions and exceptions
  • Class 2. Utility tracing and reserved for medium functions
  • Class 3. All other module entries/exits
  • Class 4. Reserved
  • Class 5. Reserved
  • Class 6. Reserved for installation use with IFI
  • Class 7. For distributed events
  • Class 8. For tracing SQL statements for distributed events at the requesting and responding locations.
  • Class 9. For tracing DDF diagnostics information.
  • Class 10. For tracing detailed DBM1 storage usage information.

The default on the global trace command is to start trace classes 1, 2, and 3. CLASS normally should not be specified for global trace.

Important: Global trace classes 1, 2, and especially 3 can significantly degrade system performance and can produce an enormous amount of data if externalized to GTF or SMF.

If class 7 is specified, the following events are traced:

  • VTAM® exits to Db2
  • All VTAM calls/returns
  • Buffer sent/received
  • Conversation allocation request queued in Db2.

If class 8 is specified the following events are traced:

  • Requesting location SQL statements before modification
  • Both requesting and responding location SQL statements after modification.

Specifying a destination

The DEST keyword specifies the location to which global trace data is sent.

Destinations include:

  • RES—Resident trace table
  • GTF—Generalized Trace Facility
  • OPn—Destination for trace output
  • SMF—System Management Facility
  • SRV—Serviceability Routine.

The default destination is the resident trace table (RES), which is located above the line in the extended common service area (ECSA). The installation defined parameter TRACTBL determines if the RES exists and its size. Global trace data can also be sent to GTF, SMF, or OPn (where n is a value from 1 to 8 that corresponds to a specific destination). SMF is not recommended. SRV is reserved for IBM® service personnel.

When specifying a location with the DEST keyword, use the appropriate abbreviation. For example, specify DEST(GTF) — not DEST(generalized trace facility):

-START TRACE(GLOBAL) DEST(GTF)

Trace data can be sent to more than one destination. This example sends data to both RES and GTF:

-START TRACE(GLOBAL) DEST(GTF,RES)

Specifying a plan

The PLAN keyword limits the trace to the activity of a particular Db2 plan or plans. Up to eight plan names can be specified. The default is an asterisk (*), which invokes the trace for all plans.

If more than one plan is specified, several traces are invoked. This example invokes a trace for SAMPLE1 and a trace for SAMPLE2.

-START TRACE(GLOBAL) PLAN(SAMPLE1,SAMPLE2)

If traces are invoked for more than one plan, specify only one authorization ID.

Specifying an authorization ID

The AUTHID keyword limits the trace to the activity of up to eight authorization IDs. The authorization IDs specified must be the primary authorization IDs. The default is an asterisk (*), which invokes the trace for all current primary authorization IDs.

If more than one authorization ID is specified, several traces are invoked. This example invokes one trace for USER1 and one trace for USER2.

-START TRACE(GLOBAL) AUTHID(USER1,USER2)

If traces are invoked for more than one authorization ID, specify only one plan.

Specifying a resource manager

The RMID keyword limits the trace to the activity of a particular Db2 resource manager. Up to 8 resource managers can be specified. The default is an asterisk (*), which invokes the trace for any resource manager.

The following table identifies the RMIDs for a global trace.

Table 1. Resource manager identifiers (RMIDs)
RMID Dec(Hex) Resource Manager
1(01) Initialization procedures
2(02) Agent services management
3(03) Recovery management
4(04) Recovery log management
6(06) Storage management
7(07) Subsystem support for allied memories
8(08) Subsystem support for SSI functions
9(09) Reserved
10(0A) Buffer management
11(0B) Reserved
12(0C) System parameter management
13(0D) Precompiler
14(0E) Data management
15(0F) Reserved
16(10) Instrumentation commands, trace, and dump services
17(11) LOB management
18(12) Data space management
19(13) Data Space management, AMS subcomponent
20(14) Service controller
21(15) Database utilities
22(16) Relational database support
23(17) General command processing
24(18) Message generator
25(19) Distributed Relational Data System Manager
26(1A) Instrumentation accounting and statistics
27(1B) Distributed Communications Resource Manager
28(1C) Distributed Transaction Manager (DDF address space)
29(1D) Distributed Data Interchange Services
30(1E) Distributed Transaction Manager (DSCF address space)
31(1F) Group Manager

Unlike the PLAN and AUTHID keywords, more than one trace does not start if more than one RMID is specified. This example invokes a single trace for 5 resource managers:

-START TRACE(GLOBAL) RMID(1,7,14,18,24)

Specifying an IFCID

The IFCID keyword specifies an optional IFCID (trace event) to start.

When a trace type is specified, then all valid IFCIDs and classes for the trace type specified in the START TRACE command are started.

Specifying a location

The LOCATION keyword limits the trace to the activity of those threads that are connected to remote locations, that is, it limits the trace to threads involved in distributed processing.

Only trace records at the local location are recorded. Up to eight location names can be specified. The default is LOCATION(*), which invokes the trace for any thread, whether or not it is connected to a remote location.

If more than one location is specified, several traces are invoked. The following example invokes a trace for threads connected to LOC1 and a trace for threads connected to LOC2.

-STA TRACE(GLOBAL) LOCATION(LOC1,LOC2)

If traces are invoked for more than one location, you can specify only one plan and one authorization ID.

Specifying a comment

The COMMENT keyword enables you to append a descriptive phrase to trace data sent to SMF or GTF. This information helps in distinguishing between several traces.

In SMF or GTF, comments appear within the record that documents that a 'start trace' occurred. In RES, the comment does not appear.

Enter any character string for the comment, but blanks, commas, and special characters must be enclosed in apostrophes. For example, specify:

-START TRACE(GLOBAL) DEST(GTF)
   COMMENT('INVESTIGATE SQL LOOP')

This command starts a global trace and sends the data to GTF. The trace start record (IFCID 0004) written to GTF shows a trace has been started and contains the comment 'INVESTIGATE SQL LOOP'.

Specifying the trace record header

The TDATA keyword specifies the type of product section header that is placed in the product section of each trace record. The default for a global trace is a trace header.

A TDATA specification indicates what information is appended to the record. If you want a trace header, then you must specify one. You can also indicate one of the following values:

  • COR to place a correlation header on the record.
  • CPU to place a CPU header on the record. The CPU header contains the current CPU time for the z/OS® TCB or SRB executing.
  • TRA to place the trace header on the record
  • DIST to place the distributed header on the record.

End program-specific programming interface information.