logging

Documentation

Overview

Package logging is a "parent" package for gRPC logging middlewares.

The gRPC logging middleware populates request-scoped data to `logging.Fields` that relate to the current gRPC call (e.g. service and method names). You can extract/inject data in the propagated context using `logging.ExtractFields` and `logging.InjectFields`.

Once the gRPC logging middleware has added the gRPC specific Fields to the ctx they will then be written with the log lines.

All logging middleware will emit a final log statement. It is based on the error returned by the handler function, the gRPC status code, an error (if any) and it emits at a level controlled via `WithLevels`. You can control this behavior using `WithDecider`.

This parent package

This particular package is intended for use by other middleware, logging or otherwise. It contains interfaces that other logging middlewares *could* share. This allows code to be shared between different implementations.

Field names

All field names of loggers follow the OpenTracing semantics definitions, with `grpc.` prefix if needed: https://github.com/opentracing/specification/blob/master/semantic_conventions.md

Implementations:

* providers/logrus * providers/zap * providers/kit * providers/zerolog * providers/phuslog * providers/logr

Index

• Constants
• Variables
• func DefaultErrorToCode(err error) codes.Code
• func InjectFields(ctx context.Context, f Fields) context.Context
• func PayloadStreamClientInterceptor(logger Logger, decider ClientPayloadLoggingDecider, timestampFormat string) grpc.StreamClientInterceptor
• func PayloadStreamServerInterceptor(logger Logger, decider ServerPayloadLoggingDecider, timestampFormat string) grpc.StreamServerInterceptor
• func PayloadUnaryClientInterceptor(logger Logger, decider ClientPayloadLoggingDecider, timestampFormat string) grpc.UnaryClientInterceptor
• func PayloadUnaryServerInterceptor(logger Logger, decider ServerPayloadLoggingDecider, timestampFormat string) grpc.UnaryServerInterceptor
• func StreamClientInterceptor(logger Logger, opts ...Option) grpc.StreamClientInterceptor
• func StreamServerInterceptor(logger Logger, opts ...Option) grpc.StreamServerInterceptor
• func UnaryClientInterceptor(logger Logger, opts ...Option) grpc.UnaryClientInterceptor
• func UnaryServerInterceptor(logger Logger, opts ...Option) grpc.UnaryServerInterceptor
• type ClientPayloadLoggingDecider
• type CodeToLevel
• type Decider
• type Decision
  • func DefaultDeciderMethod(_ string, _ error) Decision
• type DurationToFields
• type ErrorToCode
• type Fields
  • func DurationToDurationField(duration time.Duration) Fields
  • func DurationToTimeMillisFields(duration time.Duration) Fields
  • func ExtractFields(ctx context.Context) Fields
  • func (f Fields) AppendUnique(add Fields) Fields
  • func (f Fields) Iter() FieldsIterator
• type FieldsIterator
• type JsonPBMarshaler
• type Level
  • func DefaultClientCodeToLevel(code codes.Code) Level
  • func DefaultServerCodeToLevel(code codes.Code) Level
• type Logger
• type Option
  • func WithCodes(f ErrorToCode) Option
  • func WithDecider(f Decider) Option
  • func WithDurationField(f DurationToFields) Option
  • func WithLevels(f CodeToLevel) Option
  • func WithTimestampFormat(format string) Option
• type PayloadDecision
• type ServerPayloadLoggingDecider

Constants

const (
	DEBUG   = Level("debug")
	INFO    = Level("info")
	WARNING = Level("warning")
	ERROR   = Level("error")
)

Variables

var (
	// SystemTag is tag representing an event inside gRPC call.
	SystemTag = []string{"protocol", "grpc"}
	// ComponentFieldKey is a tag representing the client/server that is calling.
	ComponentFieldKey    = "grpc.component"
	KindServerFieldValue = "server"
	KindClientFieldValue = "client"
	ServiceFieldKey      = "grpc.service"
	MethodFieldKey       = "grpc.method"
	MethodTypeFieldKey   = "grpc.method_type"
)

var DefaultDurationToFields = DurationToTimeMillisFields

DefaultDurationToFields is the default implementation of converting request duration to a field.

