This chapter gives a brief description on how to use the included %
periodic samplers (Section~\ref{sec:componentsMonitoring:monitoringController:periodicSamplers}) %
for monitoring CPU utilization and memory/swap usage. %
The directory \dir{\SigarExampleDirDistro/} contains the %
sources, ant scripts etc.\ used in this example. %
These samplers employ the Sigar API~\cite{HypericSigarWebsite}. \\%

\section{Preparation}

\begin{compactenum}
\item Copy the files \file{\mainJarEMF} and \file{\sigarJar} from the %
binary distribution to the example's \dir{lib/} directory.
\item Additionally, depending on the underlying system platform, %
corresponding Sigar native libraries need to be placed in the example's \dir{lib/} directory. %
Kieker's \dir{lib/sigar-native-libs/} folder already includes the right libraries for 32 and 64~bit Linux/Windows platforms. %
Native libraries for other platforms can be downloaded from~\cite{HypericSigarWebsite}. %
\end{compactenum}

\section{Using the Sigar-Based Samplers}

\WARNBOX{
	Using a very short sampling period with Sigar ($< 500$ ms) can result in monitoring log entries with NaN values. 
}

The Sigar API~\cite{HypericSigarWebsite} provides access to a number of system-level inventory and monitoring data, %
e.g., regarding memory, swap, cpu, file system, and network devices. %
Kieker includes Sigar-based samplers %
for monitoring CPU utilization %
(\class{CPUsDetailedPercSampler}, \class{CPUsCombinedPercSampler}) %
and memory/swap usage (\class{MemSwapUsageSampler}). %
When registered as a periodic sampler (Section~\ref{sec:componentsMonitoring:monitoringController:periodicSamplers}), %
these samplers collect the data of interest employing the Sigar API, %
and write monitoring records of types \class{CPUUtilizationRecord}, %
\class{ResourceUtilizationRecord}, and \class{MemSwapUsageRecord} respectively %
to the configured monitoring log/stream. %

Listing~\ref{listing:sigarSamplerMonitoringStarterExample} shows an excerpt from %
this example's \class{MonitoringStarter} %
which creates and registers two Sigar-based peridioc samplers. %
For reasons of performance and thread-safety, the \class{SigarSamplerFactory} %
should be used to create instances of the Sigar-based Samplers. 

%\pagebreak

\setJavaCodeListing
\lstinputlisting[firstline=38, lastline=51, firstnumber=38, caption=Excerpt from MonitoringStarter.java, label=listing:sigarSamplerMonitoringStarterExample]{\SigarExampleDir/src/kieker/examples/userguide/appendixSigar/MonitoringStarter.java}

\noindent Based on the existing samplers, users can easily create custom Sigar-based %
samplers by extending the class \class{AbstractSigarSampler}. For example, Listing~%
\ref{listing:sigarSamplerMethod} in Section~\ref{sec:componentsMonitoring:monitoringController:periodicSamplers} %
shows the \class{MemSwapUsageSampler}'s \method{sample} method. %
Typically, it is also required to define a corresponding monitoring record type, %
as explained in Section~\ref{sec:componentsMonitoring:monitoringRecords}. %
When implementing custom Sigar-based samplers, the \class{SigarSamplerFactory}'s \method{getSigar} method should %
be used to retrieve a \class{Sigar} instance. %

This example uses a stand-alone Java application to set up %
a Sigar-based monitoring process. When using servlet containers,  %
users may consider implementing this routine as a \class{ServletContextListener}, %
which are executed when the container is started and shutdown. %
As an example, Kieker includes a \class{CPUMemUsageServletContextListener}. %

\section{Executing the Example}

The execution of the example is performed by the following two steps:\\

\begin{compactenum}
\item Monitoring CPU utilization and memory usage for 30~seconds (class \class{MonitoringStarter}):
\setBashListing
\begin{lstlisting}[caption=]
#\lstshellprompt{}# #\textbf{ant}# run-monitoring
\end{lstlisting}

Kieker's console output lists the location of the directory containing the file system %
monitoring log. The following listing shows an excerpt: %

