A Instrumenting Applications with DMS

Oracle Dynamic Monitoring Service (DMS) enables application developers, support analysts, system administrators, and others to measure application-specific performance information. This appendix describes DMS and shows a sample application that demonstrates how to use DMS to instrument Java applications.

Note:

Oracle Fusion Middleware provides several built-in metrics. Using DMS to instrument applications adds new metrics to the set of built-in metrics.

This appendix includes the following sections:

Section A.1, "About DMS Performance Metrics"
Section A.2, "Adding DMS Instrumentation to Java Applications"
Section A.3, "Validating and Testing Applications Using DMS Metrics"
Section A.4, "Understanding DMS Security Considerations"
Section A.5, "Conditional Instrumentation Using DMS Sensor Weight"
Section A.6, "Dumping DMS Metrics to Files"
Section A.7, "Resetting and Destroying Sensors"
Section A.8, "DMS Coding Recommendations"
Section A.9, "Using a High Resolution Clock to Increase DMS Precision"
Section A.10, "Rolling Up DMS Data for Descendent Nouns"

A.1 About DMS Performance Metrics

The Dynamic Monitoring Service (DMS) API enables you to add performance instrumentation to Oracle Fusion Middleware applications. At run time Oracle Fusion Middleware collects performance information, called DMS metrics, that developers, system administrators, and support analysts use to help analyze system performance or monitor system status.

This section includes the following subsections:

Section A.1.1, "Instrumenting Applications with DMS"
Section A.1.2, "Monitoring DMS Metrics"
Section A.1.3, "Understanding DMS Terminology (Nouns and Sensors)"
Section A.1.4, "DMS Naming Conventions"

Oracle Fusion Middleware components provide several predefined metrics. Use the Fusion Middleware Control online help to obtain a definition of a specific performance metric. See Section 4.2.1, "Viewing Performance Metrics Using Fusion Middleware Control" for information on accessing metric information.

A.1.1 Instrumenting Applications with DMS

DMS Instrumentation refers to the process you use when you insert DMS calls into application code. By using the DMS API, you can collect and analyze performance information for your application.

To create DMS metrics you add DMS API calls that notify DMS when events occur, when important intervals begin and end, or when pre-computed values change their state. At run time, DMS stores metrics in memory and enables you to save or view the metrics.

Note:

Ensure that the dms.jar file is in your application classpath.

By default, the dms.jar file is located in the following: <ORACLE_HOME>/modules/oracle.dms_11.1.1/dms.jar.

Oracle Fusion Middleware includes built-in DMS metrics. By adding DMS calls to your applications you expand the set of built-in metrics. When you instrument your applications with DMS calls, you use the same API that the built-in metrics use. In addition, to save and display your metrics, you use the same monitoring tools that you use with built-in metrics.

Note that oracle.dms.trace.triggered.enable defaults to TRUE in Oracle Fusion Middleware 11g release 1 (11.1.1) and defaults to FALSE in 11g release 1 (11.1.1.2.0).

See Section A.2, "Adding DMS Instrumentation to Java Applications" for details.

A.1.2 Monitoring DMS Metrics

Monitoring DMS metrics refers to the process of retrieving performance metrics. When an application runs, DMS stores metrics in memory; you can view the metrics on the console or using a web browser.

Oracle Fusion Middleware provides several run time tools for viewing and saving DMS metrics, including the WLST command (with the displayMetricTableNames, displayMetricTables, and dumpMetrics subcommands) and the Spy servlet.

Note:

To use WLST commands, you must invoke WLST from the Oracle home in which the component has been installed. See "Using Custom WLST Commands" in the Oracle Fusion Middleware Administrator's Guide for more information.

Example A-1 shows the output of wlst dumpMetrics.

Example A-1 Sample Output of wlst dumpMetrics for the dmsDemo Application

 /dmsDemo [type=n/a]
  /dmsDemo/BasicBinomial [type=MathSeries]
   computeSeries.active: n threads
   computeSeries.avg: n msecs
   computeSeries.completed: n ops
   computeSeries.maxActive: n threads
   computeSeries.maxTime: n msecs
   computeSeries.minTime: n msecs
   computeSeries.time: n msecs
   lastComputed.value: n    loops.count: n ops

A.1.3 Understanding DMS Terminology (Nouns and Sensors)

This section introduces terminology related to DMS. This section contains the following subsections:

Section A.1.3.1, "DMS Metrics"
Section A.1.3.2, "DMS Sensors"
Section A.1.3.3, "DMS Nouns"
Section A.1.3.4, "DMS Roll-up Nouns"
Section A.1.3.5, "DMS Object Relationships"

Figure A-1 illustrates the organization of a set of DMS metrics that correspond to the metrics in the demo application described in this chapter and the metrics shown in Example A-1.

Figure A-1 Organization of Sample Metrics for dmsDemo Application

Shows the organization of a sample metric: dmsDemo.

Description of "Figure A-1 Organization of Sample Metrics for dmsDemo Application"

A.1.3.1 DMS Metrics

DMS metrics provide performance information that developers, system administrators, and support analysts can use to help analyze system performance or monitor system status.

A.1.3.2 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 other metrics are optionally included with a Sensor.

DMS has three different kinds of sensors:

Section A.1.3.2.1, "DMS PhaseEvent Sensors"
Section A.1.3.2.2, "DMS Event Sensors"
Section A.1.3.2.3, "DMS State Sensors"

