telemetry

func NewRequestLogger ¶

func NewRequestLogger(
	handler http.Handler,
	granularity time.Duration,
	logger xlog.KeyValueLogger,
	opts ...Option) http.Handler

NewRequestLogger creates a RequestLogger that chains to handler. The logged duration is expressed in units of granularity (e.g. time.Millisecond); a zero or negative granularity logs nanoseconds. It panics if handler is nil and returns handler unchanged (no logging) if logger is nil. The remote address logged is identity.ClientIPFromRequest, which accepts forwarding headers only from configured trusted proxies.

func NewRequestMetrics ¶

func NewRequestMetrics(h http.Handler) http.Handler

NewRequestMetrics wraps h so that every request records metricskey.HTTPReqPerf (latency) and metricskey.HTTPReqByRole (count) labelled by method, status code, route and caller role. No label value is copied from the request, so callers cannot create unbounded series: the uri label is the route template recorded with SetRoute (the restserver Router records its registered path, for example "/v1/users/:id"), or UnknownRoute when no route was recorded; the verb label is the request method when it is a standard net/http method, or OtherMethod; the role label is whatever the identity mapper returned, so it is bounded only if the mapper's roles are.

A NewRequestMetrics nested inside another records nothing: it reports the role of the identity in its request (see identity.FromContext) to the enclosing one, which records the request once. Place one outside identity.NewContextHandler, so that its rejections are counted, and one inside it for the role:

h = telemetry.NewRequestMetrics(h) // reports the role
h = identity.NewContextHandler(h, mapper)
h = telemetry.NewRequestMetrics(h) // records every response

Without a nested handler, or when the request never reached it, the role is the one of the identity in the outer request, which is the guest role when none was stored.

A request whose handler panics is recorded too, with the status already sent (see ResponseCapture) or 500 when none was; the panic, including http.ErrAbortHandler, is not recovered and continues to the server. net/http then aborts the response, so the client of a handler that panicked before sending a status sees no 500; gserver TLS listeners answer it with 500.

func SetRoute ¶ added in v1.0.438

func SetRoute(ctx context.Context, pattern string)

SetRoute records pattern, the registered route template that matched the request (for example "/v1/users/:id"), as the uri label of the metrics recorded by NewRequestMetrics. The restserver Router calls it for every matched route; custom routers behind NewRequestMetrics call it with ctx from the request they dispatch. The pattern must come from the route registration, never from the request, so that the label stays bounded. The last call wins; without an enclosing NewRequestMetrics it is a no-op.

func ShouldSkip ¶ added in v0.24.0

func ShouldSkip(cfg []LoggerSkipPath, path, userAgent string) bool

ShouldSkip reports whether a request for path with the given User-Agent matches any entry in cfg and should therefore not be logged.