5 Using the Oracle Dynamic Monitoring Service
The Oracle Dynamic Monitoring Service (DMS) publishes component performance data.
- About Dynamic Monitoring Service (DMS)
The Oracle Dynamic Monitoring Service (DMS) enables Oracle Fusion Middleware components to provide administration tools, such as Oracle Enterprise Manager, with data regarding the component's performance, state, and on-going behavior. - About DMS Availability
DMS functionality is available on all certified Java EE servers. - About DMS Architecture
It is important to understand the components of DMS and how they interact with other Oracle Fusion Middleware components. - Viewing DMS Metrics
Oracle Fusion Middleware components are instrumented with DMS metrics to collect information that developers, system administrators, and support analysts can use to analyze system performance or monitor system status. - Accessing DMS Metrics with WLDF
WLDF can be configured to collect MBean data when specific conditions are met, for monitoring purposes. - About DMS Execution Context
The DMS execution context is the mechanism by which requests (such as RMI requests) can be uniquely identified and thus tracked as they flow through the system. - DMS Tracing and Events
The DMS tracing feature can be used to diagnose issues or collect specific data at a specific time for a specific set of criteria. - DMS Best Practices
Implement the following best practices when you use DMS metrics.
Parent topic: Introduction
About Dynamic Monitoring Service (DMS)
The Oracle Dynamic Monitoring Service (DMS) enables Oracle Fusion Middleware components to provide administration tools, such as Oracle Enterprise Manager, with data regarding the component's performance, state, and on-going behavior.
Fusion Middleware components push data to DMS and in turn DMS publishes that data through a range of different components. DMS measures and reports metrics, traces events and system performance, and provides a context correlation service for these components.
Parent topic: Using the Oracle Dynamic Monitoring Service
Understanding Common DMS Terms and Concepts
There are common DMS terms and concepts related to DMS Senors, DMS Nouns, and DMS Tracing and Events.
DMS Sensors
DMS sensors measure performance data and enable DMS to define and collect a set of metrics. Certain metrics are always included with a sensor and others are optional.
Parent topic: Understanding Common DMS Terms and Concepts
DMS PhaseEvent Sensors
A DMS PhaseEvent sensor measures the time spent in a specific section of code that has a beginning and an end. Use a PhaseEvent sensor to track time in a method or in a block of code.
DMS can calculate optional metrics that are associated with a PhaseEvent, including the average, maximum, and minimum time that is spent in the PhaseEvent sensor.
Table 5-1 lists the metrics that are available with PhaseEvent sensors.
Table 5-1 DMS PhaseEvent Sensor Metrics
Metric | Description |
---|---|
|
Specifies the total time spent in the phase Default metric: |
|
Specifies the number of times the phase Optional metric. |
|
Specifies the minimum time spent in the phase Optional metric. |
|
Specifies the maximum time spent in the phase Optional metric. |
|
Specifies the average time spent in the phase Optional metric. |
|
Specifies the number of threads in the phase Optional metric. |
|
Specifies the maximum number of concurrent threads in the phase Optional metric. |
Parent topic: DMS Sensors
DMS Event Sensors
A DMS event sensor counts system events. Track system events through a DMS event sensor that has a short duration, or where the occurrence of the event is of interest.
Table 5-2 describes the metric that is associated with an event sensor.
Table 5-2 DMS Event Sensor Metrics
Metric | Description |
---|---|
|
Specifies the number of times the event has occurred since the process started. Default: |
Parent topic: DMS Sensors
DMS State Sensors
A DMS state sensor tracks the value of Java primitives or the content of a Java object. Supported types include integer, double, long, and object. Use a state sensor when you want to track the system status information or when you need a metric that is not associated with an event. For example, use state sensors to track queue lengths, pool sizes, buffer sizes, or host names. You assign a precomputed value to a state sensor.
Table 5-3 describes the state sensor metrics. State sensors support a default metric value
, as well as optional metrics. The optional minValue
and maxValue
metrics only apply for state sensors if the state sensor represents a numeric Java primitive (of type integer, double, or long).
Table 5-3 DMS State Sensor Metrics
Metric | Description |
---|---|
|
Specifies the metric value for Default: |
|
Specifies the number of times Optional metric. |
|
Specifies the minimum value for Optional metric. |
|
Specifies the maximum value for this Optional metric. |
Parent topic: DMS Sensors
Sensor Naming Conventions
The following list describes the DMS sensor naming conventions:
-
Sensor names must be descriptive, but not redundant. Sensor names should not contain any part of the noun name hierarchy, or type, as it is redundant.
-
Sensor names must avoid containing the value for the individual metrics.
-
Where multiple words are required to describe a sensor, the first word must start with a lowercase letter, and the following words must start with uppercase letters. For example,
computeSeries
. -
In general, avoid using a /character in a sensor name. However, there are cases where it makes sense to use a name that contains /. If a / is used in a noun or sensor name, then when you use the sensor in a string with DMS methods, use an alternative delimiter, such as , or _, which does not appear anywhere in the path; it enables the / to be properly understood as part of the noun or sensor name rather than as a delimiter.
For example, a child noun can have a name such as:
examples/jsp/num/numguess.jsp
and you can look this up by using the string:
,default,WEBs,defaultWebApp,JSPs,example/jsp/num/numguess.jsp,service
where the delimiter is the ,character.
-
The Event sensor and PhaseEvent sensor names should have the form verbnoun. For example,
activateInstance
andrunMethod
. When a PhaseEvent monitors a function, method, or code block, it must be named to reflect the task performed as clearly as possible. -
The name of a state sensor must be a noun, possibly preceded by an adjective, which describes the semantics of the value that is tracked with this state sensor. For example,
lastComputed
,totalMemory
,port
,availableThreads, activeInstances
. -
To avoid confusion, do not name sensors with strings such as
.time
,.value
, or.avg
, which are names of sensor metrics, as shown in Table 5-1, Table 5-2, and Table 5-3.
Parent topic: DMS Sensors
DMS Nouns
DMS nouns organize performance data. Sensors, with their associated metrics, are organized in hierarchy according to nouns. Nouns enable you to organize DMS metrics in a manner comparable to a directory structure in a file system. For example, nouns can represent classes, methods, objects, queues, connections, applications, databases, or other objects that you want to measure.
A noun type is the attribute that identifies the noun's type. Nouns that represent similar types of entities typically have the same noun type and usually record a common set of measurements for each of those entities.
- General DMS Naming
- General DMS Naming Conventions and Character Sets
- Noun and Noun Type Naming Conventions
Parent topic: Understanding Common DMS Terms and Concepts
General DMS Naming
A noun name is a string, which does not include a delimiter. For example, BasicBinomial
is a noun name. A noun full name consists of the noun name with the namespace and localpart. The noun name is preceded by the full name of its parent, and a delimiter. For example, /dmsDemo/BasicBinomial/"{http://mynamespace/}JAXWSHelloService"
is a noun full name.
A sensor name is a string, which does not include the . or the derivation. For example, computeSeries
, loops
, and lastComputed
are sensor names.
A sensor full name consists of the sensor name, preceded by the name of its associated noun and a delimiter. For example, /dmsDemo/BasicBinomial/computeSeries
, /dmsDemo/BasicBinomial/loops
, /dmsDemo/BasicBinomial/lastComputed
.
A DMS metric name consists of a sensor name plus the . character plus the metric. For example, computeSeries.time
, loops.count
, and lastComputed.value
are valid DMS metric names.
Note:
The suffixes .time
, .count
, and .value
are immutable. Sensor and noun names, however, can be modified as needed.
Parent topic: DMS Nouns
General DMS Naming Conventions and Character Sets
DMS names must be as compact as possible. When you define noun and sensor names, avoid special characters such as white space, slashes, periods, parenthesis, commas, and control characters.
Table 5-4 shows the DMS replacement for special characters in names.
Table 5-4 Replacement for Special Characters in DMS Names
Character | DMS Replacement Character |
---|---|
Space character |
Underscore character: |
Period character: |
Underscore character: |
Control character |
Underscore character: |
Less than character: |
Open parenthesis: |
Greater than character: |
Close parenthesis: |
Ampersand: |
Caret: |
Double quote: |
Backquote: |
Single quote: |
Backquote: |
Note:
Oracle Fusion Middleware includes several built-in metrics. The Oracle Fusion Middleware built-in metrics do not always follow the DMS naming conventions.
Parent topic: DMS Nouns
Noun and Noun Type Naming Conventions
The following conventions are used when naming noun and noun types:
-
A noun name must be unique.
-
A noun name must identify a specific entity of interest.
-
Noun types should have names that clearly reflect the set of metrics that are being collected. For example, Servlet is the type for a noun under which the metrics that are specific to a given servlet fall.
-
Noun type names must start with a capital letter to distinguish them from other DMS names. All nouns of a given type must contain the same set of sensors.
-
The noun naming scheme uses a / as the root of the hierarchy, with each noun acting as a container under the root or under its parent noun.
Parent topic: DMS Nouns
DMS Tracing and Events
Conceptually, DMS generates a stream of events; each event is in response to one of the event-producing actions that are being performed on the DMS API by the components that integrate with DMS (such as a sensor being updated). That stream of events can be ignored or routed (and optionally filtered) to destinations that can respond in some way to events.
Table 5-5 provides a list of DMS tracing and event terminology.
Table 5-5 DMS Tracing and Event Terminology
DMS Term | Definition |
---|---|
Condition |
A condition is the logic behind a condition filter. It determines which events might pass through a filter, based on the rules defined in the condition. Every condition filter has zero or one root condition, but conditions might include AND or OR arguments together to create compound conditions. The single root condition can describe a relatively complex rule. Two types of condition exist:
|
Destination |
A destination implements a mechanism for reacting to events that are passed to it. For example, a destination logs events to a file, sends transformed copies of events to the Java Flight Recorder, renders information gathered from incoming events as data in an MBean. |
Event Route |
An event route connects a filter to a destination. Event routes can be enabled or disabled. |
Filter |
An event tracing filter selectively passes a subset of all possible DMS runtime events. Filters can be configured with rules that determine the events that are passed and the events that are blocked. For example, it is possible to define filters to:
|
Listener |
A DMS listener is also known as the destination. See Configuring Destinations. |
Parent topic: Understanding Common DMS Terms and Concepts
About DMS Availability
DMS functionality is available on all certified Java EE servers.
This includes both the runtime features and supporting commands. Also, several features of DMS operates in JSE applications and standalone C applications.
For details on which servers are certified, see the Oracle Fusion Middleware Certification Matrix.
Parent topic: Using the Oracle Dynamic Monitoring Service
About DMS Architecture
It is important to understand the components of DMS and how they interact with other Oracle Fusion Middleware components.
DMS consists of the following features:
-
DMS Metrics: The DMS metrics feature provides Java and C APIs, which the Oracle Fusion Middleware components use for instrumenting code with performance measurements and other useful state metrics.
-
Execution Context: Execution Context supports the maintenance and propagation of a specific context structure throughout the Oracle stack. By exploiting the propagated context structure, Oracle Fusion Middleware components can record diagnostic information (such as log records) that can be correlated between different components and products running on the same or different servers and hosts. See About DMS Execution Context.
-
Events and Tracing: Event Tracing enables you to configure live tracing with no restarts. DMS metrics that are updated by using Oracle Fusion Middleware products must be traced by using the DMS Event Tracing feature. The system has been designed to facilitate not only tracing, but also to support the other functionality that is driven from DMS activity.
Figure 5-1 shows the components of DMS and how they interact with other Oracle Fusion Middleware components. The arrows show the direction in which information flows from one component to the next.
Figure 5-1 DMS Interactions with Oracle Fusion Middleware Components

