Source

alerta / userguide / advancedfeatures.tex

Full commit
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
\part{Advanced features}
\section{Targets}
\label{sec:Targets} Target option -t provides an easy way to identify, by means
of a regular expression, a particular log trace in your logs. By default, it
will tail as normal and if your regex is matched, then that line will be
emphasized in a red background.\\
Example:\\
\emphlogtrace{this is a log trace matched by target option}

You can specify multiple comma separated targets. Each target is just an string
being itself a simple string or just a regular expression. It must be enclosed
within simple or double quotes.
\begin{cmd}
 ./log4tail -t [--target] 'regex1,regex2,regex3,...,regexN' pathToLogs
\end{cmd}

\subsection{Every log with its own target scheme}
If you want every log with its own targets, then you must provide them in a
config file.  In order to do that, just edit a text file and specify the next
key, value optional parameters:

\begin{config}
\begin{verbatim}
targets fullpathToLog0 = regex0 : color0; regex1 : color1;..; regexN : colorN
targets fullpathToLog1 = regex0 : color0; regex1 : color1;..; regexN : colorN
\end{verbatim}
\end{config}

Where color0, ... colorN are comma separated combinations of foreground,
background colors. Please take a look at section \ref{sec:availablecolors}.

An example of that could be:

\begin{config}
\begin{verbatim}
targets /var/log/messages = iptables$ : blue, on_red; ^2009-08-07 user : yellow
targets /var/log/mail.log = incoming \d+ : on_cyan; \d{1,3} something 
\end{verbatim}
\end{config}

If an specific regex does not have a corresponding color, then it will be
emphasized using the default color setup, which is the log trace on a red
background.

\section{Throttling}
In release v05, the throttling option is provided. Many applications when
started usually tend to upload configuration parameters and log them very fast,
which makes nearly impossible to identify anything (unless you open the log and
check). In that case, or in other ones where an application logs very fast, you
can provide the \emph{throttle} option specifying the number of seconds you want
to output in the screen the logging information one line at a time. The number 
of seconds can be a floating point number.
\begin{cmd}
 ./log4tail --throttle 0.5 pathToLogs
\end{cmd}
That would tail the logs showing the information every half a second one line at 
a time.


\section{Notifications}
\logftailer{} uses \emph{Notifications} to identify what kind of action needs to
trigger when it matches a certain line with an specific log4j level. The actions
provided as of version v05 are:
\begin{itemize}
 \item Print (see \autoref{sec:PrintAction})
 \item Filter (see \autoref{sec:filter})
 \item CornerMark (see \autoref{sec:cornermark})
 \item Mail (see \autoref{sec:mailnotification})
 \item Inactivity (see \autoref{sec:inactivitysection})
 \item Executor (see \autoref{sec:executor})
 \item Poster (see \autoref{sec:poster})
 \item PrintShot (see \autoref{sec:PrintShot})
\end{itemize}

\subsection{Print Notification}
\label{sec:PrintAction}
PrintAction does what the famous \emph{tail} command does, just printing in the
screen (terminal) but with colors. When an application logs information very
fast, colors provide and easy way to quickly identify a certain pattern or
problem. Every color identify an specific level according to the log4j java
framework.

\subsubsection{Available colors}
\label{sec:availablecolors}
\logftailer{} provides the following foreground colors:

\begin{center}
\begin{tabular}{|l || c|}
\hline
 black (default for debug) & {\color{black} \textbf{This is a test logtrace}} \\ 
\hline
 red (default for fatal and critical) & {\color{red} \textbf{This is a test logtrace}} \\ 
\hline
 green (default for info) & {\color{green} \textbf{This is a test logtrace}} \\ 
\hline
yellow (default for warning) & {\color{yellow} \textbf{This is a test logtrace}} \\ 
\hline
 blue & {\color{blue} \textbf{This is a test logtrace}} \\ 
\hline 
magenta (default for error) & {\color{magenta} \textbf{This is a test logtrace}} \\ 
\hline
 cyan & {\color{cyan} \textbf{This is a test logtrace}} \\ 
\hline 
white & \colorbox{black}{\color{white}\textbf{This is a test logtrace}} \\
\hline
\end{tabular}
\end{center}

