7 Logging Custom WLST Commands

Use the custom WLST logging commands to configure settings for log files and to view and search log files.

This chapter describes the command syntax and arguments for configuring and searching log files and provides examples of the commands.

For additional details about configuring and searching log files, see Managing Log Files and Diagnostic Data in Administering Oracle Fusion Middleware.

The following topics describe the different categories of logging commands.

• Log Configuration Commands
  The WLST log configuration commands let you configure settings for log files, such as the level of information written to the file or the maximum file size.
• Search and Display Commands
  The WLST logging commands let you search log files and view information in log files.
• Selective Tracing Commands
  Selective tracing provides fine-grained logging for specified users or other properties of a request. The WLST selective tracing commands let you configure and use selective tracing.

Log Configuration Commands

The WLST log configuration commands let you configure settings for log files, such as the level of information written to the file or the maximum file size.

Use the commands in the following sections to configure settings for log files.

• Online - Indicates that the command can only be used when connected to a running server.

• Offline - Indicates that the command can only be used when not connected to a running server.

• Online or offline - Indicates that the command can be used in both situations.

• configureLogHandler
  This command is used to configure an existing log handler, add a new handler, or remove existing handlers.
• getLogLevel
  This command is used to get the level for a given logger.
• listLoggers
  This command is used to get the list of loggers and the level of each logger.
• listLogHandlers
  This command lists the configuration of one of more log handlers.
• setLogLevel
  This command is used to set the level for a given logger.

configureLogHandler

This command is used to configure an existing log handler, add a new handler, or remove existing handlers.

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

configureLogHandler([target,] name [, maxFileSize] [,maxLogSize] [, rotationFrequency] 
 [, baseRotationTime] [, retentionPeriod] [, format] [, encoding] [, path] 
 [, handlerType] [, propertyName] [, propertyValue] [, addProperty] 
 [, removeProperty] [, addHandler] [, removeHandler] [, level] [, addToLogger] 
 [, removeFromLogger] [, useParentHandlers]  )

Argument	Definition
target	Optional. The name of a WebLogic Server instance, or a string describing a system component. For system components, refer to the component's documentation for details. The default value is the server to which WLST is connected.
name	Required. The name of a log handler.
maxFileSize	Optional. The value of the maximum file size 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. Note that this option does not apply to the QuickTrace handler.
maxLogSize	Optional. The value of the maximum size of the log files 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). Note that this option does not apply to the QuickTrace handler.
rotationFrequency	Optional. 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. Note that this options does not apply to the QuickTrace handler.
baseRotationTime	Optional. 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. Note that this option does not apply to the QuickTrace handler.
retentionPeriod	Optional. The amount of time 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. Note that this option does not apply to the QuickTrace handler.
format	Optional. 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	Optional. The character encoding for the log file.
path	Optional. The log file path. Note that this option does not apply to the QuickTrace handler.
handlerType	Optional. 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.
propertyName	Optional. 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	Optional. The new value for the handler property defined by the propertyName option.
addProperty	Optional. 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	Optional. A list of one or more handler properties to be removed.
addHandler	Optional. A boolean value. If the value is true, then the named handler is added.
removeHandler	Optional. A boolean value. If the value is true, then the named handler is removed.
level	Optional. A Java or ODL level value. The handler level is set to the given level.
addToLogger	Optional. A list of logger names. The handler is added to the given logger names.
removeFromLogger	Optional. A list of logger names. The handler is removed from the given loggers.
useParentHandlers	Optional. A boolean value. Sets the useParentHandlers flag on the loggers defined by the addToLogger or removeFromLogger options.

The following table lists the properties for the quicktrace-handler. This handler allows you to trace messages from specific loggers and store the messages in memory. See Configuring QuickTrace in Administering Oracle Fusion Middleware.

