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
Constants ¶
This section is empty.
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 ¶
DefaultClientCodeToLevel is the default implementation of gRPC return codes to log levels for client side.
func DefaultCodeToLevel ¶
DefaultCodeToLevel is the default implementation of gRPC return codes to log levels for server side.
func DurationToDurationField ¶
DurationToDurationField uses the duration value to log the request duration.
func DurationToTimeMillisField ¶
DurationToTimeMillisField converts the duration to milliseconds and uses the key `grpc.time_ms`.
func GetRawJSON ¶
GetRawJSON converts a Protobuf message to JSON bytes if less than MaxSize.
func LogRequest ¶
func LogRequestIP ¶
func LogResponse ¶
func LogResponse(log *LogParams, resp interface{})
func LogStatusError ¶
func LogUserAgent ¶
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 ¶
CodeToLevel function defines the mapping between gRPC return codes and interceptor log level.
type DurationToField ¶
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 ¶
MessageProducer produces a user defined log message
Source Files