grpc_zap

package
v1.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 15, 2023 License: Apache-2.0 Imports: 16 Imported by: 662

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.

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

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.

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.

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

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

{
  "level": "info",									// string  zap 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.345,							// 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 zap log levels
  "msg": "client request payload logged as grpc.request.content",   // string log message

  "grpc.request.content": {											// object content of RPC request
    "msg" : {														// object ZAP specific inner object
	  "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. Please see settable_test.go for canonical integration through "zaptest" with golang testing infrastructure.

Example (Initialization)

Initialization shows a relatively complex initialization sequence. 

package main

import (
	grpc_middleware "github.com/grpc-ecosystem/go-grpc-middleware"
	grpc_zap "github.com/grpc-ecosystem/go-grpc-middleware/logging/zap"

	grpc_ctxtags "github.com/grpc-ecosystem/go-grpc-middleware/tags"
	"go.uber.org/zap"
	"google.golang.org/grpc"
)

var (
	zapLogger  *zap.Logger
	customFunc grpc_zap.CodeToLevel
)

func main() {
	// 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.ReplaceGrpcLoggerV2(zapLogger)
	// 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_zap.UnaryServerInterceptor(zapLogger, opts...),
		),
		grpc_middleware.WithStreamServerChain(
			grpc_ctxtags.StreamServerInterceptor(grpc_ctxtags.WithFieldExtractor(grpc_ctxtags.CodeGenRequestFieldExtractor)),
			grpc_zap.StreamServerInterceptor(zapLogger, opts...),
		),
	)
}

Output:
Example (InitializationWithDecider) 
package main

import (
	grpc_middleware "github.com/grpc-ecosystem/go-grpc-middleware"
	grpc_zap "github.com/grpc-ecosystem/go-grpc-middleware/logging/zap"

	grpc_ctxtags "github.com/grpc-ecosystem/go-grpc-middleware/tags"
	"go.uber.org/zap"
	"google.golang.org/grpc"
)

func main() {
	opts := []grpc_zap.Option{
		grpc_zap.WithDecider(func(fullMethodName string, err error) bool {
			// will not log gRPC calls if it was a call to healthcheck and no error was raised
			if err == nil && fullMethodName == "foo.bar.healthcheck" {
				return false
			}

			// by default everything will be logged
			return true
		}),
	}

	_ = []grpc.ServerOption{
		grpc_middleware.WithStreamServerChain(
			grpc_ctxtags.StreamServerInterceptor(),
			grpc_zap.StreamServerInterceptor(zap.NewNop(), opts...)),
		grpc_middleware.WithUnaryServerChain(
			grpc_ctxtags.UnaryServerInterceptor(),
			grpc_zap.UnaryServerInterceptor(zap.NewNop(), opts...)),
	}
}

Output:
Example (InitializationWithDurationFieldOverride)

Initialization shows an initialization sequence with the duration field generation overridden. 

package main

import (
	"time"

	grpc_middleware "github.com/grpc-ecosystem/go-grpc-middleware"
	grpc_zap "github.com/grpc-ecosystem/go-grpc-middleware/logging/zap"

	grpc_ctxtags "github.com/grpc-ecosystem/go-grpc-middleware/tags"
	"go.uber.org/zap"
	"go.uber.org/zap/zapcore"
	"google.golang.org/grpc"
)

var zapLogger *zap.Logger

func main() {
	opts := []grpc_zap.Option{
		grpc_zap.WithDurationField(func(duration time.Duration) zapcore.Field {
			return zap.Int64("grpc.time_ns", duration.Nanoseconds())
		}),
	}

	_ = grpc.NewServer(
		grpc_middleware.WithUnaryServerChain(
			grpc_ctxtags.UnaryServerInterceptor(),
			grpc_zap.UnaryServerInterceptor(zapLogger, opts...),
		),
		grpc_middleware.WithStreamServerChain(
			grpc_ctxtags.StreamServerInterceptor(),
			grpc_zap.StreamServerInterceptor(zapLogger, opts...),
		),
	)
}

Output:

Index

Examples

Constants

This section is empty.

Variables

View Source 
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 statement made through grpc_zap.Can be overwritten before initialization.
	ServerField = zap.String("span.kind", "server")
)
View Source 
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")
)
View Source 
var DefaultDurationToField = DurationToTimeMillisField

DefaultDurationToField is the default implementation of converting request duration to a Zap field.

View Source 
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_logging.JsonPbMarshaler = &jsonpb.Marshaler{}
)

Functions

func AddFields 

func AddFields(ctx context.Context, fields ...zapcore.Field)

AddFields adds zap fields to the logger. Deprecated: should use the ctxzap.AddFields instead

func DefaultClientCodeToLevel 

func DefaultClientCodeToLevel(code codes.Code) zapcore.Level

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

func DefaultCodeToLevel 

func DefaultCodeToLevel(code codes.Code) zapcore.Level

DefaultCodeToLevel is the default implementation of gRPC return codes and interceptor log level for server side.

