JSR 138: Performance Metric Instrumentation

Section 1. Identification

Submitting Member: David Clay, Oracle Corporation

Name of Contact Person: David Clay, Oracle Corporation

E-Mail Address: david.clay@oracle.com

Telephone Number: 503-525-8018

Fax Number: 503-790-9074

Specification Lead: Bruce Irvin

E-Mail Address: bruce.irvin@oracle.com

Telephone Number: 503-525-8027

Fax Number: 503-790-9074

Initial Expert Group Membership:

Bruce Irvin, Oracle Corporation

Section 2: Request

2.1 Please describe the proposed Specification:

Programmers frequently add counters, timers, and application data loggers to their code in order to isolate logic or performance problems. There is no standard way of doing this, it is reinvented for every application. Among the problems the programmer faces are:

• how to associate application data such as parameters and environment variables with measurements
• how to associate application events with system events, such as those occurring in a web server or DBMS
• how to make the instrumentation efficient enough so that it does not interfere with the process being measured
• how to include instrumentation in products so that it can be enabled in the field
• how to record application specific measurements, such as queue lengths
• how to summarize measurements
• how to nest measurements
• how to export the measurements to an analysis tool
• how to collect measurements in a distributed processing environment
• how to organize and name events in a multi-application environment

Profiling services provided by the underlying language and database runtimes are useful, but often fail to capture the higher level information that is of interest to the application writer. For example, an application might be interested in the average time it takes to add a new order, which might involve a large number of associated method invocations and database operations.

2.2 What is the target Java platform? (i.e., desktop, server, personal, embedded, card, etc.)

Any.

2.3 What need of the Java community will be addressed by the proposed specification?

The primary goal of DMS is to allow developers to write as little code as possible to solve a very common problem.

2.4 Why isn't this need met by existing specifications?

There is no existing specification which deals specifically with program instrumentation. However, there are specifications which are complementary with DMS, and integration with these will be addressed in the DMS specification. These specifications deal with means for outputting DMS gathered statistics. It is proposed that DMS use

The Java Logging API (JSR 47), is an important integration point because applications may wish to log performance data collected using DMS. Note, however, that it is not the case that every DMS event should be logged; e.g., it may be sufficient to periodically log the number of occurrences of an event.

The Java Management API (JMX), defines interfaces for publishing data from managed applications to management applications (MBeans). The DMS specification will illustrate the use of MBeans for providing access to DMS statistics.

2.5 Please give a short description of the underlying technology or technologies:

An application begins by defining a hierarchical measurement framework, similar to a file directory structure. At the leaf nodes of the structure are sensors, which record application instrumentation data associated with the name. There are different types of sensors, including:

• those which summarize occurrences of an event
• those which summarize durations of an event
• those which summarize state associated with an event, such as a queue length
• those which do not record anything, but return application data when polled

2.6 Is there a proposed package name for the API Specification? (i.e., javapi.something, org.something, etc.)

java.util.dms

2.7 Does the proposed specification have any dependencies on specific operating systems, CPUs, or I/O devices that you know of?

No.

2.8 Are there any security issues that cannot be addressed by the current security model?

No.

2.9 Are there any internationalization or localization issues?

No.

2.10 Are there any existing specifications that might be rendered obsolete, deprecated, or in need of revision as a result of this work?

No.

2.11 Please describe the anticipated schedule for the development of this specification.

1 month following JSR acceptance	Release preliminary specification, including API
+ 2 weeks	Comments on first draft due
+2 weeks	2nd draft released
+ 1 week	Comments on 2nd draft due
+ 1 week	3rd draft released (if necessary)
+ 1 week	Comments on 3rd draft due (if necessary)
+ 1 week	Participant draft released

Section 3: Contributions

3.1 Please list any existing documents, specifications, or implementations that describe the technology. Please include links to the documents if they are publicly available.

Java Documentation for DMS2

3.2 Explanation of how these items might be used as a starting point for the work.

Java documentation of an existing DMS system might be used as a starting point. Existing functional and design specifications are too implementation specific to be of use to the expert group.

Section 4: Additional Information (Optional)

4.1 This section contains any additional information that the submitting Member wishes to include in the JSR.

The Oracle DMS system has been in used in Oracle products for about 2 years. It has proved to be popular among developers.