Man Linux: Main Page and Category List

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.