netbeans.apache.org/src/content/wiki/FitnessViaTimersCounter.asciidoc

// 
//     Licensed to the Apache Software Foundation (ASF) under one
//     or more contributor license agreements.  See the NOTICE file
//     distributed with this work for additional information
//     regarding copyright ownership.  The ASF licenses this file
//     to you 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.
//


= FitnessViaTimersCounter
:jbake-type: wiki
:jbake-tags: wiki, devfaq, needsreview
:markup-in-source: verbatim,quotes,macros
:jbake-status: published
:syntax: true
:description: Timers/Counters
:icons: font
:source-highlighter: pygments
:toc: left
:toc-title:
:experimental:

== Timers/Counters

Timers/counters (a.k.a Runtime watches) is a plugin that defined a convention
based on
link:http://bits.netbeans.org/dev/javadoc/org-openide-util/org/openide/util/doc-files/logging.html#structured[structured logging] 
for communicating some performance metrics. It depends on <<Probes,probes>> spread over the code of
interest, but the probes themselves don't depend on the plugin.


[[How_to_ensure_acceptable_performance.3F]]
=== How to ensure acceptable performance?

First, the code needs to have <<Probes,probes>> coded in, so it reports times taken for interesting parts of processing. Then users can see reported times in the runtime watches window as soon as each
measured action finishes (if they have the plugin installed).
The probes can also be used from inside a test by registering a special handler for the TIMER logger and using it for collecting the times. Such a test would heavily depend on the configuration and the load of the testing machine, though, so it is not recommended except for properly controlled environment (automated daily tests).


[[How_to_fight_against_memory_leaks.3F]]
=== How to fight against memory leaks?

Again, proper object reference <<Probes,probes>> needs to be in place first so users can potentially see the accumulating objects in the runtime watches window. Then the NbTestCase can be extended to intercept object reference logging messages and collect weak references to the reported objects. At the end of each test, the assertGC can be called for each reference to verify the objects were freed correctly. Of course not every test would want this functionality, so each test would need to indicate this need and maybe somehow provide a filter of objects to consider (e.g. not tracking Projects, only Documents). 


[[Probes]]
== Probes

There are two kinds of probes supported currently, but more kinds can be defined, if necessary.
Each probe reports some information keyed by (usually) two keys that form a hierarchy.
The primary key is usually a FileObject (but can be any type), while the second is always a String message.

The probe kinds are:

integer value (count, time) :: allows a number (time to perform an operation, number of objects processed during the operation) to be reported with a message and a key. The typical use case would be:

[source,java,subs="{markup-in-source}"]
----

long time = System.currentTimeMillis();
int count = parseEverything();
time = System.currentTimeMillis() - time;
Logger timer = Logger.getLogger("TIMER");
timer.log(Level.FINE, "Parsed objects",new Object[] {myFileObject, count});
timer.log(Level.FINE, "Parsed in [[Ms | ms]]",new Object[] {myFileObject, time});
----

or some simplification (log only time, only count, less local variables).

object reference :: allows tracking a life cycle of passed object. This is useful if you need to check number of created objects of given kind in given context. The probe would typically end up in the constructor of the object, like:

[source,java,subs="{markup-in-source}"]
----

SyntaxElement(FileObect fo) {
    this.fo = fo;
    Logger.getLogger("TIMER").log(Level.FINE, "SyntaxElements",new Object[] {fo, this});
}
----

There is also a simplified way of logging common IDE-wide instaces without the primary key:

[source,java,subs="{markup-in-source}"]
----

Logger.getLogger("TIMER").log(Level.FINE, "Project:", p);
----


[[Runtime_Watches_Window]]
=== Runtime Watches Window

Having the probes in your code, you can always inspect their results in the Runtime Watches window. The window can be shown by clicking on the "Run-time Watches" button in the _Memory toolbar_ (next to the memory meter).

You can see registered objects for given keys (usually files) and number of instances. You can invoke _Find References_ to see how the instances are held in memory.

image:RuntimeWatches.png[]

[[Writing_Automated_Tests]]
=== Writing Automated Tests

It is easy to enhance existing functional tests with checkpoints asserting that all probes of a kind has been released. See link:FitnessMemoryLeaks.asciidoc[FitnessMemoryLeaks].

link:Category:Performance:ToolsAndTests.html[Category:Performance:ToolsAndTests] link:Category:Performance:HowTo.html[Category:Performance:HowTo]

[NOTE]
====

The content in this page was kindly donated by Oracle Corp. to the Apache Software Foundation.

This page was exported from link:http://wiki.netbeans.org/FitnessViaTimersCounter[http://wiki.netbeans.org/FitnessViaTimersCounter] , that was last modified by NetBeans user Tpavek on 2010-02-18T17:46:48Z.

This document was automatically converted to the AsciiDoc format on 2020-03-12, and needs to be reviewed.
====