and the additional background colors:
\begin{center}
\begin{tabular}{|l | c |}
  \hline
 on\_black & \colorbox{black}{\color{green}this is a test logtrace} \\
 \hline
 on\_red & \colorbox{red}{this is a test logtrace} \\
 \hline
on\_green & \colorbox{green}{this is a test logtrace} \\
 \hline
on\_yellow & \colorbox{yellow}{this is a test logtrace} \\
 \hline
 on\_blue & \colorbox{blue}{this is a test logtrace} \\
 \hline
 on\_magenta & \colorbox{magenta}{this is a test logtrace} \\
 \hline 
on\_cyan & \colorbox{cyan}{this is a test logtrace} \\
 \hline 
on\_white & \colorbox{white}{this is a test logtrace} \\
\hline
\end{tabular}
\end{center}

%\begin{itemize}
 %\item on\_black \hspace{20pt}\colorbox{black}{\color{green}this is a test logtrace}
 %\item on\_red \hspace{29pt}\colorbox{red}{this is a test logtrace}
 %\item on\_green \hspace{20pt}\colorbox{green}{this is a test logtrace}
 %\item on\_yellow \hspace{15pt}\colorbox{yellow}{this is a test logtrace}
 %\item on\_blue \hspace{24pt}\colorbox{blue}{this is a test logtrace}
 %\item on\_magenta \hspace{6pt}\colorbox{magenta}{this is a test logtrace}
 %\item on\_cyan \hspace{22pt}\colorbox{cyan}{this is a test logtrace}
 %\item on\_white \hspace{19pt}\colorbox{white}{this is test logtrace}
%\end{itemize}

\subsubsection{Providing user defined colors}
Default colors used in \logftailer{} work well in clear background terminal,
such as white. If your terminal has black as background you can provide your own
colors in a config file combining foreground and background as you like, such as:
\begin{itemize}
 \item warn = yellow, on\_cyan \colorbox{cyan}{\color{yellow}\textbf{this is a WARN test logtrace}}
 \item fatal = red {\color{red}\textbf{this is a FATAL test logtrace}}
 \item critical = red, on\_yellow \colorbox{yellow}{\color{red}this is a CRITICAL test logtrace}
 \item error = magenta {\color{magenta}\textbf{this is an ERROR test logtrace}}
 \item info = green, on\_black \colorbox{black}{\color{green}this is an INFO test logtrace}
 \item debug = cyan {\color{cyan}\textbf{this is a DEBUG test logtrace}}
\end{itemize}
and pass -c pathtoconfig as a parameter to \logftailer{}. 

It is not necessary to 
provide all the colors in the config file. If yellow is fine for warn and red for 
fatal, you could say something like:

\begin{config}
\begin{verbatim}
 error = red
 info = magenta
 debug = green
\end{verbatim}
\end{config}

\noindent
error, info and debug colors will be overriden by your ones provided in the config 
file. 

\subsubsection{Every log with its own color}
If you want to just tail different logs and you want each log with its own specific color, 
then you can specify that in the config file. This feature overrides the level colors for that 
specific log, printing all traces with the same color. 
For example, if we write in a config file something like:

\begin{config}
\begin{verbatim}
 /opt/log4/out0.log = green
 /opt/log4/out1.log = yellow, on_blue
\end{verbatim}
\end{config}

In that specific case, if we run:
\begin{cmd}
 log4tail -c configfile /opt/log4/out0.log /opt/log4/out1.log /opt/log4/out2.log
\end{cmd}
In the output you'll see \emph{all} traces from /opt/log4/out0.log in green, 
\emph{all} traces from /opt/log4/out1.log in yellow as foreground and blue as background 
and in the specific case of /opt/log4/out2.log it will use the default color for each level. 
The example in \autoref{fig:multiple_colors} will clarify that.
% \begin{center}
% \framebox[1.2\width]{
% \parbox[c]{10cm}{
% ==$>$ fullPathLog0 $<$==\par
% {\color{green} INFO this is an info log trace from fullPathLog0}\\
% {\color{green} ERROR this is an error log trace from fullPathLog0}\\
% ==$>$ fullPathLog1 $<$==\\
% {\color{yellow} INFO this is an info log trace from fullPathLog1}\\
% {\color{yellow} DEBUG this is a debug log trace from fullPathLog1}\\
% ==$>$ fullPathLog2 $<$==\\
% {\color{red} FATAL this is a fatal log trace from fullPathLog2}\\
% {\color{green} INFO this is an info log trace from fullPathLog2}}}
% \end{center}

