E printlogs Tool Syntax and Usage

This appendix describes the printlogs command-line tool. You can use printlogs to print the contents of Oracle Application Server diagnostic log files to standard output.

It contains the following topics:

Introduction
Basic Syntax
Detailed Option Descriptions
Log Record Fields
Environment Variable
Examples

E.1 Introduction

The printlogs command-line tool reads logs generated by Oracle Application Server components and prints the content of the logs to standard output in a common format. printlogs supports many options for reading and filtering log files, and formatting the output.

See Also:

Chapter 4, "Managing Log Files" for more information on Oracle Application Server logging

Location

The printlogs command is located in:

(UNIX) ORACLE_HOME/diagnostics/bin/printlogs
(Windows) ORACLE_HOME\diagnostics\bin\printlogs

Notes

In order to run printlogs, you must log in as a user that has permission to read all of the log files in your Oracle home, for example, the user that installed Oracle Application Server.
By default, printlogs operates on the Oracle home it resides in. You can override this with the -home option. Note that printlogs does not use the ORACLE_HOME environment variable.
printlogs options are not case-sensitive.
By default, printlogs uses the contents of the directory ORACLE_HOME/diagnostics/config/registration to determine which log files to read, the location of log files, and additional configuration information about each log file. You can override this with the -repository, -registration, and -logs options.

See Also:
Section 4.6.4, "Component Diagnostic Log File Registration" for more information

E.2 Basic Syntax

printlogs [input options] [filter options] [output options] [general options]

Input Options

[-home oracle_home_path] [-repository]

[-home oracle_home_path] [-registration registration_directory_path]
[filter options] [output options] [general options]
[-logs log_path [log_path ...]]

Filter Options

[-tail n] [-last n[s|m|h|d]] [-query expression]

expression:

simple_expression
-not simple_expression
simple_expression -and simple_expression
simple_expression -or simple_expression

simple_expression:

field_name op value
( expression )

field_name:

An ODL log record field name. See Section E.4, "Log Record Fields" for a list of field names.

op:

-eq | -eq_case | -contains | -contains_case |
-startswith | -startswith_case | -from | -to

value:

A string or timestamp, depending on the operation (op)

Output Options

[-odl | -odl_complete | -text | -text_short | -text_full] [-orderBy orderByFieldList]

[-count [groupByFieldList]]

General Options

[-help] [-f] [-sleep n] [-notailopt]

E.3 Detailed Option Descriptions

This section provides detailed descriptions of printlogs options. It contains the following sections:

Input Options
Filter Options
Output Options
General Options

E.3.1 Input Options

You can use input options to specify the location of logs and log definitions. The default is the local Oracle home. Table E-1 describes the input options in detail.

Table E-1 Input Options

Input Option	Description
-home `oracle_home_path`	Specify an alternate Oracle home directory from where to read logs and log definitions
-repository	Specify that log records should be read from the common repository instead of directly from each log. The common repository is updated by the Log Loader. The Log Loader must be running in order for the repository to contain the contents of Oracle Application Server component logs.
-repos	Same as -repository
-registration `registration_directory_path`	Specify an alternate registration directory that contains definitions of log files to be read by `printlogs`. The default registration directory is `ORACLE_HOME``/diagnostics/config/registration`.
-logs `log_path` [`log_path` ...]	Specify one or more logs to be read by `printlogs`. `log_path` is the full path to the log file, or the path relative to the current directory. The registration directory is used to find the definition of each log. If one of the specified logs is not defined in the registration directory, it is read by the default "UnformattedTextLogReader". Note: The `-logs` option must be at the end of the `printlogs` argument list, after the query options, output options, and general options.

E.3.2 Filter Options

You can use filter options to define which log records printlogs should print. The default is to print all records generated in the last 10 minutes. Table E-2 describes the filter options in detail.

Table E-2 Filter Options

Filter Option Description