QuickTrace Property	Description
bufferSize	The approximate size of the circular QuickTrace buffer, in which log records are stored in memory. Note that actual memory consumption may be less than, but not more than this value.
enableDMSMetrics	If specified as true, DMS metrics are enabled for the quicktrace-handler. The default is true.
enableUserBuffer	If specified as true, the handler maintains an individual buffer for each user specified in the reserveBufferUserID property. If the user is not defined in the reserveBufferUserID property, the messages are cached in the COMMON buffer. If specified as false, the handler maintains only one buffer, COMMON. The default is false.
flushOnDump	If specified as true, the buffer is flushed when you execute the executeDump command. The default is true.
includeMessageArguments	If specified as true, message arguments are included with the formatted log messages that have a message ID. The default is false.
maxFieldLength	The maximum length, in bytes, for each field in a message. The fields can include the message text, supplemental attributes, thread name, source class name, source method name, and message arguments. The default is 240 bytes. A small number can restrict the amount of information returned for a message. An excessively large number can reduce the number of log records in the buffer because each message uses more bytes.
reserveBufferUserID	A list of user IDs, separated by a comma. If enableUserBuffer is specified as true, any log messages related to the user are written to a separate buffer.
supplementalAttributes	A list of supplemental attribute names. The attributes are listed in the logging.xml file. Setting supplemental attributes requires additional memory or CPU time.
useDefaultAttributes	If specified as true, default attribute values are added to each log message. The default attributes are HOST_ID, HOST_NWADDR, and USER_ID.
useLoggingContext	If specified as true, the log message includes DMS logging context attributes. The default is false. If you enable this option, the trace requires additional CPU time.
useRealThreadID	If specified as true, the handler attempts to use the real thread ID instead of the thread ID that is provided by the jave.util.logging.logRecord. The default is false. If you enable this option, the trace requires additional CPU time.
useThreadName	If specified as true, the log message includes the thread name instead of the thread ID. The default is false.

Examples

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:

configureLogHandler(name="odl-handler", rotationFrequency="daily", 
         retentionPeriod="week", removeProperty='maxFileSize'])

The following example configures the quicktrace-handler, adding the logger oracle.adf.faces, and enabling user buffers for user1 and user2:

configureLogHandler(name="quicktrace-handler", addToLogger="oracle.adf.faces",
       propertyName="enableUserBuffer", propertyValue="true",
      propertyName="reserveBufferUserID", propertyValue="user1, user2")

The oracle.adf logger is associated with the handlers odl-handler, wls-domain, and console-handler. When you set the level of the logger, these handlers use the same level (TRACE:1) for the logger oracle.adf. As a result, much information is written to the log files, consuming resources. To avoid consuming resources, set the level of the handlers to a lower level, such as WARNING or INFORMATION. For example:

configureLogHandler(name="odl-handler", level="WARNING:1")
configureLogHandler(name="wls-domain", level="WARNING:1")
configureLogHandler(name="console-handler", level="WARNING:1")

getLogLevel

This command is used to get the level for a given logger.

Command Category: Log Configuration

Use with WLST: Online

Description

Returns the level of a given Java logger.

The returned value is a string with the logger's level, or None if the logger does not exist. An empty string indicates that the logger level is null.

Syntax

getLogLevel( [target,] logger [, runtime] )

Argument	Definition
target	Optional. The name of a WebLogic Server instance, or a string describing a system component. For system 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	Optional. 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).

Examples

The following example returns the level for the logger oracle:

getLogLevel(logger='oracle')
NOTIFICATION:1

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

getLogLevel(logger='oracle', runtime=0)
NOTIFICATION:1

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

getLogLevel(logger='oracle', target='server2')
NOTIFICATION:1

listLoggers

This command is used to get the list of loggers and the level of each logger.

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

listLoggers([target] [, pattern] [,runtime])

Argument	Definition
target	Optional. The name of a WebLogic Server instance, or a string describing a system component. For system components, refer to the component's documentation for details. The default value is the server to which WLST is connected.
pattern	Optional. The name of a WebLogic Server instance, or a string describing a system component. For system components, refer to the component's documentation for details.
runtime	Optional. 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).

Examples

The following example lists all of the loggers:

listLoggers()

The following example lists all of the loggers that start with the name oracle.*.

listLoggers(pattern="oracle.*")

The following example list all config loggers:

listLoggers(runtime=0)

The following example list all loggers for the WebLogic Server server1:

listLoggers(target="server1")

listLogHandlers

This command lists the configuration of one of more log handlers.

Command Category: Log Configuration

Use with WLST: Online

Description

Lists Java log handlers configuration. This command returns a java.util.List with one entry for each handler. Each entry is a javax.management.openmbean.CompositeData object describing the handler.

Syntax

listLogHandlers([target] [, name])

Argument	Definition
target	Optional. The name of a WebLogic Server instance, or a string describing a system component. For system components, refer to the component's documentation for details. The default value is the server to which WLST is connected.
name	Optional. The name of a log handler. If the name is not provided, then all handlers are listed.

Examples

The following example lists all log handlers:

