diff options
Diffstat (limited to 'vendor/github.com/grpc-ecosystem/go-grpc-middleware/logging/logrus/DOC.md')
| -rw-r--r-- | vendor/github.com/grpc-ecosystem/go-grpc-middleware/logging/logrus/DOC.md | 257 |
1 files changed, 83 insertions, 174 deletions
diff --git a/vendor/github.com/grpc-ecosystem/go-grpc-middleware/logging/logrus/DOC.md b/vendor/github.com/grpc-ecosystem/go-grpc-middleware/logging/logrus/DOC.md index 7a1bb9394..ba136f195 100644 --- a/vendor/github.com/grpc-ecosystem/go-grpc-middleware/logging/logrus/DOC.md +++ b/vendor/github.com/grpc-ecosystem/go-grpc-middleware/logging/logrus/DOC.md @@ -12,65 +12,35 @@ 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. +You can use `Extract` to log into a request-scoped `logrus.Entry` instance in your handler code. The fields set on the +logger correspond to the grpc_ctxtags.Tags attached to the context. 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 +logged as structured `jsonbp` 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 whetether 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 - } +Please see examples and tests for examples of use. -*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 - } +#### Example: -Note - due to implementation ZAP differs from Logrus in the "grpc.request.content" object by having an inner "msg" object. +<details> +<summary>Click to expand code.</summary> -Please see examples and tests for examples of use. +```go +x := func(ctx context.Context, ping *pb_testproto.PingRequest) (*pb_testproto.PingResponse, error) { + // Add fields the ctxtags of the request which will be added to all extracted loggers. + grpc_ctxtags.Extract(ctx).Set("custom_tags.string", "something").Set("custom_tags.int", 1337) + // Extract a request-scoped zap.Logger and log a message. + grpc_logrus.Extract(ctx).Info("some ping") + return &pb_testproto.PingResponse{Value: ping.Value}, nil + } + return x +``` + +</details> #### Example: @@ -79,24 +49,25 @@ Please see examples and tests for examples of use. ```go // Logrus entry is used, allowing pre-definition of certain fields by the user. -logrusEntry := logrus.NewEntry(logrusLogger) -// Shared options for the logger, with a custom gRPC code to log level function. -opts := []grpc_logrus.Option{ - grpc_logrus.WithLevels(customFunc), -} -// Make sure that log statements internal to gRPC library are logged using the logrus Logger as well. -grpc_logrus.ReplaceGrpcLogger(logrusEntry) -// Create a server, make sure we put the grpc_ctxtags context before everything else. -_ = grpc.NewServer( - grpc_middleware.WithUnaryServerChain( - grpc_ctxtags.UnaryServerInterceptor(grpc_ctxtags.WithFieldExtractor(grpc_ctxtags.CodeGenRequestFieldExtractor)), - grpc_logrus.UnaryServerInterceptor(logrusEntry, opts...), - ), - grpc_middleware.WithStreamServerChain( - grpc_ctxtags.StreamServerInterceptor(grpc_ctxtags.WithFieldExtractor(grpc_ctxtags.CodeGenRequestFieldExtractor)), - grpc_logrus.StreamServerInterceptor(logrusEntry, opts...), - ), -) + logrusEntry := logrus.NewEntry(logrusLogger) + // Shared options for the logger, with a custom gRPC code to log level function. + opts := []grpc_logrus.Option{ + grpc_logrus.WithLevels(customFunc), + } + // Make sure that log statements internal to gRPC library are logged using the zapLogger as well. + grpc_logrus.ReplaceGrpcLogger(logrusEntry) + // Create a server, make sure we put the grpc_ctxtags context before everything else. + server := grpc.NewServer( + grpc_middleware.WithUnaryServerChain( + grpc_ctxtags.UnaryServerInterceptor(grpc_ctxtags.WithFieldExtractor(grpc_ctxtags.CodeGenRequestFieldExtractor)), + grpc_logrus.UnaryServerInterceptor(logrusEntry, opts...), + ), + grpc_middleware.WithStreamServerChain( + grpc_ctxtags.StreamServerInterceptor(grpc_ctxtags.WithFieldExtractor(grpc_ctxtags.CodeGenRequestFieldExtractor)), + grpc_logrus.StreamServerInterceptor(logrusEntry, opts...), + ), + ) + return server ``` </details> @@ -108,36 +79,36 @@ _ = grpc.NewServer( ```go // Logrus entry is used, allowing pre-definition of certain fields by the user. -logrusEntry := logrus.NewEntry(logrusLogger) -// Shared options for the logger, with a custom duration to log field function. -opts := []grpc_logrus.Option{ - grpc_logrus.WithDurationField(func(duration time.Duration) (key string, value interface{}) { - return "grpc.time_ns", duration.Nanoseconds() - }), -} -_ = grpc.NewServer( - grpc_middleware.WithUnaryServerChain( - grpc_ctxtags.UnaryServerInterceptor(), - grpc_logrus.UnaryServerInterceptor(logrusEntry, opts...), - ), - grpc_middleware.WithStreamServerChain( - grpc_ctxtags.StreamServerInterceptor(), - grpc_logrus.StreamServerInterceptor(logrusEntry, opts...), - ), -) + logrusEntry := logrus.NewEntry(logrusLogger) + // Shared options for the logger, with a custom duration to log field function. + opts := []grpc_logrus.Option{ + grpc_logrus.WithDurationField(func(duration time.Duration) (key string, value interface{}) { + return "grpc.time_ns", duration.Nanoseconds() + }), + } + server := grpc.NewServer( + grpc_middleware.WithUnaryServerChain( + grpc_ctxtags.UnaryServerInterceptor(), + grpc_logrus.UnaryServerInterceptor(logrusEntry, opts...), + ), + grpc_middleware.WithStreamServerChain( + grpc_ctxtags.StreamServerInterceptor(), + grpc_logrus.StreamServerInterceptor(logrusEntry, opts...), + ), + ) + return server ``` </details> ## <a name="pkg-imports">Imported Packages</a> +- github.com/sirupsen/logrus - [github.com/golang/protobuf/jsonpb](https://godoc.org/github.com/golang/protobuf/jsonpb) - [github.com/golang/protobuf/proto](https://godoc.org/github.com/golang/protobuf/proto) - [github.com/grpc-ecosystem/go-grpc-middleware](./../..) - [github.com/grpc-ecosystem/go-grpc-middleware/logging](./..) -- [github.com/grpc-ecosystem/go-grpc-middleware/logging/logrus/ctxlogrus](./ctxlogrus) -- [github.com/grpc-ecosystem/go-grpc-middleware/tags/logrus](./../../tags/logrus) -- [github.com/sirupsen/logrus](https://godoc.org/github.com/sirupsen/logrus) +- [github.com/grpc-ecosystem/go-grpc-middleware/tags](./../../tags) - [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context) - [google.golang.org/grpc](https://godoc.org/google.golang.org/grpc) - [google.golang.org/grpc/codes](https://godoc.org/google.golang.org/grpc/codes) @@ -145,7 +116,6 @@ _ = grpc.NewServer( ## <a name="pkg-index">Index</a> * [Variables](#pkg-variables) -* [func AddFields(ctx context.Context, fields logrus.Fields)](#AddFields) * [func DefaultClientCodeToLevel(code codes.Code) logrus.Level](#DefaultClientCodeToLevel) * [func DefaultCodeToLevel(code codes.Code) logrus.Level](#DefaultCodeToLevel) * [func DurationToDurationField(duration time.Duration) (key string, value interface{})](#DurationToDurationField) @@ -164,18 +134,16 @@ _ = grpc.NewServer( * [type DurationToField](#DurationToField) * [type Option](#Option) * [func WithCodes(f grpc\_logging.ErrorToCode) Option](#WithCodes) - * [func WithDecider(f grpc\_logging.Decider) Option](#WithDecider) * [func WithDurationField(f DurationToField) Option](#WithDurationField) * [func WithLevels(f CodeToLevel) Option](#WithLevels) #### <a name="pkg-examples">Examples</a> -* [Extract (Unary)](#example_Extract_unary) -* [WithDecider](#example_WithDecider) +* [Package (HandlerUsageUnaryPing)](#example__handlerUsageUnaryPing) * [Package (Initialization)](#example__initialization) * [Package (InitializationWithDurationFieldOverride)](#example__initializationWithDurationFieldOverride) #### <a name="pkg-files">Package files</a> -[client_interceptors.go](./client_interceptors.go) [context.go](./context.go) [doc.go](./doc.go) [grpclogger.go](./grpclogger.go) [options.go](./options.go) [payload_interceptors.go](./payload_interceptors.go) [server_interceptors.go](./server_interceptors.go) +[client_interceptors.go](./client_interceptors.go) [context.go](./context.go) [doc.go](./doc.go) [grpclogger.go](./grpclogger.go) [noop.go](./noop.go) [options.go](./options.go) [payload_interceptors.go](./payload_interceptors.go) [server_interceptors.go](./server_interceptors.go) ## <a name="pkg-variables">Variables</a> ``` go @@ -194,90 +162,66 @@ DefaultDurationToField is the default implementation of converting request durat ``` go var ( - // JsonPbMarshaller is the marshaller used for serializing protobuf messages. + // JsonPBMarshaller is the marshaller used for serializing protobuf messages. JsonPbMarshaller = &jsonpb.Marshaler{} ) ``` -## <a name="AddFields">func</a> [AddFields](./context.go#L11) -``` go -func AddFields(ctx context.Context, fields logrus.Fields) -``` -AddFields adds logrus fields to the logger. -Deprecated: should use the ctxlogrus.Extract instead - -## <a name="DefaultClientCodeToLevel">func</a> [DefaultClientCodeToLevel](./options.go#L129) +## <a name="DefaultClientCodeToLevel">func</a> [DefaultClientCodeToLevel](./options.go#L120) ``` go func DefaultClientCodeToLevel(code codes.Code) logrus.Level ``` DefaultClientCodeToLevel is the default implementation of gRPC return codes to log levels for client side. -## <a name="DefaultCodeToLevel">func</a> [DefaultCodeToLevel](./options.go#L87) +## <a name="DefaultCodeToLevel">func</a> [DefaultCodeToLevel](./options.go#L78) ``` go func DefaultCodeToLevel(code codes.Code) logrus.Level ``` DefaultCodeToLevel is the default implementation of gRPC return codes to log levels for server side. -## <a name="DurationToDurationField">func</a> [DurationToDurationField](./options.go#L179) +## <a name="DurationToDurationField">func</a> [DurationToDurationField](./options.go#L170) ``` go func DurationToDurationField(duration time.Duration) (key string, value interface{}) ``` DurationToDurationField uses the duration value to log the request duration. -## <a name="DurationToTimeMillisField">func</a> [DurationToTimeMillisField](./options.go#L174) +## <a name="DurationToTimeMillisField">func</a> [DurationToTimeMillisField](./options.go#L165) ``` go func DurationToTimeMillisField(duration time.Duration) (key string, value interface{}) ``` DurationToTimeMillisField converts the duration to milliseconds and uses the key `grpc.time_ms`. -## <a name="Extract">func</a> [Extract](./context.go#L17) +## <a name="Extract">func</a> [Extract](./context.go#L22) ``` go func Extract(ctx context.Context) *logrus.Entry ``` Extract takes the call-scoped logrus.Entry from grpc_logrus middleware. -Deprecated: should use the ctxlogrus.Extract instead -#### Example: +If the grpc_logrus middleware wasn't used, a no-op `logrus.Entry` is returned. This makes it safe to +use regardless. -<details> -<summary>Click to expand code.</summary> - -```go -_ = func(ctx context.Context, ping *pb_testproto.PingRequest) (*pb_testproto.PingResponse, error) { - // Add fields the ctxtags of the request which will be added to all extracted loggers. - grpc_ctxtags.Extract(ctx).Set("custom_tags.string", "something").Set("custom_tags.int", 1337) - // Extract a single request-scoped logrus.Logger and log messages. - l := ctx_logrus.Extract(ctx) - l.Info("some ping") - l.Info("another ping") - return &pb_testproto.PingResponse{Value: ping.Value}, nil -} -``` - -</details> - -## <a name="PayloadStreamClientInterceptor">func</a> [PayloadStreamClientInterceptor](./payload_interceptors.go#L74) +## <a name="PayloadStreamClientInterceptor">func</a> [PayloadStreamClientInterceptor](./payload_interceptors.go#L77) ``` go func PayloadStreamClientInterceptor(entry *logrus.Entry, decider grpc_logging.ClientPayloadLoggingDecider) grpc.StreamClientInterceptor ``` -PayloadStreamClientInterceptor returns a new streaming client interceptor that logs the paylods of requests and responses. +PayloadStreamServerInterceptor returns a new streaming client interceptor that logs the paylods of requests and responses. -## <a name="PayloadStreamServerInterceptor">func</a> [PayloadStreamServerInterceptor](./payload_interceptors.go#L45) +## <a name="PayloadStreamServerInterceptor">func</a> [PayloadStreamServerInterceptor](./payload_interceptors.go#L48) ``` go func PayloadStreamServerInterceptor(entry *logrus.Entry, decider grpc_logging.ServerPayloadLoggingDecider) grpc.StreamServerInterceptor ``` -PayloadStreamServerInterceptor returns a new server server interceptors that logs the payloads of requests. +PayloadUnaryServerInterceptor 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. -## <a name="PayloadUnaryClientInterceptor">func</a> [PayloadUnaryClientInterceptor](./payload_interceptors.go#L58) +## <a name="PayloadUnaryClientInterceptor">func</a> [PayloadUnaryClientInterceptor](./payload_interceptors.go#L61) ``` go func PayloadUnaryClientInterceptor(entry *logrus.Entry, decider grpc_logging.ClientPayloadLoggingDecider) grpc.UnaryClientInterceptor ``` PayloadUnaryClientInterceptor returns a new unary client interceptor that logs the paylods of requests and responses. -## <a name="PayloadUnaryServerInterceptor">func</a> [PayloadUnaryServerInterceptor](./payload_interceptors.go#L25) +## <a name="PayloadUnaryServerInterceptor">func</a> [PayloadUnaryServerInterceptor](./payload_interceptors.go#L28) ``` go func PayloadUnaryServerInterceptor(entry *logrus.Entry, decider grpc_logging.ServerPayloadLoggingDecider) grpc.UnaryServerInterceptor ``` @@ -299,7 +243,7 @@ func StreamClientInterceptor(entry *logrus.Entry, opts ...Option) grpc.StreamCli ``` StreamServerInterceptor returns a new streaming client interceptor that optionally logs the execution of external gRPC calls. -## <a name="StreamServerInterceptor">func</a> [StreamServerInterceptor](./server_interceptors.go#L58) +## <a name="StreamServerInterceptor">func</a> [StreamServerInterceptor](./server_interceptors.go#L50) ``` go func StreamServerInterceptor(entry *logrus.Entry, opts ...Option) grpc.StreamServerInterceptor ``` @@ -311,77 +255,42 @@ func UnaryClientInterceptor(entry *logrus.Entry, opts ...Option) grpc.UnaryClien ``` UnaryClientInterceptor returns a new unary client interceptor that optionally logs the execution of external gRPC calls. -## <a name="UnaryServerInterceptor">func</a> [UnaryServerInterceptor](./server_interceptors.go#L26) +## <a name="UnaryServerInterceptor">func</a> [UnaryServerInterceptor](./server_interceptors.go#L25) ``` go func UnaryServerInterceptor(entry *logrus.Entry, opts ...Option) grpc.UnaryServerInterceptor ``` -UnaryServerInterceptor returns a new unary server interceptors that adds logrus.Entry to the context. +PayloadUnaryServerInterceptor returns a new unary server interceptors that adds logrus.Entry to the context. -## <a name="CodeToLevel">type</a> [CodeToLevel](./options.go#L53) +## <a name="CodeToLevel">type</a> [CodeToLevel](./options.go#L51) ``` go type CodeToLevel func(code codes.Code) logrus.Level ``` CodeToLevel function defines the mapping between gRPC return codes and interceptor log level. -## <a name="DurationToField">type</a> [DurationToField](./options.go#L56) +## <a name="DurationToField">type</a> [DurationToField](./options.go#L54) ``` go type DurationToField func(duration time.Duration) (key string, value interface{}) ``` DurationToField function defines how to produce duration fields for logging -## <a name="Option">type</a> [Option](./options.go#L50) +## <a name="Option">type</a> [Option](./options.go#L48) ``` go type Option func(*options) ``` -### <a name="WithCodes">func</a> [WithCodes](./options.go#L73) +### <a name="WithCodes">func</a> [WithCodes](./options.go#L64) ``` go func WithCodes(f grpc_logging.ErrorToCode) Option ``` WithCodes customizes the function for mapping errors to error codes. -### <a name="WithDecider">func</a> [WithDecider](./options.go#L59) -``` go -func WithDecider(f grpc_logging.Decider) Option -``` -WithDecider customizes the function for deciding if the gRPC interceptor logs should log. - -#### Example: - -<details> -<summary>Click to expand code.</summary> - -```go -opts := []grpc_logrus.Option{ - grpc_logrus.WithDecider(func(methodFullName string, err error) bool { - // will not log gRPC calls if it was a call to healthcheck and no error was raised - if err == nil && methodFullName == "blah.foo.healthcheck" { - return false - } - - // by default you will log all calls - return true - }), -} - -_ = []grpc.ServerOption{ - grpc_middleware.WithStreamServerChain( - grpc_ctxtags.StreamServerInterceptor(), - grpc_logrus.StreamServerInterceptor(logrus.NewEntry(logrus.New()), opts...)), - grpc_middleware.WithUnaryServerChain( - grpc_ctxtags.UnaryServerInterceptor(), - grpc_logrus.UnaryServerInterceptor(logrus.NewEntry(logrus.New()), opts...)), -} -``` - -</details> -### <a name="WithDurationField">func</a> [WithDurationField](./options.go#L80) +### <a name="WithDurationField">func</a> [WithDurationField](./options.go#L71) ``` go func WithDurationField(f DurationToField) Option ``` WithDurationField customizes the function for mapping request durations to log fields. -### <a name="WithLevels">func</a> [WithLevels](./options.go#L66) +### <a name="WithLevels">func</a> [WithLevels](./options.go#L57) ``` go func WithLevels(f CodeToLevel) Option ``` |