logging

Documentation

Overview

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

The gRPC logging middleware populates request-scoped data to `grpc_ctxtags.Tags` that relate to the current gRPC call (e.g. service and method names).

Once the gRPC logging middleware has added the gRPC specific Tags to the ctx they will then be written with the logs that are made using the `ctx_logrus` or `ctx_zap` loggers.

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 emit at a level controlled via `WithLevels`.

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

See relevant packages below.

Index

• Constants
• Variables
• func DefaultErrorToCode(err error) codes.Code
• func PayloadStreamClientInterceptor(logger Logger, decider ClientPayloadLoggingDecider) grpc.StreamClientInterceptor
• func PayloadStreamServerInterceptor(logger Logger, decider ServerPayloadLoggingDecider) grpc.StreamServerInterceptor
• func PayloadUnaryClientInterceptor(logger Logger, decider ClientPayloadLoggingDecider) grpc.UnaryClientInterceptor
• func PayloadUnaryServerInterceptor(logger Logger, decider ServerPayloadLoggingDecider) 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
• 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
• 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 PayloadStreamClientInterceptor

func PayloadStreamClientInterceptor(logger Logger, decider ClientPayloadLoggingDecider) 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) grpc.StreamServerInterceptor

PayloadStreamServerInterceptor returns a new server 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) grpc.UnaryClientInterceptor

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

func PayloadUnaryServerInterceptor

func PayloadUnaryServerInterceptor(logger Logger, decider ServerPayloadLoggingDecider) 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 use all tags (from tags package) available in current context as fields.

func StreamServerInterceptor

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

StreamServerInterceptor returns a new stream server interceptors that optionally logs endpoint handling. Logger will use all tags (from tags package) available in current context as fields.

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 use all tags (from tags package) available in current context as fields.

func UnaryServerInterceptor

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

UnaryServerInterceptor returns a new unary server interceptors that optionally logs endpoint handling. Logger will use all tags (from tags package) available in current context as fields.

Types

type ClientPayloadLoggingDecider

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

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`.

type JsonPbMarshaler

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

JsonPbMarshaller is a marshaller 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 mockLogger 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.

type ServerPayloadLoggingDecider

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

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