sallusthttp

Documentation

Overview

SPDX-FileCopyrightText: 2024 Comcast Cable Communications Management, LLC SPDX-License-Identifier: Apache-2.0

Package sallusthttp provides HTTP request logging and binding loggers to request contexts.

SPDX-FileCopyrightText: 2024 Comcast Cable Communications Management, LLC SPDX-License-Identifier: Apache-2.0

SPDX-FileCopyrightText: 2024 Comcast Cable Communications Management, LLC SPDX-License-Identifier: Apache-2.0

SPDX-FileCopyrightText: 2024 Comcast Cable Communications Management, LLC SPDX-License-Identifier: Apache-2.0

SPDX-FileCopyrightText: 2024 Comcast Cable Communications Management, LLC SPDX-License-Identifier: Apache-2.0

Index

• Constants
• func DefaultFields(r *http.Request, l *zap.Logger) *zap.Logger
• func Get(r *http.Request) *zap.Logger
• func GetDefault(r *http.Request, def *zap.Logger) *zap.Logger
• func Header(headerName, keyName string) sallust.LoggerFunc
• func Method(r *http.Request, f []zap.Field) []zap.Field
• func NewConnStateLogger(logger *zap.Logger, lvl zapcore.Level, fs ...zap.Field) func(net.Conn, http.ConnState)
• func RemoteAddr(r *http.Request, f []zap.Field) []zap.Field
• func RequestInfo(kv []zap.Field, request *http.Request) []zap.Field
• func SetLogger(l *zap.Logger, lf ...sallust.LoggerFunc) func(context.Context, *http.Request) context.Context
• func URI(r *http.Request, f []zap.Field) []zap.Field
• func With(parent *http.Request, logger *zap.Logger, fb ...FieldBuilder) *http.Request
• type Builder
  • func Fields(fb ...FieldBuilder) Builder
  • func Named(name string) Builder
• type Builders
  • func (b *Builders) Add(more ...Builder)
  • func (b *Builders) AddFields(more ...FieldBuilder)
  • func (b Builders) Build(r *http.Request, l *zap.Logger) *zap.Logger
• type FieldBuilder
  • func MethodCustom(key string) FieldBuilder
  • func RemoteAddrCustom(key string) FieldBuilder
  • func URICustom(key string) FieldBuilder
• type Middleware
  • func (m Middleware) Decorate(next http.Handler) http.Handler
  • func (m Middleware) DecorateFunc(next http.HandlerFunc) http.Handler

Constants

const (
	// DefaultMethodKey is the default logging key for an HTTP request method
	DefaultMethodKey = "method"

	// DefaultURIKey is the default logging key for an HTTP request URI
	DefaultURIKey = "uri"

	// DefaultRemoteAddrKey is the default logging key for a request's remote address
	DefaultRemoteAddrKey = "remoteAddr"
)

Functions

func DefaultFields

func DefaultFields(r *http.Request, l *zap.Logger) *zap.Logger

DefaultFields is a Builder that simply appends the basic request fields implemented in this package under their default logging keys

func Get

func Get(r *http.Request) *zap.Logger

Get returns the zap.Logger associated with the given HTTP request

func GetDefault

func GetDefault(r *http.Request, def *zap.Logger) *zap.Logger

GetDefault returns the zap.Logger associated with the request, falling back to the given default if no such logger is found

func Header

func Header(headerName, keyName string) sallust.LoggerFunc

Header returns a logger func that extracts the value of a header and inserts it as the value of a logging key. If the header is not present in the request, a blank string is set as the logging key's value.

func Method

func Method(r *http.Request, f []zap.Field) []zap.Field

Method is a FieldBuilder that adds the request method under the DefaultMethodKey

func NewConnStateLogger

func NewConnStateLogger(logger *zap.Logger, lvl zapcore.Level, fs ...zap.Field) func(net.Conn, http.ConnState)

func RemoteAddr