A.1.3.2.1 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 associated with a PhaseEvent, including the average, maximum, and minimum time that is spent in the PhaseEvent Sensor.

Table A-1 lists the metrics available with PhaseEvent Sensors.

Table A-1 DMS PhaseEvent Sensor Metrics

Metric	Description
`sensor_name`.`time`	Specifies the total time spent in the phase `sensor_name`. Default metric: `time` is a default PhaseEvent Sensor metric.
`sensor_name`.`completed`	Specifies the number of times the phase `sensor_name` has completed since the process was started. Optional metric
`sensor_name`.`minTime`	Specifies the minimum time spent in the phase `sensor_name`, for all the times the `sensor_name` phase completed. Optional metric
`sensor_name`.`maxTime`	Specifies the maximum time spent in the phase `sensor_name`, for all the times the `sensor_name` phase completed. Optional metric
`sensor_name`.`avg`	Specifies the average time spent in the phase `sensor_name`, computed as the (total time)/(number of times the phase completed). Optional metric
`sensor_name`.`active`	Specifies the number of threads in the phase `sensor_name`, at the time the DMS statistics are gathered (the value may change over time). Optional metric
`sensor_name`.`maxActive`	Specifies the maximum number of concurrent threads in the phase `sensor_name`, since the process started. Optional metric

A.1.3.2.2 DMS Event Sensors

A DMS Event Sensor counts system events. Use a DMS Event Sensor to track system events that have a short duration, or where the duration of the event is not of interest but the occurrence of the event is of interest.

Table A-2 describes the metric that is associated with an Event Sensor.

Table A-2 DMS Event Sensor Metrics

Metric Description

Metric	Description
`sensor_name`.`count`	Specifies the number of times the event has occurred since the process started, where `sensor_name` is the name of the Event Sensor as specified in the DMS instrumentation API. Default: `count` is the default metric for an Event Sensor. No other metrics are available for an Event Sensor.

sensor_name.count

Specifies the number of times the event has occurred since the process started, where sensor_name is the name of the Event Sensor as specified in the DMS instrumentation API.

Default: count is the default metric for an Event Sensor. No other metrics are available for an Event Sensor.

A.1.3.2.3 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 system status information or when you need a performance 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 A-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 A-3 DMS State Sensor Metrics

Metric	Description
`sensor_name`.`value`	Specifies the metric value for `sensor_name`, using the type assigned when `sensor_name` is created. Default: `value` is the default State metric.
`sensor_name`.`count`	Specifies the number of times `sensor_name` is updated. Optional metric
`sensor_name`.`minValue`	Specifies the minimum value for `sensor_name` since startup. Optional metric
`sensor_name`.`maxValue`	Specifies the maximum value this `sensor_name` since startup. Optional metric

A.1.3.3 DMS Nouns

DMS Nouns organize performance data. Sensors, with their associated metrics, are organized in an 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 a name that reflects the set of metrics being collected.

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.

A.1.3.4 DMS Roll-up Nouns

DMS Roll-up Nouns are nouns that DMS generates when you include instrumentation to request a set of aggregate nouns. The roll-up noun contains metrics from a set of Sensors in the descendent nouns of a specified noun type. A roll-up noun also contains summary information.

A.1.3.5 DMS Object Relationships

This section describes the object relationships and attributes for DMS metrics, Sensors, and Nouns.

Table A-4 describes the relationships between DMS objects. Figure A-1 illustrates the relationships shown in Table A-4 using a sample set of metrics.

Table A-4 DMS Object Relationships and Attributes

Object	Contains	Attributes
Noun	Sensors or other Nouns	Name, Noun Type, Parent
Sensor There are three Sensor Types: PhaseEvent Event State	Metrics	Name, Description, Parent
Metric	Value	Name, Units designation

Object

Contains

Attributes

Noun

Sensors or other Nouns

Name, Noun Type, Parent

Sensor

There are three Sensor Types:

PhaseEvent
Event
State

Metrics

Name, Description, Parent

Metric

Value

Name, Units designation

A.1.4 DMS Naming Conventions

When you create DMS nouns and sensors, you should follow the guidelines in this section so that users can easily understand DMS metrics across applications and across Oracle Fusion Middleware components.

Note:

View the naming conventions as guidelines; for each convention there may be an exception. Try to be as clear as possible; if there is a conflict, you may need to make an exception.

This section includes the following subsections:

Section A.1.4.1, "General DMS Naming"
Section A.1.4.2, "General DMS Naming Conventions and Character Sets"
Section A.1.4.3, "Noun and Noun Type Naming Conventions"
Section A.1.4.4, "Sensor Naming Conventions"

A.1.4.1 General DMS Naming

A Noun name is a simple string, not including a delimiter. For example, BasicBinomial is a Noun name. A Noun full name consists of the Noun name, preceded by the full name of its parent, and a delimiter. For example /dmsDemo/BasicBinomial is a Noun full name.

A Sensor name is a simple string, not including 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. Examples: /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.

A.1.4.2 General DMS Naming Conventions and Character Sets

DMS names should be as compact as possible. Whenever possible, when you define Noun and Sensor names, avoid special characters such as white space, slashes, periods, parenthesis, commas, and control characters.

Table A-5 shows DMS replacement for special characters in names.

Table A-5 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.

A.1.4.3 Noun and Noun Type Naming Conventions

