dnstap Logging Reference

dnstap is a flexible, structured binary log format for DNS software. Reader implementations in various languages exist.

dnsdist supports dnstap since version 1.3.0.

Canonically, dnstap is sent over a FrameStream socket, either a local AF_UNIX (see newFrameStreamUnixLogger()) or a TCP/IP socket (see newFrameStreamTcpLogger()). As an extension, dnsdist can send raw dnstap protobuf messages over a newRemoteLogger().

To use FrameStream transport, dnsdist must have been built with libfstrm.

newFrameStreamUnixLogger(path[, options])

Changed in version 1.5.0: Added the optional parameter options.

Create a Frame Stream Logger object, to use with DnstapLogAction() and DnstapLogResponseAction(). This version will log to a local AF_UNIX socket.

Parameters:
  • path (string) – A local AF_UNIX socket path. Note that most platforms have a rather short limit on the length.
  • options (table) – A table with key: value pairs with options.

The following options apply to the settings of the framestream library. Refer to the documentation of that library for the default and allowed values for these options, as well as their exact descriptions. For all these options, absence or a zero value has the effect of using the library-provided default value.

  • bufferHint=0: unsigned
  • flushTimeout=0: unsigned
  • inputQueueSize=0: unsigned
  • outputQueueSize=0: unsigned
  • queueNotifyThreshold=0: unsigned
  • reopenInterval=0: unsigned
newFrameStreamTcpLogger(address[, options])

Changed in version 1.5.0: Added the optional parameter options.

Create a Frame Stream Logger object, to use with DnstapLogAction() and DnstapLogResponseAction(). This version will log to a possibly remote TCP socket. Needs tcp_writer support in libfstrm.

Parameters:
  • address (string) – An IP:PORT combination where the logger will connect to.
  • options (table) – A table with key: value pairs with options.

The following options apply to the settings of the framestream library. Refer to the documentation of that library for the default and allowed values for these options, as well as their exact descriptions. For all these options, absence or a zero value has the effect of using the library-provided default value.

  • bufferHint=0: unsigned
  • flushTimeout=0: unsigned
  • inputQueueSize=0: unsigned
  • outputQueueSize=0: unsigned
  • queueNotifyThreshold=0: unsigned
  • reopenInterval=0: unsigned
class DnstapMessage

This object represents a single dnstap message as emitted by dnsdist.

classmethod DnstapMessage:setExtra(extraData)

Sets the dnstap “extra” field.

Parameters:extraData (string) – Extra data stuffed into the dnstap “extra” field.
classmethod DnstapMessage:toDebugString() → string

Return a string containing the content of the message