grpc_glog

Documentation

Overview

`grpc_logrus` is a gRPC logging middleware backed by Logrus loggers

It accepts a user-configured `logrus.Entry` that will be used for logging completed gRPC calls. The same `logrus.Entry` will be used for logging completed gRPC calls, and be populated into the `context.Context` passed into gRPC handler code.

On calling `StreamServerInterceptor` or `UnaryServerInterceptor` this logging middleware will add gRPC call information to the ctx so that it will be present on subsequent use of the `ctxlogrus` logger.

This package also implements request and response *payload* logging, both for server-side and client-side. These will be logged as structured `jsonpb` fields for every message received/sent (both unary and streaming). For that please use `Payload*Interceptor` functions for that. Please note that the user-provided function that determines whether to log the full request/response payload needs to be written with care, this can significantly slow down gRPC.

If a deadline is present on the gRPC request the grpc.request.deadline tag is populated when the request begins. grpc.request.deadline is a string representing the time (RFC3339) when the current call will expire.

Logrus can also be made as a backend for gRPC library internals. For that use `ReplaceGrpcLogger`.

*Server Interceptor* Below is a JSON formatted example of a log that would be logged by the server interceptor:

{
  "level": "info",					// string  logrus log levels
  "msg": "finished unary call",				// string  log message
  "grpc.code": "OK",					// string  grpc status code
  "grpc.method": "Ping",				// string  method name
  "grpc.service": "mwitkow.testproto.TestService",      // string  full name of the called service
  "grpc.start_time": "2006-01-02T15:04:05Z07:00",       // string  RFC3339 representation of the start time
  "grpc.request.deadline": "2006-01-02T15:04:05Z07:00",   // string  RFC3339 deadline of the current request if supplied
  "grpc.request.value": "something",			// string  value on the request
  "grpc.time_ms": 1.234,				// float32 run time of the call in ms
  "peer.address": {
    "IP": "127.0.0.1",					// string  IP address of calling party
    "Port": 60216,					// int     port call is coming in on
    "Zone": ""						// string  peer zone for caller
  },
  "span.kind": "server",				// string  client | server
  "system": "grpc"					// string

  "custom_field": "custom_value",			// string  user defined field
  "custom_tags.int": 1337,				// int     user defined tag on the ctx
  "custom_tags.string": "something",			// string  user defined tag on the ctx
}

*Payload Interceptor* Below is a JSON formatted example of a log that would be logged by the payload interceptor:

{
  "level": "info",							// string logrus log levels
  "msg": "client request payload logged as grpc.request.content",   	// string log message

  "grpc.request.content": {						// object content of RPC request
    "value": "something",						// string defined by caller
    "sleepTimeMs": 9999							// int    defined by caller
  },
  "grpc.method": "Ping",						// string method being called
  "grpc.service": "mwitkow.testproto.TestService",			// string service being called
  "span.kind": "client",						// string client | server
  "system": "grpc"							// string
}

Note - due to implementation ZAP differs from Logrus in the "grpc.request.content" object by having an inner "msg" object.

Please see examples and tests for examples of use.

Index

• Variables
• func DefaultClientCodeToLevel(code codes.Code) logrus.Level
• func DefaultCodeToLevel(code codes.Code) logrus.Level
• func DurationToDurationField(duration time.Duration) (key string, value interface{})
• func DurationToTimeMillisField(duration time.Duration) (key string, value interface{})
• func GetRawJSON(i interface{}) *bytes.Buffer
• func LogMetadata(log *LogParams, md *metadata.MD) []string
• func LogRequest(log *LogParams, req interface{}, fullMethodString string)
• func LogRequestIP(ctx context.Context) string
• func LogResponse(log *LogParams, resp interface{})
• func LogStatusError(log *LogParams, err error)
• func LogUserAgent(log *LogParams, md *metadata.MD)
• func PayloadStreamClientInterceptor(opts ...Option) grpc.StreamClientInterceptor
• func PayloadStreamServerInterceptor(opts ...Option) grpc.StreamServerInterceptor
• func PayloadUnaryClientInterceptor(opts ...Option) grpc.UnaryClientInterceptor
• func PayloadUnaryServerInterceptor(opts ...Option) grpc.UnaryServerInterceptor
• func StreamClientInterceptor(opts ...Option) grpc.StreamClientInterceptor
• func StreamServerInterceptor(opts ...Option) grpc.StreamServerInterceptor
• func UnaryClientInterceptor(opts ...Option) grpc.UnaryClientInterceptor
• func UnaryServerInterceptor(opts ...Option) grpc.UnaryServerInterceptor
• type CodeToLevel
• type DurationToField
• type LogParams
• type MessageProducer
• type Option
  • func WithLogger(logger glog.ILogger) Option

Variables

var DefaultDurationToField = DurationToTimeMillisField

DefaultDurationToField is the default implementation of converting request duration to a log field (key and value).

var (
	// JsonPbMarshaller is the marshaller used for serializing protobuf messages.
	// If needed, this variable can be reassigned with a different marshaller with the same Marshal() signature.
	JsonPbMarshaller grpc_logger.JsonPbMarshaler = &jsonpb.Marshaler{}
)