%\enlargethispage{1.5cm}
\pagebreak
\setBashListing
\begin{lstlisting}
 Writer: 'kieker.monitoring.writer.filesystem.AsyncFsWriter'
     Configuration:
             kieker.monitoring.writer.filesystem.AsyncFsWriter.QueueFullBehavior='0'
             kieker.monitoring.writer.filesystem.AsyncFsWriter.QueueSize='10000'
             kieker.monitoring.writer.filesystem.AsyncFsWriter.customStoragePath=''
             kieker.monitoring.writer.filesystem.AsyncFsWriter.storeInJavaIoTmpdir='true'
     Writer Threads (1): 
             Finished: 'false'; Writing to Directory: '/tmp/kieker-20110511-10095928-UTC-avanhoorn-thinkpad-KIEKER-SINGLETON'
\end{lstlisting}

A sample monitoring log can be found in the directory \dir{\SigarExampleDirDistro/testdata/kieker-20110511-10095928-UTC-avanhoorn-thinkpad-KIEKER-SINGLETON/}.

\item Analyzing the monitoring data (class \class{AnalysisStarter}):

\setBashListing
\begin{lstlisting}[caption=]
#\lstshellprompt{}# #\textbf{ant}# run-analysis #\textbf{-Danalysis.directory}#=</path/to/monitoring/log/>
\end{lstlisting}

You need to replace \dir{</path/to/monitoring/log/>} by the location of the file system monitoring log. %
You can also use the above-mentioned monitoring log included in the example. %

The \class{AnalysisStarter} produces a simple console output for each monitoring record, %
as shown in the following excerpt: 

\setBashListing
\begin{lstlisting}
Wed, 11 May 2011 10:10:01 +0000 (UTC): [CPU] host: thinkpad ; cpu-id: 0 ; utilization: 0.00 %
Wed, 11 May 2011 10:10:01 +0000 (UTC): [CPU] host: thinkpad ; cpu-id: 1 ; utilization: 0.00 %
Wed, 11 May 2011 10:10:01 +0000 (UTC): [Mem/Swap] host: thinkpad ; mem usage: 722.0 MB ; swap usage: 0.0 MB
Wed, 11 May 2011 10:10:06 +0000 (UTC): [CPU] host: thinkpad ; cpu-id: 0 ; utilization: 5.35 %
Wed, 11 May 2011 10:10:06 +0000 (UTC): [CPU] host: thinkpad ; cpu-id: 1 ; utilization: 1.31 %
Wed, 11 May 2011 10:10:06 +0000 (UTC): [Mem/Swap] host: thinkpad ; mem usage: 721.0 MB ; swap usage: 0.0 MB
Wed, 11 May 2011 10:10:11 +0000 (UTC): [CPU] host: thinkpad ; cpu-id: 0 ; utilization: 1.80 %
Wed, 11 May 2011 10:10:11 +0000 (UTC): [CPU] host: thinkpad ; cpu-id: 1 ; utilization: 0.20 %
Wed, 11 May 2011 10:10:11 +0000 (UTC): [Mem/Swap] host: thinkpad ; mem usage: 721.0 MB ; swap usage: 0.0 MB
Wed, 11 May 2011 10:10:16 +0000 (UTC): [CPU] host: thinkpad ; cpu-id: 0 ; utilization: 1.40 %
Wed, 11 May 2011 10:10:16 +0000 (UTC): [CPU] host: thinkpad ; cpu-id: 1 ; utilization: 0.79 %
Wed, 11 May 2011 10:10:16 +0000 (UTC): [Mem/Swap] host: thinkpad ; mem usage: 721.0 MB ; swap usage: 0.0 MB
Wed, 11 May 2011 10:10:21 +0000 (UTC): [CPU] host: thinkpad ; cpu-id: 0 ; utilization: 1.80 %
Wed, 11 May 2011 10:10:21 +0000 (UTC): [CPU] host: thinkpad ; cpu-id: 1 ; utilization: 0.79 %
Wed, 11 May 2011 10:10:21 +0000 (UTC): [Mem/Swap] host: thinkpad ; mem usage: 721.0 MB ; swap usage: 0.0 MB
Wed, 11 May 2011 10:10:26 +0000 (UTC): [CPU] host: thinkpad ; cpu-id: 0 ; utilization: 0.40 %
Wed, 11 May 2011 10:10:26 +0000 (UTC): [CPU] host: thinkpad ; cpu-id: 1 ; utilization: 0.59 %
Wed, 11 May 2011 10:10:26 +0000 (UTC): [Mem/Swap] host: thinkpad ; mem usage: 721.0 MB ; swap usage: 0.0 MB
\end{lstlisting}


\end{compactenum}
