1nbdkit-log-filter(1) NBDKIT nbdkit-log-filter(1)
2
6 nbdkit-log-filter - nbdkit log filter
7
9 nbdkit --filter=log PLUGIN
10 [logfile=FILE | logscript=SCRIPT] [logappend=BOOL]
11 [PLUGIN-ARGS...]
12
14 "nbdkit-log-filter" is a filter that logs all transactions to a file or
15 external script.
16 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 When using "logfile=FILE", logs are written to a log file with the
22 format described in "LOG FILE FORMAT" below.
23 When using "logscript=SCRIPT", logs invoke the external script. See
25 "LOG SCRIPT" below.
26 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
34 "logfile" or "logscript" or both can be given. If neither then the
35 filter is inactive.
36 logfile=FILE
38 The file where the log is written. See "LOG FILE FORMAT" below.
39 logscript=SCRIPT
41 (nbdkit ≥ 1.24)
42 Log lines invoke an external script. See "LOG SCRIPT" below.
44 logappend=true
46 logappend=false
47 (nbdkit ≥ 1.8)
48 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
54 Serve the file disk.img, and log each client transaction in the file
55 disk.log:
56 nbdkit --filter=log file disk.img logfile=disk.log
58 Repeat the task, but with the cow (copy-on-write) filter to perform
60 local caching of data served from the original plugin:
61 nbdkit --filter=cow --filter=log file disk.img logfile=disk.log2
63 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
69 An example logging session of a client that requests an export list
70 before performing a single successful read is:
71 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 minsize=0x1 prefsize=0x200 maxsize=0xffffffff 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 All lines start with a timestamp in "YYYY-MM-DD HH:MM:ZZ.MS" format.
80 For connected calls, "connection=N" is present to distinguish between
82 clients.
83 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 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 Strings and lists are shell-quoted.
94
96 If "logscript=SCRIPT" is given on the command line then log entries are
97 passed to the external script.
98 The script is passed several shell variables:
100 $act
102 The action name, like "Read", "Write" etc.
103 $connection
105 The connection ID identifying the client, only for connected calls
106 like "Read".
107 $error
109 For messages of type "LEAVE" which fail ("$return = -1"), this
110 contains the errno as a string, for example "EIO".
111 $id The transaction ID, used to correlate actions which are split into
113 two messages "ENTER" and "LEAVE".
114 $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 $type
120 The message type: "ENTER", "LEAVE" or "PRINT".
121 other shell variables
123 Other parameters like "offset=N" are turned into shell variables
124 $offset etc.
125 Note the return value of the script is ignored. Log scripts cannot
127 modify or interrupt request processing.
128 Log script examples
130 The script:
131 nbdkit -f --filter=log null 10M \
133 logscript='echo $connection $type $id $act $offset >&2'
134 might print lines like:
136 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 corresponding to log file lines:
144 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 This script will trigger a message when any client reads:
152 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
161 "logfile=FILE" parameter
162 This filter writes to the file specified by the "logfile=FILE"
163 parameter.
164 $filterdir/nbdkit-log-filter.so
166 The filter.
167 Use "nbdkit --dump-config" to find the location of $filterdir.
169
171 "nbdkit-log-filter" first appeared in nbdkit 1.4.
172
174 nbdkit(1), nbdkit-file-plugin(1), nbdkit-cow-filter(1),
175 nbdkit-filter(3), nbdkit-stats-filter(1).
176
178 Eric Blake
179
181 Copyright (C) 2018 Red Hat Inc.
182
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 • Redistributions of source code must retain the above copyright
189 notice, this list of conditions and the following disclaimer.
190 • 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 • 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 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.
211nbdkit-1.30.7 2022-07-10 nbdkit-log-filter(1)