http_ctxtags

Documentation

Overview

`http_ctxtags` adds a Tag object to the request's context that identifies it for other wares.

Request Context Tags

Tags describe information about the request, and can be set and used by other middleware. Tags are used for logging and tracing of requests. This extends to both client-side (Tripperware) and server-side (Middleware) libraries.

Service Tags

`http_ctxtags` introduces a concept of services for client-side calls. This makes it easy to identify outbound requests to both internal and external services.

For calling external services a `http_ctx.Tripperware()` will automatically try to guess the service name from the URL, e.g. calling "www.googleapis.com" will yield `googleapis` as service name.

However, for calling internal services, it is recommended to explicitly state the service name by using `WithServiceName("myservice")` and reusing that particular client for all subsequent calls.

Handler Names and Groups

For server-side purposes handlers can be named (e.g. "token_exchange") and placed in a group (e.g. "auth"). This allows easy organisation of HTTP endpoints for logging and monitoring purposes.

See `TagFor*` consts below.

Custom Tags

You can provide a `WithTagExtractor` function that will populate tags server-side and client-side. Each `http.Request` passing through the Tripperware/Middleware will be passed through this function and new tags will be added.

Tags fields are typed, and shallow and should follow the OpenTracing semantics convention (be prefixed with `http.`): https://github.com/opentracing/specification/blob/master/semantic_conventions.md

Index

• Constants
• Variables
• func DefaultServiceNameDetector(req *http.Request) string
• func HandlerName(handlerName string) httpwares.Middleware
• func Middleware(handlerGroupName string, opts ...Option) httpwares.Middleware
• func Tripperware(opts ...Option) httpwares.Tripperware
• type Option
  • func WithServiceName(serviceName string) Option
  • func WithServiceNameDetector(fn serviceNameDetectorFunc) Option
  • func WithTagExtractor(f RequestTagExtractorFunc) Option
• type RequestTagExtractorFunc
• type Tags
  • func ExtractInbound(req *http.Request) *Tags
  • func ExtractInboundFromCtx(ctx context.Context) *Tags
  • func ExtractOutbound(req *http.Request) *Tags
  • func ExtractOutboundFromCtx(ctx context.Context) *Tags
  • func (t *Tags) Has(key string) bool
  • func (t *Tags) Set(key string, value interface{}) *Tags
  • func (t *Tags) Values() map[string]interface{}

Constants

const (
	// TagForCallService is a string naming the ctxtag identifying a "service" grouping for an http.Request (e.g. "github")
	TagForCallService = "http.call.service"

	// TagForHandlerGroup is a string naming the ctxtag identifying a name of the grouping of http.Handlers (e.g. auth).
	TagForHandlerGroup = "http.handler.group"
	// TagForHandlerName is a string naming the ctxtag identifying a logical name for the http.Handler (e.g. exchange_token).
	TagForHandlerName = "http.handler.name"
)

Variables

var (
	DefaultServiceName = "unspecified"
)

Functions

func DefaultServiceNameDetector

func DefaultServiceNameDetector(req *http.Request) string

DefaultServiceNameDetector is the default detector of services from URLs.

func HandlerName

func HandlerName(handlerName string) httpwares.Middleware

HandlerName is a piece of middleware that is meant to be used right around an htpt.Handler that will tag it with a given service name and method name.

This tag will be used for tracing, logging and monitoring purposes. This *needs* to be set in a chain of Middleware that has `http_ctxtags.Middleware` before it.

func Middleware

func Middleware(handlerGroupName string, opts ...Option) httpwares.Middleware

Middleware returns a http.Handler middleware values for request tags.

handlerGroupName specifies a logical name for a group of handlers.

func Tripperware

func Tripperware(opts ...Option) httpwares.Tripperware

Tripperware returns a new client-side ware that injects tags about the request.

Types

type Option

type Option func(*options)

func WithServiceName

func WithServiceName(serviceName string) Option

WithServiceName is an option for client-side wares that explicitly states the name of the service called.

This option takes precedence over the WithServiceNameDetector values.

For example WithServiceName("github").

func WithServiceNameDetector

func WithServiceNameDetector(fn serviceNameDetectorFunc) Option

WithServiceNameDetector allows you to customize the function for automatically detecting the service name from URLs.

By default it uses the `DefaultServiceNameDetector`.

func WithTagExtractor

func WithTagExtractor(f RequestTagExtractorFunc) Option

WithTagExtractor adds another request tag extractor, allowing you to customize what tags get prepopulated from the request.

type RequestTagExtractorFunc

type RequestTagExtractorFunc func(req *http.Request) map[string]interface{}

RequestTagExtractorFunc is a signature of user-customizeable functions for extracting tags from requests.

type Tags

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

Tags is the struct used for storing request tags between Context calls. This object is *not* thread safe, and should be handled only in the context of the request.

func ExtractInbound

func ExtractInbound(req *http.Request) *Tags

ExtractInbound returns a pre-existing Tags object in the request's Context meant for server-side. If the context wasn't set in the Middleware, a no-op Tag storage is returned that will *not* be propagated in context.

func ExtractInboundFromCtx

func ExtractInboundFromCtx(ctx context.Context) *Tags

ExtractInbounfFromCtx returns a pre-existing Tags object in the request's Context. If the context wasn't set in a tag interceptor, a no-op Tag storage is returned that will *not* be propagated in context.

func ExtractOutbound

func ExtractOutbound(req *http.Request) *Tags

ExtractOutbound returns a pre-existing Tags object in the request's Context meant for server-side. If the context wasn't set in the Middleware, a no-op Tag storage is returned that will *not* be propagated in context.

func ExtractOutboundFromCtx

func ExtractOutboundFromCtx(ctx context.Context) *Tags

ExtractInbounfFromCtx returns a pre-existing Tags object in the request's Context. If the context wasn't set in a tag interceptor, a no-op Tag storage is returned that will *not* be propagated in context.

func (*Tags) Has

func (t *Tags) Has(key string) bool

Has checks if the given key exists.

func (*Tags) Set

func (t *Tags) Set(key string, value interface{}) *Tags

Set sets the given key in the metadata tags.

func (*Tags) Values

func (t *Tags) Values() map[string]interface{}

Values returns a map of key to values. Do not modify the underlying map, please use Set instead.