\begin{figure}[ht]
\centering
\includegraphics[scale=0.60]{multiple_colors.png}
\caption{\logftailer{} each log with its own color scheme}\label{fig:multiple_colors}
\end{figure}

\subsection{Filter Notification}
\label{sec:filter}
With filter you can filter out information you don't want to be printed out 
in the standard output. It would be a mix of tail and grep. You tail the log 
and grep for the information you are interested in. In order to enable that 
feature you need to execute \logftailer{} with the -f option:

\begin{cmd}
  ./log4tail -f[--filter] tracetofilter pathToLogs
\end{cmd}

\subsection{CornerMark Notification}
\label{sec:cornermark}
CornerMark notification will display a colored box in the bottom right side of
the terminal in case a Fatal, Error, Warning or Target trace has been found during the specified
time. In order to activate this type of notification you need to pass the
option cornermark in the command line as follows:

\begin{cmd}
  ./log4tail --cornermark numberofseconds pathToLogs
\end{cmd}
where numberofseconds can be any number. 

Example of what you would see if that notification is activated can be seen in
 \autoref{fig:cornermark}.

\begin{figure}[ht]
\centering
\includegraphics[scale=0.60]{terminalcornermark.png}
\caption{\logftailer{} with cornermark activated}\label{fig:cornermark}
\end{figure}

For Fatals and Errors the mark will be red. For Warnings will be yellow and for Targets 
will be cyan. These three colors are fine for easy identification in either clear terminal
backgrounds or dark ones.

The motivation for having a corner mark is when you need to go for a break and
want some kind of visual alert when something goes wrong. The visual alert will
be displayed for the number of seconds you specify in the command line, so it
is always advisable to be a number greater than the number of seconds you'll be
out of your desktop. 

\subsection{Mail Notification}
\label{sec:mailnotification}
\logftailer{} has an SMTP email client built-in if you want to be notified by email.
Mail notification is used when you want to be notified by email when a target or level (error or fatal) has been found 
in the logs. It is very useful when you are tailing for long hours and you cannot take 
a look at the screen from time to time. It's not necessary to run in silent mode anymore 
to use this action.
This action can be triggered by specifying the command line option -m and
specifying the mail details in a configuration file. 

