dnstrace

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 14, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

README

dnstrace - dns trace for opentelemetry

Go Test Coverage

dnstrace is a library for OpenTelemetry trace propagation over DNS. It propagates trace context using EDNS0 private-use option code 0xFDE9.

EDNS0_TRACE specification

EDNS0_TRACE is a format for propagating traceparent and tracestate using EDNS0 private-use option code 0xFDE9.

+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|                       OPTION-CODE (0xFDE9)                    |
+---+---+---+---+---+---+---+---|---+---+---+---+---+---+---+---+
|                       OPTION-LENGTH (2byte)                   |
+---+---+---+---+---+---+---+---|---+---+---+---+---+---+---+---+
|          VERSION(1byte)       |       TRACE-FLAGS(1byte)      |
+---+---+---+---+---+---+---+---|---+---+---+---+---+---+---+---+
|                                                               |
|                                                               |
|                                                               |
|                                                               |
|                       TRACE-ID(16 byte)                       |
|                                                               |
|                                                               |
|                                                               |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
|                                                               |
|                                                               |
|                       SPAN-ID(8 byte)                         |
|                                                               |
+---+---+---+---+---+---+---+---|---+---+---+---+---+---+---+---+
|                       TRACE-STATE...                          |
+---+---+---+---+---+---+---+---|---+---+---+---+---+---+---+---+--+
  • : EDNS0 option code
  • : traceparent version
  • : traceparent trace-id
  • : traceparent span-id
  • : traceparent trace-flags
  • : ASCII string for tracestate

traceparent and tracestate follow the Trace Context specification.

Usage

See dnstrace_test.go for details.

Server side
  • Set dns.Server handler to dnstrace.NewHandler wrapping your existing handler.
  • Since context.Context is not passed to ServeDNS, your handler needs to implement ServeDNSWithContext.
  • When a DNS query is received, if EDNS0_TRACE exists, a span is added using the propagator; otherwise, a new span is created.
  • The trace context is available in the context.Context passed to ServeDNSWithContext.
Client side
  • Wrap dns.Client with dnstrace.NewClient.
  • Pass a context.Context containing trace context via ExchangeContext or ExchangeWithConnContext.
  • If the context.Context contains trace context, EDNS0_TRACE is added. If EDNS0_TRACE already exists, it is overwritten.

License

This project is licensed under Apache-2.0. See LICENSE.

Documentation

Overview

SPDX-License-Identifier: Apache-2.0

SPDX-License-Identifier: Apache-2.0

Index

Constants

View Source 
const (
	EDNS0TRACE = 0xFDE9
)

Variables

This section is empty.

Functions

func DNSQuestionType added in v0.2.0 

func DNSQuestionType(val uint16) attribute.KeyValue

func DNSResponseCode added in v0.2.0 

func DNSResponseCode(val int) attribute.KeyValue

func NewHandler 

func NewHandler(operation string, base Handler, opts ...Option) dns.Handler

func SetEDNS0_TRACE 

func SetEDNS0_TRACE(m *dns.Msg, traceOpt *EDNS0_TRACE)

func SetRequestAttributes added in v0.2.0 

func SetRequestAttributes(span trace.Span, m *dns.Msg, serverAddr string, clientAddr string)

func SetResponseAttributes added in v0.2.0 

func SetResponseAttributes(span trace.Span, r *dns.Msg, rtt time.Duration, err error)

func SplitHostPort added in v0.2.0 

func SplitHostPort(addr string) (host string, port int, err error)

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func NewClient 

func NewClient(operation string, base *dns.Client, opts ...Option) *Client

func (*Client) ExchangeContext 

func (c *Client) ExchangeContext(ctx context.Context, m *dns.Msg, a string) (r *dns.Msg, rtt time.Duration, err error)

func (*Client) ExchangeWithConnContext 

func (c *Client) ExchangeWithConnContext(ctx context.Context, m *dns.Msg, conn *dns.Conn) (r *dns.Msg, rtt time.Duration, err error)

type DNSMsgCarrier 

type DNSMsgCarrier struct {
	// contains filtered or unexported fields
}

func NewDNSMsgCarrier 

func NewDNSMsgCarrier(m *dns.Msg) *DNSMsgCarrier

func (*DNSMsgCarrier) Get 

func (c *DNSMsgCarrier) Get(key string) string

func (*DNSMsgCarrier) Keys 

func (c *DNSMsgCarrier) Keys() []string

func (*DNSMsgCarrier) Set 

func (c *DNSMsgCarrier) Set(key string, value string)

type EDNS0_TRACE 

type EDNS0_TRACE struct {
	Version    byte    `json:"version"`
	TraceID    TraceID `json:"trace_id"`
	SpanID     SpanID  `json:"span_id"`
	TraceFlags byte    `json:"trace_flags"`

	Tracestate []byte `json:"tracestate"`
}

func GetEDNS0_TRACE 

func GetEDNS0_TRACE(m *dns.Msg) *EDNS0_TRACE

func (*EDNS0_TRACE) Option 

func (e *EDNS0_TRACE) Option() uint16

func (*EDNS0_TRACE) Traceparent 

func (e *EDNS0_TRACE) Traceparent() string

type Filter added in v0.2.0 

type Filter func(m *dns.Msg) bool

Filter returns true when the message should be skipped from tracing and trace context propagation.

type Handler 

type Handler interface {
	ServeDNSWithContext(ctx context.Context, w dns.ResponseWriter, r *dns.Msg)
}

type Option 

type Option func(*config)

func SetRequestFuncs added in v0.2.0 

func SetRequestFuncs(fns ...RequestFunc) Option

SetRequestFuncs Withs the functions to use for updating the span using the request message before processing is completed.

func SetResponseFuncs added in v0.2.0 

func SetResponseFuncs(fns ...ResponseFunc) Option

SetResponseFuncs Withs the functions to use for updating the span using the response message after processing is completed.

func SetSpanStartOpts added in v0.2.0 

func SetSpanStartOpts(opts ...trace.SpanStartOption) Option

SetSpanStartOpts sets the options to use when starting a span.

func WithFilters added in v0.2.0 

func WithFilters(filters ...Filter) Option

WithFilters appends filters used to skip tracing and trace context propagation for matched messages (filter returns true).

func WithPropagator added in v0.2.0 

func WithPropagator(propagator propagation.TextMapPropagator) Option

WithPropagator sets the propagator to use for extracting and injecting trace context from/to DNS messages.

func WithRequestFuncs added in v0.2.0 

func WithRequestFuncs(f ...RequestFunc) Option

WithRequestFuncs Withs functions to use for updating the span using the request message before processing is completed.

func WithResponseFuncs added in v0.2.0 

func WithResponseFuncs(f ...ResponseFunc) Option

WithResponseFuncs Withs functions to use for updating the span using the response message after processing is completed.

func WithTracer 

func WithTracer(tracer trace.Tracer) Option

WithTracer sets the tracer to use for spans created by the handler.

type RequestFunc added in v0.2.0 

type RequestFunc func(span trace.Span, m *dns.Msg, serverAddr string, clientAddr string)

type ResponseFunc added in v0.2.0 

type ResponseFunc func(span trace.Span, r *dns.Msg, rtt time.Duration, err error)

type SpanID 

type SpanID [8]byte

func (SpanID) String 

func (s SpanID) String() string

type TraceID 

type TraceID [16]byte

func (TraceID) String 

func (t TraceID) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.