grpc_lager

README

Lager gRPC Middleware

Middlewares for gRPC Go based off of grpc-ecosystem/go-grpc-middleware

Note: This library currently does not support streams or stream interceptors

Usage example:

import (
    "github.com/grpc-ecosystem/go-grpc-middleware"
    "github.com/Unity-Technologies/go-lager-internal/grpc_lager"
)

myServer := grpc.NewServer(
    grpc.UnaryInterceptor(grpc_middleware.ChainUnaryServer(
        grpc_ctxtags.UnaryServerInterceptor(),
        grpc_lager.UnaryServerInterceptor(),
        grpc_lager.PayloadUnaryServerInterceptor(deciderFunction)
    )),
)

Documentation

Overview

grpc_lager is package for gRPC logging middlewares for the Lager library. Based on middleware from https://github.com/grpc-ecosystem/go-grpc-middleware The gRPC logging middleware populates request-scoped data to `grpc_ctxtags.Tags` that relate to the current gRPC call (e.g. service and method names). Once the gRPC logging middleware has added the gRPC specific Tags to the ctx they will then be written with the logs that are made using the Lager logger. All logging middleware will emit a final log statement. It is based on the error returned by the handler function, the gRPC status code, an error (if any) and it will emit at a level controlled via `WithLevels`.

Field names All field names of loggers follow the OpenTracing semantics definitions, with `grpc.` prefix if needed: https://github.com/opentracing/specification/blob/master/semantic_conventions.md

Index

• Variables
• func DefaultCodeToLevel(code codes.Code) byte
• func DefaultMessageProducer(ctx context.Context, msg string, level byte, code codes.Code, err error, ...)
• func DurationToDurationField(duration time.Duration) *lager.KVPairs
• func DurationToTimeMillisField(duration time.Duration) *lager.KVPairs
• func Extract(ctx context.Context, lev byte) lager.Lager
• func PayloadUnaryServerInterceptor(decider ServerPayloadLoggingDecider) grpc.UnaryServerInterceptor
• func TagsToPairs(ctx context.Context) context.Context
• func UnaryServerInterceptor(opts ...Option) grpc.UnaryServerInterceptor
• type CodeToLevel
• type DurationToPairs
• type JSONPbFormater
• type MessageProducer
• type Option
  • func WithCodes(f grpc_logging.ErrorToCode) Option
  • func WithDecider(f grpc_logging.Decider) Option
  • func WithDurationField(f DurationToPairs) Option
  • func WithLevels(f CodeToLevel) Option
  • func WithMessageProducer(f MessageProducer) Option
  • func WithTimestampFormat(format string) Option
• type ServerPayloadLoggingDecider

Variables

var (
	// SystemField is used in every log statement made through grpc_lager. Can be overwritten before any initialization code.
	SystemField = "grpc"

	// ServerField is used in every server-side log statement made through grpc_lager. Can be overwritten before initialization.
	ServerField = "server"
)

var DefaultDurationToField = DurationToTimeMillisField

DefaultDurationToField is the default implementation of converting request duration to Lager pairs.

Functions

func DefaultCodeToLevel

func DefaultCodeToLevel(code codes.Code) byte

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

func DefaultMessageProducer

func DefaultMessageProducer(ctx context.Context, msg string, level byte, code codes.Code, err error, duration *lager.KVPairs)

DefaultMessageProducer writes the default message

func DurationToDurationField

func DurationToDurationField(duration time.Duration) *lager.KVPairs

DurationToDurationField uses a Duration field to log the request duration and leaves it up to Lager's encoder settings to determine how that is output.

func DurationToTimeMillisField

func DurationToTimeMillisField(duration time.Duration) *lager.KVPairs

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

func Extract

func Extract(ctx context.Context, lev byte) lager.Lager

Pass in context and one character from "PEFWNAITDOG" to get a Lager object that has all the grpc_ctxtags updated.

func PayloadUnaryServerInterceptor

func PayloadUnaryServerInterceptor(decider ServerPayloadLoggingDecider) grpc.UnaryServerInterceptor

func TagsToPairs

func TagsToPairs(ctx context.Context) context.Context

TagsToPairs extracts the tags provided by the go-grpc-middleware library from the context, adds them to the context as Lager pairs and returns an updated context

func UnaryServerInterceptor

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

Types

type CodeToLevel

type CodeToLevel func(code codes.Code) byte

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

type DurationToPairs

type DurationToPairs func(duration time.Duration) lager.AMap

DurationToPairs function defines how to produce duration fields for logging

type JSONPbFormater

type JSONPbFormater interface {
	Format(m proto.Message) string
}

JSONPbFormater is a formatter that formats protobuf messages.

var (
	// JSONPbFormatter is the formatter used for formatting protobuf messages as strings.
	// If needed, this variable can be reassigned with a different formatter with the same Format() signature.
	JSONPbFormatter JSONPbFormater = &protojson.MarshalOptions{}
)

type MessageProducer

type MessageProducer func(ctx context.Context, msg string, level byte, code codes.Code, err error, duration *lager.KVPairs)

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 DurationToPairs) Option

WithDurationField customizes the function for mapping request durations to Lager pairs.

func WithLevels

func WithLevels(f CodeToLevel) Option

WithLevels customizes the function for mapping gRPC return codes and interceptor log level statements.

func WithMessageProducer

func WithMessageProducer(f MessageProducer) Option

WithMessageProducer customizes the function for message formation.

func WithTimestampFormat

func WithTimestampFormat(format string) Option

WithTimestampFormat customizes the timestamps emitted in the log fields.

type ServerPayloadLoggingDecider

type ServerPayloadLoggingDecider func(ctx context.Context, fullMethodName string, servingObject interface{}) bool

ServerPayloadLoggingDecider is a user-provided function for deciding whether to log the server-side request/response payloads