Filter Option	Description
-tail `n`	Perform an operation similar to the UNIX "tail" command before reading a log. The `n` argument must be a positive number. The meaning of the `n` argument depends on the log type. For ODL logs, `printlogs` searches backwards from the end of the log for `n` occurrences of the pattern "<`MESSAGE``>`" and starts reading the log from that point. For other log types, it reads the last `n` lines of the log.
-last `n`[s\|m\|h\|d]	Print only logs generated in a specified period of time. The default is 10 minutes. You can use the `n` argument to specify a different period of time. The `n` argument must be a positive number. You can use a suffix to specify a unit of time: "`s`" for seconds, "`m`" for minutes, "`h`" for hours, and "`d`" for days. The default unit of time is minutes. If you would like to search through the logs generated over a large period of time, you can use a large value such as `100d`. The value of the `-last` option is used by `printlogs` to perform a "tail optimization" before it starts reading the logs. It performs an operation similar to the UNIX "tail" command to each log until it finds a timestamp that is within the desired range. This speeds up most inquiries significantly, but, if the log contains records out of timestamp order, it can cause `printlogs` to miss some records. It can also make queries slower in a few cases, for example, when you search the entire log. You can disable "tail optimization" with the -notailopt option.
-query `expression`	Apply `expression` to each log record to filter out undesirable records. See Table E-3 for a description of `expression`.

-tail n

Perform an operation similar to the UNIX "tail" command before reading a log. The n argument must be a positive number. The meaning of the n argument depends on the log type. For ODL logs, printlogs searches backwards from the end of the log for n occurrences of the pattern "<MESSAGE>" and starts reading the log from that point. For other log types, it reads the last n lines of the log.

-last n[s|m|h|d]

Print only logs generated in a specified period of time. The default is 10 minutes.

You can use the n argument to specify a different period of time. The n argument must be a positive number. You can use a suffix to specify a unit of time: "s" for seconds, "m" for minutes, "h" for hours, and "d" for days. The default unit of time is minutes.

If you would like to search through the logs generated over a large period of time, you can use a large value such as 100d.

The value of the -last option is used by printlogs to perform a "tail optimization" before it starts reading the logs. It performs an operation similar to the UNIX "tail" command to each log until it finds a timestamp that is within the desired range. This speeds up most inquiries significantly, but, if the log contains records out of timestamp order, it can cause printlogs to miss some records. It can also make queries slower in a few cases, for example, when you search the entire log. You can disable "tail optimization" with the -notailopt option.

-query expression

Apply expression to each log record to filter out undesirable records. See Table E-3 for a description of expression.

Table E-3 describes the query expressions you can use with the -query filter option in the printlogs command.

Table E-3 Query Expression Options

Query Expression Option	Description
()	You can use parenthesis as delimiters for complex sub-expressions. Parenthesis have special meaning to most UNIX command shells and you must use an escape character with them. This is not necessary on Windows.
-not	Logical negation
-and	Logical and
-or	Logical or
`fieldname`	An ODL log record field name. See Section E.4, "Log Record Fields" for a list of available field names.
-eq	Equality operation (case-insensitive). You can use this operation with all log record fields.
-eq_case	Same as -eq, except case-sensitive
-contains	Contains operation (case-insensitive). The result is true only if the log record field value contains the value operand string. You can use this operation only with "string" log record fields (all fields except `TSTZ_ORIGINATING` and `TSTZ_NORMALIZED`).
-contains_case	Same as -contains, except case-sensitive
-startswith	Starts with operation (case-insensitive). The result is true only if the log record field value starts with the value operand string. You can use this operation only with "string" log record fields (all fields except `TSTZ_ORIGINATING` and `TSTZ_NORMALIZED`).
-startswith_case	Same as -startswith, except case-sensitive
-from	This operation can only be used with timestamped log record fields (`TSTZ_ORIGINATING` and `TSTZ_NORMALIZED`). The result is true only if the log record timestamp is equal to or greater than the operand value. The operand value must be either in the ISO 8601 time format (for example: 2003-06-30T12:00:00.000-08:00), or in the date/time format of the default Java locale. By default, `printlogs` searches for timestamped records generated in the last 10 minutes. You can use the -last `n`[s\|m\|h\|d] option in conjunction with the `-from` option to ensure the search period includes the specified timestamped records.
-to	This operation can only be used with timestamped log record fields (TSTZ_ORIGINATING and TSTZ_NORMALIZED). The result is true only if the log record timestamp is less than or equal to the operand value. The operand value must be either in the ISO 8601 time format (for example: 2003-06-30T12:00:00.000-08:00), or in the date/time format of the default Java locale. By default, `printlogs` searches for timestamped records generated in the last 10 minutes. You can use the -last `n`[s\|m\|h\|d] option in conjunction with the `-to` option to ensure the search period includes the specified timestamped records.

