Semantic conventions for DNS queries

Status: Development

This document defines semantic conventions to apply when instrumenting DNS queries.

Metrics

Metric: dns.lookup.duration

This metric is optional.

This metric SHOULD be specified with ExplicitBucketBoundaries of [ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ].

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
dns.lookup.duration	Histogram	s	Measures the time taken to perform a DNS lookup.

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
dns.question.name		Required	string	The name being queried. [1]	www.example.com; dot.net
error.type		Conditionally Required if and only if an error has occurred.	string	Describes the error the DNS lookup failed with. [2]	host_not_found; no_recovery; java.net.UnknownHostException

[1] dns.question.name: The name represents the queried domain name as it appears in the DNS query without any additional normalization.

[2] error.type: Instrumentations SHOULD use error code such as one of errors reported by getaddrinfo(Linux or other POSIX systems / Windows) or one reported by the runtime or client library. If error code is not available, the full name of exception type SHOULD be used.

error.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
_OTHER	A fallback error value to be used when the instrumentation doesn’t define a custom value.