Copyright (c) 2003, 2005, Oracle. All rights reserved.

Name

    printlogs - print the contents of diagnostic log files to
                standard output.

Description

    The printlogs command finds logs generated by Oracle Application 
    Server components and prints the contents of the logs to standard
    output in a common format. The printlogs command allows the contents
    of the logs to be filtered by time, or by a predicate based on the
    values of one or more log record fields.

Usage 

    printlogs <input logs> <filter options> <output format> <options> 

    where: 

    <input logs> 

        [ -home <path to Oracle home directory> ] [ -repository ] 

        [ -home <path to Oracle home directory> ] 
              [ -registration <path to registration directory> ] 

        [ -home <path to Oracle home directory> ]
              [ -registration <path to registration directory> ] 
              [ -logs <filename> .... ] 

    <filter options> 

         [ -tail <n> ] [ -last <n> ] [ -query <expression> ] 

    <expression> 

        <simple expression> 
        -not <simple expression> 
        <simple expression> -and <simple expression> 
        <simple expression> -or <simple expression> 

    <simple expression> 

        <fieldname> <op> value 
        ( <expression> ) 

    <fieldname>

        An ODL log record field name. See section "Log Record Fields"
        below for a list of the available field names.

    <op> 
  
         -eq | -eq_case | -contains | -contains_case
             | -startswith | -startswith_case | -from | -to 

    <output specification> 

       [ -count ] [ <groupByFieldList> ] 
       [ -odl | -odl_complete | -text | -text_short | -text_full ]
             [ -orderBy <orderByFieldList> ] 

    <options> 

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


Options Description

Input Options

    -home <path> 

        Define an alternate Oracle Home directory from where to read
        logs and log definitions.

    -repository (-repos) 

        Used to specify that log records should be read from the
        common repository, instead of directly from each log. The
        common repository is updated by the logloader. The logloader
        must be running in order to the repository have the contents 
        of Oracle components logs.

    -registration <path> 

        Specify an alternate registration directory that contains
        definitions of log files to be read by printlogs. The default
        registration directory is 
        ORACLE_HOME/j2ee/home/applications/ascontrol/ascontrol/WEB-INF/config/registration.

    -logs <log path> ..... 

        Specify a list of logs that should be read by printlogs. The
        registration directory will be used to find the definition of
        each log. If one of the specified logs is not defined in the
        registration directory, it will be 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 '-'. Therefore, a log path cannot start with
        a '-'. If a path starts with precede the path with './'
        ('.\' on Windows). For example, to print log file 
        -error.log, use "printlogs -logs ./-error.log".

Filter Options

    -tail <n> 

        Tell printlogs to "tail" each log before start reading. N must
        be a non-negative number. The exact meaning of the argument n
        depends on the log type. For ODL logs, printlogs will search
        backwards from the end of the log for n occurrences of the
        pattern "<MESSAGE>" and the it will start reading the log from
        that point. For other logs, it will count n lines from the end
        of the log and then start reading from that point. Note that
        use of the -tail option will disable the use of a default
        value for the -last option (see the description of the -last
        option for details about the default value).

    -last <period> 

        Tell printlogs to print only logs generated in the last
        <period> of time. The value of period must be a number, but it
        can have a suffix to denote the unit of time to use. The
        available suffixes are 's' (seconds), 'm' (minutes), 'h'
        (hours), and 'd' (days). The default unit is minutes.

        Note that the default value of -last is 10 minutes. That is,
        if you don't provide the -last option, it will be always set
        to 10 minutes. The only exception is when the -tail option is
        used, in which case there is no default value for the -last
        option. If you do not wish to use the -last option, you should
        use a very large value, for example, 1000d.

        The value of the last option will be used by printlogs to
        perform a "tail optimization" before it starts reading the
        logs. It will tail each log until if finds a timestamp that is
        within the desired range. This can speed up most queries
        significantly, but it can also cause printlogs to miss some
        records that would otherwise be in the result in case a log
        contains records out of timestamp order. It may also make
        queries slower in a few cases (for example, if you do want to
        search the entire logs). This "tail optimization" can be
        disabled by using the "-notailopt" option.

    -query <query expression> 

        Apply the expression to the each log record to filter out
        undesirable records. See below for a description of query
        expressions.
  

Query Expressions

    The following options can be used in a query expression: 

    ( ) 

        Parenthesis are used as delimiters for complex
        sub-expressions. Note that parenthesis have special meaning to
        most Unix command shells and will need to be escaped. Escaping
        is not necessary on Windows.

    -not 

        Logical negation. 

    -and 

        Logical and. 

    -or 

        Logical or. 

    <fieldname>

        Specify a log record field operand . Any of the fields listed
        in the section "Log Record Fields" can be used as a fieldname.

    -eq, -eq_case 

        Specify the equality operation. The -eq version is case
        insensitive, the -eq_case is case sensitive. This operation
        can be used with all log record fields.

    -contains, -contains_case 

        Contains operation. The result is true only if the log record
        field value contains the value operand string. The
        -contains_case version is case sensitive. This operation can
        only be used with "string" fields (all fields except
        TSTZ_ORIGINATING and TSTZ_NORMALIZED).

    -startswith, -startswith_case 

        Starts With operation. The result is true only if the log
        record field value starts with the value operand string. The
        -startswith_case version is case insensitive.  This operation
        can only be used with "string" fields (all fields except
        TSTZ_ORIGINATING and TSTZ_NORMALIZED).

    -from 

        This operation can only be used with timestamp 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),
        in the format of printlogs text output (for example:
        30/JUN/2003:12:00:00.000 -08:00), or in the date/time
        format of the default Java locale. The fraction of seconds,
        is optional in the first two formats. Note that if the operand
        contains a space, it must be enclosed in quotes.

    -to 

        This operation can only be used with timestamp 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. See the description of the -from operation above
        for the operand format.  

