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.
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 |
---|---|
Set and view the DMS system configuration parameters. |
|
View information about performance metrics. |
|
Create a metric, specifying a constraint and rules that associate sets of noun-types with sets of parameter name |
|
Configure Event Tracing |
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... |
---|---|---|
Display information about one or more DMS configuration parameters. |
Online |
|
Set the value of a DMS configuration parameter. |
Online |
Use online.
listDMSConfigurationParameters([name][, server])
Argument | Definition |
---|---|
name |
The name of the parameter. |
server |
The name of the server. |
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
Use online.
Sets the value of the specified DMS system configuration parameter. This command replaces the existing DMS System Properties, which are now deprecated.
setDMSConfigurationParameter(name, value, server)
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 |
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.
Use this command... | To... | Use with WLST... |
---|---|---|
Display the names of the available DMS metric tables. |
Online |
|
Display the content of the DMS metric tables. |
Online |
|
Display available metrics. |
Online |
|
Reload the metric rules. |
Online |
Command Category: DMS Metrics
Use with WLST: Online
Displays the names of the available DMS metric tables. The returned value is a list of metric table names.
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') |
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')
Command Category: DMS Metrics
Use with WLST: Online
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.
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. |
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
.
.
.
Command Category: DMS Metrics
Use with WLST: Online
Displays available metrics in the internal format or in XML. The returned value is a text document.
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. |
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>
.
.
.
Command Category: DMS Metrics
Use with WLST: Online
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.
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'
.
.
.
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... |
---|---|---|
Create a parameter constraint that can be used in the setParameterScopedMetricsRule command. |
Online |
|
Delete the specified parameter-scoped metric rules. |
Online |
|
Display the parameter-scoped metric data for the specified rule id. |
Online |
|
List the set of execution context parameters known to DMS. |
Online |
|
Display the current parameter-scoped metrics configuration. |
Online |
|
Reset the parameter-scoped metric data associated with the given rule identifiers. |
Online |
|
Collect a sample of the set of values for the named context parameter. |
Online |
|
Create or update a parameter-scoped metric rule. |
Online |
Command Category: DMS Parameter-Scoped Metrics
Use with WLST: Online
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. |
Command Category: DMS Parameter-Scoped Metrics
Use with WLST: Online
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" |
Command Category: DMS Parameter-Scoped Metrics
Use with WLST: Online
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 |
Command Category: DMS Parameter-Scoped Metrics
Use with WLST: Online
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. |
Command Category: DMS Parameter-Scoped Metrics
Use with WLST: Online
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')
|
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
Command Category: DMS Parameter-Scoped Metrics
Use with WLST: Online
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.
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" |
Command Category: DMS Parameter-Scoped Metrics
Use with WLST: Online
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:
|
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.
Command Category: DMS Parameter-Scoped Metrics
Use with WLST: Online
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.
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. |
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. |
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. |
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 Tuning Performance.
Table 6-5 DMS Tracing Commands
Use this command... | To... | Use with WLST... |
---|---|---|
Add a new destination to the Event Tracing configuration. |
Online |
|
Add a filter to the Event Tracing configuration. |
Online |
|
Add the specified event route to the Event Tracing configuration |
Online |
|
Enable an event trace and create a filter with a specified condition and destination and an enabled event-route. |
Online |
|
Display an overview of the event tracing configuration. |
Online |
|
Display the full configuration for a destination or a list of all destinations. |
Online |
|
Display the configuration of a filter or a list of all filters. |
Online |
|
Display event routes and their status (enabled or disabled). |
Online |
|
Remove the specified destination. |
Online |
|
Remove the specified filter. |
Online |
|
Remove the specified event route. |
Online |
|
Update configuration of an event destination. |
Online |
|
Update the configuration of an event filter. |
Online |
|
Update the configuration of an event route. |
Online |
Command Category: DMS Event Tracing
Use with WLST: Online
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.
addDMSEventDestination(id [, name] ,class [, props= {'name': 'value'...}] [,server])
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 destination classes. |
props |
Optional. The name/value properties to use for the destination. Some destinations require properties, as described in Table 6-6. |
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. See Table 6-7 for the list of properties for this destination. |
oracle.dms.event.HTTPRequestTrackerDestination |
Dumps the set of active HTTP requests, allowing an administrator to get a snapshot of activity. See Table 6-8 for the list of properties for this destination. |
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. See Table 6-9 for the list of properties for this destination. |
oracle.dms.jmx.MetricMBeanFactory |
Exposes Nouns as MBeans. This destination has no properties. |
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). See Table 6-10 for the list of properties for this destination. |
Table 6-7 shows the properties for the oracle.dms.trace2.runtime.LoggerDestination destination.
Table 6-7 Properties for oracle.dms.trace2.runtime.LoggerDestination
Property | Description | Valid Values |
---|---|---|
LoggerName |
Required. The name of the logger. |
A valid logger name. |
writeDataAsMessageAttributes |
Optional. If set to true, the event data is logged as supplemental attributes rather than as a colon separated string in the log message. By logging the event data as supplemental attributes, you can exploit the query features of ODL that use supplemental attributes. See "Searching Log Files Using WLST" in Administering Oracle Fusion Middleware for an example. |
true and false |
Table 6-8 shows the properties for the oracle.dms.event.HTTPRequestTrackerDestination destination.
Table 6-8 Properties for oracle.dms.event.HTTPRequestTrackerDestination
Property | Description | Valid Values |
---|---|---|
excludeHeaderNames |
Optional. Prevents the destination from reporting the specified HTTP request headers if there is a chance that such headers may contain security sensitive information. |
A comma-separated list of header names to exclude. |
requestThresholdSeconds |
Optional. The number of seconds after which a request is considered slow. If the |
A positive numeric value, in seconds. |
requestFilters |
Optional. The filters for specific URIs, or URI+Clicks, to monitor. Each filter has its own threshold. Each filter is defined as follows: thresholdInSeconds!!uri!!clickId
Each filter can be separated using /SimpleWebApp-ViewController-context-root/.!!cb.%%/HCM-App/.!!'pt1:AP1:r3:0:AT1:_ATp:resId1:[0-9]+:cl1 Any requestThresholdSeconds setting will be ignored if |
A comma-separated list of request filters |
generateIncidentMinutes |
Optional. The frequency to check if any slow requests have occurred, before generating an incident. Use this setting in conjunction with the |
A positive numeric value, in seconds. |
incidentSkipCount |
Optional. If slow-request detection is enabled (with the |
A positive numeric value, in seconds. |
maxRequestsReport |
Optional. The maximum number of requests to report when generating a delayed incident. Use this setting in conjunction with the |
A positive numeric value, in seconds. |
incidentDumps |
Optional. The list of diagnostic dumps to execute on detection of a slow request. If this setting is not defined, the default set of diagnostic rules and dumps will be evaluated when creating incidents. |
A comma-separated list of diagnostic dump names. |
dumpIntervalMinutes |
Optional. The interval for executing dumps upon detection of the first slow request. This is controlled by this setting in conjunction with the existing The following explains how it works in more detail:
The incident readme.txt will detail when each dump was taken, |
A positive numeric value, in seconds. |
enablePerformanceMetrics |
Optional. After a URI, or URI+Click combination, has been identified as slow, enables additional diagnostics for subsequent requests (in the review period) that match the same URI+Click. The additional diagnostics provide an overview of where time has been spent (for example, JDBC, MDS, ADF) in the request. The data is included in the slowrequests.txt file. |
true or false. The default is false. |
Table 6-9 shows the properties for the oracle.dms.jrockit.jfr.JFRDestination destination.
Table 6-9 Properties for oracle.dms.jrockit.jfr.JFRDestination
Property | Description | Valid Values |
---|---|---|
maxRecordingSize |
Mandatory. The size of the DMS recording (beyond which the flight recorder will drop old data) |
An integer followed by K (kilobytes), M (megabytes) or G (gigabytes) |
Table 6-10 shows the properties for the oracle.dms.util.StackTraceCollatorDestination destination.
Table 6-10 Properties for oracle.dms.util.StackTraceCollatorDestination
Property | Description | Valid Values |
---|---|---|
printStream |
Optional. A string that identifies to which output the print stream will be written |
stderr or stdout. The default is stderr. |
loggerName |
Optional. The name of a logger to which output will be written. The destination will check the logger and if no INFO messages will be recorded, the destination will revert to using stderr. |
A valid logger name. |
clearTracesWhenDumped |
Optional. Whether or not the destination should reset the set of known stacks and the count of their occurrences once the current data are written out. If false, the set of stacks and counts will accumulate in memory for the lifetime of the destination. |
true or false. The default is false. |
minDumpIntervalInMinutes |
Optional. The minimum period of time between writing out data collated for a particular type of event. |
A positive numeric value, in minutes. |
eventTypesOfInterest |
Mandatory. A string describing the event types for which stack traces are to be collated. |
A valid event type. For example, SENSOR. |
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.
Command Category: DMS Event Tracing
Use with WLST: Online
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.
addDMSEventFilter(id [, name] [, etypes,] props= {'prop-name': 'value'...} [, server])
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.
|
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 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:
|
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:
|
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. |
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.
Command Category: DMS Event Tracing
Use with WLST: Online
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.
addDMSEventRoute([filterid,] destinationid [,enable=true|false] [,server])
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. |
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".
Command Category: DMS Event Tracing
Use with WLST: Online
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.
enableDMSEventTrace(destinationid [, etypes] [, condition] [, server])
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. |
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".
Command Category: DMS Event Tracing
Use with WLST: Online
listDMSEventConfiguration([server])
Argument | Definition |
---|---|
server |
Optional. The server on which to perform this operation. The default is the server to which you are connected. |
Command Category: DMS Event Tracing
Use with WLST: Online
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.
listDMSEventDestination([id] [, server])
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. |
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
Command Category: DMS Event Tracing
Use with WLST: Online
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.
listDMSEventFilter([id] [, server])
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. |
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
Command Category: DMS Event Tracing
Use with WLST: Online
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.
listDMSEventRoutes([filterid] [, destinationid][, server])
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. |
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
Command Category: DMS Event Tracing
Use with WLST: Online
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.
removeDMSEventDestination(id [, server])
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. |
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".
Command Category: DMS Event Tracing
Use with WLST: Online
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.
removeDMSEventFilter(id [, server])
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. |
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().
Command Category: DMS Event Tracing
Use with WLST: Online
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.
removeDMSEventRoute([filterid] [, destinationid] [, server])
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. |
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".
Command Category: DMS Event Tracing
Use with WLST: Online
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.
updateDMSEventDestination(id [, name,] class [,props= {'name': 'value'...}] [, server])
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. |
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".
Command Category: DMS Event Tracing
Use with WLST: Online
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.
updateDMSEventFilter(id [, name] [,etypes], props= {'prop-name': 'value'...} [,server])
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. |
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".
Command Category: DMS Event Tracing
Use with WLST: Online
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.
updateDMSEventRoute([filterid] [, destinationid] [, enable=true|false] [, server])
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. |