db2diag - db2diag logs analysis tool command

Authorization

None

Required connection

None

Command syntax

Command parameters

-global

Specifies that all the db2diag log files from all the database partitions on all the hosts are included in the log file processing.

Note: This option supports rotating diagnostic log files and files located in split diagnostic data directories. This option can also be used in combination with the -follow option.

-merge

Merges diagnostic log files and sorts the records based on the timestamp. This option supports rotating diagnostic log files and files located in split diagnostic data directories.

If this parameter is not followed by two or more space-separated filename values, the db2diag log files in the directory or directories specified by the diagpath database manager configuration parameter and alt_diagpath database manager configuration parameter are merged. If the diagnostic data directory path is split across multiple database partitions, only the db2diag log files in the database partitions of the current host are merged.

If only one filename is specified, or only one diagnostic file exists in the path specified in the diagpath database manager configuration parameter and if alt_diagpath database manager configuration parameter is not set, then the single diagnostic log file is processed by the command as though the -merge command parameter was not specified.

This parameter is not allowed with the -facility, -follow, or -archive parameter. Starting with Db2® Version 9.7 Fix Pack 7, the -merge parameter supports automatically merging db2diag.log files in the alt_diagpath directory.

-global -merge -sdir sharedDirPathname

Specifying the -global and -merge options together results in all the db2diag log files from all the database partitions on all the hosts to be merged, and the records sorted based on the timestamp. This parameter supports rotating diagnostic log files and files located in split diagnostic data directories.

Must specify the -sdir sharedDirPathname parameter to temporarily store the merged diagnostic log files that are obtained from the different hosts. The temporary merged diagnostic log files are deleted after processing is complete. The sharedDirPathname variable must specify a shared directory to which all hosts have access and write permission.

filename

Specifies one or more space-separated path names of Db2 diagnostic logs to process. If the file name is omitted, the db2diag log file from the current directory is processed. If the file is not found, the directory or directories set by the diagpath database manager configuration parameter is searched.

-facility | -fac

Reads the files from the corresponding facility. A facility is a logical grouping of records. For example, all optimizer statistics records are grouped into the OPTSTATS facility. The output will be in text format by default. Valid facility options are the following values:

ALL

Returns records from all facilities.

MAIN

Returns records from Db2 general diagnostic logs, such as the db2diag log file, and rotating event logs.

OPTSTATS

Returns records related to optimizer statistics.

-fmt formatString

Formats the db2diag output using a format string, formatString, containing record fields in the form %field, %{field}, @field, or @{field}. The %{field} and @{field} are used to separate a field name from the alphanumeric (or any other allowed character) that may follow the field name. All field names are case-insensitive. Field names can be shortened to the several first characters that are necessary to recognize a field name without ambiguity. In addition, aliases can be used for fields with long names. A prefix before a field name, %, or @, specifies whether a text preceding the field will be displayed (%) or not (@), if the field is empty.

The following fields are currently available:

timestamp | ts

Time stamp. This field can be divided into its constituent fields: %tsyear, %tsmonth, %tsday, %tshour, %tsmin (minute), %tssec (second), %tsmsec (microsecond for UNIX operating systems, millisecond for Windows operating systems).

timezone | tz

Number of minutes difference from UTC (Universal Coordinated Time). For example, -300 is Eastern Time.

recordid | recid

A unique alphanumeric identifier for a record, such as I11455A696.

audience

Intended audience for a logged message. 'E' indicates external users (IBM customers, service analysts, and developers). 'I' indicates internal users (service analysts and developers). 'D' indicates debugging information for developers.

level

The diagnostic level of a message. The levels are Info, Warning, Error, Severe, Critical, and Event.

source

Location from which the logged error originated: Origin, OS, Received, or Sent.

instance | inst

Instance name.

node

Database partition server number.

database | db

Database name.

pid

Process ID.

tid

Thread ID.

eduid

EDU ID.

eduname

EDU name.

tenantid

Tenant ID

process

Name associated with the process ID, in double quotation marks. For example, "db2sysc.exe".

product

Product name. For example, DB2 COMMON.

component