Functions

func DefaultErrorToCode

func DefaultErrorToCode(err error) codes.Code

func InjectFields

func InjectFields(ctx context.Context, f Fields) context.Context

InjectFields allows adding Fields to any existing Fields that will be used by the logging interceptor.

func PayloadStreamClientInterceptor

func PayloadStreamClientInterceptor(logger Logger, decider ClientPayloadLoggingDecider,
	timestampFormat string) grpc.StreamClientInterceptor

PayloadStreamClientInterceptor returns a new streaming client interceptor that logs the paylods of requests and responses on INFO level. Logger tags will be used from tags context.

func PayloadStreamServerInterceptor

func PayloadStreamServerInterceptor(logger Logger, decider ServerPayloadLoggingDecider,
	timestampFormat string) grpc.StreamServerInterceptor

PayloadStreamServerInterceptor returns a new server interceptors that logs the payloads of requests on INFO level. Logger tags will be used from tags context.

func PayloadUnaryClientInterceptor

func PayloadUnaryClientInterceptor(logger Logger, decider ClientPayloadLoggingDecider,
	timestampFormat string) grpc.UnaryClientInterceptor

PayloadUnaryClientInterceptor returns a new unary client interceptor that logs the payloads of requests and responses on INFO level. Logger tags will be used from tags context.

func PayloadUnaryServerInterceptor

func PayloadUnaryServerInterceptor(logger Logger, decider ServerPayloadLoggingDecider,
	timestampFormat string) grpc.UnaryServerInterceptor

PayloadUnaryServerInterceptor returns a new unary server interceptors that logs the payloads of requests on INFO level. Logger tags will be used from tags context.

func StreamClientInterceptor

func StreamClientInterceptor(logger Logger, opts ...Option) grpc.StreamClientInterceptor

StreamClientInterceptor returns a new streaming client interceptor that optionally logs the execution of external gRPC calls. Logger will read existing and write new logging.Fields available in current context. See `ExtractFields` and `InjectFields` for details.

func StreamServerInterceptor

func StreamServerInterceptor(logger Logger, opts ...Option) grpc.StreamServerInterceptor

StreamServerInterceptor returns a new stream server interceptors that optionally logs endpoint handling. Logger will read existing and write new logging.Fields available in current context. See `ExtractFields` and `InjectFields` for details..

func UnaryClientInterceptor

func UnaryClientInterceptor(logger Logger, opts ...Option) grpc.UnaryClientInterceptor

UnaryClientInterceptor returns a new unary client interceptor that optionally logs the execution of external gRPC calls. Logger will read existing and write new logging.Fields available in current context. See `ExtractFields` and `InjectFields` for details.

func UnaryServerInterceptor

func UnaryServerInterceptor(logger Logger, opts ...Option) grpc.UnaryServerInterceptor

UnaryServerInterceptor returns a new unary server interceptors that optionally logs endpoint handling. Logger will read existing and write new logging.Fields available in current context. See `ExtractFields` and `InjectFields` for details.

Types

type ClientPayloadLoggingDecider

type ClientPayloadLoggingDecider func(ctx context.Context, fullMethodName string) PayloadDecision

ClientPayloadLoggingDecider is a user-provided function for deciding whether to log the client-side request/response payloads

type CodeToLevel

type CodeToLevel func(code codes.Code) Level

CodeToLevel function defines the mapping between gRPC return codes and interceptor log level.

type Decider

type Decider func(fullMethodName string, err error) Decision

Decider function defines rules for suppressing any interceptor logs.

type Decision

type Decision int

Decision defines rules for enabling start and end of logging.

const (
	// NoLogCall - Logging is disabled.
	NoLogCall Decision = iota
	// LogFinishCall - Only finish logs of request is enabled.
	LogFinishCall
	// LogStartAndFinishCall - Logging of start and end of request is enabled.
	LogStartAndFinishCall
)

func DefaultDeciderMethod

func DefaultDeciderMethod(_ string, _ error) Decision

DefaultDeciderMethod is the default implementation of decider to see if you should log the call by default this if always true so all calls are logged.

type DurationToFields

