JMeasurement

JMeasurement This site is dedicated to software developers using JMeasurement. Download Actual versions are only availble in maven central. http://mvnrepository.com/artifact/net.sourceforge.jmeasurement2/JMeasurement Overview JMeasurement is a free and simple java api for monitoring user defined aspects of the runtime of java production code. It was build with simple usage in mind. JMeasurement can help you to show in an running application, how long some defined parts of your application are running, and how often they've been called. JMeasurement is Open Source Software, released under the Apache License, 2.0 and hosted on SourceForge. Feature list simple to use high preformance filtering possibilities in monitoring and reporting (priority, measurepoint name) persisting in XML (files or streams) monitor complete interfaces with just one line of code monitor exceptions reporting in text, csv and HTML possible to write your own renderer possibility to add a callback for every measured data disable and enable on runtime data can be accessed at runtime auto configuration with config file in classpath auto reload if config file changes support of JMX JMeasurement can be used in a JDK5 or higher enviroment. JMeasurement is a free and simple java api for monitoring user defined aspects of the runtime of java production code. It was build with simple usage in mind. JMeasurement can help you to show in an running application, how long some defined parts of your application are running, and how often they've been called. If you work with interfaces, you can automatically monitor a complete interface with the MeasureFactory#registerInterface() methode. Now every methode of every interface will be monitored. The names of the measure points are likley the name of the class implementing the interface with a # and the methode name. Usage The simplst form of using JMeasurement is this one: ... Monitor monitor = MeasureFactory.start("myMeasurePoint"); ...<do something> monitor.stop(); System.out.println(MeasureFactory.asString()); ... In this code we will measure only one point with the name "myMeasurePoint". The result will be shown as text in the console. A more sophiticated example is shown below (from MeasureFactoryTest.java): ... Monitor monitor1; MeasurePoint point; MeasureFactory.setApplicationName("testFactory"); MeasureFactory.setPriority(5); for (int i = 0; i < 10; i++) { point = MeasureFactory.getMeasurePoint(BASEPOINT + "." + Integer.toString(i)); point.setPriority(i); monitor1 = MeasureFactory.start(point.getName()); Thread.sleep(i * 10); monitor1.stop(); } System.out.println(MeasureFactory.getReport(new CSVDataRenderer())); ... First we define a monitor and a measure point. Then for our Renderer we set the application name (used for the title in the HTML renderer). Then we set the priority of the factory to 5. With this only points with priority >= 5 will be measured. All other points will deliver a NullMonitor which does nothing. Then we request a measure point, set the priority of this point to a value, get a monitor and wait. Then we stop the monitor. After that we let us generate an CSV report for the console output. As we see this output will only show measurepoints with the priority >= 5. All other points are not shown. Set the priority of the factory before getting a monitor will lead in a filter for the measurment, only point with a higher will be monitored. You can also use the priority to filter the output. In this case you must set the priority after all data will be measured before you call getReport(). Exception handling Sometimes your code to measure will throw an exception. In this case, to avoid dead monitors, you can do something like this: ... Monitor monitor = MeasureFactory.start("myMeasurePoint"); try { ...<do something> } catch(Exception e) { <your exception handling> } finally { monitor.stop(); } System.out.println(MeasureFactory.asString()); ... In this example the monitor is always stopped, but if you don't want to measure the exception handling and you want to report the exception, you can do this: ... Monitor monitor = MeasureFactory.start("myMeasurePoint"); try { ...<do something> monitor.stop(); } catch(Exception e) { monitor.setException(e.toString()); <your exception handling> } System.out.println(MeasureFactory.asString()); ... In tis example only the exception text will be recorded. To record a full stacktrace you can use this code: ... String stackTrace = StringFormat.getStackTrace(e.getCause()); ... Monitor interfaces To monitor a interface you simply have to Instancing your class, the register this class in the measure factory. The result of the registering will be a proxy object with all methodes that are definied in the interfaces of this class. Here is a simple example, (you can see the full example in the test cases of this package) using the interface : ITestProxy public interface ITestProxy { String echo(String line); void echoNow(String line); void exceptionNow() throws ProxyException; String iTestMethode(String line); } using the class : CTestProxy public class CTestProxy implements ITestProxy { ... your code here ... public String echo(String line) { ... your code here ... } public void echoNow(String linie) { ... your code here ... } public void exceptionNow() throws ProxyException { ... your code here ... } public String iTestMethode(String line) { ... your code here ... } } Now to monitor the interface of a CProxyClass, do it like this: ... ITestProxy testProxy = (ITestProxy) MeasureFactory.registerInterface(new CTestProxy(), true, true, null); ... calling some methodes of the Interface ... String line = testProxy.echo("echo: This is my line."); ... In the report you will find automatically generated MeasurePoints for every method you have called, like this: JMeasurement HTML Report pointName priority accessCount averageMSec totalMSec minMSec maxMSec active maxActive deathCount lastActivation exceptionCount exceptionList userData de.mcs.jmeasurement.test.proxy.CTestProxy#echo 0 2 505 1011 501 510 0 1 0 28.07.06 15:05 0 de.mcs.jmeasurement.test.proxy.CTestProxy#echoNow 0 2 200 401 200 201 0 1 0 28.07.06 15:05 0 de.mcs.jmeasurement.test.proxy.CTestProxy#exceptionNow 0 2 270 541 250 291 0 1 0 28.07.06 15:05 2 View As you see, Exceptions will be automatically stored in the measure point, if you set the flag storeExceptions in the MeasureFactory#registerInterface() to true. (Click on the View link in the column exceptionList) Persisting data In the factory there is the possibility to persist and load all measured data. {@link de.mcs.jmeasurement.MeasureFactory#saveToXMLStream(OutputStream)} {@link de.mcs.jmeasurement.MeasureFactory#loadFromXMLStream(InputStream,boolean)} For convinience there are to methode to directly load and save from/to files. The persisting data will be stored and retrieved as XML. Snapshots Snapshots are used to freeze the current measuredata at a defined point. Some time later you can report them To take a snapshot simply code: ... MeasureFactory.takeSnapshot("name of this snapshot"); ... You can also render only one snapshot or remove it. Snapshots are persistent, so the loading will restore privious saved snapshots. Configuration Now you can configure the JMeasurement system with a simple configuration file. There are 2 methods in the MeasurementFactory to do so. configure() and configure(File). The first one will configure the system with a file in the classpath. This could be a standard property file called jmconfig.properties. The second will load the given file as a properrty file. Here is a short example of a property file: OPTION_BACKGROUND_TIME=10000 OPTION_ENABLE_AUTOSNAPSHOT=true OPTION_ENABLE_MEMORY_SAVINGS=true OPTION_POINT_IDLETIME=60000 OPTION_WORKINGPATH=e\:\\temp\\data\\ OPTION_EXCEPTION_HANDLING =2 OPTION_ENABLE_MEASUREMENT=true OPTION_CONFIG_AUTOFILE=true OPTION_DISABLE_DEVIATION=false JMX support For the JMX support i have added two MBeans. For the configuration you will find a MBean called JmxConfig. This could be used for Java 5 and 6. For the access to the Measure points you will find a MXBean called JmxPointsMXBean, which will only return a map of JmxPoint for every point. To start the JMX interface use the method MeasureFactory.registerMBeans(). This will register the MBeans in the standard MBean server deployed with the JRE. For other JMXX implementation please use the registration method for that. An example for using you can get in the de.mcs.jmeasurement.example.TestApplication Dependencies of this library For the persistent storage i need a xml parser. Please add one to the CLASSPATH or use Java 1.4. Extension points of this library Reporting Renderer First of all you have the possibility to add your own reporting to this library. All you have to do, is to create a class which implement the Interface MeasureDataRenderer This interface has only one methode {@link de.mcs.jmeasurement.renderer.MeasureDataRenderer#getDataAsString(MeasurePoint,String) getDataAsString()} It's a simple methode that is beeing called for every measurement point, that will be in the report. Columnheader Second you can add extra column header information. Therfor is the interface {@link de.mcs.jmeasurement.renderer.MeasureDataRendererColumnHeader MeasureDataRendererColumnHeader} This interface has only one methode too {@link de.mcs.jmeasurement.renderer.MeasureDataRendererColumnHeader#getColumnHeaderAsString(MeasurePoint) getColumnHeaderAsString()} This simple methode will be called with an empty MeasurePoint only once before calling the getDataAsString() Paging The next usefull interface is {@link de.mcs.jmeasurement.renderer.MeasureDataRendererPage MeasureDataRendererPage} It's design to da a page oriented view on the report. First the Report will call the methode {@link de.mcs.jmeasurement.renderer.MeasureDataRendererPage#getReportHeader() getReportHeader()}. For every page the {@link de.mcs.jmeasurement.renderer.MeasureDataRendererPage#beginPage() beginPage()} and {@link de.mcs.jmeasurement.renderer.MeasureDataRendererPage#endPage() endPage()} will be called. After all the {@link de.mcs.jmeasurement.renderer.MeasureDataRendererPage#getReportFooter() getReportFooter()} is the last methode to be called. A example using all interfaces you will find in {@link de.mcs.jmeasurement.renderer.DefaultHTMLRenderer DefaultHTMLRenderer}. Measurement On the side of the measurement there will be the following extension possibilities. userdata On every measure point you can add a userdata object to hold data you want to provide with the measure point. For reporting the object should implement the toString() methode. measurement callback On the other side, i have implemented a callback function for the operation of adding a measured value (Monitor) to the measure point. Your extension must implement the interface {@link de.mcs.jmeasurement.MeasureDataCallback MeasureDataCallback}. It will be called everytime before a the monitor data is added to the measurepoint. Please be sure that your object is thread safe, because this methode could be called simultaneous for different measure pointsand also for the same measure point. You can use this callback for simple things like adding/subtracting time to the monitor. Or special counting by using the userdata object. Perfomancetests In this package there is a predefined performance test implemented. To start this test simply call java -cp JMeasurement-0.##.###.jar -Xms256m -Xmx256m de.mcs.jmeasurement.test.Performance (Please exchange the ## with the right version informations of your library) The performance test will automatically generate 100000 measurepoints, than it will start for every point a monitor and stop it again. After that it will do the same, but with a disabled factory. After this test it will test the preformance of the interface proxy. It makes 100.000 calls to an interface function once with MeasurementFactory enabled, once with MeasurementFactory disabled. On my 1.5 GHz, 1GB Centrino Nootebook, the results are something like Report summary 1. :1522 msec 2. :1062 msec 3. :441 msec 4. :1031 msec 5. :371 msec On my 2 GHz, 2GB Centrino Duo Nootebook, the results are something like Report summary 1. :1328 msec 2. :703 msec 3. :156 msec 4. :657 msec 5. :172 msec Usage of third party componentes In this package only one third party part is integrated. It's the XML Writer package of David Megginson (david@megginson.com) Many Thanks. Second some inspiration of this package came from the JAMon package (www.jamonapi.com) of Steve Souza - admin@jamonapi.com License Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.