Component name.

funcname

Function name.

probe

Probe number.

function

Full function description: %prod, %comp, %funcname, probe:%probe.

appid

The application ID. This value is the same as the appl_id monitor element data. For detailed information about how to interpret this value, see appl_id - Application ID monitor element .

coordnode

Coordinator partition.

coordindex

Coordinator index.

apphdl

Application handle: %coordnode - %coordindex.

message | msg

Error message.

calledprod

Product name of the function that returned an error.

calledcomp

Component name of the function that returned an error.

calledfunc

Name of the function that returned an error.

called

Full description of the function that returned an error, in the form: %calledprod, %calledcomp, %calledfunc.

rcval

Return code value (32 bytes).

rcdesc

Error description.

retcode | rc

Return code returned by the function called: %rcval %rcdesc.

errno

System error number.

errname

System-specific error name.

oserror

Operating system error returned by a system call in the form: %errno %errname.

callstack

Call stack.

datadesc

Data description.

dataobject

Data object.

data

Full data section of a message in the form: %datadesc %dataobject.

argdesc

Argument description.

argobject

Argument object.

arg

Arguments of a function call that returned an error: %argdesc %argobject.

Event descriptions:

impact

User impact (for events only).

startevent

Start event description (*).

stopevent

Stop event description (*).

changeevent

Change event description (*).

init

Initialization event description (*).

fini

Finish or finalize event description (*).

startup

Startup event description (*).

terminate

Terminate event description (*).

bringdown

Bringdown event description (*).

interrupt

Interrupt event description (*).

associate

Associate event description (*).

disassociate

Disassociate event description (*).

changecfg

Change configuration event description (*).

transfer

Transfer event description (*).

dispatch

Dispatch event description (*).

switch

Switch event description (*).

report

Report event description (*).

get

Get event description (*).

free

Free event description (*).

open

Open event description (*).

close

Close event description (*).

work

Work event description (*).

wait

Wait event description (*).

available

Available event description (*).

connect

Connect event description (*).

disconnect

Disconnect event description (*).

accept

Accept event description (*).

recv

Receive event description (*).

send

Send event description (*).

create

Create event description (*).

destroy

Destroy event description (*).

request

Request event description (*).

reply

Reply event description (*).

dependency

Dependency event description (*).

write

Write event description (*).

read

Read event description (*).

reset

Reset event description (*).

collect

Collect event description (*).

add

Add event description (*).

alter

Alter event description (*).

drop

Drop event description (*).

invalidate

Invalidate event description (*).

grant

Grant event description (*).

revoke

Revoke event description (*).

(*) Each event field has the following subfields:

{event}type

Event type (START, STOP, READ, WRITE, GET).

{event}desc

Event description (header with event information).

{event}state

Event state (success, failure, start, stop, in progress, idle) or event progress (in %).

{event}attr

Event attributes (business level, cached, sync, async, internal, external, logical, physical, auto, manual, temporary, permanent).

{event}objid

Unique object identifier (TABLE, CFG, DBM).

{event}objname

Event object name (for example, "schema.tablename").

{event}objdata

Object data (used if object is not a string or simple integer type, for example, data structure or some complex type).

{event}qtype

Event qualifier type (FROM, TO, ON, FOR, AT, BY, CONTEXT).

{event}qname

Event qualifier name or value (for example, FOR "DB ABC").

{event}qdhdr

Event qualifier data header (contains type, text description and size of data). Used together with the %{event}qdata field.

{event}qdata

Event qualifier data (used if qualifier is not a string or simple integer type, for example, some data structure or complex type).

In the preceding list, the {event} keyword should be substituted by event type for a specific event (for example, start, stop, change, read, or write).

To always display the text preceding a field name (for example, for the required fields), the % field prefix should be used. To display the text preceding a field name when this field contains some data, the @ prefix should be used. Any combination of required and optional fields with the corresponding text descriptions is allowed.

The following special characters are recognized within a format string: \n, \r, \f, \v, and \t.

