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
connectionCountoption.Changed in version 1.5.0: Added the optional parameter
options.Create a Frame Stream Logger object, to use with
DnstapLogAction()andDnstapLogResponseAction(). 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.
connectionCountcan be used to open multiple connections to the socket, for potential throughput boost.bufferHint=0: unsignedflushTimeout=0: unsignedinputQueueSize=0: unsignedoutputQueueSize=0: unsignedqueueNotifyThreshold=0: unsignedreopenInterval=0: unsignedconnectionCount=1: unsigned
-
newFrameStreamTcpLogger(address[, options])¶ Changed in version 2.0.0: Added
connectionCountoption.Changed in version 1.5.0: Added the optional parameter
options.Create a Frame Stream Logger object, to use with
DnstapLogAction()andDnstapLogResponseAction(). 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.
connectionCountcan be used to open multiple connections to the socket, for potential throughput boost.bufferHint=0: unsignedflushTimeout=0: unsignedinputQueueSize=0: unsignedoutputQueueSize=0: unsignedqueueNotifyThreshold=0: unsignedreopenInterval=0: unsignedconnectionCount=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