httptrace

Documentation

Overview

Package httptrace provides functionalities to trace HTTP requests that are commonly required and used across contrib/** integrations.

Index

• Constants
• func BeforeHandle(cfg *ServeConfig, w http.ResponseWriter, r *http.Request) (http.ResponseWriter, *http.Request, func(), bool)
• func FinishRequestSpan(s tracer.Span, status int, errorFn func(int) bool, opts ...tracer.FinishOption)
• func GetErrorCodesFromInput(s string) func(statusCode int) bool
• func HeaderTagsFromRequest(req *http.Request, headerCfg *internal.LockMap) ddtrace.StartSpanOption
• func QueryStringRegexp() *regexp.Regexp
• func ResetCfg()
• func ResetStatusCode(w http.ResponseWriter)
• func UrlFromRequest(r *http.Request, queryString bool) string
• type FinishSpanFunc
  • func StartRequestSpan(r *http.Request, opts ...ddtrace.StartSpanOption) (tracer.Span, context.Context, FinishSpanFunc)
• type ServeConfig

Constants

const (
	// ProxyHeaderSystem is the header used to indicate the source of the
	// proxy. In the case of AWS API Gateway, the value of this header
	// will always be 'aws-apigateway'.
	ProxyHeaderSystem = "X-Dd-Proxy"

	// ProxyHeaderStartTimeMs is the header used to indicate the start time
	// of the request in milliseconds. This value corresponds to the
	// 'context.requestTimeEpoch' in AWS API Gateway, providing a timestamp
	// for when the request was initiated.
	ProxyHeaderStartTimeMs = "X-Dd-Proxy-Request-Time-Ms"

	// ProxyHeaderPath is the header used to indicate the path of the
	// request. This value corresponds to 'context.path' in AWS API Gateway,
	// and helps identify the resource that the request is targeting.
	ProxyHeaderPath = "X-Dd-Proxy-Path"

	// ProxyHeaderHttpMethod is the header used to indicate the HTTP method
	// of the request (e.g., GET, POST, PUT, DELETE). This value corresponds
	// to 'context.httpMethod' in AWS API Gateway, and provides the method
	// used to make the request.
	ProxyHeaderHttpMethod = "X-Dd-Proxy-Httpmethod"

	// ProxyHeaderDomain is the header used to indicate the AWS domain name
	// handling the request. This value corresponds to 'context.domainName'
	// in AWS API Gateway, which represents the custom domain associated
	// with the API Gateway.
	ProxyHeaderDomain = "X-Dd-Proxy-Domain-Name"

	// ProxyHeaderStage is the header used to indicate the AWS stage name
	// for the API request. This value corresponds to 'context.stage' in
	// AWS API Gateway, and provides the stage (e.g., dev, prod, etc.)
	// in which the request is being processed.
	ProxyHeaderStage = "X-Dd-Proxy-Stage"
)

These constants are intended to be used by tracers to extract and infer parent span information for distributed tracing systems.

const (

	// EnvQueryStringRegexp is the name of the env var used to specify the regexp to use for query string obfuscation.
	EnvQueryStringRegexp = "DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP"
)

The env vars described below are used to configure the http security tags collection. See https://docs.datadoghq.com/tracing/setup_overview/configure_data_security to learn how to use those properly.

Functions

func BeforeHandle

func BeforeHandle(cfg *ServeConfig, w http.ResponseWriter, r *http.Request) (http.ResponseWriter, *http.Request, func(), bool)

BeforeHandle contains functionality that should be executed before a http.Handler runs. It returns the "traced" http.ResponseWriter and http.Request, an additional afterHandle function that should be executed after the Handler runs, and a handled bool that instructs if the request has been handled or not - in case it was handled, the original handler should not run.

func FinishRequestSpan

func FinishRequestSpan(s tracer.Span, status int, errorFn func(int) bool, opts ...tracer.FinishOption)

FinishRequestSpan finishes the given HTTP request span and sets the expected response-related tags such as the status code. If not nil, errorFn will override the isStatusError method on httptrace for determining error codes. Any further span finish option can be added with opts.

func GetErrorCodesFromInput

func GetErrorCodesFromInput(s string) func(statusCode int) bool

GetErrorCodesFromInput parses a comma-separated string s to determine which codes are to be considered errors Its purpose is to support the DD_TRACE_HTTP_SERVER_ERROR_STATUSES env var If error condition cannot be determined from s, `nil` is returned e.g, input of "100,200,300-400" returns a function that returns true on 100, 200, and all values between 300-400, inclusive any input that cannot be translated to integer values returns nil

func HeaderTagsFromRequest

func HeaderTagsFromRequest(req *http.Request, headerCfg *internal.LockMap) ddtrace.StartSpanOption

HeaderTagsFromRequest matches req headers to user-defined list of header tags and creates span tags based on the header tag target and the req header value

func QueryStringRegexp

func QueryStringRegexp() *regexp.Regexp

func ResetCfg

func ResetCfg()

ResetCfg sets local variable cfg back to its defaults (mainly useful for testing)

func ResetStatusCode

func ResetStatusCode(w http.ResponseWriter)

ResetStatusCode resets the status code of the response writer.

func UrlFromRequest

func UrlFromRequest(r *http.Request, queryString bool) string

UrlFromRequest returns the full URL from the HTTP request. If queryString is true, params are collected and they are obfuscated either by the default query string obfuscator or the custom obfuscator provided by the user (through DD_TRACE_OBFUSCATION_QUERY_STRING_REGEXP) See https://docs.datadoghq.com/tracing/configure_data_security/?tab=net#redact-query-strings for more information.

Types

type FinishSpanFunc

type FinishSpanFunc = func(status int, errorFn func(int) bool, opts ...tracer.FinishOption)

func StartRequestSpan

func StartRequestSpan(r *http.Request, opts ...ddtrace.StartSpanOption) (tracer.Span, context.Context, FinishSpanFunc)

StartRequestSpan starts an HTTP request span with the standard list of HTTP request span tags (http.method, http.url, http.useragent). Any further span start option can be added with opts.

type ServeConfig

type ServeConfig struct {
	// Service specifies the service name to use. If left blank, the global service name
	// will be inherited.
	Service string
	// Resource optionally specifies the resource name for this request.
	Resource string
	// QueryParams should be true in order to append the URL query values to the  "http.url" tag.
	QueryParams bool
	// Route is the request matched route if any, or is empty otherwise
	Route string
	// RouteParams specifies framework-specific route parameters (e.g. for route /user/:id coming
	// in as /user/123 we'll have {"id": "123"}). This field is optional and is used for monitoring
	// by AppSec. It is only taken into account when AppSec is enabled.
	RouteParams map[string]string
	// FinishOpts specifies any options to be used when finishing the request span.
	FinishOpts []ddtrace.FinishOption
	// SpanOpts specifies any options to be applied to the request starting span.
	SpanOpts []ddtrace.StartSpanOption
	// isStatusError allows customization of error code determination.
	IsStatusError func(int) bool
}

ServeConfig specifies the tracing configuration when using TraceAndServe.