A Noun name should identify a specific entity of interest.

Noun types should have names that clearly reflect the set of metrics 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 should start with a capital letter to distinguish them from other DMS names. All Nouns of a given type should contain the same set of sensors.

A.1.4.4 Sensor Naming Conventions

The following list outlines DMS Sensor naming conventions:

Sensor names should be descriptive, but not redundant. Sensor names should not contain any part of the Noun name hierarchy, or type, as this is redundant.
Sensor names should avoid containing the value for the individual metrics.
Where multiple words are required to describe a Sensor, the first word should start with a lowercase letter, and the following words should start with uppercase letters. 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, you need to use an alternative delimiter, such as "," or "_", which does not appear anywhere in the path; this 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 using the string:
```
,default,WEBs,defaultWebApp,JSPs,example/jsp/num/numguess.jsp,service
```
where the delimiter is the "," character.
Event Sensor and PhaseEvent Sensor names should have the form verbNoun. Examples: activateInstance and runMethod. When a PhaseEvent monitors a function, method, or code block, it should be named to reflect the task performed as clearly as possible.
The name of a State Sensor should be a noun, possibly preceded by an adjective, which describes the semantics of the value which is tracked with this State Sensor. Examples: 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 A-1, Table A-2, and Table A-3.

A.2 Adding DMS Instrumentation to Java Applications

You can collect performance information for Java applications by adding DMS instrumentation to existing applications or by creating new applications that include DMS instrumentation.

You can download the DMS samples in this chapter from Oracle Technology Network:

http://www.oracle.com/technology/tech/java/oc4j/demos/904/DMS/dmsDemo.zip

The dmsDemo.zip file includes a ready-to-deploy .ear file and source code with build instructions. The demo includes two servlets: BasicBinomial.java and ImprovedBinomial.java.

The BasicBinomial servlet shows how to use the DMS API to add DMS Nouns and Sensors.

The ImprovedBinomial servlet expands on the BasicBinomial and illustrates measuring the improved code, as compared with the BasicBinomial. ImprovedBinomial servlet also shows how to add more costly metrics that gather more detailed information.

Refer to the sample code for full details on the examples in this chapter.

To use DMS instrumentation, add DMS calls by performing the following steps:

Section A.2.1, "Including DMS Imports"
Section A.2.2, "Organizing Performance Data"
Section A.2.3, "Defining and Using Metrics for Timing"
Section A.2.4, "Defining and Using Metrics for Counting"
Section A.2.5, "Defining and Using Metrics for Recording Status Information (State Sensors)"

A.2.1 Including DMS Imports

To use DMS you need to add DMS imports. The following example shows the imports that the sample application BasicBinomial.java requires.

import oracle.dms.instrument.DMSConsole;
import oracle.dms.instrument.Event;
import oracle.dms.instrument.Noun;
import oracle.dms.instrument.PhaseEvent;
import oracle.dms.instrument.State;
import oracle.dms.instrument.Sensor;

A.2.2 Organizing Performance Data

In the sample application with the BasicBinomial and ImprovedBinomial servlets, the Nouns are organized as follows:

Example A-2 shows a section of code from BasicBinomial.java. It shows calling Noun.create to create the /dmsDemo noun root and the BasicBinomial noun, which is a child of /dmsDemo.

Example A-2 BasicBinomial.java: Using Noun.create to Organize Sensors

private Noun binRoot;                // Container for Binomial series DMS metrics
Noun base = Noun.create("/dmsDemo");
binRoot   = Noun.create(base, "BasicBinomial", "MathSeries");

/dmsDemo is the noun root for the binomial sample application. The initial slash character marks it as the root.

The BasicBinomial noun is created with a noun type of MathSeries (the third parameter for the create method). The Noun type is a name that reflects the set of metrics being collected. In this case, MathSeries represents the metrics collected for the sample binomial application.

In the ImprovedBinomial servlet, located in the same binomial application, there is a similar set of lines (Example A-3). The only difference is that it creates a child noun called ImprovedBinomial instead of BasicBinomial.

Example A-3 ImprovedBinomial.java: Using Noun.create to Organize Sensors

private Noun binRoot;                // Container for Binomial series DMS metrics
Noun base = Noun.create("/dmsDemo");
binRoot   = Noun.create(base, "ImprovedBinomial", "MathSeries");

Note that the dmsDemo noun was not created with a noun type because its children are all nouns. It does not have any child sensors.

The Spy servlet displays all nouns of the same type as rows in a table; the name of the table is the noun-type. Metrics are represented as columns in the table.

It is good practice to only use Noun types for Nouns that directly contain Sensors. When a Noun contains only other Nouns, as in dmsDemo, and does not directly contain Sensors, the Spy servlet displays the Noun type as a metric table, with no metrics.

The dmsDemo Noun includes a Noun (BasicBinomial), but no direct Sensors. When the Noun type is not included for such a Noun, the Spy servlet does not display a metric table associated with the Noun.

Note:

Start Noun type names with a capital letter to distinguish them from other DMS names. See Section A.1.4, "DMS Naming Conventions" for details.

A.2.2.1 Choosing Noun Types

In general, you should give different names to nouns and noun types to provide a logical hierarchy for nouns of the same type at the same level. For example, in the dmsDemo application, there are two servlets: BasicBinomial and ImprovedBinomial. The DMS instrumentation uses the noun type MathSeries for both servlets. This noun type is created under /dmsDemo in the same hierarchy level for both servlets. Adhering to this practice makes the generated metric tables easier to understand. It also prevents some minimal information loss in the reporting process.

A.2.3 Defining and Using Metrics for Timing

To create metrics that measure the duration of a segment of code, you use PhaseEvent Sensors:

Section A.2.3.1, "Defining PhaseEvent Sensors"
Section A.2.3.2, "Using PhaseEvent Sensors"

A.2.3.1 Defining PhaseEvent Sensors

Example A-4 shows the DMS calls that declare and create the computeSeries PhaseEvent Sensor. This code defines a DMS metric named /dmsDemo/BasicBinomial/computeSeries.time.

Example A-4 Defining PhaseEvent Sensors

private PhaseEvent binComp; // Time to compute Binomial series
...
binComp = PhaseEvent.create(binRoot, "computeSeries", "Time to compute a Binomial series");
binComp.deriveMetric(Sensor.all);

PhaseEvent Sensors support a set of optional metrics, along with the default metric .time, which represents the time, as measured between the PhaseEvent start and the PhaseEvent stop calls. You can derive optional metrics with PhaseEvent Sensors individually or as a complete set. Table A-1 shows the available metrics for a PhaseEvent Sensor. The binComp.deriveMetric(Sensor.all) call in Example A-4 causes all the supported optional metrics to be computed and reported.

Note:

Using the method deriveMetric(Sensor.all) is recommended for adding optional metrics. Using this method with Sensor.all adds all metrics; this is good practice since the list of optional metrics could change in a future Oracle Fusion Middleware releases. In addition, the metrics are efficient to compute and are often useful in evaluating performance.

A.2.3.2 Using PhaseEvent Sensors

To use a PhaseEvent Sensor, an application calls the start method to indicate the beginning of a phase and subsequently calls the stop method to indicate the completion of the phase.

Example A-5 shows a code segment from BasicBinomial.java that uses the start and stop methods for the /dmsDemo/BasicBinomial/computeSeries.time metric. The long value named token that is returned from the PhaseEvent start method must be passed to the corresponding PhaseEvent stop method. This value is a timestamp representing the start time. Passing this value to the stop method enables DMS to compute the PhaseEvent duration.

Note:

To assure that PhaseEvents are stopped, each PhaseEvent start method, together with the code to be measured, should be in a try block with the PhaseEvent stop method in a corresponding finally block, as shown in Example A-5.

Example A-5 Using start and stop With PhaseEvent Sensors

long token = 0; // DMS
try {
    token = binComp.start(); // DMS
    BigInteger bins[] = bin(length);
    out.println("<H2>Binomial series for " +  length + "</H2>");
    for (int i = 0; i < length; i++)
        out.println("<br>" + bins[i]);
}
finally {
    binComp.stop(token); // DMS
    out.close();
}

Example A-5 shows code instrumented such that each time a phase starts, it is stopped (since the stop method is placed in the finally clause). This prevents runaway Phase Sensors; however, this can result in the time required to throw an exception possibly contributing to phase statistics. To prevent exception handling from impacting a PhaseEvent, use the abort method, as shown in Example A-6.

Example A-6 shows a code sample where a Phase that is not successfully stopped can be closed. The abort call removes the statistics corresponding to the corresponding start, and these statistics do not contribute to metric calculations.

Example A-6 Using abort with PhaseEvent Sensors

PhaseEvent pe = heavyPhase(param);
long token1 = 0;
long token2 = 0;
boolean stopped = false;
try {
      token1 = binComp.start();
      if (pe != null) token2 = pe.start();
      BigInteger bins[] = bin(length);
      out.println("<H2>ImprovedBinomial series for " +  length + "</H2>");
      for (int i = 0; i < length; i++)
        out.println("<br>" + bins[i]);
      if (pe != null) pe.stop(token2);
      binComp.stop(token1);
      stopped = true;
}
finally {
      if (!stopped) {
        if (pe != null) pe.abort(token2);
        binComp.abort(token1);
      }
}

A.2.4 Defining and Using Metrics for Counting

To create metrics that count the occurrences of an event, define and use an Event Sensor:

Section A.2.4.1, "Defining Event Sensors"
Section A.2.4.2, "Using Event Sensors"

A.2.4.1 Defining Event Sensors

Example A-7 shows the DMS calls that define an Event Sensor. This code allocates a counter and defines a DMS metric named /dmsDemo/BasicBinomial/loops.count.

Example A-7 Defining Event Sensors

private Event binLoop;   // Loops needed for Binomial series.
...
binLoop = Event.create(binRoot, "loops", "Iterations to compute series");

A.2.4.2 Using Event Sensors

DMS increments a counter when an application calls the occurred method for an Event Sensor. Example A-8 shows the occurred call for an Event Sensor that increments the /dmsDemo/BasicBinomial/loops.count metric.

Example A-8 Using occurred With Event Sensors

binLoop.occurred();

A.2.5 Defining and Using Metrics for Recording Status Information (State Sensors)

DMS captures status information with State Sensors. State Sensors track the value of Java primitives or the content of a Java Object. The supported types include integer, double, long, and object, as specified in the third argument to the create method. When a Java primitive State Sensor is updated with the wrong type, DMS attempts to convert the supplied value to the correct type. For object type State Sensors, DMS stores a reference to the object and by default calls toString on the object when the DMS value is sampled.

To create metrics that record status information, define and use State Sensors:

Section A.2.5.1, "Defining State Sensors"
Section A.2.5.2, "Using State Sensors"

A.2.5.1 Defining State Sensors

State Sensors support a default metric value, as well as optional metrics. You can define the minValue and maxValue optional metrics with State Sensors only if the State Sensor represents a numeric Java primitive (of type integer, double, or long). Table A-3 shows the available metrics for a State Sensor. Example A-4 shows how to enable optional metrics.

Example A-9 shows the DMS calls that declare and create a State Sensor. This code defines a DMS metric named /dmsDemo/BasicBinomial/lastComputed.value.

Example A-9 Defining State Sensors

private State binLast;   // Value of the last computed element in series.
...
binLast = State.create(binRoot, "lastComputed", State.OBJECT, "",
                           "Value of last computed series element");

When you define a State Sensor, use an empty string in the fourth argument to the create method if no value is associated with the State Sensor, otherwise use a string listing the appropriate values (see Example A-9). State Sensors are created without an initial value. If you need to check whether a State Sensor has been initialized, use the isInitialized method.

If you want your State Sensor to store the string value of an object, and not store a reference to the object, use the setCopy method with the value TRUE. This tells the State Sensor to store the result of calling toString on an object rather than using a reference to the object for the metric value.

A.2.5.2 Using State Sensors

When an application calls a State Sensor's update method, DMS updates the value of the State Sensor. Example A-10 shows the update call for a State Sensor that updates the /dmsDemo/BasicBinomial/lastComputed.value metric.

Example A-10 Using update With State Sensors

binLast.update(bins[k-1].toString());

A.3 Validating and Testing Applications Using DMS Metrics

You should test and verify the accuracy of the metrics that you add to Java applications. This section includes the following subsections:

Section A.3.1, "Validating DMS Metrics"
Section A.3.2, "Testing DMS Metrics For Efficiency"

A.3.1 Validating DMS Metrics

Use wlst and other available DMS monitoring tools to verify and test new metrics.

Try to validate the following for new metrics:

Do expected metrics appear in the display? Test this by examining the code to ensure that all the metric names added using DMS instrumentation appear in your display or saved set of metrics.
Do unexpected metrics appear in the display? Verify that you have only added the metrics that you planned to add.
Are the metric values you see within reasonable ranges? Usually, upper and lower bounds for metrics can be established. You then test that the reported values for metrics do not exceed the expected bounds.

For example, a "size of pool" metric should never report a negative value.
Ensure the new metrics are needed. For example, if you add a PhaseEvent that always measures an event of very short duration, consider changing the metric to an Event metric, or remove the metric.
Ensure the new metrics are accurate. For most applications using DMS metrics, accuracy is more important than the performance cost of adding the DMS instrumentation. New DMS metrics should provide reliable and useful information.

Testing for accuracy can be difficult. However, if an alternate means of measuring a particular metric is available then use it to verify metric values. For example, if you submit a known number of requests to a server and measure total time for the experiment, then you predict correct values for the relevant metrics and compare them with the actual monitored values. As another example, you can verify an Event Sensor count metric by examining records that you write to a log file or to the console.

Check for timing inaccuracies that may apply for the metrics. Timing inaccuracies may be caused when low-resolution clocks time metrics for an interval of short duration. For example on Windows systems, the default Java clock advances only once every 15 milliseconds. DMS metrics reported for brief events on these systems must be analyzed with care. Consider using the high resolution clock to address this issue.

A.3.2 Testing DMS Metrics For Efficiency

The use of DMS metrics has some influence on application performance. When adding metrics, note the following:

The processing required for computing and storing metrics can slow down the execution of an application. DMS is fast, but it may have some required performance cost. In addition, DMS cannot prevent developers from using the DMS API inefficiently. Therefore, before adding DMS instrumentation, establish reasonable expectations. After completing the implementation, measure the actual costs and compare them to your expectations. Be prepared to make changes to the instrumentation to reduce performance impacts until the measurements agree with expectations.
DMS provides the DMSConsole.getSensorWeight method to help you control the use of metrics. The central setting is an advisory measurement level that DMS does not enforce. To control which metrics to include, at run time, the code must test the value for SensorWeight to determine whether to make DMS calls. See Section A.5, "Conditional Instrumentation Using DMS Sensor Weight" for details.
When integrating DMS instrumentation with an existing package or when implementing a new feature, you should consider insulating a previously working system. For example, you could include an option to enable and disable new DMS metrics.
You should run your performance tests with and without DMS enabled. If your tests show unacceptable results with DMS enabled, then you may want to re-design or re-implement metrics.

A.4 Understanding DMS Security Considerations

DMS metrics do not support user-based access to DMS reports. When you define and use a DMS metric, the metric is available to any administrator that has access to DMS metrics. This means when you add DMS metrics, it is good practice to avoid placing customer-sensitive information in the metrics.

A.5 Conditional Instrumentation Using DMS Sensor Weight

Use the DMS Sensor weight feature to conditionally limit your instrumentation. With Sensor weight, you specify that applications execute expensive instrumentation only when the Sensor weight is set to a particular value. Using this feature enables you to include expensive metrics that you may only need for debugging.

Example A-11 shows how to use DMSConsole.getSensorWeight and optionally to define and use a metric. SensorWeight should not be used to control the content of a noun (sensors or metrics); sensor-weight should be used (as in the example below) to control the existence of a noun, and more importantly to control the existence of nouns of a particular type.

The Sensor weight is set globally using the oracle.dms.sensors property on the command-line. Set this property using the startup options. Supported values for this property include: none, normal, heavy, and all.

Example A-11 Using SensorWeight for Conditional Instrumentation

/* DMS Method
 *
 * If the SensorWeight is high enough, return a phase with the
 * parameter in the name. Otherwise, return null.
 */
PhaseEvent heavyPhase(String param) {
   PhaseEvent pe = null;
   if (DMSConsole.getSensorWeight() > DMSConsole.NORMAL) {
      Noun base = Noun.create(binRoot, param, "MathSeries");
      pe = PhaseEvent.create(base, "computeSeries",
                                   "Time to compute a Binomial series");
      pe.deriveMetric(Sensor.all);
   }
   return pe;
}

A.6 Dumping DMS Metrics to Files

In a Java application, use the following method to dump DMS metrics to a file.

The following code enables you to append or replace the contents of the specified file with the current metrics:

DMSConsole cons2 = new DMSConsole();
DMSConsole.dump("dmsmathseries.log", "xml", true);

The first argument specifies the file path name, the second argument specifies the output format, and the third argument specifies if the output is appended to the file or replaces the contents of the file.

WARNING:

This process dumps all DMS information for the JVM. In cases where the JVM is running several applications (such as J2EE) this process dumps all metrics for all applications.

A.7 Resetting and Destroying Sensors

The Sensor abstract class provides methods to control PhaseEvent, Event, and State Sensors. The reset method resets a Sensor's metrics to initial values. The getResetTime method determines if a Sensor has been reset. The destroy method removes a Sensor from DMS and releases references to its underlying resources.

Note:

Do not use these methods to reset or destroy built-in metrics. The reset and destroy methods are intended for use with metrics that you create. Fusion Middleware Control and other Oracle Fusion Middleware administrative facilities could report unexpected values or have unexpected behavior if you use these methods on internal built-in metrics.

A.8 DMS Coding Recommendations

The following list includes coding recommendations for working with DMS.

There is a global name space for DMS metrics. When you create a new Noun Sensor (PhaseEvent, Event, or State), its full name must not conflict with names in use by Oracle built-in metrics, or by other applications. It is therefore a good idea to have a root Noun for your application that contains the application's full name. This prevents name space collisions.

See Also:
Section A.1.4.1, "General DMS Naming"
Be sure all PhaseEvents are stopped. If the code block to be measured is not in a try block, then put it in a try block that includes PhaseEvent's start. Put the PhaseEvent's stop in a finally block. Alternatively, make use of the abort method in the finally block, as shown in Example A-6.

See Also:
Section A.2.3.2, "Using PhaseEvent Sensors"
Follow DMS naming conventions.

See Also:
Section A.1.4, "DMS Naming Conventions"
Avoid creating any DMS Sensor or Noun more than once. The DMS API enables this, and avoids creation of multiple objects, but DMS performs lookups for each subsequent creation attempt. Thus, whenever possible, you should define Sensors and Nouns during static initialization, or in the case of a Servlet, in the init method.
Assign a type for each Noun that contains Sensors. If no type is assigned, the type is given the value "n/a" (not available). Nouns with the type specified as "n/a" are not shown in the Spy servlet.
Only use PhaseEvents to measure a section of code that is expensive to execute, and takes a significant time to execute under some conditions. In the case where the code never takes significant time to execute, use an Event metric, or remove the PhaseEvent.
The DMS API calls are threadsafe; they provide sufficient synchronization to prevent races and access bugs.
J2EE applications should not control the lifecycle of the DMS Console - the lifecycle of the DMS Console is managed by the J2EE container. DMS is global to the J2EE server's JVM and therefore changes made to DMS can affect all applications running in that J2EE container.

Note:

The beginning part of the execution context string generated by Java API is in IP address format which is different that the string generated by C API. To avoid issues, ensure that the same ECID is used throughout a single request/transaction. The ECID can be in any format as long as it is used consistently.

A.8.1 Isolating Expensive Intervals Using PhaseEvent Metrics

Carefully consider the requirements for new metrics when you add DMS instrumentation. It is important to add a sufficient number of metrics to validate that your code is working as expected.

Try to observe the following guidelines when you add DMS metrics:

Add PhaseEvent Sensors only to provide an overview of the time the system spends in your block of code or module. You do not need to collect performance data for every method call, or for every distinct phase of your code or module.
When your code calls external code that you do not control, and that you expect could take a significant amount of time, add a PhaseEvent Sensor to track the start and the completion of the external code.

Following these guidelines for adding PhaseEvent metrics provides the following benefits:

Helps limit the amount of information that DMS collects.
Enables those analyzing the system to prove that a module gives the expected run time performance.
Ensures that people viewing DMS metrics can validate run time performance without seeing an overwhelming amount of data.
Enables those analyzing system performance to separate and track your module from other system modules that are either expensive or failure prone.

A.9 Using 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. You can use a high resolution clock when you need to time phase events more accurately than is possible using the default clock or when the system's default clock does not provide the resolution needed for your requirements.

Note:

