Documentation
¶
Overview ¶
`grpc_zap` is a gRPC logging middleware backed by ZAP loggers
It accepts a user-configured `zap.Logger` that will be used for logging completed gRPC calls. The same `zap.Logger` will be used for logging completed gRPC calls, and be populated into the `context.Context` passed into gRPC handler code.
You can use `Extract` to log into a request-scoped `zap.Logger` 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 `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.
ZAP can also be made as a backend for gRPC library internals. For that use `ReplaceGrpcLogger`.
Please see examples and tests for examples of use.
Example (HandlerUsageUnaryPing) ¶
Simple unary handler that adds custom fields to the requests's context. These will be used for all log statements.
package main
import (
pb_testproto "github.com/grpc-ecosystem/go-grpc-middleware/testing/testproto"
"context"
"time"
"github.com/grpc-ecosystem/go-grpc-middleware"
"github.com/grpc-ecosystem/go-grpc-middleware/logging/zap"
"github.com/grpc-ecosystem/go-grpc-middleware/tags"
"go.uber.org/zap"
"go.uber.org/zap/zapcore"
"google.golang.org/grpc"
)
// Initialization shows a relatively complex initialization sequence.
func main(zapLogger *zap.Logger, customFunc grpc_zap.CodeToLevel) *grpc.Server {
// Shared options for the logger, with a custom gRPC code to log level function.
opts := []grpc_zap.Option{
grpc_zap.WithLevels(customFunc),
}
// Make sure that log statements internal to gRPC library are logged using the zapLogger as well.
grpc_zap.ReplaceGrpcLogger(zapLogger)
// 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_zap.UnaryServerInterceptor(zapLogger, opts...),
),
grpc_middleware.WithStreamServerChain(
grpc_ctxtags.StreamServerInterceptor(grpc_ctxtags.WithFieldExtractor(grpc_ctxtags.CodeGenRequestFieldExtractor)),
grpc_zap.StreamServerInterceptor(zapLogger, opts...),
),
)
return server
}
// Initialization shows an initialization sequence with the duration field generation overridden.
func main(zapLogger *zap.Logger) *grpc.Server {
opts := []grpc_zap.Option{
grpc_zap.WithDurationField(func(duration time.Duration) zapcore.Field {
return zap.Int64("grpc.time_ns", duration.Nanoseconds())
}),
}
server := grpc.NewServer(
grpc_middleware.WithUnaryServerChain(
grpc_ctxtags.UnaryServerInterceptor(),
grpc_zap.UnaryServerInterceptor(zapLogger, opts...),
),
grpc_middleware.WithStreamServerChain(
grpc_ctxtags.StreamServerInterceptor(),
grpc_zap.StreamServerInterceptor(zapLogger, opts...),
),
)
return server
}
// Simple unary handler that adds custom fields to the requests's context. These will be used for all log statements.
func main() interface{} {
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_zap.Extract(ctx).Info("some ping")
return &pb_testproto.PingResponse{Value: ping.Value}, nil
}
return x
}
Output:
Index ¶
- Variables
- func DefaultClientCodeToLevel(code codes.Code) zapcore.Level
- func DefaultCodeToLevel(code codes.Code) zapcore.Level
- func DurationToDurationField(duration time.Duration) zapcore.Field
- func DurationToTimeMillisField(duration time.Duration) zapcore.Field
- func Extract(ctx context.Context) *zap.Logger
- func PayloadStreamClientInterceptor(logger *zap.Logger, decider grpc_logging.ClientPayloadLoggingDecider) grpc.StreamClientInterceptor
- func PayloadStreamServerInterceptor(logger *zap.Logger, decider grpc_logging.ServerPayloadLoggingDecider) grpc.StreamServerInterceptor
- func PayloadUnaryClientInterceptor(logger *zap.Logger, decider grpc_logging.ClientPayloadLoggingDecider) grpc.UnaryClientInterceptor
- func PayloadUnaryServerInterceptor(logger *zap.Logger, decider grpc_logging.ServerPayloadLoggingDecider) grpc.UnaryServerInterceptor
- func ReplaceGrpcLogger(logger *zap.Logger)
- func StreamClientInterceptor(logger *zap.Logger, opts ...Option) grpc.StreamClientInterceptor
- func StreamServerInterceptor(logger *zap.Logger, opts ...Option) grpc.StreamServerInterceptor
- func UnaryClientInterceptor(logger *zap.Logger, opts ...Option) grpc.UnaryClientInterceptor
- func UnaryServerInterceptor(logger *zap.Logger, opts ...Option) grpc.UnaryServerInterceptor
- type CodeToLevel
- type DurationToField
- type Option
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // SystemField is used in every log statement made through grpc_zap. Can be overwritten before any initialization code. SystemField = zap.String("system", "grpc") // ServerField is used in every server-side log statment made through grpc_zap.Can be overwritten before initialization. ServerField = zap.String("span.kind", "server") )
var ( // ClientField is used in every client-side log statement made through grpc_zap. Can be overwritten before initialization. ClientField = zap.String("span.kind", "client") )
var DefaultDurationToField = DurationToTimeMillisField
DefaultDurationToField is the default implementation of converting request duration to a Zap field.
var ( // JsonPBMarshaller is the marshaller used for serializing protobuf messages. JsonPbMarshaller = &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 and interceptor log level for server side.
func DurationToDurationField ¶
DurationToDurationField uses a Duration field to log the request duration and leaves it up to Zap's encoder settings to determine how that is output.
func DurationToTimeMillisField ¶
DurationToTimeMillisField converts the duration to milliseconds and uses the key `grpc.time_ms`.
func Extract ¶
Extract takes the call-scoped Logger from grpc_zap middleware.
It always returns a Logger that has all the grpc_ctxtags updated.
func PayloadStreamClientInterceptor ¶
func PayloadStreamClientInterceptor(logger *zap.Logger, decider grpc_logging.ClientPayloadLoggingDecider) grpc.StreamClientInterceptor
PayloadStreamServerInterceptor returns a new streaming client interceptor that logs the paylods of requests and responses.
func PayloadStreamServerInterceptor ¶
func PayloadStreamServerInterceptor(logger *zap.Logger, decider grpc_logging.ServerPayloadLoggingDecider) grpc.StreamServerInterceptor
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.
func PayloadUnaryClientInterceptor ¶
func PayloadUnaryClientInterceptor(logger *zap.Logger, decider grpc_logging.ClientPayloadLoggingDecider) grpc.UnaryClientInterceptor
PayloadUnaryClientInterceptor returns a new unary client interceptor that logs the paylods of requests and responses.
func PayloadUnaryServerInterceptor ¶
func PayloadUnaryServerInterceptor(logger *zap.Logger, decider grpc_logging.ServerPayloadLoggingDecider) 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 ReplaceGrpcLogger ¶
ReplaceGrpcLogger sets the given zap.Logger as a gRPC-level logger. This should be called *before* any other initialization, preferably from init() functions.
func StreamClientInterceptor ¶
func StreamClientInterceptor(logger *zap.Logger, opts ...Option) grpc.StreamClientInterceptor
StreamServerInterceptor returns a new streaming client interceptor that optionally logs the execution of external gRPC calls.
func StreamServerInterceptor ¶
func StreamServerInterceptor(logger *zap.Logger, opts ...Option) grpc.StreamServerInterceptor
StreamServerInterceptor returns a new streaming server interceptor that adds zap.Logger to the context.
func UnaryClientInterceptor ¶
func UnaryClientInterceptor(logger *zap.Logger, opts ...Option) grpc.UnaryClientInterceptor
UnaryClientInterceptor returns a new unary client interceptor that optionally logs the execution of external gRPC calls.
func UnaryServerInterceptor ¶
func UnaryServerInterceptor(logger *zap.Logger, opts ...Option) grpc.UnaryServerInterceptor
UnaryServerInterceptor returns a new unary server interceptors that adds zap.Logger 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 Option ¶
type Option func(*options)
func WithCodes ¶
func WithCodes(f grpc_logging.ErrorToCode) Option
WithCodes customizes the function for mapping errors to error codes.
func WithDurationField ¶
func WithDurationField(f DurationToField) Option
WithDurationField customizes the function for mapping request durations to Zap fields.
func WithLevels ¶
func WithLevels(f CodeToLevel) Option
WithLevels customizes the function for mapping gRPC return codes and interceptor log level statements.
Source Files