[[SystemMonitor]]

== SystemMonitor

*org.jpos.util.SystemMonitor*  is a very simple class that periodically 
logs useful information such as the number of running threads, memory 
usage, etc. 

Its constructor looks like this: 

[source,java]
----

     public SystemMonitor (int sleepTime, Logger logger, String realm)
  
----

 
[NOTE]
====

See 
   link:http://jpos.org/doc/javadoc/org/jpos/util/SystemMonitor.html[javadocs]
for details.
  
====

Using SystemMonitor is very easy. You simply have to instantiate it with code
like this: 

[source,java]
----

     ...
     ...
     new SystemMonitor (60*60*1000L, yourLogger, "system-monitor"); // dumps every hour
     ...
     ...
  
----

and it will dump info to your log every hour (60*60*1000 milliseconds). 
The output looks like this: 

[source,xml]
----
  <info>
               OS: Mac OS X
             host: Macintosh-2.local/192.168.2.20
          version: 1.9.3-SNAPSHOT (d3c9ac3)
         instance: 38d512f6-f812-4d85-8520-cb96de2654a0
           uptime: 00:00:00.234
       processors: 2
           drift : 0
    memory(t/u/f): 85/7/78
          threads: 4
            Thread[Reference Handler,10,system]
            Thread[Finalizer,8,system]
            Thread[Signal Dispatcher,9,system]
            Thread[RMI TCP Accept-0,5,system]
            Thread[Q2-38d512f6-f812-4d85-8520-cb96de2654a0,5,main]
            Thread[DestroyJavaVM,5,main]
            Thread[Timer-0,5,main]
            Thread[SystemMonitor,5,main]
    name-registrar:
      logger.Q2.buffered: org.jpos.util.BufferedLogListener
      logger.Q2: org.jpos.util.Logger
  </info>

----

Most output is self-explanatory, with some abbreviations, e.g., memory 't/u/f'
stands for _total_, _used_ and _free_. But there's one, *drift*, that deserves
some explanation.

In the old days of the initial JVM 1.02, where Threads were not native
operating system threads (they were called _green threads_), it was very easy
for a thread to interfere with other threads in the same JVM, so calls to set
the thread priority, and even calls to +Thread.yield()+ here and there in tight
loops where necessary.

In order to detect situations where something was really wrong we devised a 
simple approach: the system monitor is supposed to sleep for a given period
of time, and then wake up. If we sleep for say 3600 seconds, we should be
waked up exactly 3600 later, right? When threads were cooperating that was 
kind of true, we wake up just a few milliseconds later which is reasonable, 
but when some threads were hogging the CPU, that wake up happens several
hundred and sometimes thousand milliseconds later. That was an indication
that one or more threads were running in a tight loop consuming too
much CPU resources and needed further investigation.

Green Threads are over, we now have great support for native threads, but
we left that _drift_ indicator in the SystemMonitor and interesting enough,
it's still very useful. When the system is running under heavy load, or on
overloaded and poorly monitored virtualized environments, the drift goes
up, to several seconds. 

[TIP]
=====
If we have a report for a slow jPOS application, we suggest to immediately take
a look at that drift, if it looks weird, you know you need to start looking
at the whole system performance instead of just your jPOS based application.
=====
 
[NOTE]
====
If you're using Q2, the default configuration deploys a +SystemMonitor+ 
for you.

See +deploy/99_sysmon.xml+ 

====

