cloudzap

Documentation

Overview

Package cloudzap provides primitives for structured logging with go.uber.org/zap.

Index

• func ErrorReportContext(file string, line int, function string) zapcore.Field
• func ErrorReportContextForCaller(caller zapcore.EntryCaller) zapcore.Field
• func ErrorReportContextForSourceLocation(pc uintptr, file string, line int, ok bool) zapcore.Field
• func ErrorReportServiceContext(serviceName, serviceVersion string) zapcore.Field
• func GetLogger(ctx context.Context) (*zap.Logger, bool)
• func HTTPRequest(r *HTTPRequestObject) zap.Field
• func LevelToSeverity(l zapcore.Level) string
• func LevelToSlog(l zapcore.Level) slog.Level
• func NewEncoderConfig() zapcore.EncoderConfig
• func NewLogger(config LoggerConfig) (*zap.Logger, error)
• func ProtoMessage(key string, message proto.Message) zap.Field
• func Resource(key string, r *resource.Resource) zap.Field
• func SourceLocation(pc uintptr, file string, line int, ok bool) zapcore.Field
• func SourceLocationForCaller(caller zapcore.EntryCaller) zapcore.Field
• func SpanID(spanID string) zap.Field
• func Trace(projectID, traceID string) zap.Field
• func TraceSampled(sampled bool) zap.Field
• func WithLogger(ctx context.Context, logger *zap.Logger) context.Context
• func WithLoggerFields(ctx context.Context, fields ...zap.Field) context.Context
• type HTTPRequestObject
  • func (h *HTTPRequestObject) MarshalLogObject(encoder zapcore.ObjectEncoder) error
• type LoggerConfig
• type Middleware
  • func (l *Middleware) GRPCStreamServerInterceptor(srv interface{}, ss grpc.ServerStream, _ *grpc.StreamServerInfo, ...) (err error)
  • func (l *Middleware) GRPCUnaryServerInterceptor(ctx context.Context, request interface{}, _ *grpc.UnaryServerInfo, ...) (interface{}, error)
  • func (l *Middleware) HTTPServer(next http.Handler) http.Handler

Functions

func ErrorReportContext

func ErrorReportContext(file string, line int, function string) zapcore.Field

ErrorReportContext returns a structured logging field for error report context for the provided caller.

func ErrorReportContextForCaller

func ErrorReportContextForCaller(caller zapcore.EntryCaller) zapcore.Field

ErrorReportContextForCaller returns a structured logging field for error report context for the provided caller.

func ErrorReportContextForSourceLocation

func ErrorReportContextForSourceLocation(pc uintptr, file string, line int, ok bool) zapcore.Field

ErrorReportContextForSourceLocation returns an error report context structured logging field for a source location.

func ErrorReportServiceContext

func ErrorReportServiceContext(serviceName, serviceVersion string) zapcore.Field

ErrorReportServiceContext returns a structured logging field for error report context for the provided caller.

func GetLogger

func GetLogger(ctx context.Context) (*zap.Logger, bool)

GetLogger returns the logger for the current context.

func HTTPRequest

func HTTPRequest(r *HTTPRequestObject) zap.Field

HTTPRequest creates a new zap.Field for a Cloud Logging HTTP request. See: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#HttpRequest

func LevelToSeverity

func LevelToSeverity(l zapcore.Level) string

LevelToSeverity converts a zapcore.Level to its corresponding Cloud Logging severity level. See: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity.

func LevelToSlog

func LevelToSlog(l zapcore.Level) slog.Level

LevelToSlog converts a zapcore.Level to a slog.Level.

func NewEncoderConfig

func NewEncoderConfig() zapcore.EncoderConfig

NewEncoderConfig creates a new zapcore.EncoderConfig for structured JSON logging to Cloud Logging. See: https://cloud.google.com/logging/docs/agent/logging/configuration#special-fields.

func NewLogger

func NewLogger(config LoggerConfig) (*zap.Logger, error)

NewLogger creates a new Logger.

func ProtoMessage

func ProtoMessage(key string, message proto.Message) zap.Field

ProtoMessage constructs a zap.Field with the given key and proto message encoded as JSON.

func Resource

func Resource(key string, r *resource.Resource) zap.Field

Resource constructs a zap.Field with the given key and OpenTelemetry resource.

func SourceLocation