In contrast to other fields, the data and argument fields can contain several sections. To output a specific section, add the [n] after the field name where n is a section number (1≤ n ≤64). For example, to output the first data object and the second data description sections, use %{dataobj}[1] and %{datadesc}[2]. When [n] is not used, all sections logged are output using pre-formatted logged data exactly as appears in a log message, so there is no need to add the applicable text description and separating newline before each data field, argument field, or section.

-filter fieldPatternList | -g fieldPatternList

fieldPatternList is a comma-separated list of field-pattern pairs in the following format: fieldName operator searchPattern.

The operator can be one of the following values:

=

Selects only those records that contain matches that form whole words. (Word search.)

:=

Selects those records that contain matches in which a search pattern can be part of a larger expression.

!=

Selects only non-matching lines. (Invert word match.)

!:=

Selects only non-matching lines in which the search pattern can be part of a larger expression.

^=

Selects records for which the field value starts with the search pattern specified.

!^=

Selects records for which the field value does not start with the search pattern specified.

The same fields are available as described for the -fmt option, except that the % and @ prefixes are not used for this option.

-gi fieldPatternList

Same as the -g parameter, but case-insensitive.

-gv fieldPatternList

Searches for messages that do not match the specified pattern.

-gvi | -giv fieldPatternList

Same as -gv, but case-insensitive.

-lastrecords number-of-records

Displays and filters the last number of records specified from the db2diag log file. For each db2diag log file, this parameter checks whether the number of records specified are available. If the number of records available in the log file is less than the number of records you specified, the db2diag command processes all the records available in the file. If split diagnostic data directory paths are used, the last number of records specified is returned for each db2diag log file in each path.

-pid processIDList

Displays only log messages with the process IDs listed.

-tid threadIDList

Displays only log messages with the thread IDs listed.

-eduid EduIDList

Finds all records with a specified EDU ID from a list of EDU IDs containing one or more comma separated numeric values.

-tenantidTenantIDList

Finds all records with a specified TENANT ID from a list of TENANT IDs containing one or more comma separated numeric values.

-n | -node nodeList

Displays only log messages with the database partition numbers listed.

-e | -error errorList

Displays only log messages with the error numbers listed.

-l | -level levelList

Finds all records with a specified severity level from a list of severity levels containing one or more comma separated text values, namely: Info, Warning, Error, Severe, Critical and Event.

-c | -count

Displays the number of records found.

-v | -invert

Inverts the pattern matching to select all records that do not match the specified pattern

-strict

Displays records using only one field: value pair per line. All empty fields are skipped. This can be used for scripts to simplify parsing.

-V | -verbose

Outputs all fields, including empty fields.

-exist

Defines how fields in a record are processed when a search is requested. If this option is specified, a field must exist in order to be processed.

-cbe

Common Base Event (CBE) Canonical Situation Data.

-o | -output pathName

Saves the output to a file specified by a fully qualified pathName.

-f | -follow

If the input file is a single or rotating db2diag log file, specifies that the tool will not terminate after the last record of the input file has been processed. Instead, the command sleeps for a specified interval of time (sleepInterval), and then attempts to read and process further records from the input file as they become available. Only the records from the last 8 kilobytes of the input file are processed.

The -f parameter can handle rotating db2diag log files. For example, if the latest rotating diagnostic log file in use is db2diag.23.log, the command reads that file. When that file meets its size limit, the command then reads the next rotating log file that is created, which is db2diag.24.log.

This option can be used when monitoring records being written to a file by another process. The startTime option can be specified to show all the records logged after this time. The startTime option is specified using the following format: YYYY-MM-DD-hh.mm.ss.nnnnnn, where

YYYY

Specifies a year.

MM

Specifies a month of a year (01 through 12).

DD

Specifies a day of a month (01 through 31).

hh

Specifies an hour of a day (00 through 23).

mm

Specifies a minute of an hour (00 through 59).

ss

Specifies a second of a minute (00 through 59).

nnnnnn

Specifies microseconds on UNIX operating systems, or milliseconds on Windows operating systems.

Some or all of the fields that follow the year field can be omitted. If they are omitted, the default values will be used. The default values are 1 for the month and day, and 0 for all other fields.

