README
¶
lager
Note: This repository should be imported as code.cloudfoundry.org/lager.
Lager is a logging library for go.
Usage
Instantiate a logger with the name of your component.
import (
"code.cloudfoundry.org/lager/v3"
)
logger := lager.NewLogger("my-app")
Lager and log/slog
Lager was written long before Go 1.21 introduced structured logging in the standard library.
There are some wrapper functions for interoperability between Lager and slog,
which are only available when using Go 1.21 and higher.
Lager can be used as an slog.Handler using the NewHandler() function:
func codeThatAcceptsSlog(l *slog.Logger) { ... }
lagerLogger := lager.NewLogger("my-lager-logger")
codeThatAcceptsSlog(slog.New(lager.NewHandler(lagerLogger)))
An slog.Logger can be used as a Lager Sink using the NewSlogSink() function:
var *slog.Logger l = codeThatReturnsSlog()
lagerLogger := lager.NewLogger("my-lager-logger")
lagerLogger.RegisterSink(lager.NewSlogSink(l))
Sinks
Lager can write logs to a variety of destinations. You can specify the destinations using Lager sinks:
To write to an arbitrary Writer object:
logger.RegisterSink(lager.NewWriterSink(myWriter, lager.INFO))
Emitting logs
Lager supports the usual level-based logging, with an optional argument for arbitrary key-value data.
logger.Info("doing-stuff", lager.Data{
"informative": true,
})
output:
{ "source": "my-app", "message": "doing-stuff", "data": { "informative": true }, "timestamp": 1232345, "log_level": 1 }
Error messages also take an Error object:
logger.Error("failed-to-do-stuff", errors.New("Something went wrong"))
output:
{ "source": "my-app", "message": "failed-to-do-stuff", "data": { "error": "Something went wrong" }, "timestamp": 1232345, "log_level": 1 }
Sessions
You can avoid repetition of contextual data using 'Sessions':
contextualLogger := logger.Session("my-task", lager.Data{
"request-id": 5,
})
contextualLogger.Info("my-action")
output:
{ "source": "my-app", "message": "my-task.my-action", "data": { "request-id": 5 }, "timestamp": 1232345, "log_level": 1 }
License
Lager is Apache 2.0 licensed.
Documentation
¶
Index ¶
- Constants
- func DefaultValuePatterns() []string
- func NewHandler(l Logger) slog.Handler
- type Data
- type JSONRedacter
- type LogFormat
- type LogLevel
- type Logger
- type ReconfigurableSink
- type Sink
- func NewPrettySink(writer io.Writer, minLogLevel LogLevel) Sink
- func NewRedactingSink(sink Sink, keyPatterns []string, valuePatterns []string) (Sink, error)
- func NewSlogSink(l *slog.Logger) Sink
- func NewTruncatingSink(sink Sink, maxDataStringLength int) Sink
- func NewWriterSink(writer io.Writer, minLogLevel LogLevel) Sink
Constants ¶
const ( StackTraceBufferSize = 1024 * 100 RequestIdHeader = "X-Vcap-Request-Id" )
Variables ¶
This section is empty.
Functions ¶
func DefaultValuePatterns ¶
func DefaultValuePatterns() []string
func NewHandler ¶ added in v3.0.3
NewHandler wraps the logger as a slog.Handler The supplied Logger must be a lager.logger type created by lager.NewLogger(), otherwise it panics.
Note the following log level conversions:
slog.LevelDebug -> lager.DEBUG slog.LevelError -> lager.ERROR slog.LevelError -> lager.FATAL default -> lager.INFO
Types ¶
type JSONRedacter ¶
type JSONRedacter struct {
// contains filtered or unexported fields
}
func NewJSONRedacter ¶
func NewJSONRedacter(keyPatterns []string, valuePatterns []string) (*JSONRedacter, error)
func (JSONRedacter) Redact ¶
func (r JSONRedacter) Redact(data []byte) []byte
type LogFormat ¶
type Logger ¶
type Logger interface {
RegisterSink(Sink)
Session(task string, data ...Data) Logger
SessionName() string
Debug(action string, data ...Data)
Info(action string, data ...Data)
Error(action string, err error, data ...Data)
Fatal(action string, err error, data ...Data)
WithData(Data) Logger
WithTraceInfo(*http.Request) Logger
}
type ReconfigurableSink ¶
type ReconfigurableSink struct {
// contains filtered or unexported fields
}
func NewReconfigurableSink ¶
func NewReconfigurableSink(sink Sink, initialMinLogLevel LogLevel) *ReconfigurableSink
func (*ReconfigurableSink) GetMinLevel ¶
func (sink *ReconfigurableSink) GetMinLevel() LogLevel
func (*ReconfigurableSink) Log ¶
func (sink *ReconfigurableSink) Log(log LogFormat)
func (*ReconfigurableSink) SetMinLevel ¶
func (sink *ReconfigurableSink) SetMinLevel(level LogLevel)
type Sink ¶
type Sink interface {
//Log to the sink. Best effort -- no need to worry about errors.
Log(LogFormat)
}
A Sink represents a write destination for a Logger. It provides a thread-safe interface for writing logs
func NewRedactingSink ¶
NewRedactingSink creates a sink that redacts sensitive information from the data field. The old behavior of NewRedactingWriterSink (which was removed in v2) can be obtained using the following code:
redactingSink, err := NewRedactingSink(
NewWriterSink(writer, minLogLevel),
keyPatterns,
valuePatterns,
)
if err != nil {
return nil, err
}
return NewReconfigurableSink(
redactingSink,
minLogLevel,
), nil
func NewSlogSink ¶ added in v3.0.3
NewSlogSink wraps a slog.Logger as a lager Sink This allows code using slog to integrate with code that uses lager Note the following log level conversions:
lager.DEBUG -> slog.LevelDebug lager.ERROR -> slog.LevelError lager.FATAL -> slog.LevelError default -> slog.LevelInfo
func NewTruncatingSink ¶
NewTruncatingSink returns a sink that truncates strings longer than the max data string length Example:
writerSink := lager.NewWriterSink(os.Stdout, lager.INFO)
sink := lager.NewTruncatingSink(testSink, 20)
logger := lager.NewLogger("test")
logger.RegisterSink(sink)
logger.Info("message", lager.Data{"A": strings.Repeat("a", 25)})
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
Package lagerctx provides convenience when using Lager with the context feature of the standard library.
|
Package lagerctx provides convenience when using Lager with the context feature of the standard library. |