Description of "Figure 5-1 DMS Interactions with Oracle Fusion Middleware Components"
Parent topic: Using the Oracle Dynamic Monitoring Service
Viewing DMS Metrics
Oracle Fusion Middleware components are instrumented with DMS metrics to collect information that developers, system administrators, and support analysts can use to analyze system performance or monitor system status.
The Fusion Middleware Control online help provides information on each of the specific metrics. See Viewing the Performance of Oracle Fusion Middleware in Administering Oracle Fusion Middleware for information on accessing metric information.
The Oracle Fusion Middleware metrics come from various sources and locations. They include MBean attributes and DMS metrics. They also come from non-Java EE servers, such as Oracle servers.
You can use various tools to view the DMS metrics.
- Viewing Metrics By Using the Spy Servlet
- Viewing Metrics with WLDF (WebLogic Diagnostic Framework)
- Viewing Metrics with WLST (Oracle WebLogic Server)
- Viewing Metrics with JConsole
- Viewing Metrics with Oracle Enterprise Manager
Parent topic: Using the Oracle Dynamic Monitoring Service
Viewing Metrics By Using the Spy Servlet
The Spy Servlet is part of the DMS Application that is deployed by default on JRF-extended installations. The Spy Servlet is launched from http://<host>:<port>/dms/Spy
. The default port for WebLogic is 1521
.
The DMS Application's web archive file is dms.war
, and can be found in the same directory as dms.jar: oracle_common/modules/oracle.dms_12.1.2/dms.war
.
See DMS Spy Servlet.
Note:
The Spy Servlet is secured by using standard Java EE declarative security in the web-application's web.xml
file, and access is granted only to members of the Administrator's group.
Parent topic: Viewing DMS Metrics
Viewing Metrics with WLDF (WebLogic Diagnostic Framework)
You can use WebLogic Diagnostic Framework (WLDF) to harvest DMS metrics from DMS metric MBeans. You can also use WLDF to monitor changes to the attribute value of an MBean. See Configuring the Harvester for Metric Collection in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.
Parent topic: Viewing DMS Metrics
Viewing Metrics with WLST (Oracle WebLogic Server)
DMS provides three commands to view metrics in WLST and they are detailed in the table below.
Table 5-6 DMS Commands
Use this command... | To do this... |
---|---|
|
List the names of the available metric tables. If there are many metric tables, consider using the NOTE: The command syntax for For example:
|
|
Show the content of the DMS metric tables. If you have many DMS metric tables, consider using the NOTE: The command syntax for For example:
|
|
Display metrics in the internal format. Valid formats for the dumpMetrics command include raw, xml, and pdml. If you have many DMS metric tables, consider using the NOTE: The command syntax for For example:
|
As well as displaying textual output, these commands also return a structured object, or a single value that you can use in a script to process.
For details on using these commands, see the following:
-
Getting Started Using the Oracle WebLogic Scripting Tool (WLST) in Administering Oracle Fusion Middleware
-
DMS Metric Commands in WLST Command Reference for Infrastructure Components
Parent topic: Viewing DMS Metrics
Viewing Metrics with JConsole
To provide a standards-based way to access metrics, DMS exposes them through MBeans. An MBean is created and registered for each type with the runtime MBean Server. The DMS sensors contained by the noun are exposed as the attributes of the MBean. Exposing the DMS metrics as MBeans allows administrators to use tools, such as JConsole (the Java monitoring and management console) and other Java Management Extension (JMX) clients, to access the DMS metrics.
MBeans also allow for integration with other Oracle diagnostics software such as WLDF (WebLogic Diagnostics Framework), which is described in Accessing DMS Metrics with WLDF. The noun name and noun type are exposed as the name and type properties of the metric MBean object name. The MBean domain name is oracle.dms
. The object name also reflects the DMS noun hierarchy.
Note:
You can use JConsole to view DMS generated MBeans on a Java EE server either locally or remotely. DMS generates an MBean for each Java DMS noun that has a valid noun type. It does not generate MBeans for the non-Java EE component metrics and the DMS nouns that have no noun types. Each DMS metric contained under the noun is mapped to an attribute in the metric MBean.
Parent topic: Viewing DMS Metrics
Viewing Metrics with Oracle Enterprise Manager
Oracle Fusion Middleware automatically and continuously measures data regarding the component's performance, state, and the on-going behavior. The metrics are automatically enabled; there is no need to set options or perform any extra configuration to collect them. See Oracle Enterprise Manager Fusion Middleware Control.
Parent topic: Viewing DMS Metrics
Accessing DMS Metrics with WLDF
WLDF can be configured to collect MBean data when specific conditions are met, for monitoring purposes.
WLDF provides a diagnostic feature that allows MBean attributes to be harvested and monitored for specific conditions. This provides a proactive way of monitoring activity in your environment and creating email and JMX notifications when a condition is triggered.
The following steps describe how to configure WLDF to send an email notification by using the WebLogic Administration Console:
It is also possible to configure WLDF to collect the MBean data for offline storage and analysis. This is achieved by configuring a WLDF Diagnostic Module to collect specific MBean attributes, and can be done by using the WebLogic Administration Console.
For details on using WLDF to harvest and monitor MBean data, see Configuring the Harvester for Metric Collection in Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.
Parent topic: Using the Oracle Dynamic Monitoring Service
About DMS Execution Context
The DMS execution context is the mechanism by which requests (such as RMI requests) can be uniquely identified and thus tracked as they flow through the system.
It also provides the means by which context information can be communicated between cooperating Fusion Middleware components involved in fulfilling requests.
Parent topic: Using the Oracle Dynamic Monitoring Service
DMS Execution Requests and Subtasks
The DMS execution context has been developed with the understanding that a single request (or task) might create many subtasks that are coordinated to complete the request or root task. Consider the following examples of requests and their associated subtasks:
-
A request sent directly to Oracle WebLogic Server from a browser:
-
Root task only on Oracle WebLogic Server
-
-
A request sent through Oracle Server (acting as a reverse proxy) to Oracle WebLogic Server:
-
Root task on Oracle Server
-
Single sub-task on Oracle WebLogic Server
-
-
A request sent from an Oracle Server (acting as a reverse proxy) to an Oracle WebLogic Server that requires invocation of two remote web services from an Oracle WebLogic Server to fulfill the request:
-
Root task on an Oracle Server
-
Single sub-task on an Oracle WebLogic Server
-
Two sub-subtasks, one on each web service
-
A DMS execution context is composed of the following:
-
A unique identifier, the Execution Context ID (ECID).
The ECID is unique for each new root task and is shared across the tree of tasks that are associated with the root task.
-
A relationship identifier, the Relationship ID (RID).
The RID is an ordered set of numbers that describes the location of each task in the tree of tasks. The leading number is usually a zero. A leading number of 1 indicates that it has not been possible to track the location of the sub-task within the overall sub-task tree.
-
A set of name-value pairs by which globally relevant data can be shared among Oracle Fusion Middleware components.
The following three scenarios illustrate how ECID and RID are used when a request is sent from an Oracle Server (acting as a reverse proxy) to an Oracle WebLogic Server and the server requires invocation of two remote web services from Oracle WebLogic Server.
-
Root task on Oracle Server:
-
New ECID = B5C094FA...BE4AE8
-
Root RID = 0
-
-
Single subtask on Oracle WebLogic Server:
-
Same ECID = B5C094FA...BE4AE8
-
Sub-task RID = 0:1
-
-
Two subtasks, one on each web service:
-
First web service invoked
Same ECID = B5C094FA...BE4AE8
Sub-task RID = 0:1:1
-
Second web service invoked
Same ECID = B5C094FA...BE4AE8
Sub-task RID = 0:1:2
-
Parent topic: About DMS Execution Context
DMS Execution Context Usage
The most immediate benefits of the DMS execution context are realized when attempting to correlate log messages between servers. The Oracle standard format for logging involves a field dedicated to the ECID. Once the ECID is known, when its read from an ERROR level log message for example, it is possible to locate all other log messages that are associated with that task by querying the log files for messages that contain that ECID.
The following example shows a very specific case of using the command:
displayLogs(ecid="B5C094FA...BE4AE8");
In this example, any log files with messages that contain the ECID B5C094FA...BE4AE8
is displayed.
Parent topic: About DMS Execution Context
DMS Execution Context Communication
Figure 5-2 shows the components that cooperate to communicate the DMS execution context between each other. Arrows pointing to a component indicate the protocols that are inspected for incoming context information. Outgoing arrows show protocols to which context information is added. It is possible for a single component to send requests to itself, passing context information in that request.
Figure 5-2 DMS Execution Context Communication Protocols