If an exact match for the record time stamp does not exist in the diagnostic log file, the closest time earlier than the specified time stamp will be used.

The sleepInterval option specifies a sleep interval in seconds. If a smaller time unit is required, it can be specified as a floating point value. The default value is 2 seconds

-H | -history

Displays the history of logged messages for the specified time interval. This option can be specified with the following options:

historyPeriod

Specifies that logged messages are displayed starting from the most recent logged record, for the duration specified by historyPeriod. The historyPeriod option is specified using the following format: Number timeUnit, where Number is the number of time units and timeUnit indicates the type of time unit: M (month), d (day), h (hour), m (minute), and s (second). The default value for Number is 30, and for timeUnit is m.

historyPeriod:historyReference

Specifies that logged messages are displayed that were recorded within the time period after the start time specified by historyReference (if an explicit positive value for historyPeriod is given), or logged messages are displayed that were recorded within the time period before the end time specified by historyReference (if a negative value for historyPeriod is given, or by default).

The format is YYYY-MM-DD-hh.mm.ss.nnnnnn, where:

YYYY

Specifies a year.

MM

Specifies a month of a year (01 through 12).

DD

Specifies a day of a month (01 through 31).

hh

Specifies an hour of a day (00 through 23).

mm

Specifies a minute of an hour (00 through 59).

ss

Specifies a second of a minute (00 through 59).

nnnnnn

Specifies microseconds (UNIX operating systems) or milliseconds (Windows operating systems).

-t | -time

Specifies a time stamp value. This option can be specified with one or both of the following options:

startTime

Displays all messages that are logged at startTime and after the startTime.

:endTime

Displays all messages that are logged before endTime and at endTime.

To display messages that are logged from startTime to endTime, specify -t startTime:endTime.

The format is YYYY-MM-DD-hh.mm.ss.nnnnnn, where:

YYYY

Specifies a year.

MM

Specifies a month of a year (01 through 12).

DD

Specifies a day of a month (01 through 31).

hh

Specifies an hour of a day (00 through 23).

mm

Specifies a minute of an hour (00 through 59).

ss

Specifies a second of a minute (00 through 59).

nnnnnn

Specifies microseconds (UNIX operating systems) or milliseconds (Windows operating systems).

Some or all of the fields that follow the year field can be omitted. If they are omitted, the default values will be used. The default values are 1 for the month and day, and 0 for all other fields.

If an exact match for the record time stamp does not exist in the diagnostic log file, the time closest to the time stamp specified will be used.

-A | -archive dirName

Archives both single and rotating diagnostic log files. When this option is specified, all other options are ignored. If one or more file names are specified, each file is processed individually. A timestamp, in the format YYYY-MM-DD-hh.mm.ss, is appended to the file name.

You can specify the name of the file and directory where it is to be archived. If the directory is not specified, the file is archived in the directory where the file is located and the directory name is extracted from the file name.

If you specify a directory but no file name, the current directory is searched for the db2diag log file. If found, the file will be archived in the specified directory. If the file is not found, the directories specified by the diagpath and alt_diagpath configuration parameters are searched for the db2diag log file. If found, it is archived in the directory specified.

If you do not specify a file or a directory, the current directory is searched for the db2diag log file. If found, it is archived in the current directory. If the file is not found, the directories specified by the diagpath and alt_diagpath configuration parameters are searched for the db2diag log file. If found, it is archived in the directory specified by the diagpath or alt_diagpath configuration parameter.

The db2diag -archive option is available with IBM® Data Server Driver Package and IBM Data Server for ODBC and CLI. This option enables you to archive the diagnostic log file on an instance-less client. For example:

$ db2diag -A
db2diag: Moving "/home/usr1/clidriver/db2dump/db2diag.log"
         to "/home/usr1/clidriver/db2dump/db2diag.log_2010-09-14-01.16.26"

-readfile

Forces reading from a diagnostic log file ignoring any terminal input. This option can be used in scripts to guarantee that db2diag will read from a file and not from a terminal, especially in situations when stdin is disabled or when automated tools are used. Running the db2diag command using rah or db2_all also requires the -readfile option to be used.

