NAME

       nbdkit-log-filter - nbdkit log filter

SYNOPSIS

        nbdkit --filter=log plugin logfile=FILE [logappend=BOOL] [plugin-args...]

DESCRIPTION

       "nbdkit-log-filter" is a filter that logs all transactions.  When used as the first filter, it can show
       the original client requests; as a later filter, it can show how earlier filters have modified the
       original request.  The log results are placed in a user-specified file; for more details on the log
       format, see FILES.  Note that using "nbdkit -v -f" produces much more verbose logging details to stderr
       about every aspect of nbdkit operation, although this requires running nbdkit in the foreground; while
       the log filter is designed to work even when nbdkit is run as a daemon.

PARAMETERS

       The nbdkit-log-filter requires a single parameter "logfile" which specifies the path of the file to use
       for logging.  If the file already exists, it will be truncated unless the "logappend" parameter was
       specified with a value that can be parsed as a boolean true.

EXAMPLES

       Serve the file disk.img, and log each client transaction in the file disk.log:

        nbdkit --filter=log file disk.img logfile=disk.log

       Repeat the task, but with the cow (copy-on-write) filter to perform local caching of data served from the
       original plugin:

        nbdkit --filter=cow --filter=log file disk.img logfile=disk.log2

       After running a client that performs the same operations under each of the two servers, you can compare
       disk.log and disk.log2 to see the impact of the caching.

FILES

       "logfile=FILE" parameter
           This  filter  writes  to  the  file  specified  by the "logfile=FILE" parameter.  All lines include a
           timestamp, a connection counter, then details about the command.  The following actions  are  logged:
           Connect,  Read,  Write,  Zero,  Trim,  Extents, Cache, Flush, and Disconnect.  Except for Connect and
           Disconnect, an event is logged across two lines for call and return value, to allow tracking duration
           and tracing any parallel  execution,  using  id  for  correlation  (incremented  per  action  on  the
           connection).

           An example logging session of a client that performs a single successful read is:

            2018-01-27 20:38:22.959984 connection=1 Connect size=0x400 write=1 flush=1 rotational=0 trim=0 zero=1 fua=1 extents=1 cache=0 fast_zero=0
            2018-01-27 20:38:23.001720 connection=1 Read id=1 offset=0x0 count=0x100 ...
            2018-01-27 20:38:23.001995 connection=1 ...Read id=1 return=0 (Success)
            2018-01-27 20:38:23.044259 connection=1 Disconnect transactions=1

       $filterdir/nbdkit-log-filter.so
           The filter.

           Use "nbdkit --dump-config" to find the location of $filterdir.

VERSION

       "nbdkit-log-filter" first appeared in nbdkit 1.2.

SEE ALSO

       nbdkit(1), nbdkit-file-plugin(1), nbdkit-cow-filter(1), nbdkit-filter(3), nbdkit-stats-filter(1).

AUTHORS

       Eric Blake

COPYRIGHT

       Copyright (C) 2018 Red Hat Inc.

LICENSE

       Redistribution  and  use in source and binary forms, with or without modification, are permitted provided
       that the following conditions are met:

       •   Redistributions of source code must retain the above copyright notice, this list  of  conditions  and
           the following disclaimer.

       •   Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
           the following disclaimer in the documentation and/or other materials provided with the distribution.

       •   Neither  the  name  of  Red  Hat  nor the names of its contributors may be used to endorse or promote
           products derived from this software without specific prior written permission.

       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS  OR  IMPLIED  WARRANTIES,
       INCLUDING,  BUT  NOT  LIMITED  TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE  FOR  ANY  DIRECT,  INDIRECT,
       INCIDENTAL,  SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
       ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT  LIABILITY,  OR  TORT  (INCLUDING  NEGLIGENCE  OR
       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
       DAMAGE.

nbdkit-1.16.2                                      2020-01-28                               nbdkit-log-filter(1)