<commit_before>%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Kieker Monitoring Component
%
% $Date$
% $Rev$:
% $Author$


\chapter{\KiekerMonitoringPart{} Component}\label{chap:componentsMonitoring}

\NOTIFYBOX{The Java sources of this chapter, as well as a pre-compiled binary, %
can be found in the %
\file{\customComponentsBookstoreApplicationDirDistro{}/} directory of the %
binary release.}

\section{Monitoring Controller}\label{sec:componentsMonitoring:monitoringController}

The \class{MonitoringController} constructs and controls a \KiekerMonitoringPart{} %
instance. As depicted by the class diagram in Figure~\ref{fig:monitoringController:classdiagram}, it provides methods for\\

\enlargethispage{1cm}

\begin{figure}\centering % [H]
\includegraphics[scale=0.7]{images/kieker_monitoringControlleruserguide-simplified}
\caption{Class diagram of the \class{MonitoringController} (including selected methods)}
\label{fig:monitoringController:classdiagram}
\end{figure}

\begin{compactitem}
 \item Creating \class{IMonitoringController} instances (Section~\ref{sec:componentsMonitoring:monitoringController:factory}),
 \item Logging monitoring records with the configured monitoring writer (Section~\ref{sec:componentsMonitoring:monitoringController:logging}),
 \item Retrieving the current time via the configured time source (Section~\ref{sec:componentsMonitoring:monitoringController:getTime}),
 \item Scheduling and removing period samplers (Section~\ref{sec:componentsMonitoring:monitoringController:periodicSamplers}), and
 \item Controlling the monitoring state (Section~\ref{sec:componentsMonitoring:monitoringController:controState}).
\end{compactitem}

\subsection{Creating \class{MonitoringController} Instances}\label{sec:componentsMonitoring:monitoringController:factory}

The \class{MonitoringController} provides two different static methods for retrieving instances of %
\class{IMonitoringController}:\\

\begin{compactenum}
 \item The method \method{MonitoringController.getInstance()} returns a singleton instance. %
As described in Section~\ref{sec:monitoring:configuration}, the configuration is read from %
a properties file that has been passed to the JVM, is located in the classpath, or %
conforms to the default configuration (Appendix~\ref{sec:appdx:monitoringproperties}). %
 \item The method \method{MonitoringController.createInstance(Configuration config)} can be utilized to create %
an instance that is configured according to the passed \class{Configuration} object, %
as described in Section~\ref{sec:monitoring:configuration}.
\end{compactenum}

\subsection{Logging Monitoring Records}\label{sec:componentsMonitoring:monitoringController:logging}

Monitoring records are sent to the configured monitoring writers by passing %
these records, in form of \class{IMonitoringRecord} objects, to the %
\class{MonitoringController}'s \method{newMonitoringRecord} method.  %
Note, that this is not the case if monitoring is disabled or terminated (Section~\ref{sec:componentsMonitoring:monitoringController:controState}).

\subsection{Retrieving the Current Time and Using Custom Time Sources}\label{sec:componentsMonitoring:monitoringController:getTime}

The current time is maintained by a so-called time source. The \class{MonitoringController}'s method %
\method{getTimeSource} returns an \class{ITimeSource} whose method %
\method{getTime} returns a timestamp in nanoseconds. \Kieker{}'s default %
time source, \class{SystemNanoTimer}, returns the current system %
time as the number of nanoseconds elapsed since 1 Jan 1970 00:00~UTC. %
The easiest way to use a custom time source is to extend the \class{AbstractTimeSource} and %
to implement the method \method{getTime()}. Custom time sources make sense, for example, %
in simulations where not the current system time but the current simulation time is %
relevant. The configuration needs to be adjusted to use a custom time source class. %

\subsection{Scheduling and Removing Periodic Samplers}\label{sec:componentsMonitoring:monitoringController:periodicSamplers}

For certain applications, it is required to monitor runtime data periodically, %
e.g., the utilization of system resources such as CPUs. %
For this purpose, \Kieker{} supports special monitoring probes, called samplers. %
Samplers must implement the interface \class{ISampler} which includes a %
single method \method{sample(IMonitoringController monitoringController)}. %
This method is called in periodic time steps, %
as specified by the \class{MonitoringController}'s registration function %
\method{schedulePeriodicSampler}. Periodic samplers can be stopped by %
calling the \class{MonitoringController}'s method \method{removeScheduledSampler}.

