Ubuntu Manpage: logapp - An application output supervisor.

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 point‐
       ing 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 col‐
       or.  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 on‐
ly) otherwise they are passed to the application. If logapp is called via a symlink all unprefixed op‐
tions 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 omit‐
ted, 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 applica‐
tion 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 coming from the application. Neither logging nor output formating is per‐
formed, only the execution time and the exit state tracked. This is useful 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 useful if an appli‐
cation 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 detec‐
tion logapp will automatically enable char-based stream handling as soon as an escape-sequence is
part of the specific stream. This behavior can be useful 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. Nor‐
mally 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 en‐
abled 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 usu‐
ally not desired when working in UNIX environments. With this option enabled, logapp will automat‐
ically 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 ex‐
isting 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 imple‐
mented 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 extension 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 de‐
fines 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 useful if otherwise an unreadable mix up of different contents would be the result.
Depending on the value of the --maxaltlogfiles option another logfile is chosen 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 chosen 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 --warnlogfile‐
lock 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 alter‐
native 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 --warnlogfile‐
lock 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 de‐
fault 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 time‐
out 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.

--dumbterm=bool
This option disables output coloring. This is usually done automatically if a dumb terminal is de‐
tected.

-s, --print_summary=bool
If this option is set to true, then a short summary will be printed after the application has ter‐
minated. 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 spe‐
cific data stream. On a match the background color changes to the value provided with the --std‐
out_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 appro‐
priate 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 com‐
mand.

--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 spe‐
cific 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 ex‐
pression matching.

-x, --stdout_execcommand=command

-X, --stderr_execcommand=command
This option defines the command that is executed on a regular expression match. The regular ex‐
pression can be defined separately 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 de‐
       fault is to use the basic set, but you can switch to extended patterns with the --extended-regexp parame‐
       ter. 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 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.

AUTHOR

       Michael Brunner

COPYING

       Copyright (C) 2007–2011 Michael Brunner

       This program is free software; you can redistribute it and/or modify it under the terms of the GNU Gener‐
       al  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 Li‐
       cense for more details.

logapp 0.16svn                                    January 2011                                         logapp(1)