Fusion Middleware Documentation
Advanced Search


WLST Command Reference for Infrastructure Components
Close Window

Table of Contents

Show All | Collapse

6 DMS Custom WLST Commands

This chapter provides detailed descriptions of custom WLST commands for the Dynamic Monitoring Service (DMS), which you can use to view performance metrics and to configure Event Tracing. This chapter includes command syntax, arguments and command examples.

Note:

To use these DMS custom WLST commands, you must invoke the WLST script from the Oracle Common home. See "Using Custom WLST Commands" in the Administering Oracle Fusion Middleware.

Use the DMS commands in the categories in Table 6-1 to view performance metrics and to configure Event Tracing.

Table 6-1 DMS Command Categories

Command category Description

DMS Configuration Commands

Set and view the DMS system configuration parameters.

DMS Metric Commands

View information about performance metrics.

DMS Parameter-Scoped Metrics Rules Commands

Create a metric, specifying a constraint and rules that associate sets of noun-types with sets of parameter name

DMS Event Tracing Commands

Configure Event Tracing


DMS Configuration Commands

Use the commands in Table 6-2 to configure system properties and to display system properties.

Table 6-2 DMS Configuration Commands

Use this command... To... Use with WLST...

listDMSConfigurationParameters

Display information about one or more DMS configuration parameters.

Online

setDMSConfigurationParameter

Set the value of a DMS configuration parameter.

Online


listDMSConfigurationParameters

Use online.

Description

Displays information about one or more DMS system configuration parameters.

Syntax

listDMSConfigurationParameters([name='parameter_name'][, server='server_name'])
Argument Definition
name

The name of the parameter.

server

The name of the server.


Examples

The following example displays information about all DMS system configuration parameters:

listDMSConfigurationParameters()
 
Server: AdminServer
 
    Parameter Config Value Runtime Value
    DMSClockType DEFAULT DEFAULT
    SensorActivationLevel NORMAL NORMAL
    DMSClockUnits MICROSECONDS MICROSECONDS 

The following example displays information about the DMS system configuration parameter DMSClockUnits:

listDMSConfigurationParameters(name="DMSClockUnits")
 
Server: AdminServer
 
    Parameter Config Value Runtime Value
    DMSClockUnits MICROSECONDS MICROSECONDS

setDMSConfigurationParameter

Use online.

Description

Sets the value of the specified DMS system configuration parameter. This command replaces the existing DMS System Properties, which are now deprecated.

Syntax

setDMSConfigurationParameter(name='parameter_name', value='value', server='server_name')
Argument Definition
name

The name of the parameter.

value

The value of the parameter.

server

The name of the server.


The following table lists the supported configuration parameters, together with their corresponding system property. These system properties are now deprecated.

Configuration Parameter Values Default Deprecated System Property

DMSClockType

default | highres

default

oracle.dms.clock

DMSClockUnits

milliseconds | microseconds | nanoseconds

microseconds

oracle.dms.clock.units

SensorActivationLevel

none | normal | heavy | all

normal

oracle.dms.sensors

DMSPublisherClass

Any string

null (The configuration default)

oracle.dms.publisher.classes

DMSHTTPPort

Any numeric port number

0 (The configuration default)

oracle.dms.httpd.port.start


Examples

The following example shows the DMSClockType set to HIGHRES:

setDMSConfigParameter(name= 'DMSClockType', value='HIGHRES', server='mymanaged') 

DMS Metric Commands

Use the commands in Table 6-3 to view information about a specific performance metric, a set of performance metrics, or all performance metrics for a particular server or component.

For additional details about metrics, see the chapter "Monitoring Oracle Fusion Middleware" in Administering Oracle Fusion Middleware and the chapter "Using the Oracle Dynamic Monitoring Service" in Tuning Performance.

Table 6-3 DMS Metric Commands

Use this command... To... Use with WLST...

displayMetricTableNames

Display the names of the available DMS metric tables.

Online

displayMetricTables

Display the content of the DMS metric tables.

Online

dumpMetrics

Display available metrics.

Online

reloadMetricRules

Reload the metric rules.

Online


displayMetricTableNames

Command Category: DMS Metrics

Use with WLST: Online

Description

Displays the names of the available DMS metric tables. The returned value is a list of metric table names.

Syntax

displayMetricTableNames([servers])
Argument Definition
servers

Optional. Specifies the servers from which to retrieve metrics. Valid values are a list of WebLogic Server instance names and system component names.

To specify one server, use the following syntax:

servers='servername'

To specify multiple servers, use one of the following syntax options:

servers=['servername1', 'servername2', ...]
servers=('servername1', 'servername2', ...)

If this argument is not specified, the command returns the list of metric table names for all WebLogic servers and system components.

For system components, such as Oracle HTTP Server, use the following format:

