README
¶
dfuse Logging library
This is the logging library used as part of dfuse.
Usage
In all library packages (by convention, use the import path):
var zlog *zap.Logger
func init() {
logging.Register("github.com/path/to/my/package", &zlog)
}
In main packages:
var zlog *zap.Logger
func setupLogger() {
logging.Register("main", &zlog)
logging.Set(logging.MustCreateLogger())
// Optionally set a different logger here and there,
// using a regexp matching the registered names:
//logging.Set(zap.NewNop(), "eosdb")
}
In tests (to avoid a race between the init() statements)
func init() {
if os.Getenv("DEBUG") != "" {
logging.Override(logging.MustCreateLoggerWithLevel("test", zap.NewAtomicLevelAt(zap.DebugLevel)), ""))
}
}
You can switch log levels dynamically, by poking the port 1065 like this:
On listening servers (port 1065, hint: logs!)
curl http://localhost:1065/ -XPUT -d '{"level": "debug"}'
Contributing
Issues and PR in this repo related strictly to the dfuse logging library.
Report any protocol-specific issues in their respective repositories
Please first refer to the general dfuse contribution guide, if you wish to contribute to this code base.
License
Documentation
¶
Index ¶
- Variables
- func BasicLoggingConfig(serviceName string, atomicLevel zap.AtomicLevel, opts ...zap.Option) *zap.Config
- func CreateLogger(serviceName string, opts ...zap.Option) (*zap.Logger, error)
- func CreateLoggerWithLevel(serviceName string, atomicLevel zap.AtomicLevel, opts ...zap.Option) (*zap.Logger, error)
- func Debug(ctx context.Context, fallbackLogger *zap.Logger, msg string, ...)
- func Error(ctx context.Context, fallbackLogger *zap.Logger, msg string, ...)
- func Extend(extender LoggerExtender, regexps ...string)
- func FlagFields(extraFields ...zap.Field) []zap.Field
- func Info(ctx context.Context, fallbackLogger *zap.Logger, msg string, ...)
- func IsProductionEnvironment() bool
- func IsTraceEnabled(shortName string, packageID string) bool
- func LevelFromEnvironment() zap.AtomicLevel
- func Logger(ctx context.Context, fallbackLogger *zap.Logger) *zap.Logger
- func MaybeNewLogger(opts ...LoggerOption) (*zap.Logger, error)
- func MustCreateLogger(opts ...zap.Option) *zap.Loggerdeprecated
- func MustCreateLoggerWithLevel(serviceName string, atomicLevel zap.AtomicLevel, opts ...zap.Option) *zap.Logger
- func MustCreateLoggerWithServiceName(serviceName string, opts ...zap.Option) *zap.Logger
- func NewEncoder(verbosity int, enableColors bool) zapcore.Encoder
- func NewLogger(opts ...LoggerOption) *zap.Logger
- func Override(logger *zap.Logger)
- func Register(packageID string, zlogPtr **zap.Logger, options ...RegisterOption)
- func Set(logger *zap.Logger, regexps ...string)
- func TestingOverride()
- func Warn(ctx context.Context, fallbackLogger *zap.Logger, msg string, ...)
- func WithLogger(ctx context.Context, logger *zap.Logger) context.Context
- type Encoder
- func (enc Encoder) AddArray(key string, arr zapcore.ArrayMarshaler) error
- func (enc Encoder) AddBinary(key string, val []byte)
- func (enc Encoder) AddBool(key string, val bool)
- func (enc Encoder) AddByteString(key string, val []byte)
- func (enc Encoder) AddComplex128(key string, val complex128)
- func (enc Encoder) AddComplex64(k string, v complex64)
- func (enc Encoder) AddDuration(key string, val time.Duration)
- func (enc Encoder) AddFloat32(k string, v float32)
- func (enc Encoder) AddFloat64(key string, val float64)
- func (enc Encoder) AddInt(k string, v int)
- func (enc Encoder) AddInt16(k string, v int16)
- func (enc Encoder) AddInt32(k string, v int32)
- func (enc Encoder) AddInt64(key string, val int64)
- func (enc Encoder) AddInt8(k string, v int8)
- func (enc Encoder) AddObject(key string, obj zapcore.ObjectMarshaler) error
- func (enc Encoder) AddReflected(key string, obj interface{}) error
- func (enc Encoder) AddString(key, val string)
- func (enc Encoder) AddTime(key string, val time.Time)
- func (enc Encoder) AddUint(k string, v uint)
- func (enc Encoder) AddUint16(k string, v uint16)
- func (enc Encoder) AddUint32(k string, v uint32)
- func (enc Encoder) AddUint64(key string, val uint64)
- func (enc Encoder) AddUint8(k string, v uint8)
- func (enc Encoder) AddUintptr(k string, v uintptr)
- func (enc Encoder) AppendArray(arr zapcore.ArrayMarshaler) error
- func (enc Encoder) AppendBool(val bool)
- func (enc Encoder) AppendByteString(val []byte)
- func (enc Encoder) AppendComplex128(val complex128)
- func (enc Encoder) AppendComplex64(v complex64)
- func (enc Encoder) AppendDuration(val time.Duration)
- func (enc Encoder) AppendFloat32(v float32)
- func (enc Encoder) AppendFloat64(v float64)
- func (enc Encoder) AppendInt(v int)
- func (enc Encoder) AppendInt16(v int16)
- func (enc Encoder) AppendInt32(v int32)
- func (enc Encoder) AppendInt64(val int64)
- func (enc Encoder) AppendInt8(v int8)
- func (enc Encoder) AppendObject(obj zapcore.ObjectMarshaler) error
- func (enc Encoder) AppendReflected(val interface{}) error
- func (enc Encoder) AppendString(val string)
- func (enc Encoder) AppendTime(val time.Time)
- func (enc Encoder) AppendTimeLayout(time time.Time, layout string)
- func (enc Encoder) AppendUint(v uint)
- func (enc Encoder) AppendUint16(v uint16)
- func (enc Encoder) AppendUint32(v uint32)
- func (enc Encoder) AppendUint64(val uint64)
- func (enc Encoder) AppendUint8(v uint8)
- func (enc Encoder) AppendUintptr(v uintptr)
- func (c Encoder) Clone() zapcore.Encoder
- func (c Encoder) EncodeEntry(ent zapcore.Entry, fields []zapcore.Field) (*buffer.Buffer, error)
- func (enc Encoder) OpenNamespace(key string)
- type Handler
- type LoggerExtender
- type LoggerOption
- type RegisterOption
- type TestLogger
- type Tracer
Constants ¶
This section is empty.
Variables ¶
var AutoStartServer = true
Functions ¶
func BasicLoggingConfig ¶
func CreateLogger ¶
CreateLogger can be used to create the correct zap logger based on the environment.
First, if an environment variable `ZAP_PRETTY` pretty is present, a `zapdriver.NewProduction` is used but logging all levels (`Debug` level and more). Furthermore, this logger will print everything into the standard output of the process (opposed to standard error by default). If the env is set, it overrides everything. If the value of the `ZAP_PRETTY` environment variable is a valid Zap level (`debug`, `info`, `warn`, `error`), the logger level will be configured using the value. In all other cases, `debug` level is used as the default.
Then, if in production, automatically a `zap.NewProduction()` is returned. The production environment is determined based on the presence of the `/.dockerenv` file.
In all other cases, return a `zap.NewDevelopment()` logger.
func CreateLoggerWithLevel ¶
func CreateLoggerWithLevel(serviceName string, atomicLevel zap.AtomicLevel, opts ...zap.Option) (*zap.Logger, error)
CreateLoggerWithLevel behaves exactly like `CreateLogger`, but you can pass the atomic level that should be used for the logger that will use this atomic level. By keeping a reference to it, later on, you will be able to change the level at runtime by calling `atomicLevel.SetLevel` on your reference and logger level will be changed.
func Extend ¶
func Extend(extender LoggerExtender, regexps ...string)
Extend is different than `Set` by being able to re-configure the existing logger set for all registered logger in the registry. This is useful for example to add a field to the currently set logger:
``` logger.Extend(func (current *zap.Logger) { return current.With("name", "value") }, "github.com/dfuse-io/app.*") ```
func FlagFields ¶
FlagFields returns all falg as `zap.Field` element for easy logging
func IsProductionEnvironment ¶
func IsProductionEnvironment() bool
func IsTraceEnabled ¶
IsTraceEnabled receives the a short name value (usually the app name) and the fully qualified package identifier (i.e. `github.com/dfuse-io/logging/subpackage`) and determines if tracing should be enabled for such values.
To take the decision, this function inspects the `TRACE` environment variable. If the variable is **not** set, tracing is disabled. If the value is either `true`, `*` or `.*`, then tracing is enabled.
For other values, we split the `TRACE` value using `,` separator. For each split element, if the element matches directly the short name, tracing is enabled and if the element as a Regexp object matches (partially, not fully) the `packageID`, tracing is enabled.
The method also supports deny elements. If you prefix the element with `-`, it means disable trace for this match. This is applied after all allow element has been processed, so it's possible to enabled except a specific package (i.e. `TRACE=.*,-github.com/specific/package`).
In all other cases, tracing is disabled.
func LevelFromEnvironment ¶
func LevelFromEnvironment() zap.AtomicLevel
func Logger ¶
Logger is used to retrieved the logger from the context. If no logger is present in the context, the `fallbackLogger` received in parameter is returned instead.
func MaybeNewLogger ¶
func MaybeNewLogger(opts ...LoggerOption) (*zap.Logger, error)
func MustCreateLogger
deprecated
func MustCreateLoggerWithLevel ¶
func MustCreateLoggerWithLevel(serviceName string, atomicLevel zap.AtomicLevel, opts ...zap.Option) *zap.Logger
MustCreateLoggerWithLevel behaves exactly like `MustCreateLogger`, but you can pass the atomic level that should be used for the logger that will use this atomic level. By keeping a reference to it, later on, you will be able to change the level at runtime by calling `atomicLevel.SetLevel` on your reference and logger level will be changed.
func MustCreateLoggerWithServiceName ¶
MustCreateLogger has the same behavior as `CreateLogger` function. However, it automatically panic if the logger was not created successfully.
func NewLogger ¶
func NewLogger(opts ...LoggerOption) *zap.Logger
NewLogger creates a new logger with sane defaults based on a varity of rules described below and automatically registered withing the logging registry.
func Override ¶
Override sets the given logger on previously registered and next registrations. Useful in tests.
func TestingOverride ¶
func TestingOverride()
TestingOverride calls `Override` (or `Set`, see below) with a development logger setup correctly with the right level based on some environment variables.
By default, override using a `zap.NewDevelopment` logger (`info`), if environment variable `DEBUG` is set to anything or environment variable `TRACE` is set to `true`, logger is set in `debug` level.
If `DEBUG` is set to something else than `true` and/or if `TRACE` is set to something else than
Types ¶
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
func (Encoder) AddByteString ¶
func (Encoder) AddComplex128 ¶
func (enc Encoder) AddComplex128(key string, val complex128)
func (Encoder) AddComplex64 ¶
func (Encoder) AddDuration ¶
func (Encoder) AddFloat32 ¶
func (Encoder) AddFloat64 ¶
func (Encoder) AddObject ¶
func (enc Encoder) AddObject(key string, obj zapcore.ObjectMarshaler) error
func (Encoder) AddReflected ¶
func (Encoder) AddUintptr ¶
func (Encoder) AppendArray ¶
func (enc Encoder) AppendArray(arr zapcore.ArrayMarshaler) error
func (Encoder) AppendBool ¶
func (enc Encoder) AppendBool(val bool)
func (Encoder) AppendByteString ¶
func (enc Encoder) AppendByteString(val []byte)
func (Encoder) AppendComplex128 ¶
func (enc Encoder) AppendComplex128(val complex128)
func (Encoder) AppendComplex64 ¶
func (enc Encoder) AppendComplex64(v complex64)
func (Encoder) AppendDuration ¶
func (Encoder) AppendFloat32 ¶
func (enc Encoder) AppendFloat32(v float32)
func (Encoder) AppendFloat64 ¶
func (enc Encoder) AppendFloat64(v float64)
func (Encoder) AppendInt16 ¶
func (enc Encoder) AppendInt16(v int16)
func (Encoder) AppendInt32 ¶
func (enc Encoder) AppendInt32(v int32)
func (Encoder) AppendInt64 ¶
func (enc Encoder) AppendInt64(val int64)
func (Encoder) AppendInt8 ¶
func (enc Encoder) AppendInt8(v int8)
func (Encoder) AppendObject ¶
func (enc Encoder) AppendObject(obj zapcore.ObjectMarshaler) error
func (Encoder) AppendReflected ¶
func (enc Encoder) AppendReflected(val interface{}) error
func (Encoder) AppendString ¶
func (enc Encoder) AppendString(val string)
func (Encoder) AppendTime ¶
func (Encoder) AppendTimeLayout ¶
func (Encoder) AppendUint ¶
func (enc Encoder) AppendUint(v uint)
func (Encoder) AppendUint16 ¶
func (enc Encoder) AppendUint16(v uint16)
func (Encoder) AppendUint32 ¶
func (enc Encoder) AppendUint32(v uint32)
func (Encoder) AppendUint64 ¶
func (enc Encoder) AppendUint64(val uint64)
func (Encoder) AppendUint8 ¶
func (enc Encoder) AppendUint8(v uint8)
func (Encoder) AppendUintptr ¶
func (enc Encoder) AppendUintptr(v uintptr)
func (Encoder) EncodeEntry ¶
func (Encoder) OpenNamespace ¶
func (enc Encoder) OpenNamespace(key string)
type Handler ¶
type Handler struct {
// Handler is the handler used to handle the incoming request.
Next http.Handler
// Propagation defines how traces are propagated. If unspecified,
// Stackdriver propagation will be used.
Propagation propagation.HTTPFormat
// Actual root logger to instrument with request information
RootLogger *zap.Logger
}
Handler is an http.Handler wrapper to instrument your HTTP server with an automatic `zap.Logger` per request (i.e. context).
Logging ¶
This handler is aware of the incoming request's trace id, reading it from request headers as configured using the Propagation field. The extracted trace id if present is used to configure the actual logger with the field `trace_id`.
If the trace id cannot be extracted from the request, an random request id is generated and used under the field `req_id`.
type LoggerOption ¶
type LoggerOption interface {
// contains filtered or unexported methods
}
func WithAtomicLevel ¶
func WithAtomicLevel(level zap.AtomicLevel) LoggerOption
func WithAutoStartSwitcherServer ¶
func WithAutoStartSwitcherServer() LoggerOption
func WithLoggerName ¶
func WithLoggerName(name string) LoggerOption
func WithReportAllErrors ¶
func WithReportAllErrors() LoggerOption
func WithServiceName ¶
func WithServiceName(name string) LoggerOption
func WithZapOption ¶
func WithZapOption(zapOption zap.Option) LoggerOption
type RegisterOption ¶
type RegisterOption interface {
// contains filtered or unexported methods
}
RegisterOption are option parameters that you can set when registering a new logger in the system using `Register` function.
func RegisterOnUpdate ¶
func RegisterOnUpdate(onUpdate func(newLogger *zap.Logger)) RegisterOption
RegisterOnUpdate enable you to have a hook function that will receive the new logger that is going to be assigned to your logger instance. This is useful in some situation where you need to update other instances or re-configuring a bit the logger when a new one is attached.
This is called **after** the instance has been re-assigned.
type TestLogger ¶
type TestLogger struct {
// contains filtered or unexported fields
}
func NewTestLogger ¶
func NewTestLogger(t testing.T) *TestLogger
func (*TestLogger) Instance ¶
func (l *TestLogger) Instance() *zap.Logger
Instance returns the actual *zap.Logger you should pass to your dependency to accumulate log lines and inspect them later on.
func (*TestLogger) RecordedLines ¶
func (w *TestLogger) RecordedLines(t testing.T) (out []string)
RecordedLines returns all the logged line seen, each line being a full fledged JSON value
Source Files