listLogHandlers()

The following example lists all log handlers named odl-handler:

listLogHandlers(name="odl-handler")

The following example lists all log handlers for the WebLogic Server server1:

listLogHandlers(target="server1")

setLogLevel

This command is used to set the level for a given logger.

Command Category: Log Configuration

Use with WLST: Online

Description

Sets the level of information written by a given Java logger to a log file.

Syntax

setLogLevel([target,] logger [, addlogger] , level [, runtime] [, persist] )

Argument	Definition
target	Optional. The name of a WebLogic Server instance, or a string describing a system component. For system 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	Optional. A Jython boolean value (0 or 1) that determines if the logger should be created if it does not exist. This option is deprecated for runtime mode. Adding a runtime logger may have no effect because the logger may be garbage collected. If you need to set the level for a logger that has not yet been created, use the persist mode.
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). An empty string can be used to set the level to null (inherited from parent). This option is required; there is no default value.
runtime	Optional. 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 a system component that does not support changing runtime loggers, this option is ignored. Note: Because runtime loggers may be garbage collected, you should change the level of the runtime logger only if you know that the logger exists and that there is a strong reference to the logger. If the logger is garbage collected, any changes made to the logger level in runtime mode that are not persisted may be lost.
persist	Optional. A Jython boolean value (0 or 1) that determines if the level should be saved to the configuration file. A value of 0 specifies that the level will be saved; a value of 1 that it will not. The default value is 1.

Examples

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

