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 2.0.0: Added connectionCount option.

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 <https://github.com/farsightsec/fstrm>. 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. connectionCount can be used to open multiple connections to the socket, for potential throughput boost.

  • bufferHint=0: unsigned

  • flushTimeout=0: unsigned

  • inputQueueSize=0: unsigned

  • outputQueueSize=0: unsigned

  • queueNotifyThreshold=0: unsigned

  • reopenInterval=0: unsigned

  • connectionCount=1: unsigned

newFrameStreamTcpLogger(address[, options])

Changed in version 2.0.0: Added connectionCount option.

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 <https://github.com/farsightsec/fstrm>. 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. connectionCount can be used to open multiple connections to the socket, for potential throughput boost.

  • bufferHint=0: unsigned

  • flushTimeout=0: unsigned

  • inputQueueSize=0: unsigned

  • outputQueueSize=0: unsigned

  • queueNotifyThreshold=0: unsigned

  • reopenInterval=0: unsigned

  • connectionCount=1: 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