NAME
logapp - An application output supervisor.
SYNOPSIS
logapp [option]... application [--logapp_option]... [app.-argument]...
applicationsymlink [--logapp_option]... [application-argument]...
Instead of calling logapp directly you can also create a symlink with
the name of the application pointing to logapp. Logapp will
automatically start the application the name points to. It will also
work if the symlink name is prefixed with log.
DESCRIPTION
Logapp is a wrapper utility that helps supervise the execution of
applications that produce heavy console output (e.g. make, CVS and
Subversion). It does this by logging, trimming, and coloring each line
of the output before displaying it. It can be called instead of the
executable that should be monitored; it then starts the application and
logs all of its console output to a file. The output shown in the
terminal is preprocessed, e.g. to limit the length of printed lines and
to show the stderr output in a different color. It is also possible to
automatically highlight lines that match a certain regular expression.
The output is therefore reduced to the necessary amount, and all
important lines are easy to identify.
OPTIONS
The options provided before the application argument are processed
directly by logapp. Options provided after the application argument are
only parsed if they are prefixed with --logapp_ (long option names
only) otherwise they are passed to the application. If logapp is called
via a symlink all unprefixed options are passed to the application.
Every application usually uses two independent output streams: stdout
for normal output and stderr for errors and important messages. Both of
them are handled independently by logapp, therefore many options are
available for both streams.
Bool options are accepting 1/0 and true/false as value. For long
boolean options the value can be omited, in that case it will be
assumed to be ’true’.
GENERAL OPTIONS
-?, --help
Show a short overview over all available options.
--version
Show version information.
--configfile=FILE
Use a specific configuration file instead of searching the
configuration search paths.
--showconfig
Print the current configuration of logapp and exit before the
application is executed. This can be used this to check if all
configuration options are setup correctly if something doesn’t
work as expected.
--configsection=NAME
Enable a specific section in the configuration file. If this
option is not provided the application name is used as default.
--disable
This disables logapp data handling completely. The application
is still started, but logapp won’t touch the data streams
comming from the application. Neither logging nor output
formating is performed, only the execution time and the exit
state tracked. This is usefull if logapp won’t be able to deal
with expected data correctly, for example when starting curses
based applications. Have a look at --disable_keywords to see how
this option can be enabled automatically.
--disable_keywords=keywordlist
With this option a list of comma separated keywords can be
provided which will cause the --disable to be enabled
automatically if found in the applications option list. This is
usefull if an application usually provides line-based output,
but creates binary data or uses a curses based frontend if
called with a specific parameter. You can also use the
--detectescape option for another way to do this without
disabling the logging functionality.
--detectescape=bool
This option can be used to switch escape-sequence detection on
or off. With escape-sequence detection logapp will automatically
enable char-based stream handling as soon as an escape-sequence
is part of the specific stream. This behavior can be usefull if
you are working with an application that is usually line-based,
but starts other applications which may be using escape
sequences to format the screen. This option will prevent the
terminal from being messed up in that case.
--dumbterm=bool
With this option set to true there will be no terminal output
coloring for stdout and stderr. Normally this option is disabled
and logapp tries to detect "dumb" terminals itself.
--usepty=bool
This option is only available if logapp has been compiled with
PTY support. If PTY support is enabled with this option set to
true, logapp will open a pseudo terminal for stdout. This helps
wenn running logapp with applications that usually need a real
terminal for output. You can disable this option for most line
based applications like make, CVS or Subversion. Other
applications like telnet or picocom may produce strange results
when used without PTY support.
--ptyremovecr=bool
This option is only available if logapp has been compiled with
PTY support. When using a pseudo terminal for getting the
application output you will always get CR-LF line endings, which
is usually not desired when working in UNIX environments. With
this option enabled, logapp will automatically translate all CR-
LF line endings in LF line endings. This option is enabled as
default.
--stdout_blen=bytes
--stderr_blen=bytes
The line buffer size can be adjusted for stdout and stderr
independently with this option. If the value is too small, lines
will be split up if the buffer is full. The default is 2048 byte
which should be big enough for most applications.
--stdout_charbased=bool
--stderr_charbased=bool
If you want to use logapp with applications that do not produce
line based output you can enable this options for stdout and
stderr independently. With this option enabled logapp won’t
expect complete lines and will handle data as it comes in. By
default all single data packets are written to a new line if
this option is enabled, this can be changed with the --alignlog
option. If the result will be usable depends on what kind of
data is generated by the application.
--extended-regexp=bool
If this option is enabled logapp will interpret provided regular
expression patterns as extended regular expressions. The default
is to use basic regular expressions.
LOGGING OPTIONS
This section contains options that affect the logfile.
-l, --logfile=file
This option can be used to change the file that is used for
storing the logged application data. If an empty string is
provided, logging is disabled and no logfile will be created.
The default is that logapp creates a logfile called logapp.log
in the current directory.
-a, --appendlog=bool
This option specifies if the logfile will be truncated or if the
data will be appended to an existing file on logapp startup.
--maxlogsize=kibyte
To limit the maximum size of the logfile you can set this option
to a value between 10 and 4000000 kiBytes. The default is 0
which disables the logfile size limit. There are different ways
implemented how the logfile is limited. Have a look at the
options --logrename and --circularlog to learn more. The default
way is that the extension .old is added to the logfile and a new
logfile is started.
--logrename=bool
This option specifies the behavior when a logfile is to be
truncated. If --logrename is enabled the logfile is renamed. The
new filename will be the same as before with the extionsion
defined with --oldlogext added. The default extension is .old.
This option is used together with the value of --appendlog and
--maxlogsize
--circularlog=bool
If this option is enabled together with a logfile size limit set
with --maxlogsize, the logfile will be used in a circular way.
This means if the maximum size is reached, the file pointer is
set to the beginning of the file and the old content is
overwritten from the beginning. There are tags added to the
logfile to help navigating in the file.
--oldlogext=extension
This defines the extion that is used when logapp is renaming a
logfile. The --logrename option defines if logapp will rename
the file and the default extension is .old.
--locklogfile=bool
With this option active the logfile is locked in order to
prevent it to be overwritten by another task. This is usefull if
otherwise an unreadable mix up of different contents would be
the result. Depending on the value of the --maxaltlogfiles
option another logfile is choosen with the same name and a
number added. Logfile locking is activated by default.
--warnlogfilelock=bool
This options defines if there should be a warning printed to the
console if the choosen logfile is already locked or in other
means not accessible. In this case there will be a message
before the application is started and directly after its
execution where the name of the alternative logfile is
mentioned. This option is enabled by default. Also have a look
at the --printlogname where you can define to always get the
current logfile reported.
--printlogname=bool
This option defines if the name of the used logfile should be
printed after the application has finished its execution. This
option is disabled by default. Also have a look at the
--warnlogfilelock where you can enable/disable a warning if the
logfile name is changed because of a locked logfile.
--maxaltlogfiles=number
This options defines the maximum number that can be added to the
logfile name, if the original file is not accessible. On logapp
startup it will be checked if the currently defined logfile is
writeable, if this is not the case automatically a number is
added to the filename. If the alternative file is also not
accessible this number is increased until a file is writable or
the value of maxaltlogfiles is reached. In the latter case the
application will exit with an error. If a value of 0 is used
only the original logfile name is tried. Also have a look at the
--warnlogfilelock and --printlogname options to define if there
should be messages about the currently used logfile.
--alignlog=bool
This option is used together with --stdout_charbased and
--stderr_charbased and defines if data packets are written to
the logfile as they come or if they are each written to a new
line. The default is that each data packet is written to a new
line, set this option to false to disable it.
--alignlinebreaks=bool
This option is used together with --stdout_charbased and
--stderr_charbased and aligns the lines to the left in the
logfile with regard to prefix and timestamp. This option is
enabled by default.
--jointimeout=time
This option is used together with --stdout_charbased and
--stderr_charbased and defines a ms timeout for joining single
packets to one. This means if for example two chars get written
within the timeout, they are treated as one packet. This is best
used together with --alignlog and --logtime. Use this option if
the data packets have lost their coherency for some reason (e.g.
if the data comes through a serial line). This feature is
disabled by default and can be enabled by setting time to a
value bigger than 0 ms.
-t, --logtime=bool
This option can be enabled to add a ms timestamp to each line of
the logfile. Normally the time since the application start is
used, but this can be changed with the --logreltime option.
--logreltime=bool
If this option is set this to true, the --logreltime option will
use the relative time since the last line for the logged
timestamps.
--logenv=bool
With this option set to true logapp will add a list of all
active environment variables to the logfile. This option is
disabled by default.
-p, --stdout_lineprefix=prefix
-P, --stderr_lineprefix=prefix
To be able to distinguish stdout and stderr output in the
logfile logapp can prefix each line with a string that indicates
if the line belongs to a specific data stream. Those strings can
be changed with this option. The default is that stdout does not
have a prefix and stderr is prefixed with STDERR:.
CONSOLE OUTPUT OPTIONS
This section contains options that affect the visual output on the
console.
--dumpterm=bool
This option disables output coloring. This is usually done
automatically if a dumb terminal is detected.
-s, --print_summary=bool
If this option is set to true, then a short summary will be
printed after the application has terminated. This option is
disabled by default.
-f, --stdout_fgcol=color
-F, --stderr_fgcol=color
This options define the foreground color for the specific data
stream. The value can be one of the entries in the console color
table at the end of this section.
-b, --stdout_bold=bool
-B, --stderr_bold=bool
This options define if the font for the specific data stream
should be printed bold.
-r, --stdout_regexp=regular expression
-R, --stderr_regexp=regular expression
The regular expression that can be defined with this option is
applied to every line of the specific data stream. On a match
the background color changes to the value provided with the
--stdout_regexp_bgcol respectively --stderr_regexp_bgcol option.
--stdout_regexp_bgcol=color
--stderr_regexp_bgcol=color
This options define the background color for the specific data
stream for the case that the appropriate regular expression
provided with --stdout_regexp or --stderr_regexp matches. The
value can be one of the entries in the console color table at
the end of this section.
-c, --stdout_clip=width
-C, --stderr_clip=width
This options define at which column the output should be clipped
for the specific stream to reduce the amount of data written to
the console. If a value of -1 is provided clipping is disabled
for the stream. A value of -2 sets the clipping to the current
console width. It is also possible to use disable and auto
instead of the numeric values. The default is that stdout is
limited to the console width and that clipping is deactivated
for stderr.
Console color table
+---+-------------------+
|# | color |
+---+-------------------+
|-1 | (console) default |
+---+-------------------+
|0 | black |
+---+-------------------+
|1 | red |
+---+-------------------+
|2 | green |
+---+-------------------+
|3 | brown |
+---+-------------------+
|4 | blue |
+---+-------------------+
|5 | magenta |
+---+-------------------+
|6 | cyan |
+---+-------------------+
|7 | white |
+---+-------------------+
COMMAND EXECUTION OPTIONS
This section contains options that configure the execution of commands
on regular expression matches.
--exitonexecfail=BOOL
This option defines if logapp should exit and end the wrapped
application if the return value of an executed command indicates
a failure. As default this option is disabled and logapp ignores
the return state of executed commands.
--preexec=command
The command that can be provided with this option is executed
directly before the application is started. At this time the
header is already written to the logfile and can be parsed by
the command.
--postexec=command
The command that can be provided with this option is executed
directly after the application has exited. At this time the
logfile is already closed for writing so all application output
and the footer are already included and can be processed by the
command.
-e, --stdout_execregexp=regular expression
-E, --stderr_execregexp=regular expression
The regular expression that can be defined with this option is
applied to every line of the specific data stream. On a match
the command provided with the --stdout_execcommand respectively
--stderr_execcomand option is executed. An empty value for this
option disables the regular expression matching.
-x, --stdout_execcommand=command
-X, --stderr_execcommand=command
This option defines the command that is executed an a regular
expression match. The regular expression can be defined
seperately for the stdout and stderr stream with the
--stdout_execregexp respectively --stderr_execregexp option.
REGULAR EXPRESSIONS
Regular expressions are patterns that describe strings. Logapp uses
this patterns to execute actions based on strings found in the data
stream. The implementation is identical to the one that is used by
grep.
Logapp understands the "basic" and "extended" syntax of regular
expressions as defined by POSIX. The default is to use the basic set,
but you can switch to extended patterns with the --extended-regexp
parameter. Please have a look at the grep(1) and regex(7) manpage for
detailed information.
EXAMPLES
String Matches "String"
^String
Matches "String" at the beginning of a line
String$
Matches "String" at the end of a line
^String$
Line contains only "String"
[Ss]tring
Matches "String" or "string"
Str.ng The dot matches all characters, so this matches for example
"String" or "Strong"
Str.*ng
The dot together with star matches any number of characters, so
this matches for example "String" or "Streaming"
^[A-Z] *
Matches any one of the the characters from A to Z at the
beginning of a line followed by zero or any number of spaces
String\|Word
Matches "String" or "Word" when working with basic regular
expressions
String|Word
Matches "String" or "Word" when working with extended regular
expressions
ENVIRONMENT
TERM This variable is checked to see which type of console logapp is
running in. Currently only the value dumb is handled in a
special way — by disabling console colors. If the TERM variable
is missing also a dumb terminal is assumed. The setting can be
overridden by enabling/disabling the dumb terminal mode using
the --dumbterm option.
FILES
~/.logapprc, /etc/logapp.conf, /etc/logapp/logapp.conf
Configuration file locations that are tried if no --configfile
option is provided.
BUGS
See the TODO file included in the source package.
SEE ALSO
grep(1), regex(7)
AUTHOR
Michael Brunner
COPYING
Copyright (C) 2007–2009 Michael Brunner
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the General
Public License for more details.