E.3.3 Output Options

You can use output options to specify an output format. The default is format is -text_short. Table E-4 describes the output options in detail.

Table E-4 Output Options

Output Option	Description
-odl	Specify that the output should be in ODL format. This option outputs an ODL document without the enclosing LOG tags. The generated output is not a complete XML document.
-odl_complete	Specify that the output should be in ODL format and that a complete XML document should be generated
-text_short	Specify that the output should be in a short text format including only the following fields: `TSTZ_ORIGINATING`, `COMPONENT_ID`, `MSG_TYPE`, `MODULE_ID`, `EXEC_CONTEXT_ID`, `MSG_TEXT`, and `SUPPL_DETAIL`. This is the default output format.
-text	Same as -text_short
-text_full	Specify that the output should be in full text format, including all message fields
-orderBy `orderByFieldList`	Sort the result in the specified order. The `orderByFieldList` argument is a list of log record field names separated by spaces. The field names can have an optional suffix of `:asc` or `:desc` to specify ascending or descending order. The default sort order is ascending. `printlogs` sorts the result in memory. If the result is large, it could run out of memory. In this case, you must provide additional filtering options to reduce the number of records in the result.
-count [`groupByFieldList`]	Report only the record count. The `groupByFieldList` argument is an optional list of log record field names separated by spaces. If you supply this argument, `printlogs` reports the record count for each supplied field.

E.3.4 General Options

You can use general options to obtain help, cause printlogs to loop, and disable optimization. Table E-5 describes the general options on detail.

Table E-5 General Options

General Option	Description
-help	Print detailed help.
-f	Follow. When you use this option, `printlogs` will not return after printing the result. Instead, it will go on an infinite loop where it sleeps for a number of seconds (specified with the -sleep `n` option), and then checks each log again and prints any new records that satisfy the query predicate.
-sleep `n`	Set the sleep time, in seconds, for the -f option. The default value is 20 seconds.
-notailopt	Disable the "tail optimization" that is usually performed with the -last option.

E.4 Log Record Fields

The printlogs command automatically translates the contents of any log file that it reads to the Oracle Diagnostic Logging (ODL) format. The ODL log record fields can be used to create a query expression, or to specify a group-by or order-by field list. Each field must be referred to by its names as described in Table E-6. Some of these fields are designated for future use, and currently are not used in any diagnostic messages generated by an Oracle Application Server

Table E-6 Log Record Fields