var (
	// Marshaller of Protobuf to JSON
	Marshaller = &jsonpb.Marshaler{}
)

Functions

func DefaultClientCodeToLevel

func DefaultClientCodeToLevel(code codes.Code) logrus.Level

DefaultClientCodeToLevel is the default implementation of gRPC return codes to log levels for client side.

func DefaultCodeToLevel

func DefaultCodeToLevel(code codes.Code) logrus.Level

DefaultCodeToLevel is the default implementation of gRPC return codes to log levels for server side.

func DurationToDurationField

func DurationToDurationField(duration time.Duration) (key string, value interface{})

DurationToDurationField uses the duration value to log the request duration.

func DurationToTimeMillisField

func DurationToTimeMillisField(duration time.Duration) (key string, value interface{})

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

func GetRawJSON

func GetRawJSON(i interface{}) *bytes.Buffer

GetRawJSON converts a Protobuf message to JSON bytes if less than MaxSize.

func LogMetadata

func LogMetadata(log *LogParams, md *metadata.MD) []string

func LogRequest

func LogRequest(log *LogParams, req interface{}, fullMethodString string)

func LogRequestIP

func LogRequestIP(ctx context.Context) string

func LogResponse

func LogResponse(log *LogParams, resp interface{})

func LogStatusError

func LogStatusError(log *LogParams, err error)

func LogUserAgent

func LogUserAgent(log *LogParams, md *metadata.MD)

func PayloadStreamClientInterceptor

func PayloadStreamClientInterceptor(opts ...Option) grpc.StreamClientInterceptor

PayloadStreamClientInterceptor returns a new streaming client interceptor that logs the payloads of requests and responses.

func PayloadStreamServerInterceptor

func PayloadStreamServerInterceptor(opts ...Option) grpc.StreamServerInterceptor

PayloadStreamServerInterceptor returns a new server server interceptors that logs the payloads of requests.

This *only* works when placed *after* the `grpc_logrus.StreamServerInterceptor`. However, the logging can be done to a separate instance of the logger.

func PayloadUnaryClientInterceptor

func PayloadUnaryClientInterceptor(opts ...Option) grpc.UnaryClientInterceptor

PayloadUnaryClientInterceptor returns a new unary client interceptor that logs the payloads of requests and responses.

func PayloadUnaryServerInterceptor

func PayloadUnaryServerInterceptor(opts ...Option) grpc.UnaryServerInterceptor

PayloadUnaryServerInterceptor returns a new unary server interceptors that logs the payloads of requests.

This *only* works when placed *after* the `grpc_logrus.UnaryServerInterceptor`. However, the logging can be done to a separate instance of the logger.

func StreamClientInterceptor

func StreamClientInterceptor(opts ...Option) grpc.StreamClientInterceptor

StreamClientInterceptor returns a new streaming client interceptor that optionally logs the execution of external gRPC calls.

func StreamServerInterceptor

func StreamServerInterceptor(opts ...Option) grpc.StreamServerInterceptor

StreamServerInterceptor returns a new streaming server interceptor that adds logrus.Entry to the context.

func UnaryClientInterceptor

func UnaryClientInterceptor(opts ...Option) grpc.UnaryClientInterceptor

UnaryClientInterceptor returns a new unary client interceptor that optionally logs the execution of external gRPC calls.

func UnaryServerInterceptor

func UnaryServerInterceptor(opts ...Option) grpc.UnaryServerInterceptor

UnaryServerInterceptor returns a new unary server interceptors that adds logrus.Entry to the context.

Types

type CodeToLevel

type CodeToLevel func(code codes.Code) logrus.Level

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

type DurationToField

type DurationToField func(duration time.Duration) (key string, value interface{})

DurationToField function defines how to produce duration fields for logging

type LogParams

type LogParams struct {
	//Service is the HTTP method given to the request.
	Service string
	// Method is the HTTP method given to the request.
	Method string
	// TimeStamp shows the time after the webserve returns a response.
	TimeStamp time.Time
	// StatusCode is HTTP response code.
	StatusCode string
	// Latency is how much time the webserve cost to process a certain request.
	Latency time.Duration
	// IP equals Context's IP method.
	IP string
	// Path is a path the client requests.
	Path string
	// ErrorMessage is set if error has occurred in processing the request.
	ErrorMessage string

	// BodySize is the size of the Response Body
	BodySize int
	// Keys are the keys set on the request's context.
	Keys map[string]interface{}

	RequestData      string
	RequestUserAgent string
	RequestReferer   string
	RequestProto     string

	RequestId string
	TraceId   string
	SpanId    string

	ResponseData string
	// contains filtered or unexported fields
}

LogParams is the structure any formatter will be handed when time to log comes

type MessageProducer

type MessageProducer func(ctx context.Context, format string, code codes.Code, err error)

MessageProducer produces a user defined log message

type Option

type Option func(*options)

func WithLogger

func WithLogger(logger glog.ILogger) Option

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