NAME

mrtimfix - fix Oracle Database bugs in timing values

SYNOPSIS

  $ mrtimfix [options] [file]
  
  Options:
  --all               shorthand for --pef --pic --rpc --sys
  --dbcalls           shorthand for --pef --pic --rpc
  --eula              print End User License Agreement and exit
  --help              print help text and exit
  --man               print manual page and exit
  --oscalls           synonym for --sys
  --pef               convert e and tim values on database call lines
  --pic               convert tim values on PARSING IN CURSOR lines
  --rc=file           use named rc file; --norc prevents rc file usage
  --rpc               convert e values on RPC lines
  --show=n            show all or only the first n warnings
  --stderr            warn about "tim out of order" problems
  --stdout            print regular output to STDOUT
  --summary           print a summary of warnings
  --sys               convert ela and tim values on WAIT lines
  --syscalls          synonym for --sys
  --verify            shorthand for --stderr --nostdout
  --version           print version number and exit
  --waits             synonym for --sys

DESCRIPTION

mrtimfix copies Oracle extended SQL trace data from the named file (or the standard input if the file argument is omitted) to standard output, converting Oracle time and duration values (tim, e, and ela values) to real microsecond values for the options specified on the command line. If you specify no options, then mrtimfix copies its input to STDOUT. If it finds any evidence of time-related bugs in the trace data, then it will exit with a value of 1; otherwise it will exit with a value of 0.

On some Oracle Database ports, the Oracle kernel computes the timing values that it writes into its trace files by converting nanosecond timer information into microseconds by executing a ns>>10 operation (a 10-bit shift right of the nanosecond value). This is a computationally inexpensive way to approximate dividing by 1,000, but the fact is, it isn't dividing by 1,000; it's dividing by 1,024. On the ports where Oracle does this, the reported times and durations are contracted by a factor of 2.4%. It's not a big problem in many cases, because in most circumstances, you're more concerned about relative times and durations than you are about actual times and durations. But in some circumstances, the error matters. For example, if you have a tool that converts times expressed in microseconds since the Unix Epoch (1970-01-01T00:00:00.000000Z) into human-readable form, you won't be able to use such a tool upon Oracle tim values until you scale them first by 2.4%. For example:

                             Actual time (T):  2011-02-04T12:00:00.000000Z
          T in microseconds since Unix Epoch:  1296820800000000
  Oracle tim value generated at time T (tim):  1266426562500000
         Time at tim microseconds past Epoch:  2010-02-17T17:09:22.500000Z
                                 tim * 1.024:  1296820800000000

Even more important is Oracle bug 7522002, introduced in 11gR1, in which apparently some Oracle kernel developers decided to convert nanosecond time values into microseconds for WAIT lines using ms=ns/1,000, but continued to convert nanosecond time values into microseconds for PARSE, EXEC, and FETCH lines using ms=ns>>10. The result is trace files in which the tim values for WAIT lines appear in a more recent era than the tim values for PARSE, EXEC, and FETCH lines. This bug makes trace files incomprehensible to any person or software tool that pays attention to clock times of reported calls. You can repair the damage caused by this bug using the following mrtimfix command:

  mrtimfix --dbcalls ora_1492.trc

The tool processes uncompressed streams and can automatically uncompress files compressed properly with:

  Compression tool
  ----------------
  gzip
  bzip2
  zip

OPTIONS

--all

Fix all tim, e, and ela values in the file. Shorthand for --pef --pic --rpc --sys.

--dbcalls

Fix only the tim and e values on database call lines. Shorthand for --pef --pic --rpc.

--eula

Display the license information and exit.

--help

Display usage information and exit.

--man

Display the manual page and exit.

--oscalls

--oscalls is a synonym for --sys.

--pef

Fix tim and e values on lines beginning with PARSE, EXEC, FETCH, CLOSE, UNMAP, SORT UNMAP, etc. Default value is --nopef.

--pic

Fix tim values on PARSING IN CURSOR lines. Default value is --nopic.

--rc=file

Process command line options listed in file. Use --norc to prevent mrtimfix from opening the default rc files in your home directory or current working directory (see "ENVIRONMENT").

--rpc

Fix e values on RPC lines. Default value is --norpc.

--show=n