Listing~\ref{listing:sigarSamplerMethod} shows the \method{sample} method %
of the \class{MemSwapUsageSampler} which can be used to monitor memory %
and swap usage employing the Sigar library~\cite{HypericSigarWebsite}. %
Likewise to other monitoring probes described in this user guide (see for %
example Sections~\ref{sec:monitoring:probe} and \ref{sec:example:monitoring}),
it collects the data of interest (lines~53--54), creates a monitoring record~%
(lines~55--58), and passes this monitoring record to the monitoring controller~%
(line~59). %
The available Sigar-based samplers for monitoring system-level monitoring %
data, such as CPU and memory usage, are discussed in Appendix~\ref{appendix:SigarBasedSamplers}. %

\pagebreak

\setJavaCodeListing
\lstinputlisting[firstline=52, lastline=70, firstnumber=52, caption=Method \method{sample} from MemSwapUsageSampler.java, label=listing:sigarSamplerMethod]{\kiekerSrcDir/monitoring/kieker/monitoring/probe/sigar/samplers/MemSwapUsageSampler.java}

\subsection{Controlling the Monitoring State}\label{sec:componentsMonitoring:monitoringController:controState}

The \class{MonitoringController} provides methods to temporarily enable or disable monitoring %
(\method{enableMonitoring}/\method{disableMonitoring}), as well as to terminate monitoring %
permanently (\method{terminateMonitoring}). %
The current state can be requested by calling the methods \method{isMonitoringEnabled} %
and \method{isMonitoringTerminated}. If monitoring is not enabled (i.e., disabled %
or terminated), no monitoring records retrieved via the method \method{newMonitoringRecord} %
are passed to the monitoring writer. Also, probes should be passive or return immediately %
with respect to the return value of the method \method{isMonitoringEnabled}. %
Note, that once the \class{MonitoringController} is terminated, it cannot be enabled %
later on.

\subsection{JMX MBean Access to \class{MonitoringController}}

\begin{figure}\centering
\subfigure[Attributes]{%
\includegraphics[width=0.485\textwidth]{images/jmxbean-monitoringcontroller-attributes.png}
}
\subfigure[Operations]{%
\includegraphics[width=0.485\textwidth]{images/jmxbean-monitoringcontroller-operations.png}
}
\caption{Screenshots of the \class{jconsole} JMX client accessing the \class{MonitoringController}'s %
attributes and operations via the MBean interface. %
}
\label{fig:monitoringController:MBean:jconsole}
\end{figure}
<commit_msg>user guide is compilable again.<commit_after>%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Kieker Monitoring Component
%
% $Date$
% $Rev$:
% $Author$


\chapter{\KiekerMonitoringPart{} Component}\label{chap:componentsMonitoring}

\NOTIFYBOX{The Java sources of this chapter, as well as a pre-compiled binary, %
can be found in the %
\file{\customComponentsBookstoreApplicationDirDistro{}/} directory of the %
binary release.}

\section{Monitoring Controller}\label{sec:componentsMonitoring:monitoringController}

The \class{MonitoringController} constructs and controls a \KiekerMonitoringPart{} %
instance. As depicted by the class diagram in Figure~\ref{fig:monitoringController:classdiagram}, it provides methods for\\

\enlargethispage{1cm}

\begin{figure}\centering % [H]
\includegraphics[scale=0.7]{images/kieker_monitoringControlleruserguide-simplified}
\caption{Class diagram of the \class{MonitoringController} (including selected methods)}
\label{fig:monitoringController:classdiagram}
\end{figure}

\begin{compactitem}
 \item Creating \class{IMonitoringController} instances (Section~\ref{sec:componentsMonitoring:monitoringController:factory}),
 \item Logging monitoring records with the configured monitoring writer (Section~\ref{sec:componentsMonitoring:monitoringController:logging}),
 \item Retrieving the current time via the configured time source (Section~\ref{sec:componentsMonitoring:monitoringController:getTime}),
 \item Scheduling and removing period samplers (Section~\ref{sec:componentsMonitoring:monitoringController:periodicSamplers}), and
 \item Controlling the monitoring state (Section~\ref{sec:componentsMonitoring:monitoringController:controState}).
\end{compactitem}

\subsection{Creating \class{MonitoringController} Instances}\label{sec:componentsMonitoring:monitoringController:factory}

The \class{MonitoringController} provides two different static methods for retrieving instances of %
\class{IMonitoringController}:\\

\begin{compactenum}
 \item The method \method{MonitoringController.getInstance()} returns a singleton instance. %
As described in Section~\ref{sec:monitoring:configuration}, the configuration is read from %
a properties file that has been passed to the JVM, is located in the classpath, or %
conforms to the default configuration (Appendix~\ref{sec:appdx:monitoringproperties}). %
 \item The method \method{MonitoringController.createInstance(Configuration config)} can be utilized to create %
an instance that is configured according to the passed \class{Configuration} object, %
as described in Section~\ref{sec:monitoring:configuration}.
\end{compactenum}