func RemoteAddr(r *http.Request, f []zap.Field) []zap.Field

RemoteAddr is a FieldBuilder that adds the request's remote address under the DefaultRemoteAddrKey

func RequestInfo

func RequestInfo(kv []zap.Field, request *http.Request) []zap.Field

RequestInfo is a LoggerFunc that adds the request information described by logging keys in this package.

func SetLogger

func SetLogger(l *zap.Logger, lf ...sallust.LoggerFunc) func(context.Context, *http.Request) context.Context

SetLogger produces a zap RequestFunc that inserts a zap Logger into the context. Zero or more LoggerFuncs can be provided to added key/values. Note that nothing is added to the base logger by default. If no LoggerFuncs are supplied, the base Logger is added to the context as is. In particular, RequestInfo must be used to inject the request method, uri, etc.

The base logger must be non-nil. There is no default applied.

The returned function can be used with xcontext.Populate.

func URI

func URI(r *http.Request, f []zap.Field) []zap.Field

URI is a FieldBuilder that adds the request URI under the DefaultURIKey

func With

func With(parent *http.Request, logger *zap.Logger, fb ...FieldBuilder) *http.Request

With associates a zap.Logger with the given request

Types

type Builder

type Builder func(*http.Request, *zap.Logger) *zap.Logger

Builder is a strategy for augmenting a zap.Logger for an HTTP request. A Builder may copy information from the request, or it my inject information from other sources.

func Fields

func Fields(fb ...FieldBuilder) Builder

Fields adapts a sequence of FieldBuilder strategies into a single Builder.

func Named

func Named(name string) Builder

Named returns a Builder that creates a sublogger with the given name. Useful to separate functional HTTP areas, such as different handlers, servers, or packages.

type Builders

type Builders []Builder

Builders represents an aggregation of individual Builder strategies. This slice is mutable, and as such any of the methods that modify the builders slice are not safe for concurrent access.

func (*Builders) Add

func (b *Builders) Add(more ...Builder)

Add appends more Builder strategies to this Builders sequence

func (*Builders) AddFields

func (b *Builders) AddFields(more ...FieldBuilder)

AddFields adds a number of fields under a single Builder

func (Builders) Build

func (b Builders) Build(r *http.Request, l *zap.Logger) *zap.Logger

Build is itself a Builder that simply applies a sequence of strategies in order. This method is safe for concurrent access.

type FieldBuilder

type FieldBuilder func(*http.Request, []zap.Field) []zap.Field

FieldBuilder is a strategy for the special case of building sequences of zap logging fields for an HTTP request. Using this strategy to build up multiple fields at once can be more efficient than multiple calls to zap.Logger.With required by the Builder strategy.

func MethodCustom

func MethodCustom(key string) FieldBuilder

MethodCustom creates a FieldBuilder that adds the request methd under a custom key

func RemoteAddrCustom

func RemoteAddrCustom(key string) FieldBuilder

RemoteAddrCustom creates a FieldBuilder that adds the remote address under a custom key

func URICustom

func URICustom(key string) FieldBuilder

URICustom creates a FieldBuilder that adds the request URI under a custom key

type Middleware

type Middleware struct {
	// Base is the base zap.Logger from which request loggers are derived.
	// If this field is nil, a Nop logger is used instead.
	Base *zap.Logger

	// Builders is the sequence of Builder strategies used to tailor the Base logger
	Builders Builders
}

Middleware is responsible for decorating http.Handler instances with logging information

func (Middleware) Decorate

func (m Middleware) Decorate(next http.Handler) http.Handler

Decorate is a middleware function for augmenting request contexts with loggers. If next is nil, then this function decorates http.DefaultServeMux.

func (Middleware) DecorateFunc

func (m Middleware) DecorateFunc(next http.HandlerFunc) http.Handler

DecorateFunc is syntactic sugar for decorating an HTTP handler function. If the given function is nil, this function decorates http.DefaultServeMux.