Output Format Options 

    -odl 

        Specify that the output should be in ODL format. This option
        will output 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, including the 
        enclosing LOG tags.

    -text_short (or -text) 

        Specify that the output should be in a short text format,
        that only includes the following fields: TSTZ_ORIGINATING,
        COMPONENT_ID, MSG_TYPE, MODULE_ID, EXEC_CONTEXT_ID, MSG_TEXT
        and SUPPL_DETAIL.

    -text_full 

        Specify that the output should be in full text format,
        including all message fields.

    -count [ groupby fieldlist ] 

        Tell printlogs to report only the number of records. An
        optional list of log record fields can be provided, in which
        case printlogs will report the count grouping the records by
        the given fields.

    -orderBy orderByFieldList 

        Tell printlogs to sort the result in the given order. The
        required orderByFieldList is a list of log records field 
        names, with the optional suffix :asc or :desc added to 
        specify ascending or descending sorting. The default sort
        order is ascending.

        Note: printlogs will sort 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.


Additional options

    -help

        Prints this document.

    -f 

        Follow. When this option is used, printlogs will not return
        after printing the result. Instead, it will go into an infinite 
        loop where it sleeps for a specified number of seconds 
        (the default is 20 seconds), 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 the -f option. The
        default value is 20 seconds.

    -notailopt 

        Disable the "tail optimization" that is usually performed
        with the -last option (see the description of the -last
        option for more information).


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 the
    following table.

    Some of these fields are intended for future use, and currently
    are not used in any diagnostic messages generated by an Oracle
    Application Server component.


    Field Name                  Description

    TSTZ_ORIGINATING            Date and time when the message was
                                generated

    TSTZ_NORMALIZED             Date and time when the message was
                                generated, adjusted for time difference
                                between the host where 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.

    ORG_ID                      The organization that wrote the component
                                that originated the message.

    COMPONENT_ID                The component that originated the message.

    MSG_ID                      A message number or some other value that 
                                uniquely identifies the message within the 
                                component.

    HOSTING_CLIENT_ID           An identifier for the client or security 
                                group that the message relates to.

    MSG_TYPE                    The type of the message. The five defined
                                message types are: INTERNAL_ERROR, ERROR,
                                WARNING, NOTIFICATION, and TRACE.
                                In addition, the value UNKNOWN  may be 
                                used when the type is not known.

    MSG_GROUP                   The name of the group that the message
                                belongs to.

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

    HOST_ID                     The host name where the message
                                originates.

    HOST_NWADDR                 The network address of the host where
                                the message originates.

    MODULE_ID                   An identifier of the module 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.

    USER_ID                     The user whose execution context 
                                originated the message.

    SUPPL_ATTRS                 A list of name/value pairs with
                                application-specific supplemental
                                attributes. To query for a specific
                                supplemental attribute value, the
                                query expression must include
                                two sub-expressions, one to match the
                                attribute name using the field name
                                SUPPL_ATTR.NAME and a second one to macth
                                matches the value using the name
                                field name SUPPL_ATTR.VALUE.

    UPSTREAM_COMPONENT_ID       The component that the originating
                                component is working with on the 
                                upstream (client) side.

    DOWNSTREAM_COMPONENT_ID     The component that the originating 
                                component is working with on the 
                                downstream (server) side.

    EXEC_CONTEXT_ID.UNIQUE_ID   A global unique identifier of the thread
                                of execution that the originating
                                component participates in. This identifier
                                can be used to correlate messages from
                                several components that may be involved 
                                in the same thread of execution.

    EXEC_CONTEXT_ID.SEQ         The sequence number that is associated
                                with the execution context. 

    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.

    EID.SEQ                     The sequence number that is associated
                                with the error instance.

    MSG_TEXT                    A descriptive text for the message.

    MSG_ARG                     A list of arguments to be bound with the
                                message text. This field contains a list
                                of an optional name and a value.

                                NOTE: printlogs currently does not support
                                the use of this field in queries.

    DETAIL_PATH                 A URL for additional information about
                                the message.

    SUPPL_DETAIL                Supplemental information about the message.


