.\" Automatically generated by Podwrapper::Man 1.10.3 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-log-filter 1"
.TH nbdkit-log-filter 1 "2019-01-26" "nbdkit-1.10.3" "NBDKIT"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
nbdkit\-log\-filter \- nbdkit log filter
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& nbdkit \-\-filter=log plugin logfile=FILE [logappend=BOOL] [plugin\-args...]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`nbdkit\-log\-filter\*(C'\fR 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 \s-1FILES\s0.  Note that
using \f(CW\*(C`nbdkit \-v \-f\*(C'\fR 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.
.SH "PARAMETERS"
.IX Header "PARAMETERS"
The nbdkit-log-filter requires a single parameter \f(CW\*(C`logfile\*(C'\fR which
specifies the path of the file to use for logging.  If the file
already exists, it will be truncated unless the \f(CW\*(C`logappend\*(C'\fR parameter
was specified with a value that can be parsed as a boolean true.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Serve the file \fIdisk.img\fR, and log each client transaction in the
file \fIdisk.log\fR:
.PP
.Vb 1
\& nbdkit \-\-filter=log file disk.img logfile=disk.log
.Ve
.PP
Repeat the task, but with the cow (copy-on-write) filter to perform
local caching of data served from the original plugin:
.PP
.Vb 1
\& nbdkit \-\-filter=cow \-\-filter=log file disk.img logfile=disk.log2
.Ve
.PP
After running a client that performs the same operations under each of
the two servers, you can compare \fIdisk.log\fR and \fIdisk.log2\fR to see
the impact of the caching.
.SH "FILES"
.IX Header "FILES"
This filter writes to the file specified by the \f(CW\*(C`logfile=FILE\*(C'\fR
parameter.  All lines include a timestamp, a connection counter, then
details about the command.  The following actions are logged: Connect,
Read, Write, Zero, Trim, 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).
.PP
An example logging session of a client that performs a single
successful read is:
.PP
.Vb 4
\& 2018\-01\-27 20:38:22.959984 connection=1 Connect size=0x400 write=1 flush=1 rotational=0 trim=0 zero=1 fua=1
\& 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
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-file\-plugin\fR\|(1),
\&\fBnbdkit\-cow\-filter\fR\|(1),
\&\fBnbdkit\-filter\fR\|(3).
.SH "AUTHORS"
.IX Header "AUTHORS"
Eric Blake
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2018 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP "\(bu" 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP "\(bu" 4
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.
.IP "\(bu" 4
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.
.PP
\&\s-1THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS\s0 ''\s-1AS IS\s0'' \s-1AND
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\s0 (\s-1INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF
USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.\s0