.\" Automatically generated by Podwrapper::Man 1.24.1 (Pod::Simple 3.40)
.\"
.\" 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 "2021-01-20" "nbdkit-1.24.1" "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 3
\& nbdkit \-\-filter=log PLUGIN
\&                     [logfile=FILE | logscript=SCRIPT] [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 to a file
or external script.
.PP
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.
.PP
When using \f(CW\*(C`logfile=FILE\*(C'\fR, logs are written to a log file with the
format described in \*(L"\s-1LOG FILE FORMAT\*(R"\s0 below.
.PP
When using \f(CW\*(C`logscript=SCRIPT\*(C'\fR, logs invoke the external script.  See
\&\*(L"\s-1LOG SCRIPT\*(R"\s0 below.
.PP
An alternative to this filter is simply to run nbdkit with the \fI\-f\fR
and \fI\-v\fR flags which enable verbose debugging to stderr.  This logs
many aspects of nbdkit operation, but requires running nbdkit in the
foreground.  The log filter uses a more parsimonious and more easily
parsable format and works when nbdkit runs in the background.
.SH "PARAMETERS"
.IX Header "PARAMETERS"
\&\f(CW\*(C`logfile\*(C'\fR or \f(CW\*(C`logscript\*(C'\fR or both can be given.  If neither then the
filter is inactive.
.IP "\fBlogfile=\fR\s-1FILE\s0" 4
.IX Item "logfile=FILE"
The file where the log is written.  See \*(L"\s-1LOG FILE FORMAT\*(R"\s0 below.
.IP "\fBlogscript=\fR\s-1SCRIPT\s0" 4
.IX Item "logscript=SCRIPT"
(nbdkit ≥ 1.24)
.Sp
Log lines invoke an external script.  See \*(L"\s-1LOG SCRIPT\*(R"\s0 below.
.IP "\fBlogappend=true\fR" 4
.IX Item "logappend=true"
.PD 0
.IP "\fBlogappend=false\fR" 4
.IX Item "logappend=false"
.PD
(nbdkit ≥ 1.8)
.Sp
This only affects \f(CW\*(C`logfile\*(C'\fR.  If \f(CW\*(C`false\*(C'\fR (the default), if the file
already exists it will be truncated.  If \f(CW\*(C`true\*(C'\fR, the filter appends
to the existing log file.
.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 "LOG FILE FORMAT"
.IX Header "LOG FILE FORMAT"
An example logging session of a client that requests an export list
before performing a single successful read is:
.PP
.Vb 6
\& 2020\-08\-06 02:07:23.080415 ListExports id=1 readonly=0 tls=0 ...
\& 2020\-08\-06 02:07:23.080502 ...ListExports id=1 exports=("") return=0
\& 2020\-08\-06 02:07:23.080712 connection=1 Connect export="" tls=0 size=0x400 write=1 flush=1 rotational=0 trim=1 zero=2 fua=2 extents=1 cache=2 fast_zero=1
\& 2020\-08\-06 02:07:23.080907 connection=1 Read id=1 offset=0x0 count=0x200 ...
\& 2020\-08\-06 02:07:23.080927 connection=1 ...Read id=1 return=0
\& 2020\-08\-06 02:07:23.081255 connection=1 Disconnect transactions=1
.Ve
.PP
All lines start with a timestamp in \f(CW\*(C`YYYY\-MM\-DD HH:MM:ZZ.MS\*(C'\fR format.
.PP
For connected calls, \f(CW\*(C`connection=N\*(C'\fR is present to distinguish
between clients.
.PP
The action follows.  Currently the following actions are logged:
ListExports, Ready, Fork, Preconnect, Connect, Read, Write, Zero,
Trim, Extents, Cache, Flush and Disconnect.
.PP
Some actions are logged across two lines showing the call and return
value.  Because nbdkit handles requests in parallel different requests
may be intermingled.  Use the \f(CW\*(C`id=N\*(C'\fR field for correlation, it is
unique per connection.
.PP
Strings and lists are shell-quoted.
.SH "LOG SCRIPT"
.IX Header "LOG SCRIPT"
If \f(CW\*(C`logscript=SCRIPT\*(C'\fR is given on the command line then log entries
are passed to the external script.
.PP
The script is passed several shell variables:
.ie n .IP "$act" 4
.el .IP "\f(CW$act\fR" 4
.IX Item "$act"
The action name, like \f(CW"Read"\fR, \f(CW"Write"\fR etc.
.ie n .IP "$connection" 4
.el .IP "\f(CW$connection\fR" 4
.IX Item "$connection"
The connection \s-1ID\s0 identifying the client, only for connected calls
like \f(CW"Read"\fR.
.ie n .IP "$error" 4
.el .IP "\f(CW$error\fR" 4
.IX Item "$error"
For messages of type \f(CW"LEAVE"\fR which fail (\f(CW\*(C`$return = \-1\*(C'\fR), this
contains the errno as a string, for example \f(CW"EIO"\fR.
.ie n .IP "$id" 4
.el .IP "\f(CW$id\fR" 4
.IX Item "$id"
The transaction \s-1ID,\s0 used to correlate actions which are split into two
messages \f(CW"ENTER"\fR and \f(CW"LEAVE"\fR.
.ie n .IP "$return" 4
.el .IP "\f(CW$return\fR" 4
.IX Item "$return"
For messages of type \f(CW"LEAVE"\fR this is the return code, usually \f(CW0\fR
for success and \f(CW\*(C`\-1\*(C'\fR if there was an error.
.ie n .IP "$type" 4
.el .IP "\f(CW$type\fR" 4
.IX Item "$type"
The message type: \f(CW"ENTER"\fR, \f(CW"LEAVE"\fR or \f(CW"PRINT"\fR.
.IP "other shell variables" 4
.IX Item "other shell variables"
Other parameters like \f(CW\*(C`offset=N\*(C'\fR are turned into shell variables
\&\f(CW$offset\fR etc.
.PP
Note the return value of the script is ignored.  Log scripts cannot
modify or interrupt request processing.
.SS "Log script examples"
.IX Subsection "Log script examples"
The script:
.PP
.Vb 2
\& nbdkit \-f \-\-filter=log null 10M \e
\&        logscript=\*(Aqecho $connection $type $id $act $offset >&2\*(Aq
.Ve
.PP
might print lines like:
.PP
.Vb 5
\& PRINT Ready
\& 1 ENTER 1 Read 0x0
\& 1 ENTER 2 Write 0x200
\& 1 LEAVE 2 Write
\& 1 LEAVE 1 Read
.Ve
.PP
corresponding to log file lines:
.PP
.Vb 5
\& Ready thread_model=3
\& connection=1 Read id=1 offset=0x0 count=0x200 ...
\& connection=1 Write id=2 offset=0x200 count=0x200 ...
\& connection=1 ...Write id=2
\& connection=1 ...Read id=1
.Ve
.PP
This script will trigger a message when any client reads:
.PP
.Vb 6
\& nbdkit \-f \-\-filter=log memory 10M \e
\&        logscript=\*(Aq
\&            if [ "$act" = "Read" \-a "$type" = "ENTER" ]; then
\&                echo Client is reading $count bytes from $offset >&2
\&            fi
\&        \*(Aq
.Ve
.SH "FILES"
.IX Header "FILES"
.ie n .IP """logfile=FILE"" parameter" 4
.el .IP "\f(CWlogfile=FILE\fR parameter" 4
.IX Item "logfile=FILE parameter"
This filter writes to the file specified by the \f(CW\*(C`logfile=FILE\*(C'\fR
parameter.
.IP "\fI\f(CI$filterdir\fI/nbdkit\-log\-filter.so\fR" 4
.IX Item "$filterdir/nbdkit-log-filter.so"
The filter.
.Sp
Use \f(CW\*(C`nbdkit \-\-dump\-config\*(C'\fR to find the location of \f(CW$filterdir\fR.
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW\*(C`nbdkit\-log\-filter\*(C'\fR first appeared in nbdkit 1.4.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-file\-plugin\fR\|(1),
\&\fBnbdkit\-cow\-filter\fR\|(1),
\&\fBnbdkit\-filter\fR\|(3),
\&\fBnbdkit\-stats\-filter\fR\|(1).
.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