-START TRACE (DB2)
The DB2® command START TRACE starts DB2 traces.
An additional option for this command and additional values for a few other options exist. This additional information is intended for service and use under the direction of IBM® Software Support.
Abbreviation: -STA TRA
Environment
This command can be issued from a z/OS® console, a DSN session, a DB2I panel (DB2 COMMANDS), an IMS™ or CICS® terminal, or a program using the instrumentation facility interface (IFI).
Data sharing scope: Group or local, depending on the value of the SCOPE option.
Authorization
- TRACE privilege
SQLADM authority
- System DBADM authority
- SYSOPR authority
- SYSCTRL authority
- SYSADM authority
- SECADM authority
DB2 commands that are issued from a logged-on z/OS console or TSO SDSF can be checked by DB2 authorization using primary and secondary authorization IDs.
Syntax
>>-START TRACE--(-+-PERFM---+-)--+-------------------------+----> +-ACCTG---+ | .-,-------. | +-STAT----+ | V | | +-AUDIT---+ '-DEST--(----+-GTF-+-+--)-' '-MONITOR-' +-SMF-+ +-SRV-+ +-OPn-+ '-OPX-' >--+----------------------+--+---------------------+------------> '-| constraint block |-' '-| filtering block |-' >--+------+--+-----------------+--+---------------------+------>< '-RMID-' '-COMMENT(string)-' | .-LOCAL-. | '-SCOPE-(-+-GROUP-+-)-'
constraint block >>-+-------------------------------+----------------------------> | .-*-----------------. | | | .-,---------. | | | | V | | | '-PLAN(-+---plan-name-+-----+-)-' '-partial-plan-name-' >--+----------------------------------------+-------------------> | .-*------------------------. | | | .-,----------------. | | | | V | | | '-PKGLOC(-+---package-location-+-----+-)-' '-partial-package-location-' >--+---------------------------------------------+--------------> | .-*-----------------------------. | | | .-,---------------------. | | | | V | | | '-PKGCOL(-+---package-collection-id-+-----+-)-' '-partial-package-collection-id-' >--+---------------------------------------------+--------------> | .-*----------------------------. | | | .-,--------------------. | | | | V | | | '-PKGPROG(-+---package-program-name-+-----+-)-' '-partial-package-program-name-' >--+----------------------------------------+-------------------> | .-*------------------------. | | | .-,----------------. | | | | V | | | '-AUTHID(-+---authorization-id-+-----+-)-' '-partial-authorization-id-' >--+--------------------------+---------------------------------> | .-*-----------. | | | .-,-------. | | | | V | | | '-CLASS(-+---integer-+-+-)-' >--+-----------------------------------+------------------------> '-LOCATION(-+-*-----------------+-)-' | .-,-------------. | | V | | +---location-name-+-+ +-<luname>----------+ +-partial-<luname>*-+ +-ipaddr------------+ '-partial-ipaddr----' >--+------------------------------+-----------------------------> | .-*--------------. | | | .-,------. | | | | V | | | '-USERID(-+---userid-+-----+-)-' '-partial-userid-' >--+-----------------------------------------+------------------> | .-*------------------------. | | | .-,----------------. | | | | V | | | '-APPNAME(-+---application-name-+-----+-)-' '-partial-application-name-' >--+----------------------------------------+-------------------> | .-*------------------------. | | | .-,----------------. | | | | V | | | '-WRKSTN(-+---workstation-name-+-----+-)-' '-partial-workstation-name-' >--+------------------------------------------+-----------------> | .-*--------------------------. | | | .-,------------------. | | | | V | | | '-CONNID(-+---connection-role-id-+-----+-)-' '-partial-connection-role-id-' >--+--------------------------------------+---------------------> | .-*----------------------. | | | .-,--------------. | | | | V | | | '-CORRID(-+---correlation-id-+-----+-)-' '-partial-correlation-id-' >--+----------------------------------------+-------------------> | .-*--------------------------. | | | .-,---------------. | | | | V | | | '-ROLE(-+---connection-role-+--------+-)-' '-partial-connection-role-id-' >--+------------------------+--+------------------------+-------> | .-*---------. | | .-*-------. | | | .-,-----. | | '-BUFSIZE(-+-k_bytes-+-)-' | | V | | | '-IFCID(-+---ifcid-+-+-)-' >--+-------------------------------------+----------------------> | .-,---------------. | | (1) V | | '-AUDTPLCY----(-----policy-name---+-)-' >--+------------------------------+--+---------------+--------->< | .-,---------------. | '-ASID(x'dddd')-' | V | | '-TDATA(---+-CORRELATION-+-+-)-' +-TRACE-------+ +-CPU---------+ '-DISTRIBUTED-'
- You cannot specify CLASS or IFCID with AUDTPLCY. AUDTPLCY applies to trace type AUDIT.
filtering block >>-+--------------------------------+---------------------------> | .-,---------. | | V | | '-XPLAN(-+---plan-name-+-----+-)-' '-partial-plan-name-' >--+-----------------------------------------+------------------> | .-,----------------. | | V | | '-XPKGLOC(-+---package-location-+-----+-)-' '-partial-package-location-' >--+----------------------------------------------+-------------> | .-,---------------------. | | V | | '-XPKGCOL(-+---package-collection-id-+-----+-)-' '-partial-package-collection-id-' >--+----------------------------------------------+-------------> | .-,--------------------. | | V | | '-XPKGPROG(-+---package-program-name-+-----+-)-' '-partial-package-program-name-' >--+-----------------------------------------+------------------> | .-,----------------. | | V | | '-XAUTHID(-+---authorization-id-+-----+-)-' '-partial-authorization-id-' >--+-----------------------------------+------------------------> | .-,-------------. | | V | | '-XLOC(-+---location-name-+-----+-)-' +-partial-location-name-+ +-<--luname-->----------+ +-partial-<luname>*-----+ +-ipaddr----------------+ '-partial-ipaddr--------' >--+-------------------------------+----------------------------> | .-,------. | | V | | '-XUSERID(-+---userid-+-----+-)-' '-partial-userid-' >--+------------------------------------------+-----------------> | .-,----------------. | | V | | '-XAPPNAME(-+---application-name-+-----+-)-' '-partial-application-name-' >--+-----------------------------------------+------------------> | .-,----------------. | | V | | '-XWRKSTN(-+---workstation-name-+-----+-)-' '-partial-workstation-name-' >--+-------------------------------------------+----------------> | .-,------------------. | | V | | '-XCONNID(-+---connection-role-id-+-----+-)-' '-partial-connection-role-id-' >--+---------------------------------------+--------------------> | .-,--------------. | | V | | '-XCORRID(-+---correlation-id-+-----+-)-' '-partial-correlation-id-' >--+-----------------------------------------+----------------->< | .-,---------------. | | V | | '-XROLE(-+---connection-role-+--------+-)-' '-partial-connection-role-id-'
Option descriptions
You must specify a trace type.
- ( PERFM )
- The performance trace is intended
for performance analysis and tuning. This trace includes records of
specific events in the system, including events related to distributed
data processing. The data can be used for program, resource, user,
and subsystem-related tuning.
Abbreviation: P
- ( ACCTG )
- The accounting trace records transaction-level data that is
written when the processing for a transaction is completed. It provides data that enables you to
conduct DB2 capacity planning and to tune
application programs.
Abbreviation: A
- ( STAT )
- The statistics trace collects statistical data that is broadcast
by various components of DB2 at certain
time intervals. You can specify intervals for statistics collection during installation.
Abbreviation: S
LOCATION cannot be specified when you choose a statistics trace.
- ( AUDIT )
- The audit trace collects information about DB2 security controls and can be used to ensure that
data access is allowed only for authorized purposes.
Abbreviation: AU
- ( MONITOR )
- The
monitor trace enables attached monitor programs to access DB2 trace data through calls to the instrumentation
facility interface (IFI). Monitor programs can access the trace data asynchronously through an
OPx buffer by issuing READA requests, or synchronously in the monitor return area
by issuing READS requests.
Abbreviation: MON
- SCOPE
- Specifies the scope of the command in a data sharing group.
- (LOCAL)
- Specify to start traces on the local member only.
- (GROUP)
- Specify to start traces on all members of the data sharing group.
- ASID(x'dddd')
- Specifies the address space for which trace data is collected.
dddd is a four-byte hexadecimal address space ID (ASID).
- COMMENT(string)
- Gives a comment that is reproduced in the trace output (except in the resident trace
tables). This option can be used to record why the command was issued.
string is any character string; it must be enclosed between apostrophes if it includes a blank, comma, or special character.
- RMID
- Specifies resource manager identifier. You can specify up to 8 valid RMIDs, which are one or two digit identifiers. You cannot specify RMID for accounting or statistic traces.
- DEST
- Specifies where the trace output is to be recorded. You can use more than one value, but
do not use the same value twice. If you do not specify a value, the trace output is sent to the
default destination shown in the following table.
If the specified destination is not active or becomes inactive after you issue the START TRACE command, you receive message DSNW133I, which indicates that the trace data is lost. This applies for destinations GTF, SRV, and SMF. You also receive this message for destinations OPn and OPX if START TRACE is not issued by an application program.
Abbreviation: D
The allowable values and the default value depend on the type of trace started, as shown in the following table.Table 1. Allowable destinations for each trace type Type GTF SMF SRV OPn OPX PERFM Default Allowed Allowed Allowed Allowed ACCTG Allowed Default Allowed Allowed Allowed STAT Allowed Default Allowed Allowed Allowed AUDIT Allowed Default Allowed Allowed Allowed MONITOR Allowed Allowed Allowed Allowed Default The meaning of each value is as follows:- GTF
- The z/OS generalized trace facility (GTF). The record identifier for records from DB2 is X'0FB9'.
- SMF
- The system management facility. The SMF record type of DB2
trace records depends on the IFCID record, as follows:
- IFCID record
- SMF record type
- 1 (System Services Statistics)
- 0100
- 2 (Database Services Statistics)
- 0100
- 3 (Agent Accounting)
- 0101
- 202 (Dynamic System Parameters)
- 0100
- 225 (System Storage® Summary Statistics)
- 0100
- 230 (Data Sharing Global Statistics)
- 0100
- 239 (AGENT ACCOUNTING OVERFLOW)
- 0101
- All Others
- 0102
- SRV
- An exit to a user-written routine. For instructions and an example of how to write such a routine, see the macro DSNWVSER in library prefix.SDSNMACS.
- OPn
- A specific destination.
n can be an integer from 1 to 8.
- OPX
- A generic destination which uses the first free OPn slot.
Only applications that start a trace to an OPn buffer can read that buffer.
All traces to an OPX destination must be stopped before the buffer is marked as not in use. Traces that are started to an OPX buffer that was formerly in use write over the storage any previous traces had set.
The constraint and filtering
blocks
The constraint and filtering
blocks place optional limits on the kinds of data that are collected
by the trace. The filtering options are exclusionary equivalents to
the corresponding constraint options.
Only the CLASS constraint option can be specified
for starting a statistics trace. Any constraint option or filter option
can be specified for starting all other trace types. However, DB2 does not use any filters or
constraints that you specify when you start a trace for any of the
following IFCIDs:
| 1 | 2 | 4 | 5 | 104 | 105 | 107 | 124 | 129 | 147 |
| 148 | 149 | 150 | 185 | 186 | 199 | 202 | 217 | 225 | 230 |
| 254 | 306 | 316 | 317 | 365 | 373 | 401 | 402 |
A START TRACE command can contain multiple
constraint options, multiple filtering options, or a combination of
both. A constraint or a filtering option can contain multiple values.
However, the command must not contain multiple constraint options
that each contain multiple values. A single constraint option that
has multiple values can be specified with:
- Multiple other constraint options, each of which has a single value
- Multiple filtering options, each of which has a single value or multiples values
An error message is issued if the START
TRACE command contains two or more constraint options that each have
multiple options.
The meaning of each option
is as follows. Filtering options are described with their corresponding
constraint options.
- PLAN( plan-name , …) or XPLAN( plan-name , …)
- Introduces a list of specific plans for which trace information
is gathered. Use PLAN to constrain the trace to the specified plans
or XPLAN to exclude the specified plans. You cannot use this option
for a STAT trace. The default is PLAN( * ).
- ( * )
- Starts a trace for all plans.
- plan-name
- Is the name of an application plan. You can use up to eight names; a separate trace is started for each name. If you use more than one name, you can use only one value for AUTHID and LOCATION.
- PKGLOC or XPKGLOC
- Specifies the location name where the package is bound. Use PKGLOC
to constrain the trace to the specified locations or XPKGLOC to exclude
the specified locations.
- PKGCOL or XPKGCOL
- Specifies the package collection name. Use PKGCOL to constrain
the trace to the specified collections or XPKGCOL to exclude the specified
collections.
- PKGPROG or XPKGPROG
- Specifies the DBRM or program name. Use PKGPROG to constrain the
trace to the specified programs or XPKGPROG to exclude the specified
programs.
- AUTHID( authorization-id , …) or XAUTHID( authorization-id , …)
- Introduces a list of specific authorization IDs for which trace
information is gathered. Use AUTHID to constrain the trace to the
specified authorization IDs or XAUTHID to exclude the specified authorization
IDs. The authorization IDs specified must be the primary authorization
IDs. You cannot use this option for a STAT trace. The default is AUTHID( * ).
- ( * )
- Starts a trace for all authorization IDs.
- authorization-id
- Specifies an authorization ID. You can use up to eight identifiers; a separate trace is started for each identifier. If you use more than one identifier, you can use only one value for PLAN and LOCATION.
- LOCATION( location-name ,
…) or XLOC( location-name ,
…)
- Specifies
a list of location names for which trace information is gathered.
Use LOCATION to constrain the trace to the specified locations or
XLOC to exclude the specified locations. The use of the LOCATION or
XLOC option precludes tracing threads that have no distributed data
relationship. LOCATION or XLOC cannot be specified when you want to
start a statistics trace.
- location-name
- Identifies the DB2 subsystems
whose distributed threads you want to trace. Activates the DB2 trace for the remote TCP/IP
or SNA location that you specify by location-name.
You can specify up to eight locations; a separate trace is started for each one. You can specify only one location if you use more than one plan name or authorization ID.
- <luname>
- Activates the DB2 trace for the remote clients that are connected to DDF through the remote SNA LU name that you specified in luname.
- ipaddr
- Activates the DB2 trace for the remote clients that are
connected to DDF through the remote TCP/IP host. ipaddr is the IP address. The format of the IP address depends on
whether the TCP/IP stack has been configured as an IPv4-only stack or a dual-mode stack. An IPv4
stack supports only the IPv4 protocol. A dual-mode stack supports IPv4 and IPv6 protocols.
- For an IPv4-only stack, you enter the IP address in IPv4 format:
x.x.x.x - For a dual-mode stack:
- You enter an IPv6 address in IPv6 format:
y:y:y:y:y:y - You enter an IPv4 address in dual IPv6 and IPv4 format, with ::FFFF: as the IPv6 portion:
::FFFF:x.x.x.x
- You enter an IPv6 address in IPv6 format:
- For an IPv4-only stack, you enter the IP address in IPv4 format:
- (*)
- Indicates that you want to start trace events that occur under
distributed threads regardless of which location they are connected
to. Specifying the local location name is equivalent to specifying
LOCATION(*). Clients other than DB2 for z/OS: DB2 for z/OS does not receive a location name from clients that are not DB2 for z/OS subsystems. To start a trace for a client that is not a DB2 for z/OS subsystem, enter its LUNAME or IP address. Enclose the LUNAME by the less-than (<) and greater-than (>) symbols. Enter the IP address in the form nnn.nnn.nnn.nnn. For example, to start a trace for a client with the LUNAME of LULA, enter the following command:
To start a trace for a client with the IP address of 123.34.101.98, enter the following command:-START TRACE (PERFM) CLASS (*) LOCATION (<LULA>)-START TRACE (PERFM) CLASS (*) LOCATION (::FFFF:123.34.101.98)
- USERID or XUSERID
- Specifies
the user ID. Use USERID to constrain the
trace to the specified user IDs or XUSERID to
exclude the specified user IDs. You can specify multiple values and
wildcard values as described in Usage
notes.
- APPNAME or XAPPNAME
- Specifies
the application name. Use APPNAME to constrain
the trace to the specified applications or XAPPNAME to
exclude the specified applications. You can specify multiple values
and wildcard values as described in Usage
notes.
- WRKSTN or XWRKSTN
- Specifies
the workstation name. Use WRKSTN to constrain
the trace to the specified workstations or XWRKSTN to
exclude the specified workstations. You can specify multiple values
and wildcard values as described in Usage
notes.
- CONNID or XCONNID
- Specifies
the connection ID. Use CONNID to constrain the trace to the specified
connections or XCONNID to exclude the specified connections.
The CONNID or XCONNID value is one of the following values:
CONNID value Type of connection to DB2 BATCH Batch TSO TSO DB2CALL QMF™ UTILITY DB2 utility subsystem-id DB2 internal cics-connection-name CICS ims-connection-name IMS RRSAF RRSAF connection-name A connection from a remote DB2 for z/OS requester. This value is the connection name of the thread at the requesting location. SERVER A connection from a remote requester that is not DB2 for z/OS. - CORRID or XCORRID
- Specifies
the correlation ID. Use CORRID to constrain the trace to the specified
correlation IDs or XCORRID to exclude the specified correlation IDs.
- ROLE or XROLE
- Specifies
the connection roles. Use ROLE to constrain the trace to the specified
roles or XROLE to exclude the specified roles.
- CLASS( integer , …)
- Introduces
a list of classes of data gathered. What classes are allowable, and
their meaning, depends on the type of trace started.
Abbreviation: C
When the CLASS option is omitted, the default classes within the trace type are activated. The default classes are identified in the Description column of the following tables.- ( * )
- Starts a trace for all classes of the trace type.
- integer
- Any number in the following table. You can use any number of classes that are allowed for the type of trace started.
- Accounting trace (ACCTG)
Table 2. Classes for DB2 accounting trace Class Description of class Activated IFCIDs 1Standard accounting data. This default class is also
activated when you omit the CLASS keyword from the START TRACE command when you
start the accounting trace.0003, 0106, 0200,
02392 Entry or exit from DB2 event signaling. 0232 3 Elapsed wait time in DB2. 0006-0009, 0032, 0033, 0044, 0045, 0117, 0118, 0127, 0128, 0170, 0171, 0174, 0175, 0213-0216, 0226, 0227, 0242, 0243, 0321, 0322, 0329, 0378, 0379 4 Installation-defined accounting record. 0151 5 Time spent processing IFI requests. 0187 6 Reserved. 7Package-level accounting in-DB2 time.0200, 0232, 0239, 02408 Package-level accounting wait time in DB2. 0006-0009, 0032, 0033, 0044, 0045, 0117,
0118, 0127, 0128, 0170, 0171, 0174, 0175, 0213-0216, 0226, 0227, 0239, 0241-0243, 0321, 0322,
0378, 037910 Package detail. One
of the following traces must also be activated before the IFCID 0239 records are written:- Accounting class 7
- Accounting class 8
- Monitor class 7
- Monitor class 8
023911-29 Reserved. 30 - 32 Available for local use. - Audit trace (AUDIT)
Table 3. Classes for DB2 audit trace Class Description of class Activated IFCIDs 1 Access attempts denied due to inadequate authorization. This default class is also activated when you omit the CLASS keyword from the START TRACE command when you start the audit trace. 0140 2 Explicit GRANT and REVOKE. 0141 3 CREATE, ALTER, and DROP operations against audited tables. 0142 4 First change of audited object. 0143 5 First read of audited object. 0144 6 Bind time information about SQL statements that involve audited objects. 0145 7 Assignment or change of authorization ID. 0055, 0083, 0087, 0169, 0319 8 Utilities. 0023, 0024, 0025, 0219, 0220 9 Installation-defined audit record. 146 10Trusted context information.0269, 027011Audits of successful access.0361112 - 29 Reserved. 30 - 32 Available for local use. Notes:- If IFCID 0361 is started through START TRACE, all successful access
is traced. If IFCID 0361 is started because audit policy category SYSADMIN is on, only successful
access using the SYSADMIN administrative authority is traced. If IFCID 0361 is started because audit
policy category DBADMIN is on, only successful access using the DBADMIN administrative authority is
traced.
- Statistics trace (STAT)
Table 4. Classes for DB2 statistics trace Class Description of class Activated IFCIDs 1 Information about system services, database statistics, statistics for the DBM1 address space, and information about the system parameters that were in effect when the trace was started. This default class is also activated when you omit the CLASS keyword from the START TRACE command when you start the statistics trace. 0001, 0002, 0105, 0106, 0202, 0225 2 Installation-defined statistics record 0152 3 Deadlock, lock escalation, group buffer pool, data set extension information, and indications of long-running uncommitted reads, and active log space shortages. 0172, 0196, 0250, 0258, 0261, 0262, 0313, 0330, 0337 4 DB2 exceptional conditions. 0173, 0191-0195, 0203-0210, 0235, 0236, 0238, 0267, 0268 5 DB2 data sharing statistics record. 0230 6 Storage statistics for the DB2
subsystem.0225 7DRDA location statistics.03658 Data set I/O statistics. 0199 9Aggregate CPU and
wait time statistics by connection type.036910 - 29 Reserved. 30 - 32 Available for local use. - Performance trace (PERFM)
Table 5. Classes for DB2 performance trace Class Description of class Activated IFCIDs 1 Background events. This default class is also activated when you omit the CLASS keyword from the START TRACE command when you start the performance trace. 0001, 0002, 0031, 0042, 0043, 0076-0079, 0102, 0103, 0105-0107, 0153 2 Subsystem events. This default class is also activated when you omit the CLASS keyword from the START TRACE command when you start the performance trace. 0003, 0068-0075, 0080-0089, 0106, 0174, 0175 3 SQL events. This default class is also activated when you omit the CLASS keyword from the START TRACE command when you start the performance trace. 0022, 0053, 0055, 0058-0066, 0092, 0095-0097, 0106, 0112, 0173, 0177, 0233, 0237, 0250, 0272, 0273, 0325 4 Reads to and writes from the buffer and EDM pools. 0006-0010, 0029-0030, 0105-0107, 0127, 0128, 0226, 0227, 0321, 0322 5 Write to log; archive log. 0032-0041, 0104, 0106, 0114-0120, 0228, 0229 6 Summary lock information. 0020, 0044, 0045, 0105-0107, 0172, 0196, 0213, 0214, 0218, 0337 7 Detailed lock information. 0021, 0105-0107, 0223 8 Data scanning detail. 0013-0018, 0105-0107, 0125, 0221, 0222, 0231, 0305, 0311, 03639 Sort detail. 0026-0028, 0095-0096, 0106 10 BIND, commands, and utilities detail. 0023-0025, 0090, 0091, 0105-0107, 0108-0111, 0201, 0256 11 Execution unit switch and latch contentions. 0046-0052, 0056, 0057, 0093, 0094, 0106, 0113 12 Storage manager. 0098-0101, 0106 13 Edit and validation exits. 0011, 0012, 0019, 0105-0107 14 Entry from and exit to an application. 0067, 0106, 0121, 0122 15 Installation-defined performance record. 0154 16 Distributed processing. 0157-0163, 0167, 0183 17 Claim and drain information. 211-216 18 Event-based console messages. 0197 19Data set open and close activity.0370, 037120 Data sharing coherency summary. 0249-0251, 0256-0257, 0261, 0262, 0267, 0268 21 Data sharing coherency detail. 0255, 0259, 0263 22 Authorization exit parameters. 0314 23 Language environment runtime diagnostics. 0327 24Stored procedure detail.0380, 049925-29 Reserved. 30 - 32 Available for local use. - Monitor trace (MONITOR)
Table 6. Classes for DB2 monitor types Class Description of class Activated IFCIDs 1 Standard accounting data. This default class is also activated when you omit the CLASS keyword from the START TRACE command when you start the monitor trace. 0200 2 Entry or exit from DB2 event signaling. 0232 3 DB2 wait time for I/O, locks; resource usage information. 0006-0009, 0032, 0033,0044, 0045, 0117, 0118, 0127, 0128, 0170, 0171, 0174, 0175, 0213,0 214, 0215, 0216, 0226, 0227, 0242, 0243, 0321, 0322, 0378, 0379 4 Installation-defined monitor record. 0155 5 Time spent processing IFI requests. 0187 6 Changes to tables created with DATA CAPTURE CHANGES. 0185 7 Entry or exit from DB2 event signaling for package accounting. The data traces the amount of time an agent spent in DB2 to process each package. 0200, 0232, 0240 8 Wait time for a package. 0006-0009, 0032, 0033, 0044, 0045, 0051, 0052, 0056, 0057, 0117, 0118, 0127, 0128, 0170,171,174, 175, 213-216, 226, 227, 239, 241-243, 321, 322, 0378, 0379 9 Enables statement level accounting. 0124 10 Package detail for buffer manager, lock manager and SQL statistics. One of the following traces must also be activated before the IFCID 0239 records are written:
- Accounting class 7
- Accounting class 8
- Monitor class 7
- Monitor class 8
0239 11-28 Reserved. 29 Controls the subsystem-wide collection of statistics for SQL statements. 0316 , 0318, 0400, 0401 30 - 32 Available for local use.
- IFCID ( ifcid , …)
- Specifies
which other IFCIDs (trace events), in addition to those IFCIDs contained
in the classes specified in the CLASS option, are to be started. To
start only those IFCIDs specified in the IFCID option, use trace classes
30-32. These classes have no predefined IFCIDs and are available for
a location to use. See Example
1 for an example of activating only those trace events specified
in the IFCID option.
If you do not specify the IFCID option, only those IFCIDs contained in the activated trace classes are started.
The maximum number of IFCIDs is 156.
The range of values that are valid for the IFCID option is 0001 through
0511, with the exceptions of: 0004, 0005, 0185, 0187, 0217, 0232,
0234, 0240, 0241, and 0362. These exceptions are invalid values for
the IFCID option. IFCIDs 4 and 5 are always automatically active.
IFCID 0362 is automatically started if you specify the AUDTPLCY option.
Some of the other invalid IFCIDs can be activated only by certain
trace classes. The invalid values for the IFCID option that can be
started only by trace classes are:- To start...
- Start...
- IFCID 0185
- monitor trace class 6
- IFCID 0232
- monitor trace class 2 or 7, or accounting trace class 2 or 7
- IFCID 0240
- monitor trace class 7 or accounting trace 7
- IFCID 0241
- monitor trace class 8 or accounting trace 8
The default is IFCID( * ).
- BUFSIZE ( k_bytes , …)
- Specifies
the size of an IFC managed buffer that receives the trace data. You
can specify this option only if you specified an OP n destination.
k_bytes can
range from 256 KB to 65536 KB. The number must be evenly divisible
by 4. If you specify a value outside of this range, the range limit
closest to the specified value is used. To allocate a buffer size
of 256 KB, you would specify BUFSIZE(256).
The default is BUFSIZE ( * ), which is the size set when DB2 was installed.
- AUDTPLCY( policy-name ,
…)
- Introduces
a list of up to eight audit policy names for which trace information
is gathered. This option starts the IFCIDs that correspond to the
categories that are specified in the listed audit policies, and starts
a trace for IFCID 0362.
AUDTPLCY applies to trace type AUDIT. You cannot specify AUDTPLCY with CLASS or IFCID.
- TDATA
- Specifies
the product section headers to be placed into the product section
of each trace record. If you do not specify TDATA, then the type of
trace determines the type of product section header. The product section
of a trace record can contain multiple headers. All IFC records have a standard IFC header. The correlation header is added for accounting, performance, audit, and monitor records. The trace header is added for serviceability records.
- CORRELATION
- Places
a correlation header on the record.
Abbreviation: COR
- TRACE
- Places
a trace header on the record.
Abbreviation: TRA
- CPU
- Places a CPU header on the record. The CPU header contains the current processor time for the z/OS TCB or SRB executing.
- DISTRIBUTED
- Places
a distributed header on the record.
Abbreviation: DIST
Usage notes
Audit policies: Up to 32 audit policies can be active
concurrently. If you specify multiple audit policies to start, and some of those policies do not
start successfully, warning message DSNW196I is returned. The remaining audit policies are
started.
Number of traces: If you use one or no values for PLAN, AUTHID, or LOCATION, the START TRACE command starts a single trace. If you use multiple values for PLAN, AUTHID, or LOCATION, the command starts a trace for each plan, authorization ID, or location. Up to 32 traces can be active concurrently. If a START TRACE command is entered from the console or from the DB2I panels to an OP n or an OPX destination, message DSNW133I is issued to indicate trace data lost.
Using the options PLAN, AUTHID, or LOCATION when starting monitor trace class 1 has no effect on the amount of data returned on IFI READS requests.
Using the options PLAN, AUTHID, or LOCATION has no effect when starting either accounting or monitor trace classes 2, 5, or 7.
Stopping and starting DB2: If DB2 is stopped and started after you have started a trace, the trace is not restarted automatically.
Specifying SCOPE (GROUP): When you issue START TRACE with SCOPE(GROUP), DB2 issues a START TRACE command on each member of the data sharing group. The data goes to the destination as it is defined for each member of the data sharing group. If you want to gather trace data for all members of the data sharing group in one place, use a monitor program with IFI READA or READS calls to collect the data.
If a trace is started with SCOPE(GROUP), and a new member joins the data sharing group after the trace is started, the new member also writes the trace data that is specified by the START TRACE command.
Starting a trace with SCOPE(GROUP) can generate large amounts of trace data, so you might need to increase the size of the return area in your monitor program to hold the extra data.
Tracing threads using the * wildcard in
a partial name or address: In a partial name or address,
you can use the wildcard suffix, “*” to filter threads. For example,
if you specify “-START TRACE PLAN (A,B,C*)”, DB2 will trace, and then return A, B, CDE, CDEFG,
CDEFGH, and so on. It will trace threads “A”, “B” and all threads
starting with “C”.
You cannot include
the wildcard character in the middle of a partial name or address.
Tracing threads using the positional, (_)
wildcard in a partial name or address: In a partial name
or address, you can use the positional wildcard, which is represented
by the, “_” character, to trace threads when you want the wildcard
in the middle, or when you want to trace threads of a specific length.
For example, if you specify “-START TRACE PLAN (A_C), all threads
will be traced that are three characters that have “A” as the first
character, and “C” as the third. This command would return “ABC”,
“ADC”, “AEC”, and so on. If you want to trace the thread “A_C” then
you can specify “-START TRACE PLAN (A/_C). The “/” before the “_”
tells DB2 to trace for the underscore
in the search, rather than treating it as a wildcard. The same logic
applies if you are trying to trace a thread that includes a “/” or
“*” character. Because the character “/” is an escape character,
if you are trying to trace a thread that has an “/” character in it,
you can specify, for example, “-START TRACE PLAN (A//C)” to trace
the thread “A/C”. You can also specify “-START TRACE PLAN (A/*C)
to trace the thread “A*C”.
- Begin with “A”, have a one character wild card as the second character in the thread, have a “B” as the third character in the thread, and end with any type or number of characters (ADBIOP, AOBTYJDP,)
- begin with “C”, and end with any combination of characters (CDE, CGHKO)
- begin with “C_D” and end with any type of character combination (C_DEFGH, C_DLMNOP)
Specifying filtering criteria for threads: You
can control the set of threads for which trace records are written
by setting specific filtering criteria in the -START TRACE command.
The following rules apply to all trace filters:- DB2 applies trace filters when an external trace record is written. The state of a thread at that time dictates whether a thread is written in its entirety or eliminated completely.
- Trace filters do not alter the contents of a trace record.
- Trace classes or IFCIDs that are not associated with specific
trace records, such as accounting classes 2, 3, 7, 8, and 10, or IFCID
0318, are not affected by filtering. For example, the following command
does not result in filtering because no external records are written
by accounting classes 7 or 8:
-START TRACE(ACCTG) CLASS(7,8) DEST(SMF) PKGPROG(ABC) - DB2 allows only one filtering
option to have more than one value in a -START TRACE command. For
example, the following command is valid:
-START TRACE PLAN(A,B) USERID(B) WRKSTN(E)The following command is not valid:
-START TRACE PLAN(A,B) USERID(A,B) WRKSTN(E)
Filtering threads using exclude functionality: When you specify an “X” with any constraint keyword, such as XPLAN, when you are filtering threads, you are using the exclude functionality for the –START TRACE command. You have the option of excluding specific types of threads when you are running trace commands. You can use the “X” character to exclude specific combinations of characters when you are running a trace. For example, you can specify this command to trace all threads except “A”:
-START TRACE XPLAN(A)In this instance, b, bcd, bcde, or cd might be returned.
You can also exclude multiple types of threads
from your trace. For example, you can specify this command to start
a trace for all threads except threads for plans that start
with “A”, with any combination of characters following “A”, and all
those characters starting with “B”, with any combination of characters
following “B”:
-START TRACE XPLAN(A*, B*)Specifying XPLAN (*) excludes all threads from
your search, and is not allowed. You also cannot use the * wildcard
in the middle of trace criteria with exclude functionality, such as:
“-START TRACE XPLAN (A*C).” You can, however, specify this command
to return all threads except those for plans that start with
“A”, any two characters next, a “C” in the fourth space, and
any characters at the end.
-START TRACE XPLAN (A_ _ C *)You can start two traces at once, in order to help you optimize your tracing capabilities. For example, you can specify this command:
-START TRACE XPLAN (A, B, C) USERID(D)This command tells DB2 to
start tracing threads for all plans except plans “A”, “B”,
or “C”, and only where the user ID = “D”.
Combining trace qualifiers: You can customize the threads you trace by commanding DB2 to trace specific threads, while excluding other specific threads. For example, you can specify, “-START TRACE USERID (A,B) XPLAN (C)” . This criteria only traces threads where the user ID is equal to “A” or “B”, and plan is not equal to “C”. In this example, a thread where the user id is “A” and the plan is equal to “D” would pass, and be traced, but a thread where the user ID is “A” and plan is “C” would not pass, and would not be traced.
You can introduce multiple wildcards into your start trace commands to add more customization to your traces. For example, you can specify “-START TRACE PLAN (C*) USERID (Z, X) XPLAN (C, D, E)”. In this example, for the thread to be traced, the plan must begin with C, the user ID must be equal to Z or to X, and the plan cannot be C, D, or E. So a plan of CB, with a user ID of Z would pass, and the thread would be traced, but plan C with a user ID of X would fail because the command specifies not to trace threads where the plan is “C”, without additional characters in the thread.
Trace destination precedence: If an IFCID is associated with a class, and you specify that IFCID in the IFCID keyword, the destination for the class takes precedence. This rule affects IFCIDs in accounting classes 2, 3, 5, 7, 8, and monitoring classes 1, 2, 3, 5, 7, 8 because these classes have preset destinations for the IFCIDs.
For example, the following command "-START TRACE(ACCTG) CLASS (1,2,3) IFCID(6,7) DEST SMF," will not write IFCIDs 6 and 7 to SMF because they are part of accounting class 3, which has a preset destination. To write IFCIDs 6 and 7 to SMF, you need to start the trace as follows:
-START TRACE(ACCTG) CLASS(1,2,3) DEST(SMF)
-START TRACE(ACCTG) CLASS(30) IFCID(6,7) DEST(SMF)Examples
Example: Start
a performance trace for threads with remote activity to location USIBMSTODB21.
Only activate IFCIDs 0044 (lock suspends) and 0045 (lock resumes).
Trace class 30 is available for installation use. -START TRACE (PERFM)
DEST(GTF)
LOCATION(USIBMSTODB21)
CLASS(30)
IFCID(44,45)-START TRACE (ACCTG)
PLAN (DSN8BC81)
COMMENT ('ACCTG TRACE FOR DSN8BC81')-START TRACE=S-START TRACE(MON)-START TRACE(MON) SCOPE(GROUP)-START TRACE(PERFM) CLASS(3) DEST(SMF) PKGPROG(ABC)-START TRACE(ACCTG) CLASS(1,2,3,7,8) DEST(SMF) PKGPROG(ABC)START TRACE (A) XCORRID (*)
- 10.46.05 STC00051 DSNW150I ) EXCLUDE FOR ALL CORRID VALUES IS NOT
- ALLOWED
- 10.46.05 STC00051 DSN9023I ) DSNWVCM1 '-START TRACE' ABNORMAL COMPLETION-STA TRACE(AUDIT) DEST(GTF) AUDTPLCY(AUDITADMIN)