func DefaultMessageProducer added in v1.2.1 

func DefaultMessageProducer(ctx context.Context, msg string, level zapcore.Level, code codes.Code, err error, duration zapcore.Field)

DefaultMessageProducer writes the default message

func DurationToDurationField 

func DurationToDurationField(duration time.Duration) zapcore.Field

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 

func DurationToTimeMillisField(duration time.Duration) zapcore.Field

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

func Extract 

func Extract(ctx context.Context) *zap.Logger

Extract takes the call-scoped Logger from grpc_zap middleware. Deprecated: should use the ctxzap.Extract instead

Example (Unary)

Simple unary handler that adds custom fields to the requests's context. These will be used for all log statements. 

package main

import (
	"context"

	"github.com/grpc-ecosystem/go-grpc-middleware/logging/zap/ctxzap"

	grpc_ctxtags "github.com/grpc-ecosystem/go-grpc-middleware/tags"

	pb_testproto "github.com/grpc-ecosystem/go-grpc-middleware/testing/testproto"
)

func main() {
	_ = 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 zap.Logger and log messages. (containing the grpc.xxx tags)
		l := ctxzap.Extract(ctx)
		l.Info("some ping")
		l.Info("another ping")
		return &pb_testproto.PingResponse{Value: ping.Value}, nil
	}
}

Output:

func PayloadStreamClientInterceptor 

func PayloadStreamClientInterceptor(logger *zap.Logger, decider grpc_logging.ClientPayloadLoggingDecider) grpc.StreamClientInterceptor

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

func PayloadStreamServerInterceptor 

func PayloadStreamServerInterceptor(logger *zap.Logger, decider grpc_logging.ServerPayloadLoggingDecider) grpc.StreamServerInterceptor

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

This *only* works when placed *after* the `grpc_zap.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 payloads 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_zap.UnaryServerInterceptor`. However, the logging can be done to a separate instance of the logger.

func ReplaceGrpcLogger 

func ReplaceGrpcLogger(logger *zap.Logger)

ReplaceGrpcLogger sets the given zap.Logger as a gRPC-level logger. This should be called *before* any other initialization, preferably from init() functions. Deprecated: use ReplaceGrpcLoggerV2.

func ReplaceGrpcLoggerV2 added in v1.1.0 

func ReplaceGrpcLoggerV2(logger *zap.Logger)

ReplaceGrpcLoggerV2 replaces the grpclog.LoggerV2 with the provided logger. It should be called before any gRPC functions. Logging verbosity defaults to info level. To adjust gRPC logging verbosity, see ReplaceGrpcLoggerV2WithVerbosity.

func ReplaceGrpcLoggerV2WithVerbosity added in v1.1.0 

func ReplaceGrpcLoggerV2WithVerbosity(logger *zap.Logger, verbosity int)

ReplaceGrpcLoggerV2WithVerbosity replaces the grpclog.Logger with the provided logger and verbosity. It should be called before any gRPC functions. verbosity correlates to grpclogs verbosity levels. A higher verbosity value results in less logging.

func SetGrpcLoggerV2 added in v1.3.0 

func SetGrpcLoggerV2(settable grpc_logsettable.SettableLoggerV2, logger *zap.Logger)

SetGrpcLoggerV2 replaces the grpc_log.Logger with the provided logger. It can be used even when grpc infrastructure was initialized.

func SetGrpcLoggerV2WithVerbosity added in v1.3.0 

func SetGrpcLoggerV2WithVerbosity(settable grpc_logsettable.SettableLoggerV2, logger *zap.Logger, verbosity int)

SetGrpcLoggerV2WithVerbosity replaces the grpc_.LoggerV2 with the provided logger and verbosity. It can be used even when grpc infrastructure was initialized.

func StreamClientInterceptor 

func StreamClientInterceptor(logger *zap.Logger, opts ...Option) grpc.StreamClientInterceptor

StreamClientInterceptor 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 

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

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

type DurationToField 

type DurationToField func(duration time.Duration) zapcore.Field

DurationToField function defines how to produce duration fields for logging

type MessageProducer added in v1.2.1 

type MessageProducer func(ctx context.Context, msg string, level zapcore.Level, code codes.Code, err error, duration zapcore.Field)

MessageProducer produces a user defined log message

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 WithDecider 

func WithDecider(f grpc_logging.Decider) Option

WithDecider customizes the function for deciding if the gRPC interceptor logs should log.

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.

func WithMessageProducer added in v1.2.1 

func WithMessageProducer(f MessageProducer) Option

WithMessageProducer customizes the function for message formation.

func WithTimestampFormat added in v1.3.0 

func WithTimestampFormat(format string) Option

WithTimestampFormat customizes the timestamps emitted in the log fields.

Source Files

View all Source files

Directories

Path Synopsis
`ctxzap` is a ctxlogger that is backed by Zap
 `ctxzap` is a ctxlogger that is backed by Zap

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.