7.3 Selective Tracing Commands

Use the commands in Table 7-4 to configure and use selective tracing. Selective tracing provides fine-grained logging for specified users or other properties of a request. In the Use with WLST column, online means the command can only be used when connected to a running server.

Table 7-4 Tracing Commands

Use this command...	To...	Use with WLST...
configureTraceProvider	Configure a trace provider.	Online
configureTracingLoggers	Configure one or more loggers for selective tracing.	Online
listActiveTraces	List the active traces.	Online
listTraceProviders	List the tracing providers.
listTracingLoggers	List the loggers that support selective tracing.	Online
startTracing	Start a selective tracing sessions.	Online
stopTracing	Stop one or more selective tracing sessions.	Online

7.3.1 configureTraceProvider

Command Category: 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')

7.3.2 configureTracingLoggers

Command Category: 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 will be 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

7.3.3 listActiveTraces

Command Category: Tracing

Use with WLST: Online

Description

Lists the active traces.

Syntax

listActiveTraces([target])

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.

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 |  5/28/13 12:28 PM | 
a04b47f7-2830-4d80-92ee-ba160cdacf6b |USER_ID   |user2      | FINE |  5/28/13 12:30 PM |

7.3.4 listTraceProviders

Command Category: 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 will be 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()

7.3.5 listTracingLoggers

Command Category: 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
 .
 .
 .

7.3.6 startTracing

Command Category: 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

7.3.7 stopTracing

Command Category: 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 will be 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