\begin{cmd}
 ./log4tail -m [--mail] -c [--config] [[-t [--targets] 'regex1,...,regexN'] pathToLogs
\end{cmd}

\textbf{You'll need to provide a configuration file} with the following key parameters:

\begin{config}
\begin{verbatim}
 mail_username = yourusername
 mail_hostname = youremailhostname 
 mail_port = port
 mail_ssl = True or False
 mail_from = Email from, it can be the same as your to address 
 mail_to = Email to where you will receive the alerts
\end{verbatim}
\end{config}

\noindent
The password will be asked during runtime to avoid being left in plain ascii in
the configuration file. For SSL connection you will need a Python 2.6 runtime,
otherwise mail\_ssl should be left to False.

If an alert is raised, you will receive an email from mail\_from with the
subject ``Log4tailer alert'' for easy filtering.

\logftailer{} works with SMTP Google email accounts\footnote{Using SMTP SSL
connection. For SMTP SSL connectivity you'll need a Python 2.6 runtime, as
Python 2.4 does not support it.} if you have one.  In \autoref{fig:mailalert}
you can see how it looks like.

\begin{figure}[hb]
%\centering
\includegraphics[scale=0.55]{emailalert.png}
\caption{\logftailer{} email alert in gmail}\label{fig:mailalert}
\end{figure}

I have not tested \logftailer{} with \textbf{sendmail}. For that you would have
to configure sendmail to accept smtp localhost connections.  Explaining that is
out of the scope of this document. You can take a look in the sendmail
documentation book in the Sendmail Consortium webpage at
\href{http://www.sendmail.org}{http://www.sendmail.org}.

\subsubsection{Flood control}
In order to avoid being sent lots of notification emails when a flood of
undesirable log traces turn up, log4tailer has a way to control that by means
of a 60 second gap, which means that non desirable levels that happen within
that gap are not notified. After that expiration time, the first undesirable
log trace to be found will be notified, triggering again a 60 second gap
period. 
 
\subsubsection{When should I use Mail notification}

MailAction would be like having additional eyes taking a look at the logs. That
means, that you can take a rest from time to time basically. If something is
found, then you are notified. At this stage, it will notify errors and fatals,
considered to be non desired levels in an application. Along with that, you can
specify a series of patterns (regexes), log4tailer's targets, that if found
could mean that the application is not behaving as expected. In that specific
case, you will get notified as well.
  
\subsection{Inactivity Notification}
\label{sec:inactivitysection}
Inactivity monitors for inactivity time in the logs. Inactivity as of this
release will just send an emphasized line in the standard output notifying that
there has been a lot of inactivity in that log. The inactivity time must be
provided in the command line with the -i parameter followed by the number of
seconds of inactivity to be monitored in the log.  If there has not been any
activity for the number of seconds given, \logftailer{} will print an
emphasized line in the standard output.\\ 
As an example:\\
\emphlogtrace{{Inactivity in the log for 5.99955296516 seconds}}
 
The command line interface to activate the inactivity monitoring is:
\begin{cmd}
 ./log4tail -i [--inact] numberinseconds pathToLogs
\end{cmd}

\subsubsection{Inactivity Mail Notification}
If you want a notification by email when inactivityAction is raised, just specify in the 
config file:

\begin{config}
\begin{verbatim}
 inactivitynotification = mail
\end{verbatim}
\end{config}

\noindent
By default is notification to the standard output as shown before. 

\subsection{Executor}
\label{sec:executor}

The executor is another type of notification. \logftailer{} will execute a
program provided by the user if the levels Error, Fatal or Critical have been
found in the log trace. The user must provide the command line option
\emph{--executable} along with a config file specifying the key \emph{executor}
with value the program you want log4tailer to execute and its parameters
separated by whitespaces. You can specify a couple of place holders as well,
where the first will be the log trace found and the second the log path where
the trace was found.

\begin{cmd}
 ./log4tail --executable -c configfile pathToLogs
\end{cmd}

where in configfile you could write something like:

\begin{verbatim}
 executor = anyscript %s %s 
\end{verbatim}

Where anyscript can be any program accepting two parameters, namely, lograce and log path. The script 
you provide, of course, will need to have execution permissions for the user 
owning the \logftailer{} process. 

As a simple example, if you cannot configure SMTP for log4tailer, then you could 
setup a script to use the \emph{mail} linux command line to send you an email by means of sendmail.

\subsection{Poster notification}
\label{sec:poster}
The poster notification is basically a REST client built in \logftailer{}. That will open 
the possibility to communicate with a centralized web server with a frontend. Poster 
notification will register to the server and notify all those fatal, critical, errors or 
targets found in the log. 
\begin{cmd}
 log4tail --post -c configfile.txt pathToLogs
\end{cmd}
where in the configfile.txt you will need to specify the following parameters:

\begin{config}
\begin{verbatim}
 server_url = url to the server
 server_port = port
 server_service_uri = /where/go/notifications
 server_service_register_uri = /register/log4tailer/toserver
 server_service_unregister_uri = /unregister/log4tailer/fromserver
\end{verbatim}
\end{config}

Upon unregistration, the server will delete the log from the database and all its related 
logtraces. So, if you don't want that happen, just point the unregister uri to a non existent one, 
and the server will not do anything, although it will keep the log as registered. Please, take a 
look at \autoref{sec:log4server}.

\subsection{PrintShot}
\label{sec:PrintShot}
The PrintShot notification is basically the Print notification adding the
capability of taking an screenshot whenever we find an alertable log trace. An
alertable log trace is any trace within levels Critical, Fatal and Error or
those that are targetable. In order to activate this notification, you need to
execute \logftailer{} in the following manner:

\begin{cmd}
 log4tail --screenshot -c configfile.txt pathToLogs
\end{cmd}

Where in the configfile.txt you should specify the following key:

\begin{config}
screenshot = fullpathtopicture.png
\end{config}

\subsubsection{requirements}
The PrintShot notification requires you have the \textbf{import} command line
program to take screenshots. So, make sure you have that software installed.
Most modern Linux distributions have it. 

\subsubsection{When should I use this feature}
This feature is useful whenever you are testing in your local desktop any
software and you would like to have a proof that some log trace is getting
traced by that software. It would be good for software documentation purposes
as well. 

\section{Pause Modes}
\label{sec:PauseModes}
As of release 1.2 \logftailer{} includes pausemodes feature. You will be able
to pause or freeze the output by a number of seconds if an specific level or
target has been found. In order to enable pausemodes, you must configure them
in a config file providing any of the following keys\footnote{the keys are case
insensitive, so is the same pauseDEBUG or pausedebug\ldots} :

\begin{config}
\begin{verbatim}
 pausedebug = secondsfordebug
 pauseinfo = secondsforinfo
 pausewarn = secondsforwarn
 pauseerror = secondsforerror
 pausefatal = secondsforfatal
 pausetarget = secondsfortarget
\end{verbatim}
\end{config}

\noindent
You specify only those ones you want to use.
For instance, if we want to freeze the output momentarily (one second) for warnings:

\begin{config}
\begin{verbatim}
 pausewarn = 1
\end{verbatim}
\end{config}

\noindent
Then, we should run log4tailer like:
\begin{cmd}
./log4tail -c yourconfig /pathToLogs
\end{cmd}
Pausetarget keyword will pause the output for any regex found in the log when
running log4tailer with -t option.

\section{Reporting}
Every time we finish the tailing, log4tailer will output a report, specifying
how long log4tailer has been running and the number of events for debug, info
and warn. In case of error and fatal, it will provide the timestamps when they
were found and their corresponding logtrace.  Example:

\begin{verbatim}
Analytics: 
Uptime: 
0.0 years 0.0 days 0.0 hours 0.0 mins 45.9482619762 secs 
Report for Log out.log
Levels Report: 
FATAL:
ERROR:
15 May 2009 17:17:43=>> There was an error here
15 May 2009 17:17:44=>> There was another one in here
15 May 2009 17:17:45=>> Oops, another one
WARN:
4
INFO:
9
DEBUG:
14
TARGET:
3
OTHERS:
18 Jul 2010 11:45:44=>> Inactivity action detected
Ended log4tailer, because colors are fun
\end{verbatim}

\subsection{Reports by email}
If you want a report by email after a given amount of time, then you can do
that by means of the config file. There are two values that can be setup,
namely:

\begin{config}
\begin{verbatim}
 analyticsnotification = mail
 analyticsgaptime = 10.5
\end{verbatim}
\end{config}

If these two values are uncommented, then you will be required to provide the
mail details in the same configuration file, please check the
\autoref{sec:mailnotification}. The analyticsgaptime should be given in
seconds, by default is 3600 seconds (1 hour).  You'll receive a report after
that period. After that period the statistical information is flushed and then
sent again once the gap notification time is expired and so on.  In
\autoref{fig:emailnotification} %in page \pageref{fig:emailnotification}, you
can see an email report notification in a Google gmail account.

\begin{figure}[ht]
%\centering
\includegraphics[scale=0.50]{emailnotification.png}
\caption{\logftailer{} email report notification}\label{fig:emailnotification}
\end{figure}

\subsection{Reports to a file}
\logftailer{} can give you a report to a file if you want to. Just provide the
analyticsnotification in the configuration file pointing to the reporting file
(full path). An example of that would be:

\begin{config}
\begin{verbatim}
 analyticsnotification = /opt/reportlog4tailer.txt
 analyticsgaptime = 10.5
\end{verbatim}
\end{config}

\section{Silent Mode}
Silent mode, tails the logs in the background (daemonized tailer) and triggers
the Mail notification, notifying if error, fatal or any target has been found
in the logs. 

The syntax to activate the silent mode is:
\begin{cmd}
 ./log4tail -s -c [--config] configfile [-t [--targets] 'regex1,..,regexN'] fullPathToLogs
\end{cmd}

\logftailer{} will require a configuration file with your email details. Please
take a look at the \autoref{sec:mailnotification} where specifies the key
parameters that need to be specified. 

\begin {bclogo}[logo =\bcinfo, barre = none,noborder = true]{Note}
\begin {gbar}{yellow}
It is very important to note that the
path to the logs must be the full path, no relative. That's because when
\logftailer{} enters in daemonized mode, it switches to the root directory
closing all buffers and detaching itself from the terminal, in other words, it
becomes a real daemon. As a consequence, it is not necessary to execute it with
the nohup Linux command line tool.
\end{gbar}
\end{bclogo}

\subsection{Silent Mode when no access to email notification}
\logftailer{} provides the no-mail-silence optional command line parameter,
where it enters in daemonized mode with no notification setup. It will be up to
the user to setup some type of notification by means of a configuration file.
Actually, this option is thought to be used along with the -config parameter
where you can specify some notification. One of the scenarios would be when you
want automatic monitoring when the server you are running \logftailer{} has no
ports available for email notification. You could provide a config file with
\emph{analyticsnotification} pointing to a file where \logftailer{} would do a
report of the logs status every \emph{analyticsgaptime} seconds or one hour by
default.

\begin{cmd}
 ./log4tail --no-mail-silence -c [--config] configfile fullPathToLogs
\end{cmd}


\section{Coloring Standard Input}
Log4tailer can colorize its standard input to the standard output. Main use
would be when your application does some output and finishes. In order to do
that just type:
\begin{cmd}
 yourapplication | log4tail -
 cat somelog.log | log4tail -
\end{cmd}
You can use the \emph{more} Linux/Unix application in order to page the output.
Example:
\begin{cmd}
 cat somelog.log | log4tail - | more
\end{cmd}

\section{Tailing last N lines}
You can tail last \emph{N} lines from the log with the \emph{-n} option. Just type:
\begin{cmd}
 ./log4tail -n numberOfLines pathToLog
\end{cmd}
and it will output the last \emph{numberOfLines} from the log colorizing the
corresponding levels.

\section{SSH Tailing}
SSH Tailing or remote tailing will allow you to tail multiple remote logs from
different hosts. As of now, only PrintAction is available, so you'll be able to
tail multiple remote logs in a colorful way as specified in section
\ref{sec:PrintAction}. In order to tail remotely you'll need to pass as a
parameter the -r option along with some config file parameters:

\begin{cmd}
 ./log4tail -r -t targets -c yourconfig.txt
\end{cmd}
In your configfile you must provide the following parameters:

\begin{config}
\begin{verbatim}
 sshhostnames = hostname0, hostname1, hostnameN-1
 hostname0 = username0, /var/log/log0, /var/log/log1, /var/log/logN-1
 hostname1 = username1, /var/log/log0, /var/log/log1, /var/log/logN-1
 hostnameN-1 = usernameN-1, /var/log/log0, /var/log/log1, /var/log/logN-1
\end{verbatim}
\end{config}

\noindent
Where:
\begin{itemize}
\item \textbf{sshhostnames} is a comma separated values of hostnames
\item every \textbf{hostname} must be a parameter itself where first 
value should be its username and then the logs you want to tail.
\end{itemize}

By default log4tailer will try to authenticate by using your rsa key under your
$\sim$/.ssh/id\_rsa key if it exists, otherwise it will use normal username, password
authentication. 

\begin {bclogo}[logo =\bcinfo, barre = none,noborder = true]{Note}
\begin {gbar}{yellow}
Please be aware that you need to be the same username
in both client and server. So, if you are logging in as root the ssh key needs
to be for the root user. Otherwise, it would request your password.
\end{gbar}
\end{bclogo}
If you want to use another rsa key other than the default
id\_rsa key then you can provide one in the config file by using the rsa\_key
parameter. Example:

\begin{config}
\begin{verbatim}
 rsa_key = /home/youruser/.ssh/myrsakey
\end{verbatim} 
\end{config}

\noindent
rsa\_key value must be the full path to the rsa\_key.

Some considerations are to be taking into account. As of now, remote tailing
\textbf{only} provides PrintAction along with targets, that means that you will
be able to tail with colors and emphasize those log traces that match the comma
separated regexes provided with -t. Besides, you'll be able to use pauseModes
set up in the config file as explained in section \ref{sec:PauseModes}.

To finish, just Ctrl-c and it will close all channels opened to communicate to
the remote hosts. 

\subsection{Dependencies for SSH tailing}
It is very important to note that for remote tailing, you'll need to install
the \textbf{paramiko module}, available in major Linux distributions. In most
of them is available under the name of python-paramiko. In Debian systems,
you'll need to type:
\begin{cmd}
 sudo apt-get install python-paramiko
\end{cmd}

\section{Configuration file}
Config file is provided fully documented for convenience; just uncomment those
lines you are interested to enable and modify them for your specific purposes.
In order to enable those values in the config file, you must notify that to
\logftailer{} as a parameter in startup time.

\begin{cmd}
 ./log4tail -c yourconfig.txt logs
\end{cmd}
If you always use the same configuration file, you can copy it in your HOME
directory as \emph{.log4tailer} and log4tail will read it next time you execute
the program, even if you don't provide the -c option.

The config file provided for convenience is called log4tailerconfig.txt and is quoted below:

\begin{verbatim}

# Optional config for log4tailer
# to activate it
# log4tail -c config yourlogs

# ====================================================
# Custom colours for every level. Available 
# colours are: red, green, yellow, blue, magenta, cyan 
# and white. Uncomment to override the default ones.
# ====================================================

# warn = yellow, on_cyan
# error = magenta 
# fatal = red, on_green
# info = green
# debug = black

# ================================
# targets: which lines do you want 
# to emphasize by using regexes
# uncomment and provide your values.
# ================================

# targets fullpathToLog0 = regex0 : color0; regex1 : color1;..; regexN : colorN
# targets fullpathToLog1 = regex0 : color0; regex1 : color1;..; regexN : colorN

# ======================================================
# Every log with its own color scheme, overriding colors 
# for every level.
# ======================================================

# /path/to/log0 = yellow
# /path/to/log1 = red

# ======================================================
# Pause the output by the number of seconds specified if 
# a level or target has been found. Uncomment the ones 
# you want. The value can be any number in seconds. 
# ======================================================

# pausedebug = 4
# pauseinfo = 2
# pausewarn = 1
# pauseerror = 1
# pausefatal = 1
# pausetarget = 1

# ======================================================
# Mail details 
# ======================================================

# mail_username = yourhostusername
# mail_hostname = mailhostname
# mail_port = 25
# mail_ssl = True or False
# mail_from = any from address
# mail_to = alerts will be sent in the address you specify in here

# ===================================================================
# executor notification
# ===================================================================

# executor = program command1 command2 %s %s
# executor = program command1 command2 

# ===================================================================
# poster notification
# ===================================================================

# server_url = url to the server
# server_port = port
# server_service_uri = /where/go/notifications
# server_service_register_uri = /register/log4tailer/toserver
# server_service_unregister_uri = /unregister/log4tailer/fromserver

# ===================================================================
# Inactivity notification, by email or stdout.
# Possible values can be "mail" or "print". By default is "print".
# ===================================================================

# inactivitynotification = mail

# ===================================================================
# PrintShot notification
# ===================================================================

# screenshot = fullpathtopicture.png

# ====================================================================
# Analytics notification. You can make log4tailer send you 
# a report every analyticsgaptime seconds. By default it will be 
# printed out once finished. Uncomment analyticsnotification to 
# report by email or to a file. Another possible value can be "print".
# ====================================================================

# analyticsnotification = mail
# analyticsnotification = fullPathToaFile
# analyticsgaptime = 10.5

# ==============================
# SSH Tailing parameters
# ==============================

# sshhostnames = hostname0, hostname1, hostnameN-1
# hostname0 = username0, /var/log/log0, /var/log/log1, /var/log/logN-1
# hostname1 = username1, /var/log/log0, /var/log/log1, /var/log/logN-1
# hostnameN-1 = usernameN-1, /var/log/log0, /var/log/log1, /var/log/logN-1

# rsa_key defaults to ~/.ssh/id_rsa, if that's not your case then 
# provide yours

# rsa_key = fullpathToRsaKeyName 


\end{verbatim}

\newpage