Log Configuration Commands

Use the commands in Table 8-2 to configure settings for log files, such as the level of information written to the file or the maximum file size. In the Use with WLST column, online means the command can only be used when connected to a running server. Offline means the command can only be used when not connected to a running server. Online or offline means the command can be used in both situations.

configureLogHandler

Command Category: Log Configuration

Use with WLST: Online

Description

Configures an existing Java logging handler, adds a new handler, or removes an existing handler. It returns a java.util.List with one entry for each handler. Each entry is a javax.management.openmbean.CompositeData object describing the handler.

With this command, you can change the location of the log files, the frequency of the rotation of log files, and other log file properties.

Syntax

target—The name of a WebLogic server, or a string describing an OPMN-managed component. For OPMN-managed components, refer to the component's documentation for details.

The default value is the server to which WLST is connected.

name—The name of a log handler. This option is required.

maxFileSize—The value of the maxFileSize attribute for an ODL handler. The value is a string representing a numeric value, optionally followed by a suffix indicating a size unit (k for kilobytes, m for megabytes, g for gigabytes).

If you do not specify a suffix, the value is returned in bytes.

maxLogSize—The value of the maxLogSize attribute for an ODL handler. The value is a string representing a numeric value, optionally followed by a suffix indicating a size unit (k for kilobytes, m for megabytes, g for gigabytes).

rotationFrequency—The value of the rotation frequency for an ODL handler. The value is a string representing a numeric value, optionally followed by a suffix indicating a time unit (m for minutes, h for hours, d for days). The default unit is minutes. The following special values are also accepted and are converted to a numeric value in minutes: HOUR, HOURLY, DAY, DAILY, WEEK, WEEKLY, MONTH, MONTHLY.

baseRotationTime—The base rotation time, to be used with the rotationFrequency option. The value must be a string representing a date/time value. It can be a full date/time in ISO 8601 date/time format, or a short form including only hours and minutes. The default baseRotationTime is 00:00.

retentionPeriod—The amount of time, in minutes, that the log file is retained. The value must be a string representing a numeric value, optionally followed by a suffix indicating a time unit (m for minutes, h for hours, d for days). The default unit is minutes. The following special values are also accepted and are converted to a numeric value in minutes: HOUR, HOURLY, DAY, DAILY, WEEK, WEEKLY, MONTH, MONTHLY.

format—The format for the ODL handler. Valid values are one of the following strings: "ODL-Text" or "ODL-XML". The default format is ODL-Text.

encoding—The character encoding for the log file.

path—The log file path.

handlerType—The name of the Java class that provides the handler implementation. It must be an instance of java.util.logging.Handler or oracle.core.ojdl.logging.HandlerFactory.

options (continued)

propertyName—The name of an advanced handler property to be added or updated. The property value is specified with the propertyValue option. See the documentation for the handler for valid properties.

propertyValue—The new value for the handler property defined by the propertyName option.

addProperty—A Jython boolean value. Used in conjunction with the propertyName and propertyValue options to define that a new property is to be added to the handler.

removeProperty—A list of one or more handler properties to be removed.

addHandler—A boolean value. If the value is true, then the named handler will be added.

removeHandler—A boolean value. If the value is true, then the named handler is removed.

addToLogger—A list of logger names. The handler is added to the given logger names.

removeFromLogger—A list of logger names. The handler is removed from the given loggers.

Example

The following example specifies the maximum file size for the odl-handler:

configureLogHandler(name="odl-handler", maxFileSize="5M")

The following example specifies the rotation frequency for the odl-handler:

configureLogHandler(name="odl-handler", rotationFrequency="daily")

The following example specifies the rotation frequency and the retention period for the odl-handler. It also removes the properties maxFileSize and maxLogSize:

Syntax

target—The name of a WebLogic server, or a string describing an OPMN-managed component. For OPMN-managed components, refer to the component's documentation for details.

The default value is the server to which WLST is connected.

logger—A logger name. An empty string denotes the root logger.

This option is required and has no default.

runtime—A Jython boolean value (0 or 1) that determines if the operation is to list runtime loggers or config loggers. The default value is 1 (runtime).