\subsection{Logging Monitoring Records}\label{sec:componentsMonitoring:monitoringController:logging}

Monitoring records are sent to the configured monitoring writers by passing %
these records, in form of \class{IMonitoringRecord} objects, to the %
\class{MonitoringController}'s \method{newMonitoringRecord} method.  %
Note, that this is not the case if monitoring is disabled or terminated (Section~\ref{sec:componentsMonitoring:monitoringController:controState}).

\subsection{Retrieving the Current Time and Using Custom Time Sources}\label{sec:componentsMonitoring:monitoringController:getTime}

The current time is maintained by a so-called time source. The \class{MonitoringController}'s method %
\method{getTimeSource} returns an \class{ITimeSource} whose method %
\method{getTime} returns a timestamp in nanoseconds. \Kieker{}'s default %
time source, \class{SystemNanoTimer}, returns the current system %
time as the number of nanoseconds elapsed since 1 Jan 1970 00:00~UTC. %
The easiest way to use a custom time source is to extend the \class{AbstractTimeSource} and %
to implement the method \method{getTime()}. Custom time sources make sense, for example, %
in simulations where not the current system time but the current simulation time is %
relevant. The configuration needs to be adjusted to use a custom time source class. %

\subsection{Scheduling and Removing Periodic Samplers}\label{sec:componentsMonitoring:monitoringController:periodicSamplers}

For certain applications, it is required to monitor runtime data periodically, %
e.g., the utilization of system resources such as CPUs. %
For this purpose, \Kieker{} supports special monitoring probes, called samplers. %
Samplers must implement the interface \class{ISampler} which includes a %
single method \method{sample(IMonitoringController monitoringController)}. %
This method is called in periodic time steps, %
as specified by the \class{MonitoringController}'s registration function %
\method{schedulePeriodicSampler}. Periodic samplers can be stopped by %
calling the \class{MonitoringController}'s method \method{removeScheduledSampler}.

Listing~\ref{listing:sigarSamplerMethod} shows the \method{sample} method %
of the \class{MemSwapUsageSampler} which can be used to monitor memory %
and swap usage employing the Sigar library~\cite{HypericSigarWebsite}. %
Likewise to other monitoring probes described in this user guide (see for %
example Sections~\ref{sec:monitoring:probe} and \ref{sec:example:monitoring}),
it collects the data of interest (lines~53--54), creates a monitoring record~%
(lines~55--58), and passes this monitoring record to the monitoring controller~%
(line~59). %
The available Sigar-based samplers for monitoring system-level monitoring %
data, such as CPU and memory usage, are discussed in Appendix~\ref{appendix:SigarBasedSamplers}. %

\pagebreak

\setJavaCodeListing
\lstinputlisting[firstline=52, lastline=70, firstnumber=52, caption=Method \method{sample} from MemSwapUsageSampler.java, label=listing:sigarSamplerMethod]{\kiekerSrcDir/monitoring/kieker/monitoring/sampler/sigar/samplers/MemSwapUsageSampler.java}

\subsection{Controlling the Monitoring State}\label{sec:componentsMonitoring:monitoringController:controState}

The \class{MonitoringController} provides methods to temporarily enable or disable monitoring %
(\method{enableMonitoring}/\method{disableMonitoring}), as well as to terminate monitoring %
permanently (\method{terminateMonitoring}). %
The current state can be requested by calling the methods \method{isMonitoringEnabled} %
and \method{isMonitoringTerminated}. If monitoring is not enabled (i.e., disabled %
or terminated), no monitoring records retrieved via the method \method{newMonitoringRecord} %
are passed to the monitoring writer. Also, probes should be passive or return immediately %
with respect to the return value of the method \method{isMonitoringEnabled}. %
Note, that once the \class{MonitoringController} is terminated, it cannot be enabled %
later on.

\subsection{JMX MBean Access to \class{MonitoringController}}

\begin{figure}\centering
\subfigure[Attributes]{%
\includegraphics[width=0.485\textwidth]{images/jmxbean-monitoringcontroller-attributes.png}
}
\subfigure[Operations]{%
\includegraphics[width=0.485\textwidth]{images/jmxbean-monitoringcontroller-operations.png}
}
\caption{Screenshots of the \class{jconsole} JMX client accessing the \class{MonitoringController}'s %
attributes and operations via the MBean interface. %
}
\label{fig:monitoringController:MBean:jconsole}
\end{figure}

{'fraction_non_alphanumeric': 0.09285614622575694, 'fraction_numerical': 0.0050230221850146506, 'mean_word_length': 6.999441964285714, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5446542', 'n_tokens_mistral': 3832, 'n_tokens_neox': 3719, 'n_words': 1252}