Log Record Field Name	Description
COMPONENT_ID	The component that originated the message
DETAIL_PATH	A URL for additional information about the message
DOWNSTREAM_COMPONENT_ID	The component that the originating component is working with on the downstream (server) side
EID.SEQ	The sequence number that is associated with the error instance
EID.UNIQUE_ID	A global unique identifier of an error instance associated with the message. This identifier can be used to correlate error messages from different components.
EXEC_CONTEXT_ID.SEQ	The sequence number that is associated with the execution context
EXEC_CONTEXT_ID.UNIQUE_ID	A global unique identifier of the thread of execution in which the originating component participates. This identifier can be used to correlate messages from several components that may be involved in the same thread of execution.
HOST_ID	The host name where the message originates
HOST_NWADDR	The network address of the host where the message originates
HOSTING_CLIENT_ID	An identifier for the client or security group to which the message relates
MODULE_ID	An identifier of the module that originated the message
MSG_ARG	A list of arguments to be bound with the message text. The argument is a list of an optional name and value. Note: This field is not currently supported.
MSG_GROUP	The name of the group to which the message belongs
MSG_ID	A message number, or some other value, that uniquely identifies the message within the component
MSG_LEVEL	The level qualifies the message type, indicating the degree of severity of the message. The value is an integer from 1 (highest severity) to 32 (lowest severity).
MSG_TEXT	A descriptive text for the message
MSG_TYPE	The type of the message. The defined message types are: `INTERNAL_ERROR`, `ERROR`, `WARNING`, `NOTIFICATION`, and `TRACE`. The value `UNKNOWN` may be used when the type is not known.
ORG_ID	The organization that wrote the component that originated the message
PROCESS_ID	An identifier of the process or execution unit that generated the message. For Java processes, the value can also include a thread identifier.
SUPPL_DETAIL	Supplemental information about the message
TSTZ_NORMALIZED	Date and time when the message was generated, adjusted for time difference between the host on which the message was generated and the host of the common repository. This field is only used if the log record is being read from a database repository.
TSTZ_ORIGINATING	Date and time when the message was generated
UPSTREAM_COMPONENT_ID	The component that the originating component is working with on the upstream (client) side
USER_ID	The user whose execution context originated the message

E.5 Environment Variable

You can use an environment variable to pass information to printlogs. Table E-7 describes the environment variable in detail.

Table E-7 Environment Variable

Environment Variable	Description
ORACLE_PRINTLOGS_JVM_ARGS	Provide additional arguments to the JVM that runs `printlogs`. Is is usually not necessary to provide additional JVM arguments, but this environment variable can be used in some situations, such as to set memory size, or provide additional properties to `printlogs`.

E.6 Examples

To print records from all known logs in the last 10 minutes:
```
printlogs
```
To print records from all known logs in the last 10 minutes and follow:
```
printlogs -f
```
After reaching the end of all log files, printlogs will go into an infinite loop where it sleeps for 20 seconds, then reads and prints any new records that are added to the log files.
To print records from the common repository in the last 2 hours:
```
printlogs -repository -last 2h
```
To print records from all known logs in the specified Oracle home in the last 2 days, in ODL format:
```
printlogs -home /private/orahome2 -last 7d -odl
```
To print records that are timestamped between 14:00 and 14:05 hours:
```
printlogs -last 100d -query TSTZ_ORIGINATING -from 2003-07-15T14:00:00-07:00 -and TSTZ_ORIGINATING -to 2003-07-15T14:05:00-07:00
```
In this example, we assume that the specified time interval is more than 10 minutes before the current time. By default, printlogs searches logs generated in the last 10 minutes. We therefore need to use the -last option to increase the overall search length to include the timestamp interval. To save the trouble of calculating the amount of time to the timestamp interval, you can specify a very large value, such as -last 100d.
To print records from OC4J logs that contain the word "exception" and are for the local Oracle home:
```
printlogs -last 1d -query \( COMPONENT_ID -eq OC4J -and MODULE_ID -startswith home \)-and MSG_TEXT -contains exception
```
Note: On the Windows platform the parenthesis should not be escaped.
To print records in the last 10 minutes, sorted in ascending order by component id, and in descending order by time:
```
printlogs -orderBy COMPONENT_ID TSTZ_ORIGINATING:desc
```
To print the number of records from all known logs in the last 10 minutes, grouping by component and message type:
```
printlogs -count COMPONENT_ID MESSAGE_TYPE
```
To print records in the last hour from daemon_logs and dcmctl_logs:
```
cd ORACLE_HOME/dcm/logs
printlogs -last 1h -logs daemon_logs dcmctl_logs
```
Note that this example uses log file names relative to the current directory.
To print records in the last 10 minutes from ipm.log and ons.log:
```
printlogs -logs ORACLE_HOME/opmn/logs/ipm.log ORACLE_HOME/opmn/logs/ons.log
```
Note that this example uses the full path to the log files and can be run from any directory.