Example

The following example returns the level for the logger oracle:

getLogLevel(logger='oracle')

The following example returns the level for the logger oracle, specifying only config loggers:

getLogLevel(logger='oracle', runtime=0)

The following example returns the level for the logger oracle on the Oracle WebLogic Server server2:

getLogLevel(logger='oracle', target='server2')

listLoggers

Command Category: Log Configuration

Use with WLST: Online

Description

Lists Java loggers and their levels. The command returns a PyDictionary object where the keys are logger names and the associated values are the logger levels. An empty level is used to indicate that the logger does not have the level set.

Syntax

target—The name of a WebLogic server, or a string describing an OPMN-managed component. For OPMN-managed components, refer to the component's documentation for details.

The default value is the server to which WLST is connected.

logger—A logger name. An empty string denotes the root logger.

This option is required and has no default. The command throws an exception if the logger does not exist, unless the addLogger option is also used.

addLogger—A Jython boolean value (0 or 1) that determines if the logger should be created if it does not exist.

level—The level name. It can be either a Java level or an ODL level. Some valid Java levels are: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, OR FINEST. Valid ODL levels include a message type followed by a colon and a message level. The valid ODL message types are: INCIDENT_ERROR, ERROR, WARNING, NOTIFICATION, TRACE, and UNKNOWN. The message level is represented by an integer value that qualifies the message type. Possible values are from 1 (highest severity) through 32 (lowest severity).

This option is required; there is no default value.

runtime—A Jython boolean value (0 or 1) that determines if the operation is to list runtime loggers or config loggers. The default value is 1 (runtime). If the target is an OPMN-managed component that does not support changing runtime loggers, this option is ignored.

persist—A Jython boolean value (0 or 1) that determines if the level should be saved to the configuration file. The default value is 1.

Example

The following example sets the log level to NOTIFICATION:1 for the logger oracle.my.logger:

setLogLevel(logger="oracle.my.logger", level="NOTICATION:1")

The following example sets the log level to TRACE:1 for the logger oracle.my.logger and specifies that the level should be saved to the configuration file:

setLogLevel(logger="oracle.my.logger", level="TRACE:1", persist=0)

The following example sets the log level to WARNING for the config logger oracle.my.logger on the WebLogic server server1:

displayLogs

Command Category: Search and Display

Use with WLST: Online or Offline

Description

Search and display the contents of diagnostic log files. The command returns a value only when the returnData option is set to true. By default it will not return any data. The return value depends on the option used.

Syntax

displayLogs([searchString,][options])

Argument

Definition

searchString

An optional search string. Only messages that contain the given string (case-insensitive) will be returned.

Note that the displayLogs command can read logs in multiple formats and it converts the messages to ODL format. The search will be performed in the native format, if possible. Otherwise, it may be performed in the message contents, and it may exclude mark-up. Therefore you should avoid using mark-up characters in the search string.

log—A log file path. The command will read messages from the given log file. If the log file path is not given, the command will read all logs associated with the given target.

options, continued

last—An integer value. Restricts the search to messages logged within the last minutes. The value can have a suffix 's' (second), 'm' (minute), 'h' (hour), or 'd' (day) to specify a different time unit. (For example, last='2h' will be interpreted as the last 2 hours).

tail—An integer value. Restrict the search to the last n messages from each log file and limits the number of messages displayed to n.

pattern—A regular expression pattern. Only messages that contain the given pattern are returned. Using the pattern option is similar to using the searchString argument, except that you can use a regular expression.

The regular expression pattern search is case sensitive (unless you explicitly turn on case-insensitive flags in the pattern). The pattern must follow java.util.regex syntax.

ecid—A string or string sequence containing one or more Execution Context ID (ECID) values to be used as a filter for log messages.

component—A string or string sequence containing one or more component ID values to be used as a filter for log messages.

module—A string or string sequence containing one or more module ID values to be used as a filter for log messages.

type—A string or string sequence containing one or more message type values to be used as a filter for log messages.

app—A string or string sequence containing one or more application values to be used as a filter for log messages.

query—A string that specifies an expression used to filter the contents of log messages.

