Structured logging dictionary

This page describes the common entries of the Structured Logging component. Currently these backends are supported:

  • The default text based backend

  • The systemd-journal backend

  • The json backend

The default backend

The default backend uses a text representation of the key-value pairs. A line is constructed by appending all key-value pairs as key="value", separated by spaces. The output is written by passing the resulting text line to the standard error stream and also to syslog if --disable-syslog was not passed on the command-line.

An example line looks like this:

msg="Raised send buffer size" subsystem="setup" level="0" prio="Info" ts="2025-12-29T17:16:17+0100" frontend.address="127.0.0.1:8053" network.send_buffer_size="4194304

  • Key names are not quoted.

  • Values are quoted with double quotes.

  • If a value contains a double quote, it is escaped with a backslash.

  • Backslashes in the value are escaped by prepending a backslash.

The following keys are always present:

Key

Type

Example

Remarks

msg

string

"Raised send buffer size"

Value is the same for all instances of this log entry, together with subsystem it uniquely identifies the log message.

subsystem

string

"setup"

Uniquely identifies the log entry together with the value of msg.

level

number

"0"

The detail level of the log entry. Not actively used currently.

prio

enum

"Notice"

One of Alert=1, Critical=2, Error=3, Warning=4, Notice=5, Info=6, Debug=7.

ts

number

"1697614303.039"

Number of seconds since the Unix epoch, including fractional part.

A log entry can also have zero or more additional key-value pairs. We tried to adhere to OpenTelemetry’s general attributes when possible, or more specific ones like for example dns attributes or http attributes for DNS over HTTPS.

Common keys are:

Key

Type

Example

Remarks

error

string

"No such file or directory"

An error cause.

address

ip address:port

"[::]:5301"

An IP: port combination.

addresses

list of subnets

"127.0.0.0/8 ::ffff:0:0/96"

A list of subnets, space separated.

client.address

ip address:port

"[2001:db8::1]:1234"

Address of the DNS client.

backend.address

ip address:port

"[2001:db8::2]:53"

Address of the downstream backend.

backend.name

string

"my-backend"

Name of the downstream backend, if any.

backend.protocol

string

"DoT"

Protocol used to send DNS queries to the downstream backend.

destination.address

ip address:port

"192.0.2.42:53"

Destination address of a packet (may be more specific than frontend.address, or be the next hop and differ from client.address when the proxy protocol is being used, for example).

dns.question.class

unsigned integer

1

The DNS query class.

dns.question.id

unsigned integer

42

The DNS query ID.

dns.question.name

DNS name

"example.com"

The DNS query name.

dns.question.real_time_sec

integer

1767095038

The time this query was received, as the number of seconds since EPOCH.

dns.question.real_time_nsec

integer

23

Additional nano-seconds for dns.question.real_time_sec, for extra precision.

dns.question.size

unsigned integer

42

Size of the DNS query packet, in bytes.

dns.question.type

unsigned integer

28

The DNS query type.

dns.response.class

unsigned integer

1

The DNS response class.

dns.response.id

unsigned integer

42

The DNS response ID.

dns.response.latency_us

float

180.63

The latency between the query and the response, in microseconds.

dns.response.name

DNS name

"example.com"

The DNS response name.

dns.response.rcode

DNS Response Code

"No Error"

DNS response code

dns.response.size

unsigned integer

42

Size of the DNS response packet, in bytes.

dns.response.type

unsigned integer

28

The DNS response type.

frontend.address

ip address:port

"[::]:53"

Address this frontend is listening on.

frontend.protocol

string

"DoQ"

Protocol this frontend is accepting DNS queries over.

http.method

string

"GET"

HTTP/2 query method for DoH.

http.path

string

"/dns-query"

HTTP/2 query path for DoH.

http.response.status_code

HTTP status code

"200"

HTTP/2 response code for DoH.

http.stream_id

HTTP stream ID

"4242"

HTTP/2 stream identifier for DoH.

network.local.address

string

"192.0.2.2:53"

Local address and port DNSdist is listening on (webserver, console, …).

network.peer.address

string

"192.0.2.2:53"

Peer address of the network connection (may differ from client.address when the proxy protocol is used, for example).

path

filesystem path

"tmp/api-dir/apizones"

pool

string

"my-pool"

Downstream backends pool name.

protocol

string

"udp"

The systemd-journal backend

The systemd-journal structured logging backend uses mostly the same keys and values as the default backend, with the exceptions:

  • keys are capitalized as required for systemd-journal.

  • msg is translated to MESSAGE.

  • prio is translated to PRIORITY.

  • ts is translated to TIMESTAMP.

  • If the original key is in a list of keys special to systemd-journal, it is capitalized and prepended by PDNS_. The list of special keys is: message, message_id, priority, code_file, code_line, code_func, errno, invocation_id, user_invocation_id, syslog_facility, syslog_identifier, syslog_pid, syslog_timestamp, syslog_raw, documentation, tid, unit, user_unit, object_pid.

To use this logging backend, add the --structured-logging-backend systemd-journal to the command line in the systemd unit file.

To query the log, use a command similar to:

# journalctl -r -n 1 -o json-pretty -u dnsdist.service

The json backend

The json structured logging backend uses the same keys and values as the default backend. An example of a log object:

{"level": "0", "msg": "Adding TCP worker thread to handle TCP connections from clients", "priority": "6", "ts": "2025-12-29T17:20:20+0100"}

All values are represented as strings.

The JSON log objects are written to the standard error stream.