README
¶
Cloud Logging for Go
This module provides a log wrapper that is intended to handle logging in cloud-based backend environment.
Changelog
- 1.1.0: Renamed Stackdriver -> Google Cloud Logging; this is API-breaking change.
- 1.0.0: Bumped version to 1.0.0. Fixed zap logger accumulating structured logging fields.
- 0.0.16: Added JSON formatting output hints
- 0.0.15: Added default parameters for structured logging
- 0.0.13: Argument handling bugfix, added GoDoc reference to README
- 0.0.11: Improved documentation.
Usage
Install the dependency:
go get -u github.com/qvik/go-cloudlogging
Convenience constructors & examples
For convenience, several constructor methods are provided; see below.
Google Compute Engine (GCE) example:
func init() {
log = cloudlog.MustNewComputeEngineLogger("project-id", "MyAppLog")
}
This could also used for Kuhernetes.
Google App Engine (GAE) ecample:
func init() {
log = cloudlog.MustNewAppEngineLogger() // Optionally define log ID as arg
}
Google Cloud Functions (GCF) example:
func init() {
log = cloudlog.MustNewCloudFunctionLogger() // Optionally define log ID as arg
}
AWS Elastic Beanstalk / EC2 example:
logfile := "/var/log/example-app.log"
log = cloudlogging.MustNewLogger(cloudlogging.WithZap(),
cloudlogging.WithOutputHints(cloudlogging.JSONFormat),
cloudlogging.WithOutputPaths(logfile),
cloudlogging.WithErrorOutputPaths(logfile))
}
License
The library is distributed with the MIT License.
Documentation
¶
Overview ¶
Package cloudlogging provides logging wrapper for Google Cloud Platform environments.
Index ¶
- type Level
- type LogOption
- func WithCommonKeysAndValues(commonKeysAndValues ...interface{}) LogOption
- func WithErrorOutputPaths(paths ...string) LogOption
- func WithGoogleCloudLogging(gcpProjectID, credentialsFilePath, googleCloudLoggingLogID string, ...) LogOption
- func WithLevel(logLevel Level) LogOption
- func WithOutputHints(hints ...OutputHint) LogOption
- func WithOutputPaths(paths ...string) LogOption
- func WithZap(config ...*zap.Config) LogOption
- type Logger
- func MustNewAppEngineLogger(args ...string) *Logger
- func MustNewCloudFunctionLogger(args ...string) *Logger
- func MustNewCloudRunLogger(location, projectID string, args ...string) *Logger
- func MustNewComputeEngineLogger(projectID, logID string) *Logger
- func MustNewLogger(opt ...LogOption) *Logger
- func MustNewZapLogger(config ...*zap.Config) *Logger
- func NewAppEngineLogger(args ...string) (*Logger, error)
- func NewCloudFunctionLogger(args ...string) (*Logger, error)
- func NewCloudRunLogger(location, projectID string, args ...string) (*Logger, error)
- func NewComputeEngineLogger(projectID, logID string) (*Logger, error)
- func NewLogger(opt ...LogOption) (*Logger, error)
- func NewZapLogger(config ...*zap.Config) (*Logger, error)
- func (l *Logger) Close() error
- func (l *Logger) Debug(payload interface{}, keysAndValues ...interface{})
- func (l *Logger) Debugf(format string, args ...interface{})
- func (l *Logger) Error(payload interface{}, keysAndValues ...interface{})
- func (l *Logger) Errorf(format string, args ...interface{})
- func (l *Logger) Fatal(payload interface{}, keysAndValues ...interface{})
- func (l *Logger) Fatalf(format string, args ...interface{})
- func (l *Logger) Flush() error
- func (l *Logger) Info(payload interface{}, keysAndValues ...interface{})
- func (l *Logger) Infof(format string, args ...interface{})
- func (l *Logger) Panic(payload interface{}, keysAndValues ...interface{})
- func (l *Logger) Panicf(format string, args ...interface{})
- func (l *Logger) Print(payload interface{}, keysAndValues ...interface{})
- func (l *Logger) Printf(format string, args ...interface{})
- func (l *Logger) SetLogLevel(logLevel Level) *Logger
- func (l *Logger) Trace(payload interface{}, keysAndValues ...interface{})
- func (l *Logger) Tracef(format string, args ...interface{})
- func (l *Logger) Warning(payload interface{}, keysAndValues ...interface{})
- func (l *Logger) Warningf(format string, args ...interface{})
- func (l *Logger) WithAdditionalKeysAndValues(keysAndValues ...interface{}) *Logger
- type OutputHint
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type LogOption ¶
type LogOption interface {
// contains filtered or unexported methods
}
LogOption is an option for the cloudlogging API.
func WithCommonKeysAndValues ¶ added in v0.0.16
func WithCommonKeysAndValues(commonKeysAndValues ...interface{}) LogOption
WithCommonKeysAndValues returns a LogOption that adds a set of common keys and values (labels / fields) to all structured log messages. For parameters should be: key1, value1, key2, value2, ..
func WithErrorOutputPaths ¶ added in v0.0.16
WithErrorOutputPaths log output paths, eg. URLs or file paths. Different loggers use these in different ways. For example Zap uses them as log output file paths.
func WithGoogleCloudLogging ¶ added in v1.1.0
func WithGoogleCloudLogging(gcpProjectID, credentialsFilePath, googleCloudLoggingLogID string, monitoredResource *monitoredres.MonitoredResource) LogOption
WithGoogleCloudLogging returns a LogOption that enables Google Cloud Logging Logger and configures it to use the given project id. If you supply empty string for credentialsFilePath, the default service account is used. Google cloud logging log backend does not react to OutputHints.
func WithOutputHints ¶ added in v0.0.16
func WithOutputHints(hints ...OutputHint) LogOption
WithOutputHints adds output hints to the log backend.
func WithOutputPaths ¶ added in v0.0.16
WithOutputPaths log output paths, eg. URLs or file paths. Different loggers use these in different ways. For example Zap uses them as log output file paths.
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger writes logs to the local logger as well as the Google Cloud Logging cloud logs. Logger is mostly immutable - the only thing that can be modified is the log level.
Logger is thread-safe to use for any of the logging calls. Some methods such as SetLogLevel(), Close(), Flush() however are not and you should either call them at the start / end of your program or synchronize your access to the Logger instance if setting on them on the fly. The reasoning here being that standard Logger calls should not suffer a performance hit from locking.
Logger uses the Zap (https://github.com/uber-go/zap) library for local logging.
Logger uses Google Cloud Logging Go library for cloud logging.
The API is compatible (and thus a drop-in replacement) for popular logging libraries such as: - Go's standard "log" interface - https://github.com/op/go-logging - https://github.com/sirupsen/logrus - https://github.com/uber-go/zap
func MustNewAppEngineLogger ¶
MustNewAppEngineLogger returns a Logger suitable for use in AppEngine. On local dev server it uses the local stdout -logger and in the cloud it uses the Google Cloud Logging logger. The first value of args is the logID. If omitted or empty string is given, the default value of "appengine.googleapis.com/request_log" is used. Panics on errors.
func MustNewCloudFunctionLogger ¶
MustNewCloudFunctionLogger returns a Logger suitable for use in Google Cloud Functions. It will emit the logs using the Google Cloud Logging API. The first value of args is the logID. If omitted or empty string is given, the default value of "cloudfunctions.googleapis.com/cloud-functions" is used. Panics on errors.
func MustNewCloudRunLogger ¶ added in v1.1.0
MustNewCloudRunLogger returns a Logger suitable for use in Cloud Run. On local dev server it uses the local stdout -logger and in the cloud it uses the Google Cloud Logging logger. The first value of args is the logID. If omitted or empty string is given, the default value of "run.googleapis.com/request_log" is used. Panics on errors.
func MustNewComputeEngineLogger ¶
MustNewComputeEngineLogger returns a Logger suitable for use in Google Compute Engine instance as well as Google Kubernetes Engine. The returned logger only logs via Google Cloud Logging. Panics on errors.
func MustNewLogger ¶ added in v0.0.16
MustNewLogger creates a new Logger instance using the given options. The default log level is Debug. Panics if logger creation fails.
func MustNewZapLogger ¶ added in v0.0.16
MustNewZapLogger returns a logger that only logs to a local stdout/stderr Zap logger, optionally with a Zap configuration. Panics on error(s).
func NewAppEngineLogger ¶
NewAppEngineLogger returns a Logger suitable for use in AppEngine. On local dev server it uses the local Zap logger and in the cloud it uses the Google Cloud Logging logger. The first value of args is the logID. If omitted or empty string is given, the default value of "appengine.googleapis.com/request_log" is used.
func NewCloudFunctionLogger ¶
NewCloudFunctionLogger returns a Logger suitable for use in Google Cloud Functions. It will emit the logs using the Google Cloud Logging API. The first value of args is the logID. If omitted or empty string is given, the default value of "cloudfunctions.googleapis.com/cloud-functions" is used.
func NewCloudRunLogger ¶ added in v1.1.0
NewCloudRunLogger returns a Logger suitable for use in Cloud Run. On local dev server it uses the local Zap logger and in the cloud it uses the Google Cloud Logging logger. The first value of args is the logID. If omitted or empty string is given, the default value of "run.googleapis.com/request_log" is used.
func NewComputeEngineLogger ¶
NewComputeEngineLogger returns a Logger suitable for use in Google Compute Engine instance as well as Google Kubernetes Engine. The returned logger only logs via Google Cloud Logging.
func NewLogger ¶
NewLogger creates a new Logger instance using the given options. The default log level is Debug.
func NewZapLogger ¶ added in v0.0.16
NewZapLogger returns a logger that only logs to a local stdout/stderr Zap logger, optionally with a Zap configuration.
func (*Logger) Close ¶
Close closes the logger and flushes the underlying loggers' buffers. Returns error if there are errors.
func (*Logger) Debug ¶
func (l *Logger) Debug(payload interface{}, keysAndValues ...interface{})
Debug writes a structured log entry using the debug level. Compatibility alias for Debug().
Example ¶
log, _ := NewLogger() // Allocates a null logger
log.Debug("Debug log message", "label1", 1, "label2", 2)
Output:
func (*Logger) Debugf ¶
Debugf writes debug level logs
Example ¶
log, _ := NewLogger() // Allocates a null logger
myMsg := "message"
log.Debugf("Debug with msg: %v", myMsg)
Output:
func (*Logger) Error ¶
func (l *Logger) Error(payload interface{}, keysAndValues ...interface{})
Error writes a structured log entry using the error level.
func (*Logger) Fatal ¶
func (l *Logger) Fatal(payload interface{}, keysAndValues ...interface{})
Fatal writes a structured log entry using the fatal level.
func (*Logger) Flush ¶
Flush flushes the underlying loggers' buffers. Returns error if there are errors.
func (*Logger) Info ¶
func (l *Logger) Info(payload interface{}, keysAndValues ...interface{})
Info writes a structured log entry using the info level.
func (*Logger) Panic ¶
func (l *Logger) Panic(payload interface{}, keysAndValues ...interface{})
Panic writes a structured log entry using the fatal level. Compatibility alias for Fatal().
func (*Logger) Print ¶
func (l *Logger) Print(payload interface{}, keysAndValues ...interface{})
Print writes a structured log entry using the debug level. Compatibility alias for Debug().
func (*Logger) SetLogLevel ¶
SetLogLevel sets the log levels of the underlying logger interfaces. Note that this operation is not mutexed and thus not inherently thread-safe.
func (*Logger) Trace ¶
func (l *Logger) Trace(payload interface{}, keysAndValues ...interface{})
Trace writes a structured log entry using the debug level.
func (*Logger) Warning ¶
func (l *Logger) Warning(payload interface{}, keysAndValues ...interface{})
Warning writes a structured log entry using the warning level.
func (*Logger) WithAdditionalKeysAndValues ¶ added in v0.0.15
WithAdditionalKeysAndValues creates a new logger that uses the current logger as its base logger (all logging calls will be forwarded to the base logger). Making changes to the base logger will be reflected in any calls to the new logger. Additional keys and values may be added for structured logging purposes. This is a light operation. Panics if number of elements in keysAndValues is not even. Panics on internal errors.
Example ¶
// Allocates a null logger with no actual backends
baseLog, _ := NewLogger(WithCommonKeysAndValues("key1", "value1"))
// Create a "sub" logger that inherits the default keys and values from
// its defined baselogger (baseLog)
subLog := baseLog.WithAdditionalKeysAndValues("key2", "value2")
subLog.Debug("Sublog debug message", "label", "value")
Output:
type OutputHint ¶ added in v0.0.16
type OutputHint int32
OutputHint provides a mechanism to instruct log backends to adjust their output / formatting. Not all log backends react to any / all of the hints.
const ( // JSONFormat output hint requests the log backend to output JSON(NL). JSONFormat OutputHint = iota )
Source Files
Directories