func SourceLocation(pc uintptr, file string, line int, ok bool) zapcore.Field

SourceLocation returns a structured logging field for the provided source location.

func SourceLocationForCaller

func SourceLocationForCaller(caller zapcore.EntryCaller) zapcore.Field

SourceLocationForCaller returns a structured logging field for the source location of the provided caller.

func SpanID

func SpanID(spanID string) zap.Field

func Trace

func Trace(projectID, traceID string) zap.Field

func TraceSampled

func TraceSampled(sampled bool) zap.Field

func WithLogger

func WithLogger(ctx context.Context, logger *zap.Logger) context.Context

WithLogger adds a logger to the current context.

func WithLoggerFields

func WithLoggerFields(ctx context.Context, fields ...zap.Field) context.Context

WithLoggerFields attaches structured fields to a new logger in the returned child context.

Types

type HTTPRequestObject

type HTTPRequestObject struct {
	// RequestMethod is the request method. Examples: "GET", "HEAD", "PUT", "POST".
	RequestMethod string
	// RequestURL is the scheme (http, https), the host name, the path and the query portion of the URL
	// that was requested. Example: "http://example.com/some/info?color=red".
	RequestURL string
	// The size of the HTTP request message in bytes, including the request headers and the request body.
	RequestSize int
	// Status is the response code indicating the status of response. Examples: 200, 404.
	Status int
	// ResponseSize is the size of the HTTP response message sent back to the client, in bytes,
	// including the response headers and the response body.
	ResponseSize int
	// UserAgent is the user agent sent by the client.
	// Example: "Mozilla/4.0 (compatible; MSIE 6.0; Windows 98; Q312461; .NET CLR 1.0.3705)".
	UserAgent string
	// RemoteIP is the IP address (IPv4 or IPv6) of the client that issued the HTTP request.
	// This field can include port information.
	// Examples: "192.168.1.1", "10.0.0.1:80", "FE80::0202:B3FF:FE1E:8329".
	RemoteIP string
	// ServerIP is the IP address (IPv4 or IPv6) of the origin server that the request was sent to.
	// This field can include port information.
	// Examples: "192.168.1.1", "10.0.0.1:80", "FE80::0202:B3FF:FE1E:8329".
	ServerIP string
	// Referer is the referer URL of the request, as defined in HTTP/1.1 Header Field Definitions.
	Referer string
	// Latency is the request processing latency on the server, from the time the request was received
	// until the response was sent.
	Latency time.Duration
	// Protocol is the protocol used for the request. Examples: "HTTP/1.1", "HTTP/2", "websocket"
	Protocol string
}

HTTPRequestObject is a common message for logging HTTP requests. See: https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#HttpRequest

func (*HTTPRequestObject) MarshalLogObject

func (h *HTTPRequestObject) MarshalLogObject(encoder zapcore.ObjectEncoder) error

MarshalLogObject implements zapcore.ObjectMarshaler.

type LoggerConfig

type LoggerConfig struct {
	// Development indicates if the logger should output human-readable output for development.
	Development bool `default:"true" onGCE:"false"`
	// Level indicates which log level the logger should output at.
	Level zapcore.Level `default:"debug" onGCE:"info"`
	// ReportErrors indicates if error reports should be logged for errors.
	ReportErrors bool `onGCE:"true"`
}

LoggerConfig configures the application logger.

type Middleware

type Middleware struct {
	Logger *zap.Logger
}

func (*Middleware) GRPCStreamServerInterceptor

func (l *Middleware) GRPCStreamServerInterceptor(
	srv interface{},
	ss grpc.ServerStream,
	_ *grpc.StreamServerInfo,
	handler grpc.StreamHandler,
) (err error)

GRPCStreamServerInterceptor adds a zap logger to the server stream context.

func (*Middleware) GRPCUnaryServerInterceptor

func (l *Middleware) GRPCUnaryServerInterceptor(
	ctx context.Context,
	request interface{},
	_ *grpc.UnaryServerInfo,
	handler grpc.UnaryHandler,
) (interface{}, error)

GRPCUnaryServerInterceptor implements grpc.UnaryServerInterceptor to add a logger to the request context.

func (*Middleware) HTTPServer

func (l *Middleware) HTTPServer(next http.Handler) http.Handler

HTTPServer implements HTTP server middleware to add a logger to the request context.