1nbdkit-log-filter(1)                NBDKIT                nbdkit-log-filter(1)
2
3
4

NAME

6       nbdkit-log-filter - nbdkit log filter
7

SYNOPSIS

9        nbdkit --filter=log PLUGIN
10                            [logfile=FILE | logscript=SCRIPT] [logappend=BOOL]
11                            [PLUGIN-ARGS...]
12

DESCRIPTION

14       "nbdkit-log-filter" is a filter that logs all transactions to a file or
15       external script.
16
17       When used as the first filter, it can show the original client
18       requests.  As a later filter, it can show how earlier filters have
19       modified the original request.
20
21       When using "logfile=FILE", logs are written to a log file with the
22       format described in "LOG FILE FORMAT" below.
23
24       When using "logscript=SCRIPT", logs invoke the external script.  See
25       "LOG SCRIPT" below.
26
27       An alternative to this filter is simply to run nbdkit with the -f and
28       -v flags which enable verbose debugging to stderr.  This logs many
29       aspects of nbdkit operation, but requires running nbdkit in the
30       foreground.  The log filter uses a more parsimonious and more easily
31       parsable format and works when nbdkit runs in the background.
32

PARAMETERS

34       "logfile" or "logscript" or both can be given.  If neither then the
35       filter is inactive.
36
37       logfile=FILE
38           The file where the log is written.  See "LOG FILE FORMAT" below.
39
40       logscript=SCRIPT
41           (nbdkit ≥ 1.24)
42
43           Log lines invoke an external script.  See "LOG SCRIPT" below.
44
45       logappend=true
46       logappend=false
47           (nbdkit ≥ 1.8)
48
49           This only affects "logfile".  If "false" (the default), if the file
50           already exists it will be truncated.  If "true", the filter appends
51           to the existing log file.
52

EXAMPLES

54       Serve the file disk.img, and log each client transaction in the file
55       disk.log:
56
57        nbdkit --filter=log file disk.img logfile=disk.log
58
59       Repeat the task, but with the cow (copy-on-write) filter to perform
60       local caching of data served from the original plugin:
61
62        nbdkit --filter=cow --filter=log file disk.img logfile=disk.log2
63
64       After running a client that performs the same operations under each of
65       the two servers, you can compare disk.log and disk.log2 to see the
66       impact of the caching.
67

LOG FILE FORMAT

69       An example logging session of a client that requests an export list
70       before performing a single successful read is:
71
72        2020-08-06 02:07:23.080415 ListExports id=1 readonly=0 tls=0 ...
73        2020-08-06 02:07:23.080502 ...ListExports id=1 exports=("") return=0
74        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
75        2020-08-06 02:07:23.080907 connection=1 Read id=1 offset=0x0 count=0x200 ...
76        2020-08-06 02:07:23.080927 connection=1 ...Read id=1 return=0
77        2020-08-06 02:07:23.081255 connection=1 Disconnect transactions=1
78
79       All lines start with a timestamp in "YYYY-MM-DD HH:MM:ZZ.MS" format.
80
81       For connected calls, "connection=N" is present to distinguish between
82       clients.
83
84       The action follows.  Currently the following actions are logged:
85       ListExports, Ready, Fork, Preconnect, Connect, Read, Write, Zero, Trim,
86       Extents, Cache, Flush and Disconnect.
87
88       Some actions are logged across two lines showing the call and return
89       value.  Because nbdkit handles requests in parallel different requests
90       may be intermingled.  Use the "id=N" field for correlation, it is
91       unique per connection.
92
93       Strings and lists are shell-quoted.
94

LOG SCRIPT

96       If "logscript=SCRIPT" is given on the command line then log entries are
97       passed to the external script.
98
99       The script is passed several shell variables:
100
101       $act
102           The action name, like "Read", "Write" etc.
103
104       $connection
105           The connection ID identifying the client, only for connected calls
106           like "Read".
107
108       $error
109           For messages of type "LEAVE" which fail ("$return = -1"), this
110           contains the errno as a string, for example "EIO".
111
112       $id The transaction ID, used to correlate actions which are split into
113           two messages "ENTER" and "LEAVE".
114
115       $return
116           For messages of type "LEAVE" this is the return code, usually 0 for
117           success and "-1" if there was an error.
118
119       $type
120           The message type: "ENTER", "LEAVE" or "PRINT".
121
122       other shell variables
123           Other parameters like "offset=N" are turned into shell variables
124           $offset etc.
125
126       Note the return value of the script is ignored.  Log scripts cannot
127       modify or interrupt request processing.
128
129   Log script examples
130       The script:
131
132        nbdkit -f --filter=log null 10M \
133               logscript='echo $connection $type $id $act $offset >&2'
134
135       might print lines like:
136
137        PRINT Ready
138        1 ENTER 1 Read 0x0
139        1 ENTER 2 Write 0x200
140        1 LEAVE 2 Write
141        1 LEAVE 1 Read
142
143       corresponding to log file lines:
144
145        Ready thread_model=3
146        connection=1 Read id=1 offset=0x0 count=0x200 ...
147        connection=1 Write id=2 offset=0x200 count=0x200 ...
148        connection=1 ...Write id=2
149        connection=1 ...Read id=1
150
151       This script will trigger a message when any client reads:
152
153        nbdkit -f --filter=log memory 10M \
154               logscript='
155                   if [ "$act" = "Read" -a "$type" = "ENTER" ]; then
156                       echo Client is reading $count bytes from $offset >&2
157                   fi
158               '
159

FILES

161       "logfile=FILE" parameter
162           This filter writes to the file specified by the "logfile=FILE"
163           parameter.
164
165       $filterdir/nbdkit-log-filter.so
166           The filter.
167
168           Use "nbdkit --dump-config" to find the location of $filterdir.
169

VERSION

171       "nbdkit-log-filter" first appeared in nbdkit 1.4.
172

SEE ALSO

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

AUTHORS

178       Eric Blake
179
181       Copyright (C) 2018 Red Hat Inc.
182

LICENSE

184       Redistribution and use in source and binary forms, with or without
185       modification, are permitted provided that the following conditions are
186       met:
187
188       •   Redistributions of source code must retain the above copyright
189           notice, this list of conditions and the following disclaimer.
190
191       •   Redistributions in binary form must reproduce the above copyright
192           notice, this list of conditions and the following disclaimer in the
193           documentation and/or other materials provided with the
194           distribution.
195
196       •   Neither the name of Red Hat nor the names of its contributors may
197           be used to endorse or promote products derived from this software
198           without specific prior written permission.
199
200       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
201       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
202       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
203       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
204       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
205       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
206       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
207       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
208       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
209       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
210       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
211
212
213
214nbdkit-1.28.2                     2021-11-09              nbdkit-log-filter(1)
Impressum