Provided by: logapp_0.15-1_amd64 bug

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 omitted, 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  coming  from  the  application.  Neither
              logging  nor  output  formating  is performed, 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 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
              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.  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 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 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 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 --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.

       --dumbterm=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 on a regular expression match. The
              regular expression 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 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 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–2010 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.