servers=['component_name], servertype='component_type')    

Examples

The following example displays metric table names for all WebLogic servers and system components:

displayMetricTableNames()
ADF
ADFc
ADFc_Metadata_Service
ADFc_Region
ADFc_Taskflow
ADFc_Viewport
BAM_common_connectionpool
BAM_common_connectionpool_main
BAM_common_messaging
BAM_common_messaging_consumers
.
.
.

The following example displays metric table names for the WebLogic Managed Server wls_server1:

displayMetricTableNames(servers='wls_server1')
ADF
JVM
JVM_ClassLoader
JVM_Compiler
JVM_GC
JVM_Memory
JVM_MemoryPool
JVM_MemorySet
JVM_OS
JVM_Runtime
.
.
.

The following example displays metric table names for two WebLogic Managed Servers:

displayMetricTableNames(servers=['wls_server1', 'bam-server1'])
ADF
ADFc
ADFc_Metadata_Service
ADFc_Region
ADFc_Taskflow
ADFc_Viewport
BAM_common_connectionpool
BAM_common_connectionpool_main
BAM_common_messaging
BAM_common_messaging_consumers
.
.
.

The following example displays the metric table names for the Oracle HTTP Server instance ohs_1:

displayMetricTableNames(servers='ohs_1', servertype='OHS') 

displayMetricTables

Command Category: DMS Metrics

Use with WLST: Online

Description

Displays the content of the DMS metric tables.

The returned value is list of DMS metric tables, with the following information about each table:

  • The metric table name.

  • The metric table schema information.

  • The metric table Rows.

The metric table schema information contains the following:

  • The name of the column.

  • The type of the column value.

  • The unit of the column.

  • The description of the column.

Syntax

displayMetricTables([metricTable_1] [, metricTable_2], [...] [, servers]
                    [, variables])
Argument Definition
metricTable_n 

Optional. Specifies a list of metric tables. By default, this argument displays all available metrics. The metric table name can contain special characters for simple pattern matching. The character '?' matches any single character. The character '*' matches zero or more characters.

You specify the metric table name. You can specify multiple metric table names in a comma-separated list.

These are the same names output by the WLST command displayMetricTableNames.

servers

Optional. Specifies the servers from which to retrieve metrics. Valid values are a list of WebLogic Server instance names and system component names.

To specify one server, use the following syntax:

servers='servername'

To specify multiple servers, use one of the following syntax options:

servers=['servername1', 'servername2', ...]
servers=('servername1', 'servername2', ...)

If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components.

For system components, such as Oracle HTTP Server, use the following format:

servers=['component_name], servertype='component_type')    
variables

Optional. Defines the metric aggregation parameters. Valid values are a set of name-value pairs. It uses the following syntax:

variables={name1:value1, name2:value2, ...}

The specific name-value pairs depend on the aggregated metric tables. Each aggregated metric table has its specific set of variable names.


Examples

The following example displays the data from the JVM and the weblogic.management.runtime.WebAppComponentRuntimeMBean metric tables, and limits it to data retrieved from wls_server1 and wls_server2:

displayMetricTables('JVM','weblogic.management.runtime.WebAppComponentRuntimeMBean',
    servers=['wls_server1','wlsserver2'])
.
.
.
---
JVM
---
 
Host:   host.example.com
Name:   JVM
Parent: /
Process:        wls_server_2:7004
ServerName:     wls_server_2
activeThreadGroups.maxValue:    8.0     groups
activeThreadGroups.minValue:    7.0     groups
activeThreadGroups.value:       8       groups
activeThreads.maxValue: 58.0    threads
activeThreads.minValue: 39.0    threads
activeThreads.value:    57      threads
freeMemory.maxValue:    174577.0        kbytes
freeMemory.minValue:    12983.0 kbytes
freeMemory.value:       98562   kbytes
startTime.value:        1368467917680   msecs
.
.
.

The following example displays the aggregated metric tables with the specified metric aggregation parameters:

displayMetricTables('j2ee_application:webservices_port_rollup',
      servers=['wls_server1','ls_server1'],
      variables={'host':'hostname', 'servletName':'dms'})
----------------------------------------
j2ee_application:webservices_port_rollup
----------------------------------------
 
Faults: 0
Requests:       0
Requests.averageTime:   0.0
Requests.totalTime:     0.0
ServerName:     wls_server1
moduleName:     RuntimeConfigService
moduleType:     WEBs
portName:       RuntimeConfigServicePortSAML
processRequest.active:  0
service.throughput:     0.0
service.time:   0.0
startTime:      1238182359291
webserviceName: RuntimeConfigService
 
Faults: 0
Requests:       0
Requests.averageTime:   0.0
Requests.totalTime:     0.0
ServerName:     wls_server1
moduleName:     TaskMetadataService
moduleType:     WEBs
portName:       TaskMetadataServicePort
processRequest.active:  0
service.throughput:     0.0
service.time:   0.0
startTime:      1238182358096
webserviceName: TaskMetadataService
.
.
.

The following example displays the metric tables which names match the specified patterns:

displayMetricTables('J??', 'JVM_*')
.
.
.
---------------
JVM_ThreadStats
---------------
 
Host:   hostname.com
JVM:    JVM
Name:   threads
Parent: /JVM/MxBeans
Process:        AdminServer:7001
ServerName:     AdminServer
contention.value:       enabled in JVM
daemon.value:   85      threads
deadlock.value: 0       threads
live.value:     89      threads
peak.value:     95      threads
started.value:  836     threads
.
.
.

dumpMetrics

Command Category: DMS Metrics

Use with WLST: Online

Description

Displays available metrics in the internal format or in XML. The returned value is a text document.

Syntax

dumpMetrics([servers] [, format])
Argument Definition
servers

Optional. Specifies the servers from which to retrieve metrics. Valid values are a list of WebLogic Server instance names and system component names.

To specify one server, use the following syntax:

servers='servername'

To specify multiple servers, use one of the following syntax options:

servers=['servername1', 'servername2', ...]
servers=('servername1', 'servername2', ...)

If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components.

For system components, such as Oracle HTTP Server, use the following format:

servers=['component_name], servertype='component_type')    
format

Optional. Specifies the command output format. Valid values are 'raw' (the default), 'xml, and 'pdml'. For example:

format='raw'
format='xml'
format='pdml'

DMS raw format is a simple metric display format; it displays one metric per line.


Examples

The following example outputs all available metrics, including native WebLogic Server metrics and internal DMS metrics, in the XML format:

dumpMetrics(format='xml')
<table name='weblogic_j2eeserver:jvm' keys='ServerName serverName'
 componentId='wls_server1' cacheable='false'>
<row cacheable='false'>
<column name='serverName'><![CDATA[wls_server2]]></column>
<column name='nurserySize.value' type='DOUBLE'>0.0</column>
<column name='jdkVersion.value'><![CDATA[1.6.0_05]]></column>
<column name='jdkVendor.value'><![CDATA[BEA Systems, Inc.]]></column>
<column name='daemonThreads.active' type='LONG'>68</column>
<column name='cpuUsage.percentage' type='DOUBLE'>100.0</column>
<column name='threads.active' type='LONG'>71</column>
<column name='ServerName'><![CDATA[wls_server2]]></column>
<column name='heapUsed.value' type='DOUBLE'>0.0</column>
</row>

The following example outputs metrics from Server-0 in the default raw format:

dumpMetrics(servers='Server-0')
.
.
.
    /JVM/MxBeans/threads/Thread-44 [type=JVM
_Thread]
     ECID.value:        null
     RID.value: null
     blocked.value:     0       msec
     blockedCount.value:        1       times
     cpu.value: 40      msecs
     lockName.value:    null
     lockOwnerID.value: null
     lockOwnerName.value:       null
     name.value:        LDAPConnThread-0 ldap://host:7001
     state.value:       RUNNABLE
     waited.value:      0       msec
     waitedCount.value: 0       times
    /JVM/MxBeans/threads/Thread-45 [type=JVM_Thread]
     ECID.value:        null
     RID.value: null
     blocked.value:     0       msec
.
.
.

The following example outputs metrics from wls_server1 and wls_server2 in XML format:

dumpMetrics(servers=['wls_server1', 'wls_server2'], format='xml')
<table name='oracle_soainfra:high_latency_sync_composites' keys='ServerName
 soainfra_composite soainfra_composite_revision soainfra_domain'
 componentId='wls_server2' cacheable='false'>
</table>
<table name='weblogic_j2eeserver:ejb_transaction' keys='ServerName appName
 ejbModuleName name serverName' componentId='wls_server2' cacheable='false'>
<row cacheable='false'>
<column name='serverName'><![CDATA[wls_server2]]></column>
<column name='name'><![CDATA[MessagingClientParlayX]]></column>
<column name='ejbTransactionCommit.percentage' type='DOUBLE'>0.0</column>
<column name='ejbTransactionRollback.completed' type='LONG'>0</column>
<column name='ejbTransactionTimeout.throughput' type='DOUBLE'>0.0</column>
<column name='ejbTransactionCommit.completed' type='LONG'>0</column>
<column name='ejbTransactionTimeout.completed' type='LONG'>0</column>
<column name='appName'><![CDATA[usermessagingserver]]></column>
<column name='ejbTransactionRollback.throughput' type='DOUBLE'>0.0</column>
<column name='ServerName'><![CDATA[wls_server2]]></column>
<column name='ejbTransactionCommit.throughput' type='DOUBLE'>0.0</column>
<column name='ejbModuleName'><![CDATA[sdpmessagingclient-ejb-parlayx.jar]]></column>
</row>
.
.
.

reloadMetricRules

Command Category: DMS Metrics

Use with WLST: Online

Description

Reloads the metric rules. You must run this command after you deploy system components or after you modify metric rules. Generally, Oracle does not recommend that you modify metric rules.

Syntax

reloadMetricRules()

Example

The following example reloads metric rules for all servers running in the domain:

reloadMetricRules()
Location changed to domainRuntime tree. This is a read-only tree with DomainMBean
 as the root. 
For more help, use help(domainRuntime)
loaded 'server-mds-11.0.xml'
loaded 'server-weblogic_j2ee_application_webservices-11.0.xml'
loaded 'server-weblogic_j2eeserver_adf-11.0.xml'
loaded 'server-weblogic_soa_composite-11.0.xml'
loaded 'server-weblogic_j2eeserver_webservices-11.0.xml'
loaded 'server-oracle_sdpmessaging-11.0.xml'
loaded 'server-weblogic_j2ee_application_webcenter-11.0.xml'
loaded 'server-weblogic_j2eeserver-11.0.xml'
reloaded metric rules for server 'wls_server_1'

.
.
.

DMS Parameter-Scoped Metrics Rules Commands

Parameter-scoped metrics commands enable you to create a metric, specifying a constraint and rules that associate sets of noun-types with sets of parameter names.

Use the commands in Table 6-4 to manage parameter-scoped metrics.

Table 6-4 DMS Parameter-Scoped Metrics Rules Commands

Use this command... To... Use with WLST...

createDMSScopedMetricsParameterConstraint

Create a parameter constraint that can be used in the setParameterScopedMetricsRule command.

Online

deleteDMSParameterScopedMetricsRules

Delete the specified parameter-scoped metric rules.

Online

dumpParameterScopedMetrics

Display the parameter-scoped metric data for the specified rule id.

Online

listDMSContextParameters

List the set of execution context parameters known to DMS.

Online

listDMSParameterScopedMetricsRules

Display the current parameter-scoped metrics configuration.

Online

resetDMSParameterScopedMetrics

Reset the parameter-scoped metric data associated with the given rule identifiers.

Online

sampleDMSContextParameterValues

Collect a sample of the set of values for the named context parameter.

Online

setDMSParameterScopedMetricsRule

Create or update a parameter-scoped metric rule.

Online


createDMSScopedMetricsParameterConstraint

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Creates a constraint that can be used with the setParameterScopedMetricsRule command.

Syntax

createDMSScopedMetricsParameterConstraint(name [, values] [,maxnumofvalues])
Argument Definition
name

The name of the parameter to which the constraint refers.

values

Optional. A list of specific values to be applied by the constraint.

maxmumofvalues

Optional. The maximum number of values that the constraint will use. If omitted, and relevant, a value of 10 is assumed. This value is ignored if the values option is provided.


Example

The following example creates the parameter constraint name URI. It applies the values MyApp/advSearch.jspx and MyApp/basicSearch.jspx.

createDMSScopedMetricsParameterConstraint(  name="URI", values=["MyApp/advSearch.jspx", "MyApp/basicSearch.jspx"])

deleteDMSParameterScopedMetricsRules

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Deletes the specified parameter-scoped metric rule and its accumulated data.

Syntax

deleteDMSParameterScopedMetricsRules([server,] ids)
Argument Definition
server

Optional. Specifies the server from which to delete the parameter-scoped metrics. Valid values are a list of WebLogic Server instance names and system component names.

To specify the server, use the following syntax:

server='servername'

If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components.

You must be connected to the Administration Server to use this argument.

For system components, such as Oracle HTTP Server, use the following format:

servers=['component_name], servertype='component_type')    

ids

The list of identifiers of the rules to be deleted. To specify more than one identifier, surround the ids with brackets and separate them with commas. For example:

ids=["id1", "id2"

Example

The following example deletes the parameter-scoped metric rules for the Managed Server wls_server1 and with the id of rule1:

deleteDMSParameterScopedMetricsRules(server='wls_server1', rule1)

dumpParameterScopedMetrics

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Displays the parameter-scoped metric data for the specified rule id.

Syntax

dumpParameterScopedMetrics([server, ]ruleid)
Argument Definition
server

Optional. Specifies the server for which to dump the parameter-scoped metric data. Valid values are a list of WebLogic Server instance names and system component names.

To specify the server, use the following syntax:

server='servername'

If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components.

You must be connected to the Administration Server to use this argument.

For system components, such as Oracle HTTP Server, use the following format:

servers=['component_name], servertype='component_type')    
ruleid

The id of the parameter-scoped metric rule for which data is to be displayed


Example

The following example displays data for the parameter-scoped metric rule regionRule for the Managed Server wls_server1:

dumpParameterScopedMetrics(server="wls_server1", ruleid="regionRule")

listDMSContextParameters

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Lists the set of execution context parameters known to DMS.

Syntax

listDMSContextParameters([server][, parameternames] [,verbose])
Argument Definition
server

Optional. Specifies the server for which to display the execution context parameters. Valid values are a list of WebLogic Server instance names and system component names.

To specify the server, use the following syntax:

server='servername'

If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components.

You must be connected to the Administration Server to use this argument.

For system components, such as Oracle HTTP Server, use the following format:

servers=['component_name], servertype='component_type')    
parameternames

Optional. A list of names of execution context parameters of interest. Any parameter name not found on the server will be ignored (no error will be reported). If this argument is not used, all execution context parameters will be listed.

verbose

Optional. If true, then for each execution context parameter the output will include, where available, the description of the execution context parameter along with its set of possible values and their descriptions.


Example

The following example shows the parameter-scoped metric rules for the Managed Server wls_server1:

listDMSContextParameters(server='wls_server1')
Server: ManagedServer1
 
    Module
    FlowId
    Action
    RCID

listDMSParameterScopedMetricsRules

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Displays the current parameter-scoped metric configuration.

Syntax

listDMSParameterScopedMetricsRules([server])
Argument Definition
server

Optional. Specifies the server for which to display the parameter-scoped metric configuration. Valid values are a list of WebLogic Server instance names and system component names.

To specify the server, use the following syntax:

server='servername'

If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components.

You must be connected to the Administration Server to use this argument.

For system components, such as Oracle HTTP Server, use the following format:

servers=['component_name], servertype='component_type')    

Example

The following example shows the parameter-scoped metric rules for the Managed Server wls_server1:

listDMSParameterScopedMetricsRules(server='wls_server1')

  Rule: ruleA 
   Noun types: 
      JDBC_Connection 
   Context Parameter Constraints: 
      Parameter: URI 
        Constraining values: 
          MyApp/advSearch.jspx 
          MyApp/basicSearch.jspx 

resetDMSParameterScopedMetrics

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Resets the parameter-scoped metric data associated with the given rule identifiers. The operation is not guaranteed to be atomic, that is, metric data will continue to be gathered while the reset operation is in progress.

Syntax

resetDMSParameterScopedMetrics([server,] ids)
Argument Definition
server

Optional. Specifies the server for which to reset the parameter-scoped metrics. Valid values are a list of WebLogic Server instance names and system component names.

To specify the server, use the following syntax:

server='servername'

If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components.

You must be connected to the Administration Server to use this argument.

For system components, such as Oracle HTTP Server, use the following format:

servers=['component_name], servertype='component_type')    
ids

The list of identifiers of the rules to be reset. To specify more than one identifier, surround the ids with brackets and separate them with commas. For example:

ids=["id1", "id2"

Example

The following example resets the rule with the id ruleA for the managed server wls_server1:

resetDMSParameterScopedMetrics(server="wls_server1", ids="ruleA")

sampleDMSContextParameterValues

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Collects a sample of the set of values for the named context parameter.

Syntax

sampleDMSContextParameterValues(parametername [, naxmuofvaleus] [,action])
Argument Definition
parametername

Optional. The name of the context parameter to be sampled. This argument must be used in combination with the argument action.

manmumofvalues

Optional. The maximum number of distinct values to include in the sample. If omitted, a value of 10 is applied. A value of 0 will cause all distinct values to be sampled. Depending on the context parameter, this could mean sampling a set of unbounded size. Only relevant when specifying the action="start".

action

Optional. The action to be sampled. This argument must be used in combination with the argument parametername.

The valid values are:

  • start: Start sampling values

  • stop: Stop sampling values and show the values

  • show: Display the histogram of sampled values.


Examples

The following example starts sampling the values for the parameter bespoke.ServiceLevel:

sampleDMSContextParameterValues(parametername="bespoke.ServiceLevel", maxnumofvalues=5, action="start")
Values of the parameter bespoke.ServiceLevel are now being sampled.
 List of parameters currently being sampled:
    bespoke.ServiceLevel has been sampled for 0 seconds.

The following example stops the sampling and displays the histogram of the values:

sampleDMSContextParameterValues()
  List of parameters currently being sampled:    bespoke.ServiceLevel has been sampled for 87 seconds.
sampleDMSContextParameterValues(parametername="bespoke.ServiceLevel", action="stop")
  Histogram of values for parameter bespoke.ServiceLevel.
    Gold 21
    Silver 5
    Bronze 37
  Values of the parameter bespoke.ServiceLevel will no longer be sampled.

setDMSParameterScopedMetricsRule

Command Category: DMS Parameter-Scoped Metrics

Use with WLST: Online

Description

Creates or updates a parameter-scoped metric rule. Only one rule at a time can manage the collection of metrics for a particular noun type and parameter combination. For example, you cannot have two separate rules to attempt to collect parameter-scoped metrics based on the context parameter URI and the noun type JDBC_Connection.

Syntax

setDMSParameterScopedMetricsRule([server,] id, nountypes [, ctxparamconstraints][, actparamconstraints] [,replace={true|false}])
Argument Definition
server

Optional. Specifies the server for which to set the parameter-scoped metric rule. Valid values are a list of WebLogic Server instance names and system component names.

To specify the server, use the following syntax:

server='servername'

If this argument is not specified, the command returns the list of metric tables for all WebLogic servers and system components.

You must be connected to the Administration Server to use this argument.

For system components, such as Oracle HTTP Server, use the following format:

servers=['component_name], servertype='component_type')    
id

The identifier of the rule.

nountypes

The list of noun types to which the rule applies.

ctxparamconstraints

Optional. The list of context parameter constraints to be used by this rule. You must specify at least one of this argument or actparamconstraints.

See createDMSScopedMetricsParameterConstraint.

actparamconstraints

Optional. The list of activation parameter constraints to be used by the rule. You must specify at least one of this argument or ctxparamconstraints.

See createDMSScopedMetricsParameterConstraint.

replace

Optional. If true, the new rule replaces an existing rule of the same id. If false or if left unset, and a rule with the id already exists an error is raised.


Example

The following example creates the rule with the id ruleA, the nountype JDBC_Connection and the context parameter constraint ctxP1:

setDMSParameterScopedMetricsRule(id="ruleA", nountypes=["JDBC_Connection"],  ctxparamconstraints=[ctxP1])

DMS Event Tracing Commands

Use the commands in Table 6-5 to configure Event Tracing. Event Tracing configures live tracing with no restarts. DMS metrics that were updated using Oracle Fusion Middleware products may be traced using the DMS Event Tracing feature.

For information about using DMS Event Tracing, see "DMS Tracing and Events" in the Tuning Performance.

Table 6-5 DMS Tracing Commands

Use this command... To... Use with WLST...

addDMSEventDestination

Add a new destination to the Event Tracing configuration.

Online

addDMSEventFilter

Add a filter to the Event Tracing configuration.

Online

addDMSEventRoute

Add the specified event route to the Event Tracing configuration

Online

enableDMSEventTrace

Enable an event trace and create a filter with a specified condition and destination and an enabled event-route.

Online

listDMSEventConfiguration

Display an overview of the event tracing configuration.

Online

listDMSEventDestination

Display the full configuration for a destination or a list of all destinations.

Online

listDMSEventFilter

Display the configuration of a filter or a list of all filters.

Online

listDMSEventRoutes

Display event routes and their status (enabled or disabled).

Online

removeDMSEventDestination

Remove the specified destination.

Online

removeDMSEventFilter

Remove the specified filter.

Online

removeDMSEventRoute

Remove the specified event route.

Online

updateDMSEventDestination

Update configuration of an event destination.

Online

updateDMSEventFilter

Update the configuration of an event filter.

Online

updateDMSEventRoute

Update the configuration of an event route.

Online


addDMSEventDestination

Command Category: DMS Event Tracing

Use with WLST: Online

Description

Adds a new destination to the Event Tracing configuration. If a destination with the same ID already exists, the command reports this and does not add the destination. You must be connected to the Administration Server to add a destination. If you are not, an error is returned.

Syntax

addDMSEventDestination(id=id [, name=dest_name] ,class=class_name
              [, props= {'name': 'value'...}] [,server=server_name])
Argument Definition
id

The unique identifier for the specified destination.

name

Optional. A name for the destination.

class

The full class name of the destination.

See Table 6-6 for a list of available classes.

props

Optional. The name/value properties to use for the destination. Some destinations require properties. For example, the LoggerDestination class requires the property loggerName.

See addDMSEventFilter for information about the syntax and allowed values.

server

Optional. The server on which to perform this operation. The default is the server to which you are connected.


Table 6-6 shows the built-in destinations, with the full runtime class name.

Table 6-6 Built-In Destinations

Runtime Destination Class Name Description

oracle.dms.trace2.runtime.LoggerDestination

Uses ODL to send the log messages to a file.

oracle.dms.event.HTTPRequestTrackerDestination

Dumps the set of active HTTP requests, allowing an administrator to get a snapshot of activity.

oracle.dms.jrockit.jfr.JFRDestination

Passes events to the JRockit Flight Recorder so that they can be viewed in the context of other data coming from the JRockit JVM and WLDF using JRockit Mission Control.

oracle.dms.jmx.MetricMBeanFactory

Exposes Nouns as MBeans.

oracle.dms.util.StackTraceCollatorDestination

Collates the stack traces that are in play whenever the events of interest occur. This is primarily a debugging tool.

The collated data is written out on shutdown, and also when an event being handled has not been reported for a certain period of time (defaults to one minute).


Examples

The following example adds a destination with the ID destination1, the name File-system, the class oracle.dms.trace2.runtime.LoggerDestination. Because the LoggerDestination requires the property loggerName, it sets the value to trace2-logger:

addDMSEventDestination(id='destination1', name='File-system',
                        class='oracle.dms.trace2.runtime.LoggerDestination', 
                        props={'loggerName': 'trace2-logger'})
 
Destination "destination1" added. 

The following example attempts to add a destination with an ID that already exists:

addDMSEventDestination(id='destination1', name='File-system',
                        class='oracle.dms.trace2.runtime.LoggerDestination', 
                        props={'loggerName': 'trace2-logger'})
 
Destination "destination1" already exists. Unable to add this.

addDMSEventFilter

Command Category: DMS Event Tracing

Use with WLST: Online

Description

Adds a filter to the Event Tracing configuration. If a filter with the same ID already exists, the command returns an error and does not add the filter.

You must be connected to the Administration Server to add an event filter. If you are not, an error message is reported.

Syntax

addDMSEventFilter(id=id [, name=name] [, etypes] 
                   , props= {'prop-name': 'value'...} 
                   [, server=server_name])
Argument Definition
id

The unique identifier for specified filter.

name

Optional. The name of the filter.

etypes

Optional. A string containing a comma-separated list of event/action pairs. This argument allows you to create a filter with a broader granularity when used with a condition. It also allows you to create a filter with a broader range of metrics. For example, all nouns or all nouns with the action create.

props

prop-name: The name of the filter property. <condition> is the only valid property, and only one condition may be specified.

value: The value of the property of the filter.

server

Optional. The server on which to perform this operation. The default is the server to which you are connected.


The following shows the syntax for etypes:

<etypes>:==
<type>:[<action>]

The following lists the valid etypes:

NOUN:CREATE|DELETE|TYPE_CHANGE                        
SENSOR                        
EVENT_SENSOR:CREATE|DELETE|METRIC_SELECTION_CHANGED,
PHASE_SENSOR:CREATE|DELETE|METRIC_SELECTION_CHANGED|START|STOP|ABORT
STATE_SENSOR:CREATE|DELETE|METRIC_SELECTION_CHANGED|UPDATE
ROLLUP_SENSOR:CREATE|DELETE|METRIC_SELECTION_CHANGED
EXECUTION_CONTEXT:START|STOP|SUSPEND
HTTP_REQUEST:START|STOP|CONTEXT_CHANGED

Note the following:

  • SENSOR has no associated actions and is expanded to include all related SENSORS and associated actions.

  • A type specified with no associated action, will default to all actions for that type. For example, HTTP_REQUEST would default to

    HTTP_REQUEST:START,HTTP_REQUEST:STOP, HTTP_REQUEST:CONTEXT_CHANGED

The following shows an etype with two event/action pairs, separated by a comma:

etypes='NOUN:DELETE, STATE_SENSOR:DELETE'

The following shows the syntax for the <condition> property of the argument props. The arguments are described in the tables following the syntax:

<condition>::=
<type>  [<operator> <condition>]
<type>::=  
<nountype> | <context>
<nountype>::=
NOUNTYPE <nountype-operator> value
<nountype-operator>::=
"equals" | "starts_with" | "contains" | "not_equals"
<context>::=
CONTEXT <name> <context-operator> [<value>] [IGNORECASE=true|false] [DATATYPE="string|long|double"
]
<context-operator>::=
"equals" | "starts_with" | "contains" | "not_equals" | "is_null" | "gt" | "le" | "ge"
<operator>::=
 AND |OR 

The following table describes the arguments for <type>:

Value Description
<nountype>

Each Sensor, with its associated metric, is organized in a hierarchy according to Nouns. A Noun type is a name that reflects the set of metrics being collected. For example, JDBC could be a Noun type. For information about Sensors and Nouns, see "Understanding Common DMS Terms and Concepts" in the Tuning Performance

<context>

An Execution Context is an association of the Execution Context ID (ECID), Relationship ID (RID), and Maps of Values. This argument allows the data stored in the map of values to be inspected and used by the filter. For example, if the map contains the key "user", you can create a filter that returns requests with "user" equal to "bruce".


The following table describes the arguments for <nountype>:

Value Description
NOUNTYPE

A keyword.

<nountype-operator>

The following are valid operators:

  • equals: Filters only if the Noun type name equals the value.

  • starts_with: Filters only if the Noun type name starts with the value.

  • contains: Filters only if the Noun type name equals the value.

  • not_equals: Filters only if the Noun type name does not equal the value.

value

The name of the Noun type on which to operate. The name can be any object for which you want to measure performance.


The following table describes <context>

Value Description
CONTEXT

A keyword.

name

The name of the context to filter.

value

The name of the context on which to operate.

<context-operator>

The following are valid operators:

  • equals: Filters only if the context name equals the value.

  • starts_with: Filters only if the context name starts with the value.

  • contains: Filters only if the context name equals the value.

  • not_equals: Filters only if the context name does not equal the value.

  • is_null: Filters only if the context name is null.

  • lt: Filters only if the context name is less than the value.

  • gt: Filters only if the context name is greater than the value.

  • le: Filters only if the context name is less than or equal to the value.

  • ge: Filters only if the context name is greater than or equal to the value.

IGNORECASE

Optional. If specified, the case of a string data type is ignored. The default is that the case of a context is used.

The IGNORECASE AND DATATYPE are not dependent on their position in the command.

DATATYPE

Optional. The valid values are string, long, or double. The default is string.

The IGNORECASE AND DATATYPE are not dependent on their position in the command.


Examples

The following example adds a filter with the name MyFilter, specifying a Noun type and context:

addDMSEventFilter(id='mds1', name='MyFilter', 
        props={'condition': 'NOUNTYPE equals MDS_Connections AND CONTEXT user equals bruce IGNORECASE'})
 
Filter "mds1" added.
 
 

The following example attempts to add a filter with the same id. The command returns an error:

addDMSEventFilter(id='mds1', name='MyFilter', 
      props={'condition': 'NOUNTYPE equals MDS_Connections AND CONTEXT user equals bruce'})
 
Unable to add filter "mds1" as a filter with that ID already exists for server "AdminServer".

The following example adds a filter with two event/action pairs:

addDMSEventFilter(id='mds2', name='MyFilter', 
          etypes='NOUN:CREATE,HTTP_REQUEST:START', 
          props={'condition': 'NOUNTYPE equals MDS_Connections 
                  AND CONTEXT user equals bruce IGNORECASE=true'})
 Filter "mds2" added.

addDMSEventRoute

Command Category: DMS Event Tracing

Use with WLST: Online

Description

Adds the specified event route to the Event Tracing configuration. If an event route with the same ID already exists, the command returns an error and does not add the event route.

You must be connected to the Administration Server to add an event route. If you are not, an error is returned.

Syntax

addDMSEventRoute([filterid=filter_id], destinationid=destination_id, [enable=true|false] [,server=server_name])
Argument Definition
filterid

Optional. The unique identifier for the filter.

destinationid

The unique identifier for the specific destination. The destination must exist.

enable

Optional. Enables the filter. Valid values are true and false. The default is true.

server

Optional. The server on which to perform this operation. The default is the server to which you are connected.


Examples

The following example adds an event route with the filter id of mds1 and the destination id of destination1:

addDMSEventRoute(filterid='mds1', destinationid='destination1', enable='false')
Event-route for filter "mds1", destination "destination1" added for server "AdminServer".

The following example attempts to add an event route that already exists:

addDMSEventRoute(filterid='mds1', destinationid='destination1', enable='false')
Unable to add event route as a mapping with filter "mds1" and destination "destination1" already exists for server "AdminServer".

enableDMSEventTrace

Command Category: DMS Event Tracing

Use with WLST: Online

Description

Enables an event trace and creates a filter with a specified condition and destination and an enabled event-route. This is a simple way to start filtering, without having to explicitly create a filter, destination and event-route, but with less configuration options. The specified destination must exist.

You must be connected to the Administration Server to enable a DMS event trace. If you are not, an error is returned.

If you require a more complex configuration, use the addDMSEventDestination, addDMSEventFilter, and addDMSEventRoute.

Syntax

enableDMSEventTrace(destinationid=destinationid [, etypes=etype] 
                     [, condition=condition]  [, server=server_name])
Argument Definition
destinationid

The unique identifier for the specific destination. Any existing destination is valid.

etypes

Optional. A string containing a comma-separated list of event/action pairs. See addDMSEventFilter for a list of available etypes.

condition

Optional. A condition on which to filter. See addDMSEventFilter for the syntax for a condition.

If no condition is specified, all DMS events will be passed

server

Optional. The server on which to perform this operation. The default is the server to which you are connected.


Example

The following example enables an event trace with a specified condition:

enableDMSEventTrace(destinationid='destination1', condition='CONTEXT username EQUALS Joe AND CONTEXT ip EQUALS 192.168.1.5')
 
Filter "auto215443800" using Destination "destination1" added, and event-route enabled for server "AdminServer".

listDMSEventConfiguration

Command Category: DMS Event Tracing

Use with WLST: Online

Description

Displays an overview of the Event Tracing configuration.

Syntax

listDMSEventConfiguration([server=server_name]] 
Argument Definition
server

Optional. The server on which to perform this operation. The default is the server to which you are connected.


Example

The following example lists the configuration for the Managed Server to which you are connected:

listDMSEventConfiguration()
 
Server: AdminServer
 
Event routes:
   Filter        :  auto215443800
   Destination   :  destination1
   Enabled       :  true

listDMSEventDestination

Command Category: DMS Event Tracing

Use with WLST: Online

Description

For a specific destination, display the full configuration. If no destination ID is specified, list the destination ID and name for all the destinations in the Event Tracing configuration.

Syntax

listDMSEventDestination([id=id] [, server=server_name)
Argument Definition
id

Optional. The unique identifier for the specific destination.

server

Optional. The server on which to perform this operation. The default is the server to which you are connected.


Examples

The following example displays information about the destinations for the Managed Server to which you are connected:

listDMSEventDestination()
Server: AdminServer
 
   Id            : HTTPRequestTrackerDestination
   Name          : HTTP Request Tracker Destination
 
 
   Id            : mbeanCreationDestination
   Name          : MBean Creation Destination

The following example displays information about the destinations for the Managed Server, wls_server_1:

listDMSEventDestination(server='wls_server_1')
Server: wls_server_1
 
   Id            : HTTPRequestTrackerDestination
   Name          : HTTP Request Tracker Destination
 
 
   Id            : mbeanCreationDestination
   Name          : MBean Creation Destination
 .
 .
 .

The following example displays information about the destination destination1:

listDMSEventDestination(id='destination1')
Server: AdminServer
 
   Id            : destination1
   Name          : File-system
   Class         : oracle.dms.trace2.runtime.LoggerDestination
   Class Info    : Logs incoming events to the logger configured for the Destination.
   Properties    : 
       Name                         Value                                 
       loggerName                   trace2-logger              

listDMSEventFilter

Command Category: DMS Event Tracing

Use with WLST: Online

Description

For a specific filter, displays the full configuration. If you do not specify a filter ID, the command displays the filter ID and name for all the filters in the Event Tracing configuration.

Syntax

listDMSEventFilter([id=id] [, server=server_name])
Argument Definition
id

Optional. The unique identifier for specified filter.

server

Optional. The server on which to perform this operation. The default is the server to which you are connected.


Example

The following example displays the list of all the filters in the Event Tracing configuration:

listDMSEventFilter()
    Id                              Name                                  
    auto215443800                   auto generated using enableEventTrace 
    JFRFilter                       JFRFilter                             
    traceFilter                                                           
    mds2                            MyFilter                              
    mds1                            MyFilter        

The following example displays the configuration of the filter mds1:

listDMSEventFilter(id='mds1')
Server: AdminServer
 
Id            : mds1
Name          : MyFilter
Properties    : 
      Condition :
      NOUNTYPE equals MDS_Connections AND CONTEXT user equals bruce IGNORECASE

listDMSEventRoutes

Command Category: DMS Event Tracing

Use with WLST: Online

Description

List the events routes and their status (enabled or disabled) that are associated with the specified filter or destination. If you do not specify a filterid or destinationid, this command lists all the event routes in the Event Tracing configuration.

Syntax

listDMSEventRoutes([filterid=filter_id] [, destinationid=destination_id]
                   [, server=server_name])
Argument Definition
filterid

Optional. The unique identifier for the filter.

destinationid

Optional. The unique identifier for the specific destination. The destination must exist.

server

Optional. The server on which to perform this operation. The default is the server to which you are connected.


Examples

The following example lists all event routes:

listDMSEventRoutes()
Server: AdminServer
 
   Filter        :  auto215443800
   Destination   :  destination1
   Enabled       :  true
 
 
   Filter        :  None
   Destination   :  HTTPRequestTrackerDestination
   Enabled       :  true

The following example lists the event routes with the filter id of filter1:

listDMSEventRoutes(filterid='mds1')
Server: AdminServer
 
   Filter        : mds1
   Destination   : destination1
   Enabled       : false

The following example lists the event routes with the destination id of destination1:

listDMSEventRoutes(destinationid='destination1')
Server: AdminServer
 
   Filter        : auto215443800
   Destination   : destination1
   Enabled       : true
   Filter        : mds2
   Destination   : destination1
   Enabled       : false
   Filter        : mds1
   Destination   : destination1
   Enabled       : false

removeDMSEventDestination

Command Category: DMS Event Tracing

Use with WLST: Online

Description

Removes an existing destination from the Event Tracing configuration. You can remove a destination only if no event route depends on the destination. If an event route that depends on the destination exists, a warning is returned.

You must be connected to the Administration Server to remove a destination. If you are not, an error is returned.

Syntax

removeDMSEventDestination(id=id [, server=server_name]) 
Argument Definition
id

The unique identifier for the destination to be removed.

server

Optional. The server on which to perform this operation. The default is the server to which you are connected.


Examples

The following example removes the destination jfr:

removeDMSEventDestination(id='jfr')
 
Destination "jfr" removed. 

The following example attempts to remove the destination styx.inpass.db1. However, because an event route exists for the destination, the command returns an error.

removeDMSEventDestination(id='styx.inpass.db1')
 
An event-route for destination 'styx.inpass.db1' exists. Unable to remove this destination for server "AdminServer".

removeDMSEventFilter

Command Category: DMS Event Tracing

Use with WLST: Online

Description

Removes an existing filter from the Event Tracing configuration. You can remove a filter only if no event route depends on the filter. If an event route that depends on the filter exists, a warning is returned.

You must be connected to the Administration Server to remove an event filter. If you are not, an error is returned.

Syntax

removeDMSEventFilter(id=id [, server=server_name])
Argument Definition
id

The unique identifier for the filter to be removed.

server

Optional. The server on which to perform this operation. The default is the server to which you are connected.


Example

The following example removes the filter mds1:

removeDMSEventFilter(id='mds1')
 
Filter "mds1" removed  for server "AdminServer". 

The following example attempts to remove a filter for which and event-route currently exists:

removeDMSEventFilter(id='allaccounts')
 
Filter "allaccounts" cannot be removed. An event-route currently exists for that
filter. Remove the event-route first using the command removeDMSEventRoute().

removeDMSEventRoute

Command Category: DMS Event Tracing

Use with WLST: Online

Description

Removes the specified event route. You must be connected to the Administration Server to add an event route. If you are not, an error is returned.

Syntax

removeDMSEventRoute([filterid=filter_id] [, destinationid=destination_id]
                    [, server=server_name])
Argument Definition
filterid

Optional. The unique identifier for the filter.

destinationid

Optional. The unique identifier for the specific destination. The destination must exist.

server

Optional. The server on which to perform this operation. The default is the server to which you are connected.


Example

The following example removes the event route with the filterid mds1 and the destination jfr:

removeDMSEventRoute(filterid='mds1', destinationid='jfr')
Event-route for filter "mds1", destination "jfr" removed for server "AdminServer".

The following example removes the event route with the destination destination1:

removeDMSEventRoute(destinationid='destination1')
Event-route for filter "None", destination "destination1" removed for server "AdminServer".

updateDMSEventDestination

Command Category: DMS Event Tracing

Use with WLST: Online

Description

Updates an existing destination, allowing a specified argument to be updated. You must be connected to the Administration Server to update a destination. If you are not, an error is returned.

Syntax

updateDMSEventDestination(id=id [, name=dest_name], class=class_name 
                 [,props= {'name': 'value'...}] [, server=server_name)
Argument Definition
id

The unique identifier for the destination to be updated.

name

Optional. A name for the destination.

class

The full classname of the destination.

See Table 6-6 for a list of available destinations.

props

Optional. The name/value properties to use for the destination. You can add a new property, or update or remove an existing one. If you update properties, you must specify all properties. If you omit a property, it is removed. For example, if a destination contains the properties LoggerName and severity, and you omit severity, it will be removed from the destination.

See addDMSEventFilter for information about the syntax and allowed values.

server

Optional. The server on which to perform this operation. The default is the server to which you are connected.


Examples

The following example updates the name of the destination jfr:

updateDMSEventDestination(id='jfr', name='Alternative Flight-Recorder')
 
Destination "jfr" updated  for server "AdminServer". 

The following example attempts to update a destination that does not exist. The command returns an error:

updateDMSEventDestination(id='destination1', 
           props={'loggerName': 'MyNewTrace2-logger'})
 
Destination "destination1" does not exist for server "AdminServer".

updateDMSEventFilter

Command Category: DMS Event Tracing

Use with WLST: Online

Description

Updates an existing filter in the Event Tracing configuration.

You must be connected to the Administration Server to update an event filter. If you are not, an error is returned.

Syntax

updateDMSEventFilter(id=id [, name=name] [,etypes=etypes], 
                     props= {'prop-name': 'value'...} 
                     [,server=server_name])
Argument Definition
id

The unique identifier for the filter to be updated.

name

Optional. The name of the filter to be updated.

etypes

Optional. A string containing a comma-separated list of event/action pairs. See addDMSEventFilter for a list of valid values.

props

prop-name: The name of the filter property. <condition> is the only valid property, and only one condition may be specified. See addDMSEventFilter for information on the syntax of prop-name.

value: The value of the property of the filter.

server

Optional. The server on which to perform this operation. The default is the server to which you are connected.


Examples

The following example updates the filter properties for the filter with the id mds1:

updateDMSEventFilter(id='mds1', 
 props={'condition': 'NOUNTYPE equals XYZ_Total_Connections AND CONTEXT user equals bruce'})
 
Filter "mds1" updated for server "AdminServer"..

The following example attempts to update a filter that does not exist:

updateDMSEventFilter(id='Filter2')
 
Filter "Filter2" does not exist for server "AdminServer".

updateDMSEventRoute

Command Category: DMS Event Tracing

Use with WLST: Online

Description

Enables or disables the specified event route. You must be connected to the Administration Server to update an event route. If you are not, an error is returned.

Syntax

updateDMSEventRoute([filterid=filter_id], destinationid=destination_id 
         [, enable=true|false] [, server=server_name])
Argument Definition
filterid

Optional. The unique identifier for the filter.

destinationid

Optional. The unique identifier for the specific destination. The destination must exist.

enable

Optional. Enables the filter. Valid values are true and false.

server

Optional. The server on which to perform this operation. The default is the server to which you are connected.


Example

The following example disables the event route with the filterid mds1 and the destinationid jfr:

updateDMSEventRoute(filterid='mds1', destinationid='jfr', enable='false')
Event-route for filter "mds1", destination "destination1" updated for server "AdminServer".