\subsection*{Problem}

Both code comments and assertions are unfortunately not very popular. A quite efficient way to still get some documentation about the code are logging statements. In Elektra they are currently inconsistent and unusable. Thus there is an urge for this decision.

\subsection*{Constraints}


\begin{DoxyItemize}
\item this decision is irrelevant for plugins and bindings that are not written in C/\+C++. In any case, however, logging must be disabled by default.
\item should completely compile away with E\+N\+A\+B\+L\+E\+\_\+\+L\+O\+G\+G\+ER=O\+FF
\item should support minimalistic, compile-\/time filtering (per modules and verbosity level?) and some sinks (stderr, syslog or files)
\end{DoxyItemize}

\subsection*{Assumptions}


\begin{DoxyItemize}
\item run-\/time problems are checked via assertions, not logged
\item opinions about if logging should be to stderr or files differ
\item filtering with grep is not enough
\item per default there should be no output
\item with E\+N\+A\+B\+L\+E\+\_\+\+L\+O\+G\+G\+ER=ON only warnings and errors should be shown on stderr
\item other sinks like syslog and file may log more (they are not immediately visible and distracting)
\item performance is not so important (because logging is usually turned off anyway)
\end{DoxyItemize}

\subsection*{Considered Alternatives}


\begin{DoxyItemize}
\item log similar to the warnings/error system work, discarded because of the run-\/time overhead and no use case why end users should see log statements.
\item C++ logging library (boost, apache,..), discarded because C++ should not be in core
\item libraries needed static initializing\+: problematic, logging should just work, even if application does not initialize anything
\item using syslog\+: no info from which source file the logging statement comes from
\item using journald\+: adds deps problematic for non-\/linux
\item zlog\+: incompatible licence (L\+G\+PL)
\end{DoxyItemize}

\subsection*{Decision}

Provide a Macro


\begin{DoxyCode}
ELEKTRA\_LOG (\textcolor{keywordtype}{int} module, \textcolor{keyword}{const} \textcolor{keywordtype}{char} *msg, ...);
\end{DoxyCode}


that calls


\begin{DoxyCode}
elektraLog ([as above], \textcolor{keyword}{const} \textcolor{keywordtype}{char} * \textcolor{keyword}{function}, \textcolor{keyword}{const} \textcolor{keywordtype}{char} * file,
            \textcolor{keyword}{const} \textcolor{keywordtype}{int} line, ...);
\end{DoxyCode}


and adds current function, file and line to {\ttfamily elektra\+Log}\textquotesingle{}s arguments.

{\ttfamily elektra\+Log} is implemented in a separate {\ttfamily \hyperlink{log_8c}{log.\+c}} file. If someone needs filtering, logging to different sources or similar, he/she simply modifies {\ttfamily \hyperlink{log_8c}{log.\+c}}.

\subsubsection*{Severity}

The severity passed to {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+G\+\_\+} should be as in syslog\textquotesingle{}s priority, except the error conditions which are not needed (asserts should be used in these situations).

So we would have\+:


\begin{DoxyItemize}
\item {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+G\+\_\+\+W\+A\+R\+N\+I\+NG}\+: warning conditions
\item {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+G\+\_\+\+N\+O\+T\+I\+CE}\+: normal, but significant, condition
\item {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+G\+\_\+\+I\+N\+FO}\+: informational message
\item {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+G\+\_\+\+D\+E\+B\+UG}\+: debug-\/level message
\end{DoxyItemize}

\subsubsection*{Modules}

To add a new module, one simply adds his/her module to {\ttfamily elektramodules.\+h} via {\ttfamily \#define}\+:


\begin{DoxyCode}
\textcolor{preprocessor}{#define ELEKTRA\_MODULE\_<NAME> <SEQNUMBER>}
\end{DoxyCode}


The module name {\ttfamily $<$N\+A\+ME$>$} shall be consistent with module names used in {\ttfamily module\+:} of {\ttfamily src/error/specification}.

\subsection*{Rationale}

A more complex system seems to be overkill. Thus libraries should not have any effects other than what is described by their A\+PI, logging should nearly always be disabled.

A more \char`\"{}hackable\char`\"{} logger seems to be more suitable for individual needs. Having a separate {\ttfamily \hyperlink{log_8c}{log.\+c}} means that the logger can be changed without the need to recompile anything but a single file. It also removes the dependency of {\ttfamily stdio.\+h} from every individual file to a single place.

Thus logging is very easy to use (only include {\ttfamily elektralog.\+h} and use {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+OG}) and still very flexible (with modules, severity, file, line and function information nearly everything someone wants from a logging system can be achieved in {\ttfamily \hyperlink{log_8c}{log.\+c}}.

\subsection*{Implications}

The current V\+E\+R\+B\+O\+SE would be turned off forever and the code within V\+E\+R\+B\+O\+SE needs to be migrated to {\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+OG}.

\subsection*{Related Decisions}


\begin{DoxyItemize}
\item assertions
\end{DoxyItemize}

\subsection*{Notes}