Description of "Figure 5-2 DMS Execution Context Communication Protocols"
Parent topic: About DMS Execution Context
DMS Tracing and Events
The DMS tracing feature can be used to diagnose issues or collect specific data at a specific time for a specific set of criteria.
DMS can selectively trace the following:
-
DMS sensor lifecycle events (create, update, delete of state sensors, event sensors, and phase sensors)
-
Context events (start, stop)
-
Events (start, stop)
The configuration that controls which of these types of events are traced, and how those events are processed, is recorded in the dms_config.xml
file. The DMS trace configuration is split into three parts:
-
Filter Configuration
Defines the rules that select the events that are of interest
-
Destination Configuration
Defines how the events are used
-
eventRoute Configuration
Defines which filters are wired to which destinations
A filter can be associated with one or more destinations thus granting the administrator to define a filter rule once and have the resulting subset of all possible events processed on one or more destinations.
The configuration can be modified by using the DMS configuration MBean or WLST commands at runtime; this makes the DMS tracing feature invaluable for diagnosing issues within a specific time period or collecting specific data at a specific time for a specific set of criteria.
See Configuring Selective Tracing Using WLST in Administering Oracle Fusion Middleware.
The following types of filter rules are supported:
-
Event Type Conditions
Used to identify if an event was triggered from the
START
orSTOP
of aPHASE_SENSOR
-
Context Type Conditions
Used to identify if the event was generated from a unit of work whose context contains a value (for example,
USER
) -
Noun Type Conditions
Used to identify if the event was triggered from a sensor whose noun is of a specific type (for example,
JDBC_CONNECTION
) -
Logical
AND
andOR
combinations of the conditions mentioned
- Configuring the DMS Event System
- Configuring Destinations
- Understanding the Format of DMS Events in Log Messages
- Understanding DMS Event Actions
Parent topic: Using the Oracle Dynamic Monitoring Service
Configuring the DMS Event System
Configuration is recorded in each server dms_config.xml
file. MBean updates can be made at runtime by using the command-line interface (CLI) commands and through the Event Configuration Mbean. Configuration updates are applied to the running system in a thread safe, but non-atomic, manner.
The object name of the DMS Event configuration MBean is: oracle.dms.event.config:name=DMSEventConfigMBean,type=JMXEventConfig
To review the current state of the DMS event configuration on your system , use the following command:
listDMSEventConfiguration([server=<server>])
The resulting output looks similar to:
Event routes: FILTER : auto662515911 DESTINATION : destination1 ENABLED : true FILTER : filter0 DESTINATION : q ENABLED : true Filters with no event route: Fred Destinations with no event route: des4
- Adding and Editing Filters
- Adding and Editing Destinations
- Adding and Editing Event Routes
- Compound Operations
Parent topic: DMS Tracing and Events
Adding and Editing Filters
Filters define the rules that select the events that are considered for tracing.
The following example shows how to add a filter that selects all events related to JDBC operations:
addDMSEventFilter(id='myJDBCFilter', props={'condition': 'NOUNTYPE sw JDBC_'})
Or:
addDMSEventFilter(id='myJDBCFilter', props={'condition': 'NOUNTYPE startsWith JDBC_'})
This filter assumes that all DMS sensor updates that are associated with JDBC operations are performed on nouns of types whose names begin with JDBC_
.
If the rule must be modified, the filter must be updated as shown in the following example:
updateDMSEventFilter(id="myJDBCFilter", props={'condition': 'NOUNTYPE startsWith JDBC_ OR NOUNTYPE startsWith MDS_'});
As of Oracle Fusion Middleware 11.1.1.6.0, the following shortened convenience operators have been added. Operators can be specified by using either the shortened or longer name.
Operators with an underscore have been deprecated in favor of the ODL format, which is to use mixed case. For example, not_equals
becomes notEquals
or ne
. The old format works, but is discouraged.
Table 5-7 DMS Operators
Noun Type Operators | Details |
---|---|
|
|
|
|
|
- |
Context Operators | Details |
---|---|
|
|
|
|
|
|
|
|
Example:
addDMSEventFilter(id='mdsbruce', name='MyFilter', props={'condition': 'NOUNTYPE eq MDS_Connections AND CONTEXT user ne bruce'}) addDMSEventFilter(id='mdsbruce', name='MyFilter', props={'condition': 'NOUNTYPE equals MDS_Connections AND CONTEXT user notequals bruce'})
For details on the syntax used to describe a filter's rule (the condition property), refer to the WebLogic Scripting Tool Command Reference or the command help.
Parent topic: Configuring the DMS Event System
Adding and Editing Destinations
Destinations encapsulate logic for responding to events. For example, a basic destination logs the event, a different destination might transform an event and pass it to another system for further processing.
The following example shows how to add a destination that logs events:
addDMSEventDestination(id="myLoggerDestination", class="oracle.dms.trace2.runtime.LoggerDestination", props={"loggerName":"myLogger"});
Merely adding the destination is not sufficient for events to be logged; to log the events, you must associate a filter with a destination by using an eventRoute, and the eventRoute must be enabled (default).
The types of destination available, and their configuration options, are described in Configuring Destinations. The following example shows how to edit an existing destination:
updateDMSEventDestination(id="myLoggerDestination", props={"loggerName":"myTraceLogger"});
Parent topic: Configuring the DMS Event System
Adding and Editing Event Routes
The following example shows how to join the filter and create a destination.
addDMSEventRoute(filterid='myJDBCFilter', destinationid='myLoggerDestination')
You can invoke addDMSEventRoute
without an explicit filterId
. In these scenarios, all events are passed to the destination without filtering.
To remove a filter or destination, you must first remove the event routes that are associated with the filter or destination (even if the event route is disabled). For example, if you wanted to remove myJDBCFilter
, you would first need to remove the eventRoute created in the previous example, and then remove the filter as shown in the following example:
removeDMSEventRoute(filterid='myJDBCFilter', destinationid='myLoggerDestination') removeDMSEventFilter(id='myJDBCFilter')
Parent topic: Configuring the DMS Event System
Compound Operations
It is possible to create a filter and an eventRoute based on that filter by using a single command (rather than using two separate commands as shown in Adding and Editing Event Routes).
Note:
The destination to be used by the event route must already be defined:
enableDMSEventTrace (destinationid='myLoggerDestination', condition='NOUNTYPE starts_with JDBC_')
In the example above, enableDMSEventTrace
automatically creates a filter with the specified condition, and also creates and enables an event route by using the new filter and the nominated destination. The output is shown in the following example:
Filter "auto605449842" using Destination "myLoggerDestination" added, and event-route enabled for server "AdminServer"
Parent topic: Configuring the DMS Event System
Configuring Destinations
DMS offers several types of destinations.
- LoggerDestination
- MBean Creator Destination
- Request Tracker Destination
- Java Flight Recorder Destination
Parent topic: DMS Tracing and Events
LoggerDestination
Table 5-8 Logger Destination
Properties | Details |
---|---|
Description |
The LoggerDestination writes each event to the associated logger. |
Implementing Class |
oracle.dms.trace2.runtime.LoggerDestination |
Properties |
|
|
The name of the ODL logger to which events are written. |
Instances of logger destinations write events to the named logger at a log level of FINER
.
The loggerName
property specifies the name of a logger, but the logger does not necessarily have to be described in logging.xml
, though it can be. If the logger name refers to a logger that is explicitly named in logging.xml
, then the logger is referred to as a static logger (see Static Loggers and Handlers). If the logger name refers to a logger that is not explicitly named in logging.xml
, then the logger is referred to as a dynamic logger (see Dynamic Loggers and Handlers).
Default configuration: the default
configuration defines the logger destination, with an identification of LoggerDestination
. This instance does not form part of any eventRoute
and therefore is not active. It is provided for convenience, and uses a dynamic logger.
- Static Loggers and Handlers
- Dynamic Loggers and Handlers
- Default Locations of the logging.xml File
- Using a CLI Command to Query the Trace Log File
Parent topic: Configuring Destinations
Static Loggers and Handlers
Loggers are the objects to which log records are presented. Log handlers are the objects through which log records are written to log files.
For complete control over the log file to which DMS trace data is written, define the logger named in the logger destination in logging.xml
. It allows you to define the name of the log file, the maximum size, format, file rotation, and policies.
Oracle recommends using commands (like the example here) to update the configuration.
setLogLevel(logger="myTraceLogger", level="FINER", addLogger=1); configureLogHandler(name="my-trace-handler", addToLogger=["myTraceLogger"], path="/tmp/myTraceLogFiles/trace", maxFileSize="10m", maxLogSize="50m", handlerType="oracle.core.ojdl.logging.ODLHandlerFactory", addHandler=1, useParentHandlers=0); configureLogHandler(name="my-trace-handler", propertyName="useSourceClassandMethod", propertyValue="false", addProperty=1);
For details on logging configuration, see Managing Log Files and Diagnostic Data in Administering Oracle Fusion Middleware.
The use of the optional property useSourceClassandMethod
set to FALSE
prevents the SRC_CLASS
and SRC_METHOD
from appearing in every message and improves performance by reducing file output times.
For static loggers, consider setting the useParentHandlers
parameter to FALSE
, otherwise duplicate event messages are logged to [server]-diagnostics.log
, and are shown in a log query.
Parent topic: LoggerDestination
Dynamic Loggers and Handlers
If the named logger has no associated handler defined in logging.xml
, then the logger destination dynamically creates a handler object that writes to a file in the server's default log output directory. (Instances of logger destinations write events to the named logger at a log level of FINER
.) The file name is the logger's name followed by -event.log
. For instance, in the example in Static Loggers and Handlers, DMS events would be written to myTraceLogger-event.log
.
Parent topic: LoggerDestination
Default Locations of the logging.xml File
The logging.xml
file can typically be found in one of the following platform locations:
Table 5-9 Default locations of the logging.xml file
Platform | Server | Location |
---|---|---|
Oracle WebLogic Server |
|
|
Parent topic: LoggerDestination
Using a CLI Command to Query the Trace Log File
If the logger destination's logger and handler are defined in the logging.xml
file then you can take advantage of the displayLogs()
command to access logged trace data without having to manually locate or search for it.
Examples:
-
To display all the log messages for the myTraceLogger:
displayLogs(query='MODULE equals myTraceLogger')
-
To display only the log messages for
myTraceLogger
that have an ECID of0000HpmSpLWEkJQ6ub3FEH194kwB000004
:displayLogs(query='MODULE equals myTraceLogger and ECID equals 0000HpmSpLWEkJQ6ub3FEH194kwB000004')
-
To display only the log messages for
myTraceLogger
that have an ECID of0000HpmSpLWEkJQ6ub3FEH194kwB000004
in the last 10 minutes:displayLogs(query='MODULE equals myTraceLogger and ECID equals 0000HpmSpLWEkJQ6ub3FEH194kwB000004', last=10)
-
To display all the log messages from a dynamic logger the log file name must be included:
displayLogs(disconnected=1, log=DOMAIN_ROOT+"/servers/AdminServer/logs/myTraceLogger-event.log")
Parent topic: LoggerDestination
MBean Creator Destination
Table 5-10 MBean Creator Destination Details
Properties | Details |
---|---|
Description |
The MBean creator destination make nouns accessible as MBeans, exposing their metrics as attributes, for access through WLDF, JConsole, and so on. |
Implementing Class |
|
Use in the default configuration: An instance of the MBean Creator destination is configured and active by default, and creates MBeans for all nouns created in the server.
By associating an instance of this destination type with a filter based on a noun-type rule, it is possible to expose (as MBeans) only those types that are of interest to the administrator.
Although it is possible to modify the configuration that is associated with an MBean creator destination at runtime, it must be understood that the reinitialization process for this type of destination impacts the performance. Frequent runtime reconfiguration is therefore discouraged.
WebLogic Diagnostic Framework (WLDF) can be used to harvest DMS metrics exposed by the MBean creator destination. See Configuring and Using the Diagnostics Framework for Oracle WebLogic Server.
Parent topic: Configuring Destinations
Metric MBean Object Name
The noun name and noun type are exposed as the name and type properties of the metric MBean object name. The MBean domain name is oracle.dms
. The object name also reflects the DMS noun hierarchy.
For example, if the noun's full path name is:
/oracle/dfw/ofm/base_domain/AdminServer
and the noun type is DFW_Incident
, the object name of the MBean representing the noun is
oracle.dms:Location=AdminServer,name=/oracle/dfw/ofm/base_domain/AdminServer,type=DFW_Incident
.
Parent topic: MBean Creator Destination
Request Tracker Destination
Table 5-11 Request Tracker Destination Details
Properties | Details |
---|---|
Description |
The Request Tracker destinations maintains a list of active requests, and makes the requests accessible to other Diagnostic Framework (DFW) components. |
Implementing Class |
|
Properties |
|
|
Comma-separated list of header names to exclude from tracking. |
Use in the default configuration: An instance of the request tracker destination is enabled by default. When a DFW incident is generated, the active request list is dumped automatically, allowing an administrator to correlate the failure with a specific request.
For each request the following information is dumped:
-
Uniform Resource Identifier (URI)
-
Start time of the request
-
Execution Context ID (ECID)
-
Query string
-
Headers
When the request tracker is not enabled the Request Dump outputs the following:
Requests are not being tracked. To enable request tracking enable the DMS oracle.dms.event.RequestTrackerDestination in dms_config.xml
Parent topic: Configuring Destinations
Executing the Request Tracker Dump
The information maintained by the request tracker can be accessed manually. When connected to a server, to execute the dump that reports the request information the WLST executeDump
command can be used, as follows:
> executeDump(name=".requests") Active Requests: StartTime: 2009-12-14 02:24:41.870 ECID: 0000IMChyqEC8xT6uBf9EH1B9X9^000009,0 URI: /myApp/Welcome.jsp QueryString: Headers: Host: myHost.example.com:7001 Connection: keep-alive User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/532.5 (KHTML, like Gecko) Chrome/4.0.249.30 Safari/532.5 Accept: application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5 Accept-Encoding: gzip,deflate Cookie: ORA_MOS_LOCALE=en%7CGB; s_nr... Accept-Language: en-GB,en-US;q=0.8,en;q=0.6 Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3
Parent topic: Request Tracker Destination
Java Flight Recorder Destination
The Java Flight Recorder (JFR) records information regarding the runtime status and behavior of the Java JVM. JFR also exposes an API through which third party events can be reported.
DMS traces and JFR traces only show part of the picture of the actions that are being performed in the server. DMS integration with JFR enhances the diagnostic information that is available to administrators and developers as follows:
-
Application level events and JVM level events can be reported as a single sequence. This avoids the need to combine such events from separate log files based only on the timestamp (which might not tick over fast enough to order events created at or around the same time).
-
Recent DMS activity can be dumped, retroactively, from the JVM at will.
-
Recent DMS and JVM events can be dumped to disk in the event of a fatal error so the JVM exits gracefully.
-
The DMS ECID can be used to correlate activity relating to the same request, or unit of work, across the span of a JFR recording.
-
The DMS ECID can be used to collect diagnostic information from all systems involved with an event, or series of events, recorded by JFR.
Parent topic: Configuring Destinations
Dynamically Derived JFR Event Types – Names, Values, and Descriptions
A DMS noun type is associated with a JFR InstantEvent
event type:
-
The name of the JFR event type for a noun type is the noun type name with the suffix
state
. -
The path of the JFR event type for a noun type is
dms/
followed by theproducer-name
, followed by the event type name. -
Event sensors do not contribute any values to the JFR event type.
-
The values of the JFR event for a noun type are described in Table 5-12:
Table 5-12 Values of the JFR Event for a Noun Type
Value Name Description Relational Notes ECID
The Execution Context ID (ECID) associated with the action.
Yes
RID
The RID associated with the action.
Yes
<noun type> name
The full path of the noun.
This field is populated with the full path of the noun. The field name assumes that the noun_type meaningfully categorizes all objects measured by the nouns of that type.
<state-sensor-name>
The value of the state sensor.
No
Each state sensor belonging to the noun contributes one of these values to the instant event. There might be more that one value in each noun.
event name
The name of the event sensor that was updated, left null otherwise.
No
The event name field is required for counting the number of times a DMS event sensor has been updated in a recording (event sensors do not contribute values to an event type).
A DMS phase sensor is associated with a JFR DurationEvent event type in the following ways:
-
The name of the JFR event type for a phase sensor belonging to a noun of a particular noun type is the noun type name followed by the phase sensor name.
-
The path of the JFR event for a noun type is
dms/
followed by theproducer-name
, followed by the event type name. -
The values of the duration event is as mentioned (except for the sensorName value). For example, the stop of a phase event results in a JFR duration event being reported to JFR that contains the state information of the phase event parent noun.
Several DMS objects allow integrators to add descriptions. Descriptions from DMS objects are used as follows:
-
Noun type description is used in creation of the JFR event type.
-
State and event sensor descriptions are not applied–there is nowhere to apply them.
-
Phase sensor descriptions are applied to their JFR event type.
Examples of Dynamically Derived Producers and Events
Table 5-13 provides examples for the rules described in Dynamically Derived JFR Event Types – Names, Values, and Descriptions:
Table 5-13 Examples of Dynamically Derived Producers and Events
DMS | Java Flight Recorder (JFR) |
---|---|
Noun type:
Noun path:
Sensors:
Where:
|
Producer Name: JDBC The Producer Name is based on the leading component of the noun path. Event Type 1 Event Type Name:
Event Type Path:
Fields:
|
- |
Producer Name: JDBC Event Type 2 Event Type Name: Event Type Path:
Fields:
|
- |
Producer Name: JDBC Event Type 3 Event Type Name: Event Type Path:
Fields:
|
- |
Producer Name: JDBC
Event Type 4 Event Type Name: Event Type Path:
Fields:
|
Understanding the Format of DMS Events in Log Messages
Table 5-14 describes the fields that make up a DMS event. Field elements are separated by : (with a few exceptions). Sample events are provided to illustrate the position of the field within an actual event string.
Table 5-14 Event Formatting Descriptions
Applicable Events | Field Number | Name | Description |
---|---|---|---|
All |
1 |
Version number |
The version number of the event format. For example:
|
All |
2 |
Event time |
The time at which the event occurred. For example:
|
All |
3 |
Source object type |
The type of object on which an action was performed to produce the event including:
For example:
|
All |
4 |
Action type |
The type of action that resulted in the generation of this event. A given source object type might not produce events for every action type:
For example: v1 |
Nouns |
5 |
Noun type |
The name of the noun type. For example:
|
6 |
Noun path |
The full path identifying the noun to which the sensor belongs For example:
|
|
All Sensor Types |
5 |
Noun type |
The name of the noun type to which this sensor belongs. For example: v1:1280503318973:STATE_SENSOR:UPDATE:JDBC_Connection:LogicalConnection:/JDBC/JDBC Data Source-0/CONNECTION_1:State.ANY:LogicalConnection@13bed086 |
6 |
Sensor name |
The name of the sensor. For example:
|
|
7 |
Noun path |
The full path identifying the noun to which the sensor belongs. For example:
|
|
Phase Sensor Types |
8 |
Start token |
The start token of the phase. For example:
|
9 |
Stop token |
The end token of the phase. For example:
|
|
State Sensor Types |
8 |
State value type |
The type of value held by the state sensor including:
For example:
|
9 |
State value |
The value of the state represented in string form. For example:
|
|
Requests |
5 |
URI |
Uniform Resource Identifier (URI) identifies the resource upon which to apply the request. For example:
|
Execution Context |
5 |
ECID, RID |
The context identifier (composed of ECID and RID separated by a comma). For execution context events the complete substring starting at the first character after the fourth event field separator (:) records the ECID, RID identifiers-the context identifiers might contain : but do not interpret them as event field separators. For example:
|
Parent topic: DMS Tracing and Events
Understanding DMS Event Actions
Table 5-15 shows the action types that can be performed on source object types.
Table 5-15 Actions Performed on Source Object Types
Object Type | Create | Update | Delete | Start | Stop | Abort |
---|---|---|---|---|---|---|
Noun |
Yes |
- |
Yes |
- |
- |
- |
Event Sensor |
Yes |
Yes |
Yes |
- |
- |
- |
Phase Sensor |
Yes |
- |
Yes |
Yes |
Yes |
Yes |
State Sensor |
Yes |
Yes |
Yes |
- |
- |
- |
Execution Context |
- |
- |
- |
Yes |
Yes |
- |
Request |
- |
- |
- |
Yes |
Yes |
- |
Parent topic: DMS Tracing and Events
DMS Best Practices
Implement the following best practices when you use DMS metrics.
The use of DMS metrics can have an impact on application performance. When you add metrics, consider the following:
-
Use a High Resolution Clock to increase DMS Precision.
By default, DMS uses the system clock for measuring time intervals during a
PhaseEvent
. The default clock reports microsecond precision in C processes such as Apache and reports millisecond precision in Java processes. Optionally, DMS supports a high resolution clock to increase the precision of performance measurements and lets you select the values for reporting time intervals. Use a high resolution clock to time phase events accurately than using the default clock or when the system's default clock does not provide the resolution needed for your requirements.System clocks are not necessarily as accurate as their precision implies. For example, a system clock that reports time in milliseconds might not tick (change) once per millisecond. Instead, it might take up to 15 ms to tick as shown in the following example:
Table 5-16 Default System Clock Time versus Actual Time (in milliseconds)
Actual Time System Time 12:00:00.000
12:00:00.000
12:00:00.001
12:00:00.000
12:00:00.002
12:00:00.000
[...]
12:00:00.014
12:00:00.000
12:00:00.015
12:00:00.015
12:00:00.016
12:00:00.015
Table 5-16 shows a phase with a 12 ms duration that runs from actual time 12:00:00.002 to 12:00:00.014 would be calculated in system time as having a duration of zero. Similarly, a phase with a 2 ms duration running from 12:00:00.014 to 12:00:00.016 would be reported in system time as having a duration of 15 ms.
Note:
These behaviors are more evident on some operating systems than others. Use caution when you analyze individual periods of time that are shorter than the tick period of the system clock. Configuring DMS to use a higher resolution clock causes DMS to record phase sensor activations with higher resolution, but the accuracy will still be limited by the underlying system.
-
Configure DMS Clocks for Reporting Time for Java.
Selecting the high resolution clock changes clocks for all applications running on the server where the clock is changed. You set the DMS clock and the reporting values globally by using the
oracle.dms.clock
andoracle.dms.clock.units
properties, which control process startup options.For example, to use the high resolution clock with the default values, set the following property on the Java command line:
-Doracle.dms.clock=highres
Caution:
If you use the high resolution clock, the default values are different from the value that Fusion Middleware Control expects (msecs). If you need the Fusion Middleware Control displays to be correct when you use the high resolution clock, then set the units property as follows:
-Doracle.dms.clock.units=msecs
Table 5-17 shows the supported values for the
oracle.dms.clock
property.Table 5-17 The oracle.dms.clock Property Values
Value Description DEFAULT
Specifies that DMS use the default clock. With the default clock, DMS uses the Java call
java.lang.System.currentTimeMillis
to obtain times for PhaseEvents.The default value for the units for the default clock is
MSECS
.HIGHRES
The Java Highres clock uses
System.nanoTime()
(no JNI required).Table 5-18 shows the supported values for the
oracle.dms.clock.units
property.Table 5-18 oracle.dms.clock.units Property Values
Value Description MSECS
Specifies that the time must be converted to milliseconds and reported as msecs. A millisecond is 10-3 seconds.
Note: This is the default value for the default clock.
USECS
Specifies that the time must be converted to microseconds and reported as
usecs
. A microsecond is 10-6 seconds.NSECS
Specifies that the time must be converted to nanoseconds and reported as
nsecs
. A nanosecond is 10-9 seconds.Note: This is the default value for the high resolution clock.
Note the following when you use the high resolution DMS clock:
-
When you set the
oracle.dms.clock
and theoracle.dms.clock.units
properties, any combination of upper and lower case characters is valid for the value that you select (case is not significant). For example, any of the following values are valid to select the high resolution clock: highres, HIGHRES, and HighRes. -
DMS checks the property values at startup. When the clock property is set with a value that is not listed in Table 5-17, DMS uses the default clock. If the
oracle.dms.clock
property is not set, DMS uses the default clock. -
When the clock units property is set to a value not listed in Table 5-18, DMS uses the default units for the specified clock.
-
Parent topic: Using the Oracle Dynamic Monitoring Service