Show only the first n occurrences of each type of warning. The default is --show=5. Use --show=0 to show all warnings.

--stderr

Warn about tim values that emit out of order to STDERR. Such warnings indicate that your mrtimfix output isn't going to be usable. The default is --stderr. Use --nostderr to suppress.

--stdout

Write regular standard output to STDOUT. Default value is --stdout. Use --nostdout to suppress.

--summary

Write a warning summary to STDERR. Default value is --summary. Use --nosummary to suppress.

--sys

Fix tim and ela values on WAIT lines. Default value is --nosys.

--syscalls

--syscalls is a synonym for --sys.

--verify

Show warnings only (STDERR), without generating output to STDOUT. Shorhand for --stderr --nostdout.

--verbose=level

Print more or less information about option values. The default value is --verbose=0, which means to print nothing. To print options values, use use --verbose or --verbose=1.

--version

Display the program version number and exit.

--waits

--waits is a synonym for --sys.

RC FILES

With .rc files, you can conveniently change the default behavior of any mrtimfix option. For example:

  $ cat ~/.mrtimfix.rc
  --all

You can also construct .rc files that allow you to customize mrtimfix executions without having to type a complex command line each time:

  $ cat mrtimfix.rc
  # Fix Oracle bug 7522002.
  --dbcalls

A line beginning with the '#' character (in the first column of the line) is a comment. A comment must be on a line by itself; do not put a comment on a line after an option. There is no need to use a line continuation character to specify a multi-line option.

Such a .rc file would be called into use like this:

  $ mrtimfix --rc=mrtimfix.rc

This command would first execute the options listed in ~/.mrtimfix.rc (picking up the --reverse argument shown above), next execute the options listed in ./.mrtimfix.rc (if the file exists), and then finally execute the options listed on the command line. Upon encountering the --rc=filename option, mrtimfix will execute the options listed within the named file.

EXAMPLES

The following command will tell you (on STDERR) whether the tim values in a trace file are in the right order:

  mrtimfix --verify ora_1492.trc

The following command will scale time and duration values in a trace files by a factor of 1.024, except for those times and durations on WAIT lines. In other words, it will undo the errors introduced by Oracle bug 7522002:

  mrtimfix --dbcalls ora_1492.trc > ora_1492-fix.trc

This command will scale all time and duration values in a trace file by a factor of 1.024 (which should be unnecessary in Oracle versions 11.2 and beyond):

  mrtimfix --all ora_1492.trc > ora_1492-fix.trc

DIAGNOSTICS

Exit status is 0 on successful completion, and >0 if an error or warning occurs.

tim not changing (requires Oracle Database patch)

Oracle Database bugs like 7561762 can cause erroneous tim values to be emitted into the trace data, resulting in dbcall duration values of e=0. Unfortunately, this is an unfixable problem, short of installing an Oracle Database patch.

tim values out of order (possibly fixable with mrtimfix)

Oracle Database bug 7522002 is fixable with the mrtimfix command shown in "EXAMPLES".

ENVIRONMENT

.mrtimfix.rc

By default, mrtimfix will execute the options listed in the following files, in the following order, before the options you actually list on your command line:

  ~/.mrtimfix.rc
  ./.mrtimfix.rc

If you do not wish to execute the options in these files, then specify --norc on the command line.

MRTOOLS_RCPATH

The MRTOOLS_RCPATH environment variable contains a list of directories that each --rc=file option will search for file. Value syntax is identical to the PATH environment value syntax (e.g., ".:a:a/b" in Unix, ".;c:a;c:a\b" in DOS). If file begins with '/', '.', or '~', then --rc looks for the file in the location you have specified. Otherwise, --rc will search each directory named in the MRTOOLS_RCPATH list for file, using only the first readable file that it finds.

AUTHORS

Cary Millsap, Jeff Holt

SUPPORT

mrtimfix version 3.1.0.4.

Contact <> at Method R Corporation for support, or visit method-r.com for more information.

COPYRIGHT AND LICENSE

Copyright (c) 2011, 2014 by Method R Corporation. All rights reserved.

This is commercially licensed software. You may not redistribute copies of it. Please confirm with your software license administrator that you are licensed to use this Method R software product. Write <> for information.

There is NO WARRANTY, to the extent permitted by law.