A simple expression has the form:

field-nameoperatorvalue

where field-name is a log record field name and operator is an appropriate operator for the field type (for example, you can specify equals, startsWith, contains or matches for string fields).

A field name is either one of the standard ODL attribute names (such as COMPONENT_ID, MSG_TYPE, MSG_TEXT, and SUPPL_DETAIL), or the name of a supplemental attribute (application specific), prefixed by SUPPL_ATTR. (for example, SUPPL_ATTR.myAttribute).

A few common supplemental attributes can be used without the prefix, for example, you can use "APP" to filter by application name.

You can combine multiple simple expressions using the boolean operators "and", "or" and "not" to create complex expressions, and you can use parenthesis for grouping expressions.

groupBy—A string list. When the groupBy option is used, the output is a count of log messages, grouped by the attributes defined in the string list.

orderBy—A string list that defines the sort order for the result. The values are log message attribute names. The name may be extended with an optional suffix ":asc" or ":desc" to specify ascending or descending sorting. The default sort order is ascending.

exportFile—The name of a file to where the command output is written. By default, the output is written to standard output.

follow (f)—Puts the command in "follow" mode so that it continues to read the logs and display messages as new messages are added to the logs (similar to the UNIX "tail -f" command). The command will not return when the f option is used. This option is currently not supported with OPMN-managed components.

returnData—A Jython boolean value (0 or 1). If the value is true the command will return data (for example, to be used in a script). The default value is false, which means that the command only displays the data but does not return any data.

Example

The following example displays the last 100 messages from all log files in the domain:.

displayLogs(tail=100)

The following example displays all messages logged in the last 15 minutes:

displayLogs(last='15m')

The following example displays log messages that contain a given string:

displayLogs('Exception')

The following example displays log messages that contain a given ECID:

displayLogs(ecid='0000Hl9TwKUCslT6uBi8UH18lkWX000002')

The following example displays log messages of type ERROR or INCIDENT_ERROR:

displayLogs(type=['ERROR','INCIDENT_ERROR'])

The following example displays log messages for a given Java EE application:

displayLogs(app="myApplication")

The following example displays messages for an OPMN-managed component:

displayLogs(target="opmn:instance1/ohs1")

The following example displays a message summary by component and type:

displayLogs(groupBy=['COMPONENT_ID', 'MSG_TYPE'])

The following example displays messages for a particular time interval:

displayLogs(query="TIME from 11:15 and TIME to 11:20")

The following example shows an advanced query:

displayLogs(query="TIME from 11:15 and TIME to 11:20 and ( MSG_TEXT contains
exception or SUPPL_DETAIL contains exception )")

A similar query could be written as:

displayLogs("exception", query="TIME from 11:15 and TIME to 11:20")

listLogs

Command Category: Search and Display

Use with WLST: Online or Offline

Description

Lists log files for Oracle Fusion Middleware components. This command returns a PyArray with one element for each log. The elements of the array are javax.management.openmbean.CompositeData objects describing each log.

Syntax

target—The name of a WebLogic server, or an OPMN-managed Oracle Fusion Middleware component. For an OPMN-managed component, the syntax for the target is "opmn:instance-name/component-name"

In connected mode, the default target is the WebLogic domain.

In disconnected mode, there is no default; the target option is required.

oracleInstance—In disconnected mode, defines the path to the ORACLE_INSTANCE (or WebLogic domain home). In connected mode, this option is ignored.

unit—defines the unit to use for reporting file size. Valid values are B (bytes), K (kilobytes), M (megabytes), G (gigabytes), or H (display size in a human-readable form, similar to the UNIX "ls -h" option). The default value is H.

fullTime—A Jython Boolean value. If true, reports the full time for the log file last modified time. Otherwise, it displays a short version of the time. The default value is false.

Example

The following example lists all of the log files for the WebLogic domain:

listLogs()

The following example lists the log files for the WebLogic server server1:

listLogs(target="server1")

The following example lists the log files for the Oracle HTTP Server ohs1:

listLogs(target="opmn:instance1/ohs1")

The following example, used in disconnected mode, lists the log files for the WebLogic server server1: