|
Oracle® Application Server Performance Guide
10g Release 2 (10.1.2) B14001-02 |
|
 Previous |
 Next |
|
Oracle® Application Server Performance Guide
10g Release 2 (10.1.2) B14001-02 |
|
|
Previous |
Next |
The Oracle Dynamic Monitoring Service (DMS) enables application developers, support analysts, system administrators, and others to measure application specific performance information. This chapter describes DMS and shows a sample application that demonstrates how to instrument Oracle Application Server Java applications using DMS.
|
Note: Oracle Application Server provides a number of built-in metrics. Using DMS to instrument applications adds new metrics to the set of built-in metrics. |
This chapter covers the following topics:
The Dynamic Monitoring Service (DMS) API allows you to add performance instrumentation to Oracle Application Server applications. During runtime DMS 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 covers the following topics:
|
Note: Oracle Application Server components, including OC4J, provide a number of predefined metrics. For a listing of the predefined metrics see Appendix A, "Performance Metrics". |
DMS Instrumentation refers to the process of inserting DMS calls into application code. Using the DMS API is a simple and efficient way to enable your application to measure, collect, and save performance information.
To create DMS metrics developers add calls that notify DMS when events occur, when important intervals begin and end, or when pre-computed values change their state. At runtime, DMS stores metrics in memory and allows you to save or view the metrics.
Oracle Application Server includes built-in DMS metrics. By adding DMS calls to your applications you can 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.
Monitoring DMS metrics refers to the process of retrieving performance metrics. When an application runs, DMS stores metrics in memory and allows you to show metrics on the console or to view metrics using a web browser.
Oracle Application Server provides several runtime tools for viewing and saving DMS metrics, including dmstool and the AggreSpy Servlet.
Example 9-1 shows a set of metrics output using dmstool.
Example 9-1 Set of Sample dmsDemo Metrics Using dmstool
computeSeries.active: 0 threads computeSeries.avg: 5931.7 msecs computeSeries.completed: 20 ops computeSeries.maxActive: 1 threads computeSeries.maxTime: 57086 msecs computeSeries.minTime: 2 msecs computeSeries.time: 118634 msecs lastComputed.value: 184756 loops.count: 4325 ops timeStamp.ts: 1091035411174 milliseconds Host: system1 Name: BasicBinomial Parent: /dmsDemo Process: home:OC4J:3301:6004 iasInstance: 10g2.tv.us.oracle.com uid: 2109472775
This section introduces the terminology you need to understand to use DMS. Figure 9-1 illustrates the organization of a set of DMS metrics corresponding to the metrics in the demo application described in this chapter and the metrics shown in Example 9-1.
This section covers the following topics:
Figure 9-1 Organization of Sample Metrics From dmsDemo Application
DMS Metrics track performance information that developers, system administrators, and support analysts use to help analyze system performance or monitor system status.
DMS Sensors measure performance data and allow 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.
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 9-1 describes metrics available with a PhaseEvent Sensor.
Table 9-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 |
A DMS Event Sensor is a Sensor that 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 9-2 describes the metric that is associated with an Event Sensor.
Table 9-2 DMS Event Sensor Metrics
| Metric | Description |
|---|---|
|
|
Specifies the number of times the event has occurred since the process started, where Default: count is the default metric for an Event Sensor. No other metrics are available for an Event Sensor. |
A DMS State Sensor is a Sensor to which you assign a precomputed value. State Sensors track the value of Java primitives or the content of a Java Object. The 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 represent queue lengths, pool sizes, buffer sizes, or host names.
Table 9-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 9-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 this Optional metric |
DMS Nouns (Nouns) organize performance data. Each Sensor, with its associated metrics is organized in a hierarchy according to Nouns. Nouns allow 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. For example, in the built-in metrics the Noun type oc4j_servlet represents the metrics collected for each servlet in each Web module within each J2EE application. And the Noun type JVM represents the set of metrics for each Java process (OC4J) currently running in the site.
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.
This section describes the object relationships and attributes for DMS metrics, Sensors, and Nouns.
Table 9-4 describes the relationships between DMS objects. Figure 9-1 illustrates the relationships shown in Table 9-4 using a sample set of metrics.
Certain guidelines apply for defining DMS names. By following these guidelines, people viewing DMS metric reports can easily understand metrics across applications and across Oracle Application Server 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 covers the following topics:
DMS metric names consist of a Sensor name plus the "." character plus the metric. For example, the names: computeSeries.time, loops.count, and lastComputed.value are valid DMS metric names.
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. For example, /dmsDemo/BasicBinomial/computeSeries, /dmsDemo/BasicBinomial/loops, and /dmsDemo/BasicBinomial/lastComputed.
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 full Noun name.
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 9-5 shows DMS replacement for special characters in names.
Table 9-5 DMS Naming Special Character Replacement
| Character | DMS Replacement Character |
|---|---|
|
Space " " or Period "." |
Underscore "_" |
|
Control Character |
Underscore "_" |
|
"<" |
"(" |
|
">" |
")" |
|
"&" |
"^" |
|
"" (double quote) |
"'" (backquote) That is, a backquote replaces a double quote. |
|
'' (single quote) |
" (backquote). That is, a backquote replaces a single quote. |
|
Note: Oracle Application Server includes a number of built-in metrics. The Oracle Application Server built-in metrics do not always follow the DMS naming conventions. |
A Noun name should be a name which identifies a specific entity of interest.
Noun types should have names which 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 capitol letter to distinguish them from other DMS names. All Nouns of a given type should contain the same set of sensors.
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 specification of the units 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. For example computeSeries.
In general, using a "/" in a Sensor name should be avoided. 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 allows 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:
,oc4j,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 where verb and Noun are interpreted as defined by English grammar. For example, 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. For example, lastComputed, totalMemory, port, availableThreads, activeInstances.
To avoid confusion, do not name Sensors with strings such as: ".time", ".value", or ".avg", that are the same as the default metrics or optional derivations for a Sensor, as shown in Table 9-1, Table 9-2, and Table 9-3.
You can collect performance information in Java applications by adding DMS instrumentation to existing applications or by creating new applications that include DMS instrumentation.
The DMS samples shown in this chapter are supplied on the Oracle Technology Network Web site,
http://www.oracle.com/technology/tech/java/oc4j/demos/index.html
The DMS demo.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 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:
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;
Define DMS Nouns to organize Sensors and their associated metrics. DMS Nouns organize Sensors in a tree hierarchy in a manner comparable to a directory structure in a file system, starting with a root at the top of the tree.
Example 9-2 shows a section of code using Noun.create() from the BasicBinomial.java.
In Example 9-2, MathSeries specifies the Noun type. The Noun type is a name that reflects the set of metrics being collected. For example, MathSeries represents the metrics collected for the sample application containing a Binomial series computation. AggreSpy displays Sensors using the same Noun type together.
It is good practice to only use Noun types for Nouns that directly contain Sensors. When a Noun contains only Nouns, as in the Noun dmsDemo, and does not directly contain Sensors, AggreSpy displays the Noun type as a metric table, with no metrics. Example 9-2 shows the dmsDemo Noun that includes a Noun, BasicBinomial, but no Sensors. When the Noun type is not included for such a Noun, AggreSpy 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. |
Example 9-2 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");
To create metrics that measure the duration of a segment of code, define and use a PhaseEvent Sensor using the following steps:
Example 9-3 shows the DMS calls that declare and create the computeSeries PhaseEvent Sensor. This code defines a DMS metric named /dmsDemo/BasicBinomial/computeSeries.time.
PhaseEvent Sensors support a set of optional metrics, along with the default metric .time (representing 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 9-1 shows the available metrics for a PhaseEvent Sensor. The binComp.deriveMetric(Sensor.all) call in Example 9-3 causes all the supported optional metrics to be computed and reported.
|
Note: Using the methodderiveMetric(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 Application Server release. In addition, the metrics are efficient to compute and are often useful in evaluating performance.
|
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 9-4 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 allows DMS to compute the PhaseEvent duration.
|
Note: To assure that PhaseEvents are stopped, each PhaseEventstart() 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 9-4.
|
Example 9-4 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 9-4 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 9-5.
Example 9-5 shows a code sample where a Phase that is not successfully stopped will be aborted. The abort call removes the statistics corresponding to the corresponding start, and these statistics do not contribute to metric calculations.
Example 9-5 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);
}
To create metrics that count the occurrences of an event, define and use an Event Sensor as follows:
Example 9-6 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 9-6 Defining Event Sensors
private Event binLoop; // Loops needed for Binomial series. . . . binLoop = Event.create(binRoot, "loops", "Iterations to compute series");
DMS increments a counter when an application calls the occurred() method for an Event Sensor. Example 9-7 shows the occurred() call for an Event Sensor that increments the /dmsDemo/BasicBinomial/loops.count metric.
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 and calls toString() on the object when the DMS value is sampled.
To create metrics that record status information, define and use a State Sensor as follows:
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 9-3 shows the available metrics for a State Sensor. Example 9-3 shows how to enable optional metrics.
Example 9-8 shows the DMS calls that declare and create a State Sensor. This code defines a DMS metric named /dmsDemo/BasicBinomial/lastComputed.value.
Example 9-8 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 units are associated with the State Sensor, otherwise use a string listing the appropriate units (see Example 9-8). 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.
When an application calls a State Sensor's update() method, DMS updates the value of the State Sensor. Example 9-9 shows the update() call for a State Sensor that updates the /dmsDemo/BasicBinomial/lastComputed.value metric.
You should test and verify the accuracy of the metrics that you add to Java applications.
This section covers the following topics:
Use the dmstool and the 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 make sure 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.
Make sure that 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.
Make sure that 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.
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 does have some required overhead 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 overhead costs 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 runtime, the code must test the value for SensorWeight to determine whether to make DMS calls.
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.
Worrying about performance too soon often leads to costly design and implementation errors. According to Donald Knuth, "Premature optimization is the root of all evil".
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.
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.
When you add DMS instrumentation, the following users have access to the DMS metrics that you create:
Applications running in the same OC4J instance can access the DMS metrics.
All users that have access to the dmstool command, or the AggreSpy Servlet have access to the metrics (by default this is limited to Administrators).
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 9-10 shows how to use DMSConsole.getSensorWeight() to test the value of the Sensor weight, and optionally define and use a metric.
The Sensor weight is set globally using the oracle.dms.sensors property on the command-line. Set this property using the OC4J startup options. Supported values for this property include: none, normal, heavy, and all.
Example 9-10 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;
In a Java application, use the following method to dump DMS metrics to a file.
The following code allows you to append or replace the contents of the specified file with the current metrics:
DMSConsole cons2 = new DMSConsole();
DMSConsole.dump("dmsmathseries.log", true, 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.
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. Thereset() and destroy() methods are intended for use with metrics that you create. Application Server Control Console, and other Oracle Application Server administrative facilities could report unexpected values or have unexpected behavior if you use these methods on internal, built-in metrics.
|
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.
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 9-5.
Use the DMS naming conventions.
Avoid creating any DMS Sensor or Noun more than once. The DMS API allows 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 AggreSpy display.
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.
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 behaving as desired.
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 to limit the amount of information that DMS collects.
Allows those analyzing the system to prove that a module gives the expected runtime performance.
Ensures that people viewing DMS metrics can validate runtime performance without seeing an overwhelming amount of data.
Allows those analyzing system performance to separate and track your module from other system modules that are either expensive or failure prone.
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 such as OC4J. Optionally, DMS supports a high resolution clock to increase the precision of performance measurements and lets you select the units 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 default clock and of the high resolution clock is system 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. |
This section covers the following topics:
For Java processes, the default clock uses java.lang.System.currentTimeMillis(). Selecting the high resolution clock changes this call for all applications running on the process where the clock is changed. You set the DMS clock and the reporting units 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 units, set the following property on the Java command line for OC4J.
-Doracle.dms.clock=highres
|
Caution: Using the high resolution clock, the default units are different than the value that Application Server Control Console expects (msecs). If you need the Application Server Control Console 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 9-6 shows supported values for the oracle.dms.clock property.
Table 9-7 shows supported values for the oracle.dms.clock.units property.
Table 9-6 oracle.dms.clock Property Values
| Value | Description |
|---|---|
|
DEFAULT |
Specifies that DMS use the default clock. With the default clock, DMS uses the Java call The default value for the units for the default clock is MSECS. |
|
HIGHRES |
Specifies that DMS use the high resolution clock. DMS accesses the high resolution clock using JNI (the JNI calls depend on the clocks available on the underlying operating system). The default value for the units for the HIGHRES clock is NSECS. |
|
Note: On Windows platforms with a Pentium processor, DMS uses theQueryPerformanceCounter function to provide timing for the high resolution clock (HIGHRES). If you are running on a system without a Pentium processor, DMS uses the DMS C clock to provide timing for the high resolution clock. The DMS C clock has microsecond precision which offers a significant improvement over the default clock available with System.currentTimeMillis().
|
Table 9-7 oracle.dms.clock.units Property Values
| Value | Description |
|---|---|
|
MSECS |
Specifies that the time be converted to milliseconds and reported as "msecs". Note: This is the default value for the default clock. |
|
NSECS |
Specifies that the time be converted to nanoseconds and reported as "nsecs". Note: This is the default value for the high resolution clock. |
|
USECS |
Specifies that the time be converted to microseconds and reported as "usecs". |
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 9-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 9-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 the clock.
Table 9-8 lists the platform specific environment variables settings for supported platforms. To use the high resolution DMS clock, the environment variables need to be set appropriately. The high resolution clock uses the DMS C library. On UNIX systems, this requires libdms2.so to be in the specified environment variable path. On Windows systems this requires yod.dll to be in the PATH environment. If a nanosecond clock is not available, high resolution timings use a microsecond clock.
Table 9-8 Library Path Environment Variables for Supported Platforms
| Platform | Environment Variable |
|---|---|
|
AIX |
LIBPATH
LD_LIBRARY_PATH
|
|
HP-UX |
SHLIB_PATH
LD_LIBRARY_PATH
|
|
Linux |
LD_LIBRARY_PATH
|
|
Tru64 UNIX |
LD_LIBRARY_PATH
|
|
Solaris |
LD_LIBRARY_PATH
|
|
Windows 2000 |
|
|
Windows 2003 |
|
|
Windows XP |
|
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 9-9 lists the environment variables that control the Oracle HTTP Server DMS clock. Table 9-10 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 9-9 OHS 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 |
Table 9-10 OHS DMS Clock Configuration Parameters
| Parameter | Description |
|---|---|
|
|
Specifies the clock for HTTP listener processes started by OHS, as the oracle.dms.clock property does for Java processes. Valid Values: DEFAULT, HIGHRES |
|
|
Specifies the time units for HTTP listener processes started by OHS, exactly as the oracle.dms.clock.units property is for Java processes. Valid Values: MSECS, NSECS, USECS Default Value: USECS |
|
Note: On Windows platforms with a Pentium processor, DMS uses theQueryPerformanceCounter function to provide timing for the high resolution clock (HIGHRES). If you are running on a system without a Pentium processor, DMS uses the DMS C clock to provide timing for the high resolution clock. The DMS C clock has microsecond precision which offers a significant improvement over the default clock available with System.currentTimeMillis().
|
For example, if you want to use the high resolution clock and use the same units to show times for Java processes running under OC4J and for mod_oc4j running under Oracle HTTP Server, update the Oracle HTTP Server httpd.conf file to include the following parameters and values:
DmsClock=HIGHRES DmsClockUnits=MSECS
Also, include the following values as startup options for the OC4J process:
-Doracle.dms.clock=HIGHRES -Doracle.dms.clock.units=MSECS
Using these options DMS uses a high resolution clock for all the Oracle HTTP Server processes that it monitors, for the Java OC4J processes that it monitors, and DMS reports values using the milliseconds units (msecs).
|
Caution: Using the high resolution clock for the Oracle HTTP Server, the default units for the high resolution clock are NSECS on most platforms. If you need to use Application Server Control Console, it expects USECS for the units. If you need the Application Server Control Console displays to be correct when using the high resolution clock, then you need to set the units property as follows:DmsClock=HIGHRES DmsClockUnits=USECS |
