nbdkit-log-filter - Man Page

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

logfile=FILE

The file where the log is written.  This parameter is required.

logappend=true
logappend=false

(nbdkit ≥ 1.8)

When set to false (the default), if the file already exists it will be truncated.  When set to true, the filter appends to the existing file.

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

License

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

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.

Referenced By

nbdkit(1), nbdkit-filter(3), nbdkit-fua-filter(1), nbdkit-release-notes-1.4(1), nbdkit-release-notes-1.8(1), nbdkit-stats-filter(1).

2020-06-29 nbdkit-1.21.13