nbdkit-log-filter(1)

📦
version 1.48.1 · 14 versions
, in fedora 44

💖 nbdkit-log-filter — the nbdkit log filter 💖

hii bestie, welcome to nbdkit-log-filter(1), straight out of the nbdkit manual (section 1, obvs). this is the little filter that ✨logs everything✨. let's get into it.

✨ NAME ✨

nbdkit-log-filter — the nbdkit log filter. that's it, that's the whole vibe.

🌸 SYNOPSIS 🌸

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

🦋 DESCRIPTION 🦋

okay so nbdkit-log-filter is a filter that logs all the transactions to a file or to an external script. like, every single one. it's giving surveillance but make it wholesome 💅.

Where you put it in the filter chain matters, and that's the fun part:

  • when you use it as the first filter, it shows you the original client requests.
  • as a later filter, it shows you how the earlier filters have modified the original request.

When you use logfile=FILE, the logs get written to a log file in the format described down in LOG FILE FORMAT below.

When you use logscript=SCRIPT, the logs invoke the external script. see LOG SCRIPT below for the tea.

An alternative to this whole filter is to just run nbdkit with the -f and -v flags, which enable verbose debugging to stderr. that logs many aspects of nbdkit operation, ngl — but it requires running nbdkit in the foreground 🙈. the log filter uses a more parsimonious and more easily parsable format, and it works even when nbdkit runs in the background. so like... pick your fighter.

🎀 PARAMETERS 🎀

logfile or logscript or both can be given. if neither is given, then the filter is just... inactive. sitting there. not logging. a vibe check that failed 💀.

  • logfile=FILE — the file where the log is written. peek LOG FILE FORMAT below for the whole format situation.
  • logscript=SCRIPT — (nbdkit ≥ 1.24) log lines invoke an external script. see LOG SCRIPT below, bestie.
  • logappend=true
  • logappend=false — (nbdkit ≥ 1.8) this only affects logfile. if it's false (which is the default), and the file already exists, it will be truncated 😭. if it's true, the filter appends to the existing log file. no cap.

🌈 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. it's literally a side-by-side glow-up comparison, obsessed 😌.

💜 LOG FILE FORMAT 💜

An example logging session of a client that requests an export list before performing a single successful read is:

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 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
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

All lines start with a timestamp in YYYY-MM-DD HH:MM:ZZ.MS format. yes, with milliseconds, she's precise like that ⏱️.

For connected calls, connection=N is present to distinguish between clients. multiple clients, one log, no confusion, we love to see it.

The action follows. Currently the following actions are logged: ListExports, Ready, Fork, Preconnect, Connect, Read, Write, Zero, Trim, Extents, Cache, Flush and Disconnect. that's the full roster 👑.

Some actions are logged across two lines showing the call and the return value. Because nbdkit handles requests in parallel, different requests may be intermingled — like a group chat where everyone talks at once, chaos but functional 🫶. Use the id=N field for correlation, it is unique per connection.

Strings and lists are shell-quoted.

🧚 LOG SCRIPT 🧚

If logscript=SCRIPT is given on the command line then log entries are passed to the external script. your script, your rules, your lil log-goblin ✨.

The script is passed several shell variables:

  • $act — the action name, like Read, Write etc.
  • $connection — the connection ID identifying the client, only for connected calls like Read.
  • $error — for messages of type LEAVE which fail ($return = -1), this contains the errno as a string, for example EIO.
  • $id — the transaction ID, used to correlate actions which are split into two messages ENTER and LEAVE.
  • $return — for messages of type LEAVE this is the return code, usually 0 for success and -1 if there was an error.
  • $type — the message type: ENTER, LEAVE or PRINT.
  • other shell variables — other parameters like offset=N are turned into shell variables $offset etc.
ngl, note that the return value of the script is ignored. Log scripts cannot modify or interrupt request processing. it's a read-only bestie, no backtalk 💀.

🍓 Log script examples 🍓

The script:

nbdkit -f --filter=log null 10M \
       logscript='echo $connection $type $id $act $offset >&2'

might print lines like:

PRINT Ready
1 ENTER 1 Read 0x0
1 ENTER 2 Write 0x200
1 LEAVE 2 Write
1 LEAVE 1 Read

corresponding to log file lines:

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

This script will trigger a message when any client reads:

nbdkit -f --filter=log memory 10M \
       logscript='
           if [ "$act" = "Read" -a "$type" = "ENTER" ]; then
               echo Client is reading $count bytes from $offset >&2
           fi
       '

like, a little notification whenever someone reads. iconic behaviour fr fr 📣.

👑 FILES 👑

  • logfile=FILE parameter — this filter writes to the file specified by the logfile=FILE parameter.
  • $filterdir/nbdkit-log-filter.so — the filter itself. the actual star of the show. use nbdkit --dump-config to find the location of $filterdir. iykyk.

⭐ VERSION ⭐

nbdkit-log-filter first appeared in nbdkit 1.4. a classic, an elder, we respect our elders 🫶.

🌸 SEE ALSO 🌸

nbdkit(1), nbdkit-file-plugin(1), nbdkit-cow-filter(1), nbdkit-filter(3), nbdkit-count-filter(1), nbdkit-stats-filter(1).

the whole friend group, go say hi 💖.

💅 AUTHORS 💅

Eric Blake. thank you for your service 🎀.

Copyright Red Hat.

📜 LICENSE 📜

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

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • 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.
  • 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.
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.

okay bestie that's the whole page, and before you go — this masterpiece is from nbdkit-1.48.1, dated 2026-08-29, and it's page nbdkit-log-filter(1) of the manual. now go log something, slay, periodt 💅✨🦋

📦 where this page comes from