The resolution of the clocks (both default and high resolution) is platform-dependent. On some systems the default clock may not provide sufficient resolution for timing requirements. In particular, on Windows platforms, many users request greater precision than the default clock provides, because it advances only once every 15 milliseconds. DMS metrics reported for brief events on these systems must be analyzed with care. Consider using the high resolution clock to address this issue.

Also note that the accuracy of high resolution clocks are also platform-dependent. Selecting a high resolution clock does not guarantee that the system reports nanosecond times accurately.

This section covers the following topics:

Section A.9.1, "Configuring DMS Clocks for Reporting Time for Java"
Section A.9.2, "Configuring DMS Clocks for Reporting Time for Oracle HTTP Server"

A.9.1 Configuring DMS Clocks for Reporting Time for Java

Selecting the high resolution clock changes clocks for all applications running on the process where the clock is changed. You set the DMS clock and the reporting values globally using the oracle.dms.clock and oracle.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 using the high resolution clock, then you need to set the units property as follows:

-Doracle.dms.clock.units=msecs

Table A-6 shows supported values for the oracle.dms.clock property.

Table A-7 shows supported values for the oracle.dms.clock.units property.

Table A-6 oracle.dms.clock Property Values

Value Description

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).

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 A-7 oracle.dms.clock.units Property Values

Value	Description
MSECS	Specifies that the time 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 be converted to microseconds and reported as "usecs". A microsecond is 10^-6 seconds.
NSECS	Specifies that the time 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.

Value

Description

MSECS

Specifies that the time 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 be converted to microseconds and reported as "usecs". A microsecond is 10^-6 seconds.

NSECS

Specifies that the time 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 using the high resolution DMS clock:

When you set the oracle.dms.clock and the oracle.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, HighRes.
DMS checks the property values at startup. When you set the clock with a value that does not match those listed in Table A-6, then DMS uses the default clock. If the oracle.dms.clock property is not set, DMS also uses the default clock.
If the specified clock units property value does not match those listed in Table A-7, then DMS uses the default units for the specified clock. If the oracle.dms.clock.units property is not set, DMS uses the default units for the specified clock.

A.9.2 Configuring DMS Clocks for Reporting Time for Oracle HTTP Server

The default clock for measuring Oracle HTTP Server performance has a resolution of microseconds (usecs). You can optionally select a higher resolution clock to monitor C processes running under Oracle HTTP Server. To use the high resolution clock under Oracle HTTP Server, you need to set configuration options in httpd.conf, or specify environment variables on the command line.

Table A-8 lists the environment variables that control the Oracle HTTP Server DMS clock. Table A-9 describes the httpd.conf configuration options that control the Oracle HTTP Server DMS clock. If you set both the command line options and the httpd.conf configuration options, the configuration options override the values set on the command line.

Table A-8 Oracle HTTP Server DMS Clock Environment Variables

Environment Variable	Description
DMS_CLOCK	Specifies the clock to use for DMS timing. The values are interpreted the same as with oracle.dms.clock. Valid Values: DEFAULT, HIGHRES
DMS_CLOCK_UNITS	Specifies the units for reporting DMS timing values. The values are Interpreted the same as with oracle.dms.clock.units. Valid Values: MSECS, NSECS, USECS Default Value: USECS

Environment Variable

Description

DMS_CLOCK

Specifies the clock to use for DMS timing. The values are interpreted the same as with oracle.dms.clock.

Valid Values: DEFAULT, HIGHRES

DMS_CLOCK_UNITS

Specifies the units for reporting DMS timing values. The values are Interpreted the same as with oracle.dms.clock.units.

Valid Values: MSECS, NSECS, USECS

Default Value: USECS

Table A-9 Oracle HTTP Server DMS Clock Configuration Parameters

Parameter Description

Parameter	Description
`DmsClock`	Specifies the clock for HTTP listener processes started by Oracle HTTP Server, as the oracle.dms.clock property does for Java processes. Valid Values: DEFAULT, HIGHRES
`DmsClockUnits`	Specifies the time units for HTTP listener processes started by Oracle HTTP Server, as the oracle.dms.clock.units property is for Java processes. Valid Values: MSECS, NSECS, USECS Default Value: USECS

DmsClock

Specifies the clock for HTTP listener processes started by Oracle HTTP Server, as the oracle.dms.clock property does for Java processes.

Valid Values: DEFAULT, HIGHRES

DmsClockUnits

Specifies the time units for HTTP listener processes started by Oracle HTTP Server, as the oracle.dms.clock.units property is for Java processes.

Valid Values: MSECS, NSECS, USECS

Default Value: USECS

With these options DMS uses a high resolution clock for all the Oracle HTTP Server processes that it monitors, and DMS reports values using the milliseconds units (msecs).

Caution:

If you are using the high resolution clock for the Oracle HTTP Server, the default units are NSECS on most platforms. If you need to use Fusion Middleware Control, it expects USECS for the units. If you need the Fusion Middleware Control displays to be correct when using the high resolution clock, then you need to set the units property as follows:

DmsClock=HIGHRES
DmsClockUnits=USECS

A.10 Rolling Up DMS Data for Descendent Nouns

Oracle Fusion Middleware includes the DMS Roll-up feature which enables you to specify metric aggregation. You can use the Roll-up feature to specify metric aggregation during DMS instrumentation; roll-up is specified to apply to descendents of a specified noun type. You can specify whether the roll-up should only apply to direct descendents or to all descendents. Example A-12 shows code that generates a DMS tree, as represented in Figure A-2. Each noun of type myContainer contains the percentageFull, close, and open Sensors (see Figure A-2).