setLogLevel(logger="oracle.my.logger", level="NOTIFICATION: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:

setLogLevel(target="server1", logger="oracle.my.logger", level="WARNING", runtime=0)

Search and Display Commands

The WLST logging commands let you search log files and view information in log files.

Use the commands in the follwoinfg sections to view Oracle Fusion Middleware log files and to search log files for particular messages.

• displayLogs
  This command lists the logs for one or more components.
• listLogs
  This command is used to search and display the contents of log files.

displayLogs

This command lists the logs for one or more components.

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 does not return any data. The return value depends on the option used.

Syntax

displayLogs([searchString,][target] [, oracleInstance] [, log] [, last] [, tail]
[, pattern] [, ecid] [, component] [, module] [, type] [, app] [, query] [, groupBy]
[, orderBy [, returnData] [, format] [, exportFile] [, follow])

Argument	Definition
searchString	An optional search string. Only messages that contain the given string (case-insensitive) is returned. Note that the displayLogs command can read logs in multiple formats and it converts the messages to ODL format. The search is 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.
target	Optional. The name of a WebLogic Server instance, or a system component. For a system component, the syntax for the target is: sc: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	Optional. Defines the path to the ORACLE_INSTANCE or WebLogic domain home. The command is executed in disconnected mode when you use this parameter.
log	Optional. A log file path. The command reads messages from the given log file. If the log file path is not given, the command reads all logs associated with the given target.
last	Optional. 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' is interpreted as the last 2 hours).
tail	Optional. 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	Optional. 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	Optional. A string or string sequence containing one or more Execution Context ID (ECID) values to be used as a filter for log messages.
component	Optional. A string or string sequence containing one or more component ID values to be used as a filter for log messages.
module	Optional. A string or string sequence containing one or more module ID values to be used as a filter for log messages.
type	Optional. A string or string sequence containing one or more message type values to be used as a filter for log messages.
app	Optional. A string or string sequence containing one or more application values to be used as a filter for log messages.
query	Optional. A string that specifies an expression used to filter the contents of log messages. A simple expression has the form: field-name operator value 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. See Searching Log Files Using WLST in Administering Oracle Fusion Middlewarefor a detailed description of the query syntax.
groupBy	Optional. 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	Optional. A string list that defines the sort order for the result. The values are log message attribute names. You can extend te name with an optional suffix :asc or :desc to specify ascending or descending sorting. The default sort order is ascending. By default, the result is sorted by time.
returnData	Optional. A Jython boolean value (0 or 1). If the value is true, he command returns 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.
format	Optional. A string defined the output format. Valid values are ODL-Text, ODL-XML, ODL-complete and simple. The default format is ODL-Text.
exportFile	Optional. The name of a file to where the command output is written. By default, the output is written to standard output.
follow (f)	Optional. 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 system components.

Examples

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 a system component, ohs1:

displayLogs(target="sc: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

This command is used to search and display the contents of log files.

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

listLogs([target] [, oracleInstance] [, unit] [, fullTime]

Argument	Definition
target	Optional. The name of a WebLogic Server instance, or an Oracle Fusion Middleware system component. For a system component, the syntax for the target is: sc: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	Optional. Defines the path to the ORACLE_INSTANCE or WebLogic domain home. The command is executed in disconnected mode when you use this parameter.
unit	Optional. 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	Optional. 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.

Examples

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="sc:ohs1")

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

listLogs(oracleInstance="/scratch/Oracle/domains/base_domain",
           target="server1")

Selective Tracing Commands

Selective tracing provides fine-grained logging for specified users or other properties of a request. The WLST selective tracing commands let you configure and use selective tracing.

Use the commands in the following sections to configure and use selective tracing.

Based on use with WLST, if the command is online, then it can only be used when connected to a running server.

• configureTraceProvider
  This command is used to configure a trace provider.
• configureTracingLoggers
  This command is used to configure one or more loggers for selective tracing.
• listActiveTraces
  This command lists the active traces.
• listTraceProviders
  This command lists the tracing providers.
• listTracingLoggers
  This command lists the loggers that support selective tracing.
• startTracing
  This command is used to start a selective tracing session.
• stopTracing
  This command is used to stop one or more selective tracing sessions.

configureTraceProvider

This command is used to configure a trace provider.

Command Category: Selective Tracing

Use with WLST: Online

Description

Configures a trace provider. Currently, the only available option is to enable or disable the provider.

Syntax

configureTraceProvider([target,] name, action)

Argument	Definition
target	Optional. The name of a WebLogic Server instance, or an array of strings containing one or more target names. By default, the targets are all running server instances in the domain that are JRF-enabled.
name	Required. The trace provider name.
action	Enables or disables tracing for the provider. Valid values are enable and disable. This option is required; there is no default value.

Examples

The following example disables the DMS trace provider on all running servers in the domain:

configureTraceProvider(name='DMS', action='disable')

The following example enables the DMS trace provider for the server wls_server1:

configureTraceProvider(target='wls_server1', name='DMS', action='enable')

configureTracingLoggers

This command is used to configure one or more loggers for selective tracing.

Command Category: Selective Tracing

Use with WLST: Online

Description

Configures one or more loggers for selective tracing. This command also enables or disables a logger for selective tracing.

Syntax

configureTracingLoggers([target] [, pattern,] action)

Argument	Definition
target	Optional. The name of a WebLogic Server instance, or an array of strings containing one or more target names. By default, loggers on all running server instances in the domain that are JRF-enabled are configured for tracing.
pattern	Optional. A regular expression pattern that is used to filter logger names. The default value matches all tracing logger names.
action	Required. Enables or disables all loggers for tracing. Valid values are enable and disable. There is no default value.

Examples

The following example configures selective tracing for all loggers beginning with oracle.security:

configureTracingLoggers(pattern='oracle.security.*', action="enable")
Configured 80 loggers

The following example disables selective tracing for all loggers:

configureTracingLoggers(action="disable")
Configured 969 loggers

listActiveTraces

This command lists the active traces.

Command Category: Selective Tracing

Use with WLST: Online

Description

Lists the active traces.

Syntax

listActiveTraces([target])

Argument	Definition
targer	Optional. The name of a WebLogic Server instance, or an array of strings containing one or more target names. By default, loggers on all running server instances in the domain that are JRF-enabled are listed.

Example

The following example lists the active traces:

listActiveTraces()

-------------------------------------+----------+-----------+------+-------------------+---
Trace ID                             |Attr. Name|Attr. Value| Level| Start Time        |Exp. Time
-------------------------------------+----------+-----------+------+-------------------+---
bf13025b-b8f8-480d-8d92-14200a669b3e |USER_ID   |user1      | FINE |  1/28/17 12:28 PM | 
a04b47f7-2830-4d80-92ee-ba160cdacf6b |USER_ID   |user2      | FINE |  1/28/17 12:30 PM |

listTraceProviders

This command lists the tracing providers.

Command Category: Selective Tracing

Use with WLST: Online

Description

Lists the name, status, description, and supported parameters for the available trace providers. The status of a provider can be either enabled meaning that the provider is enabled on all targets, disabled meaning that the provider is disabled on all targets, or mixed meaning that the provider is enabled on some targets.

Syntax

listTraceProviders([target,] [name])

Argument	Definition
target	Optional. The name of a WebLogic Server instance, or an array of strings containing one or more target names. By default, providers on all running server instances in the domain that are JRF-enabled are listed.
name	Optional. A trace provider name. If you specify this parameter, only this provider is listed.

Example

The following example lists all trace providers for all running servers in the domain:

listTraceProviders()

listTracingLoggers

This command lists the loggers that support selective tracing.

Command Category: Selective Tracing

Use with WLST: Online or Offline

Description

Lists the loggers that support selective tracing. This command displays a table of logger names and their tracing status. The status enabled means that the logger is enabled for tracing on all servers. The status disabled means that the logger is disabled for tracing on all servers. The status mixed means that the logger is enabled for tracing on some servers, but disabled on others.

Syntax

listTracingLoggers([target] [, pattern])

Argument	Definition
target	Optional. The name of a WebLogic Server instance, or an array of strings containing one or more target names. By default, loggers on all running server instances in the domain that are JRF-enabled are listed.
pattern	Optional. A regular expression pattern that is used to filter logger names. The default value matches all tracing logger names.

Example

The following example lists all tracing loggers beginning with oracle.security:

listTracingLoggers(pattern="oracle.security.*")
------------------------------------------------------------------+--------
Logger                                                            | Status 
------------------------------------------------------------------+--------
oracle.security                                                   | enabled
oracle.security.audit.logger                                      | enabled
oracle.security.audit.config                                      | enabled
 .
 .
 .

startTracing

This command is used to start a selective tracing session.

Command Category: Selective Tracing

Use with WLST: Online

Description

Starts a new selective tracing session for a specified user or DMS context attribute at a specified level of tracing.

Syntax

startTracing([target,] [ traceId,] [attrName, attrValue,] [user,] level [, desc])

Argument	Definition
target	Optional. The name of a WebLogic Server instance, or an array of strings containing one or more target names. By default, loggers on all running server instances in the domain that are JRF-enabled are included in the trace.
traceId	Optional. An identifier for the tracing session. If a traceId is not provided, the command generates a unique traceId.
attrName	Optional, unless the user argument is not specified. Valid values are USER _ID, APP, CLIENT_HOST, CLIENT_ADDR, composite_name, WEBSERVICE.name, WEBSERVICE_PORT.name.
attrValue	Required if attrName is specified. The value of the attribute.
user	The user name. Messages associated with the user are returned. This is equivalent to passing the USER_ID with the attrName and AttrValue options.
level	Required. The tracing level. The level must be a valid Java or ODL level. See the table Mapping of Log Levels Among ODL, Oracle WebLogic Server, and Java in Administering Oracle Fusion Middleware.
desc	Optional. A description of the tracing session.

Example

The following example starts a trace for messages associated with user1 and sets the level of information to FINE:

startTracing(user="user1",level="FINE")
Started tracing with ID: 885649f7-8efd-4a7a-9898-accbfc0bbba3 

stopTracing

This command is used to stop one or more selective tracing sessions.

Command Category: Selective Tracing

Use with WLST: Online

Description

Stops one or more selective tracing sessions.

Syntax

stopTracing([target,] {stopAll] | traceId | attrName, attrValue | user} [, createIncident)

Argument	Definition
target	Optional. The name of a WebLogic Server instance, or an array of strings containing one or more target names. By default, loggers on all running server instances in the domain that are JRF-enabled are included in the operation.
stopAll	A Jython boolean value (0 or 1) that determines if all of the active traces are stopped. Required if the traceId, user, or attrName and attrValue arguments are not specified. The default value is 0 (false).
traceId	An identifier for the tracing session to be stopped. Required if the stopAll, user, or attrName and attrValue arguments are not specified.
attrName	Valid values are USER _ID, APP, CLIENT_HOST, CLIENT_ADDR, composite_name, WEBSERVICE.name, WEBSERVICE_PORT.name. Required if the traceId, user, stopAll arguments are not specified.
attrValue	Required if attrName is specified. The value of the attribute.
user	The user name. All tracing sessions associated with the user are stopped. Required if the stopAll, traceId, or attrName and attrValue arguments are not specified.
createIncident	Optional. A Jython boolean value (0 or 1). If true, an incident is created for each trace that is stopped. The default value is 0 (false).

Examples

The following example stops a tracing session with a specified traceId:

stopTracing(traceId="a04b47f7-2830-4d80-92ee-ba160cdacf6b")
Stopped 1 traces

The following example stops all tracing sessions:

stopTracing(stopAll=1)
Stopped 1 traces