Skip Headers
Oracle® Application Server Administrator's Guide
10g Release 2 (10.1.2)
B13995-06
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

F 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:

F.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 5, "Managing Log Files" for more information on Oracle Application Server logging

Location

The printlogs command-line tool is located in:

Notes

F.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 )

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

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

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]

F.3 Detailed Option Descriptions

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

F.3.1 Input Options

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

Table F-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 Log Loader. 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:

(UNIX) ORACLE_HOME/diagnostics/config/registration
(Windows) 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".

The path list is terminated by the end of the argument list or by the first argument following the -logs option that starts with a hyphen (-). Therefore, a log path cannot start with a hyphen (-). If a path starts with hyphen (-), precede the path with: ./ (UNIX) or .\ (Windows). For example, to print log file -error.log, use:

(UNIX) printlogs -logs ./-error.log
(Windows) printlogs -logs .\-error.log

F.3.2 Filter Options

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

Table F-2 Filter Options

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 backward 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.

Note that the use of the -tail option disables the use of a default value for the -last option. See the -last option for default value details.

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

Print only logs generated in a specified period of time. The default is 10 minutes. If you do not specify the -last option, the period of time is set to 10 minutes except when the -tail option is specified. When the -tail option is specified, the default value for -last is disabled. If you specify both -tail and -last options, both options are used.

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.

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 F-3 for a description of expression.


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

Table F-3 Query Expression Options

Query Expression Option Description
()

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 F.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 in one of the following formats:

  • ISO 8601 time format:

    2003-06-30T12:00:00:0000-08:00
    
  • printlogs text output format:

    30/JUN/2003:12:00:00.000-08:00
    
  • date/time of the default Java locale format

The fraction of seconds is optional for the ISO 8601 time format and the printlogs text output format.

If the operand contains a space, the operand must be enclosed in quotes.

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 in one of the following formats:

  • ISO 8601 time format:

    2003-06-30T12:00:00:0000-08:00
    
  • printlogs text output format:

    30/JUN/2003:12:00:00.000-08:00
    
  • date/time of the default Java locale format

The fraction of seconds is optional for the ISO 8601 time format and the printlogs text output format.

If the operand contains a space, the operand must be enclosed in quotes.

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.


F.3.3 Output Options

Table F-4 describes the output options you can use to specify an output format. The default format is -text_short.

Table F-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.


F.3.4 General Options

Table F-5 describes the general options you can use to obtain help, cause printlogs to loop, and disable optimization.

Table F-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.


F.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 name, as described in Table F-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 F-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 name of the host 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


F.5 Environment Variable

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

Table F-7 Environment Variable

Environment Variable Description
ORACLE_PRINTLOGS_JVM_ARGS

Provide additional arguments to the JVM that runs printlogs. It 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.


F.6 Examples