-rc rcList | switch

Displays descriptions of Db2 internal error return codes for a space separated list, rcList, of the particular ZRC or ECF hexadecimal or negative decimal return codes. A full list of ZRC or ECF return codes can be displayed by specifying one of the following switches:

zrc

Displays short descriptions of Db2 ZRC return codes.

ecf

Displays short descriptions of Db2 ECF return codes.

html

Displays short descriptions of Db2 ZRC return codes in the HTML format.

When this option is specified, all other options are ignored and output is directed to a display.

-ecfid ecfId

Displays function information extracted from the numeric ecfId. When this option is specified, all other options are ignored.

-h | -help | ?

Displays help information. When this option is specified, all other options are ignored, and only the help information is displayed. If a list of options, optionList, containing one or more comma separated command parameters is omitted, a list of all available options with short descriptions is displayed. For each option specified in the optionList, more detailed information and usage examples are displayed. Help output can be modified by using one of the following switches in place of the optionList argument to display more information about the tool and its usage:

brief

Displays help information for all options without examples.

examples

Displays a few typical examples to assist in using the tool.

tutorial

Displays examples that describe advanced features.

notes

Displays usage notes and restrictions.

all

Displays complete information about all options, including usage examples for each option.

-lastlines number-of-lines

Displays and filters the last number of lines specified from the db2diag log file. For each db2diag log file, this parameter checks whether the number of lines specified are available. If the number of lines available in the log file is less than the number of records you specified, the db2diag command processes all the lines available in the file. If split diagnostic data directory paths are used, the last number of lines specified is returned for each db2diag log file in each path.

Usage notes

• Each option can appear only once. They can be specified in any order and can have optional parameters. You cannot combine short names of parameters. For example, use -l -e and not -le.
• By default, db2diag looks for the db2diag log file in the current directory. If the file is not found, the directory set by the diagpath configuration parameter is searched next. If the db2diag log file is not found, db2diag returns an error and exits.
• Filtering and formatting options can be combined on a single command line to perform complex searches using pipes. The formatting options -fmt, -strict,-cbe, and -verbose should be used only after all filtering is done to ensure that only original logged messages with standard fields will be filtered, not those fields either defined or omitted by the user. It is not necessary to use - when using pipes.
• When pipes are used and one or more files names are specified on the command line, the db2diag input is processed differently depending on whether the - has been specified or not. If the - is omitted, input is taken from the specified files. In contrast, when the - option is specified, file names (even if present on the command line) are ignored and input from a terminal is used. When a pipe is used and a file name is not specified, the db2diag input is processed exactly the same way with or without the - specified on the command line.
• The -exist option overrides the default db2diag behavior for invert match searches when all records that do not match a pattern are output independent of whether they contain the proper fields or not. When the -exist option is specified, only the records containing fields requested are processed and output.
• If the -fmt (format) option is not specified, all messages (filtered or not) are output exactly as they are written in the diagnostic log file. Output record format can be changed by using the -strict,-cbe, and -verbose options.
• The -fmt option overrides the -strict,-cbe and -verbose options.
• Some restrictions apply when the -cbe option is specified and the db2diag log file has been transferred over a network from the original computer. The db2diag tool collects information about Db2 and the computer host name locally, meaning that the Db2 version and the source or reporter componentID location field for the local system can be different from the corresponding values that were used on the original computer.
• It is recommended to specify the -readfile option when using db2diag in scripts. It will ensure reading from a file ignoring any terminal input.
• Ordinarily, the exit status is 0 if matches were found, and 1 if no matches were found. The exit status is 2 if there are syntax errors in the input data and patterns, the input files are inaccessible, or other errors are found.
• Severe errors resulting from Db2 Text Search can be found logged in the db2diag log file.
• Be aware that using this tool to read and filter rotating db2diag log files (when the diagsize database configuration parameter is nonzero) will result in all the rotating diagnostic log files, to a series maximum of 10 files, to be read and filtered.
• Attempts to connect to the database while a restore is in progress will result in error messages in the db2diag.log. These error messages are ignorable if the restore command succeeds.