type DurationToFields func(duration time.Duration) Fields

DurationToFields function defines how to produce duration fields for logging.

type ErrorToCode

type ErrorToCode func(err error) codes.Code

ErrorToCode function determines the error code of an error. This makes using custom errors with grpc middleware easier.

type Fields

type Fields []string

Fields represents logging fields. It has to have even number of elements (pairs).

func DurationToDurationField

func DurationToDurationField(duration time.Duration) Fields

DurationToDurationField uses a Duration field to log the request duration and leaves it up to Log's encoder settings to determine how that is output.

func DurationToTimeMillisFields

func DurationToTimeMillisFields(duration time.Duration) Fields

DurationToTimeMillisFields converts the duration to milliseconds and uses the key `grpc.time_ms`.

func ExtractFields

func ExtractFields(ctx context.Context) Fields

ExtractFields returns logging.Fields object from the Context. Logging interceptor adds fields into context when used. If there are no fields in the context, returns an empty Fields value.

It's useful for server implementations to use this method to instantiate request logger for consistent fields (e.g request-id/tracing-id).

func (Fields) AppendUnique

func (f Fields) AppendUnique(add Fields) Fields

AppendUnique returns fields which is the union of all keys. Any keys that already exist in the log fields will take precedence over duplicates in add.

func (Fields) Iter

func (f Fields) Iter() FieldsIterator

Iter returns FieldsIterator.

type FieldsIterator

type FieldsIterator interface {
	Next() bool
	At() (k, v string)
}

FieldsIterator is an interface allowing to iterate over fields.

type JsonPBMarshaler

type JsonPBMarshaler interface {
	Marshal(pb proto.Message) ([]byte, error)
}

JsonPBMarshaler is a marshaler that serializes protobuf messages.

type Level

type Level string

Level represents logging level.

func DefaultClientCodeToLevel

func DefaultClientCodeToLevel(code codes.Code) Level

DefaultClientCodeToLevel is the helper mapper that maps gRPC return codes to log levels for client side.

func DefaultServerCodeToLevel

func DefaultServerCodeToLevel(code codes.Code) Level

DefaultServerCodeToLevel is the helper mapper that maps gRPC return codes to log levels for server side.

type Logger

type Logger interface {
	// Log logs the fields for given log level. We can assume users (middleware library) will put fields in pairs and
	// those will be unique.
	Log(Level, string)
	// With returns Logger with given fields appended. We can assume users (middleware library) will put fields in pairs
	// and those will be unique.
	With(fields ...string) Logger
}

Logger is unified interface that we used for all our interceptors. Official implementations are available under provider/ directory as separate modules.

type Option

type Option func(*options)

func WithCodes

func WithCodes(f ErrorToCode) Option

WithCodes customizes the function for mapping errors to error codes.

func WithDecider

func WithDecider(f Decider) Option

WithDecider customizes the function for deciding if the gRPC interceptor logs should log.

func WithDurationField

func WithDurationField(f DurationToFields) Option

WithDurationField customizes the function for mapping request durations to log fields.

func WithLevels

func WithLevels(f CodeToLevel) Option

WithLevels customizes the function for mapping gRPC return codes and interceptor log level statements.

func WithTimestampFormat

func WithTimestampFormat(format string) Option

WithTimestampFormat customizes the timestamps emitted in the log fields.

type PayloadDecision

type PayloadDecision int

PayloadDecision defines rules for enabling payload logging of request and responses.

const (
	// NoPayloadLogging - Payload logging is disabled.
	NoPayloadLogging PayloadDecision = iota
	// LogPayloadRequest - Only logging of requests is enabled.
	LogPayloadRequest
	// LogPayloadResponse - Only logging of responses is enabled.
	LogPayloadResponse
	// LogPayloadRequestAndResponse - Logging of both requests and responses is enabled.
	LogPayloadRequestAndResponse
)

type ServerPayloadLoggingDecider

type ServerPayloadLoggingDecider func(ctx context.Context, fullMethodName string, servingObject interface{}) PayloadDecision

ServerPayloadLoggingDecider is a user-provided function for deciding whether to log the server-side request/response payloads