Note:

The code in Example A-12 generates a noun tree hierarchy that violates the guidance described in Section A.2.2.1, "Choosing Noun Types". In this example, it makes sense for some nouns to have descendents and ancestors of the same noun type. The roll-up feature described in this section can collect data which might otherwise be lost.

Example A-12 DMS sample code creating noun hierarchy of metrics

// Create DMS Noun hierarchy for metrics
Noun home = Noun.create(Noun.getRoot(), "Home", "myContainer");
Noun containers = Noun.create(home, "Containers", "myContainer");
Noun closets = Noun.create(containers, "Closets", "myContainer");
Noun bedrooms = Noun.create(closets, "Bedrooms", "myContainer");
Noun br1 = Noun.create(bedrooms, "BR1", "myContainer");

// Create a closet Noun and create Sensors for it
Noun c1 = Noun.create(br1, "C1", "myContainer");
State percent = State.create(br1, "percentageFull", State.INTEGER, "percent", "percentage full");
Event close = Event.create(br1, "close", "container closed");
PhaseEvent open = PhaseEvent.create(br1, "open", "open container");

// Derive metrics for State and PhaseEvent Sensors
percent.deriveMetric(Sensor.all);
open.deriveMetric(Sensor.all);

Figure A-2 Containers DMS Hierarchy Showing Tree Containing Metrics

Description of "Figure A-2 Containers DMS Hierarchy Showing Tree Containing Metrics"

Figure A-3 shows a tree with a set of descendent containers. The nouns C1 and C2 under the bedrooms BR1 and BR2 are of type myContainer (see Figure A-3 for a description of myContainer metrics).

Figure A-3 Noun myContainer showing Sample Sensors

Description of "Figure A-3 Noun myContainer showing Sample Sensors"

The roll-up feature enables you to aggregate a summary for descendent Nouns. For example, you can add the roll-up call to a bedrooms noun, as shown in Example A-12. To aggregate myContainer type metrics under BR1, use the following call:

br1.rollup("myContainer", Noun.DIRECT);

This call creates a roll-up noun named myContainer_rollup under /Home/Containers/Closets/Bedrooms/BR1. The roll-up noun contain the same sensors as the associated noun, including: percentageFull, close, and open.

DMS roll-up metrics let you roll-up the sensors in all descendent nouns of the given types or only those in the direct descendent nouns. Specifying Noun.DIRECT in the roll-up call aggregates only direct descendent nouns of the specified type. To aggregate the metrics from all descendent nouns of type myContainer instead, use a call such as the following including Noun.ALL:

closets.rollup("myContainer", Noun.ALL);

Roll-up metrics include aggregate summary information for their contents. Table A-10 shows the available derived rollup metrics for each Sensor type.

Table A-10 Roll-up Metrics Included Derived Metrics

Metric	Description
PhaseEvent	The derived metrics for a PhaseEvent rollup metric include the following: `time`: the sum of `time` metrics. `completed`: the sum of the `completed` metrics. `maxTime`: the maximum of the `maxTime` metrics. `minTime`: the minimum of the `minTime` metrics: `avg`: the average time computed for all Sensors. `active`: the sum of the `active` metrics.
Event	The derived metrics for a Event roll-up metrics include the following: `sum`: the total of all `count` metrics. `avg`: the average of all `count` metrics.
State	The derived metrics for a State rollup metrics include the following: `sum`: the total of all `value` metrics. `avg`: the average of all value metrics. `maxValue`: the maximum of the `maxValue` metrics. `minValue`: the minimum of the `minValue` metrics.
`descendents`	The roll-up noun includes a `descendents` state sensor that reports whether the roll-up covers only direct descendents or all descendents.
`rolled`	The roll-up noun includes a `rolled` state sensor, which reports the number of nouns that are rolled up.
`refresh`	The roll-up noun includes a `refresh` phase event, which reports the time spent aggregating the metrics for this rollup noun.

Example A-13 shows sample metrics created for the myContainer roll-up noun under /Home/Containers/Closets.

Example A-13 Test

myContainer_rollup
  descendent.value: all  
  percentageFull.sum 40 percent
  percentageFull.avg 10.0 percent
  percentageFull.min 1 percent
  percentageFull.max 29 percent
  close.sum: 3 
  close.avg: 0.75
  open.time: 871 msecs 
  open.completed: 4 ops 
  open.maxTime: 722 msecs 
  open.minTime: 23 msecs 
  open.avg: 217.7 msecs 
  open.active: 0 
  rolled.value: 4 nouns
  refresh.maxActive:   1 threads
  refresh.active:      0 threads
  refresh.avg: 0.2857142857142857 msecs
  refresh.maxTime:     1 msecs
  refresh.minTime:     0 msecs
  refresh.completed:   7 ops
  refresh.time:        2 msecs

Note that the metrics are similar to the myContainer metrics. The roll-up metrics have several key differences, as follows:

The roll-up noun contains the descendent, rolled, and refresh metrics (see Table A-10 for details).
The percentageFull State contains sum and avg metrics rather than the value metric. The name of each metric reflects its content.
The close Event contains sum and avg metrics rather than the count metric. The name of each metric reflects its content.
The open PhaseEvent does not contain a maxActive metric as it would have no meaning in this context.