Environment Variables

    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, to set
                                memory size, or provide additional
                                properties to printlogs.


Examples 

    1.  Print records from all known logs in the last 10 minutes: 

        printlogs 

    2.  Print records from all known logs in the last 10 minutes and
        follow (after reaching the end of all log files, printlogs
        will go into an infinite loop, where it sleeps for 20 seconds
        and then reads and prints any new records that are added to
        the log files):

        printlogs -f 

    3.  Print records from the common repository in the last 2 hours: 

        printlogs -repository -last 2h 

    4.  Print records from all known logs in the given Oracle home in
        the last 2 days, in ODL format:

        printlogs -home /private/orahome2 -last 7d -odl 

    5.  Print records between 14:00 and 14:05 hours (Note: since the
        default value for the -last option is 10 minutes, it is
        necessary to specify a large value for this option to insure
        that it includes the required interval. The default value of
        the -last option will not be affected by the use of additional
        time specifications in the query expression):

        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 

    6.  Print records from OC4J logs for the home instance that
        contain the word "exception":

        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.

    7.  Print records from the last 10 minutes, sorting by component
        id, ascending, and by time, descending:

        printlogs -orderBy COMPONENT_ID TSTZ_ORIGINATING:desc 

    8.  Print the number of records from all known logs, in the last
        10 minutes, grouping by component and message type:

        printlogs -count COMPONENT_ID MSG_TYPE 

    9.  Print records that contains a particular supplemental
        attribute value. This example assumes that some messages contains
        supplemental attributes with name "MySupplAttrName" and it will
        print all messages for which the MySupplAttrName has a value of
        MySupplAttrValue. 

        printlogs -last 1d -query SUPPL_ATTR.NAME eq MySypplAttrName -and
            SUPPL_ATTR.VALUE eq MySupplAttrValue

