README
¶
nblog
The nblog package provides a handler for the slo package that formats records in the style of NetBackup "legacy" logs:
time [pid] <sev> caller: message
Additional attributes will appear JSON-style after the message.
Usage
go get github.com/rkennedy/nblog
package main
import (
"os"
"github.com/rkennedy/nblog"
"golang.org/x/exp/slog"
)
func main() {
logger := slog.New(nblog.NewHandler(os.Stdout))
logger.Info("message")
}
Documentation
¶
Overview ¶
Package nblog provides a handler for slog that formats logs in the style of Veritas NetBackup log messages.
Index ¶
Examples ¶
Constants ¶
const ( FullDateFormat = time.DateTime + ".000" TimeOnlyFormat = time.TimeOnly + ".000" )
Formats for use with TimestampFormat.
const ( TimeKey = "time-75972059-5741-41f7-9248-e8594177835c" // message timestamp PidKey = "pid-47482072-7496-40a0-a048-ccfdba4e564e" // process ID LevelKey = "level-933f69a5-69b4-4f8a-a6a6-14810b97fdad" // severity level MessageKey = "message-5ae1bf30-54b2-4d50-8af7-7076b3a39e20" )
When formatting a message, the handler calls any ReplaceAttrFunc callbacks on any attributes associated with the message. It will synthesize attributes representing the timestamp, process ID, level, and message, giving the program an opportunity to modify, replace, or remove any of them, just as for any other attributes. Such synthetic attributes are identified with these labels, which should be unique enough not to collide with any attribute keys in the program.
If the replacement callback returns a time.Time value for the “time” attribute, then it will be formatted with the configured TimestampFormat option. Othe types for “time,” as well as other synthetic attributes, are recorded in the log with slog.Value.String.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type LegacyHandler ¶
type LegacyHandler struct {
// contains filtered or unexported fields
}
LegacyHandler is an implementation of slog.Handler that mimics the format used by legacy NetBackup logging. Attributes, if present, are appended to the line after the given message.
If an attribute named “who” is present, it overrides the name of the calling function.
func NewHandler ¶
func NewHandler(dest io.Writer, options ...LegacyOption) *LegacyHandler
NewHandler creates a new LegacyHandler. It receives a destination io.Writer and a list of LegacyOption values to configure it.
func (*LegacyHandler) Enabled ¶
Enabled implements slog.Handler.Enabled.
func (*LegacyHandler) Handle ¶
Handle implements slog.Handler.Handle.
func (*LegacyHandler) WithAttrs ¶
func (h *LegacyHandler) WithAttrs(attrs []slog.Attr) slog.Handler
WithAttrs implements slog.Handler.WithAttrs.
func (*LegacyHandler) WithGroup ¶
func (h *LegacyHandler) WithGroup(name string) slog.Handler
WithGroup implements slog.Handler.WithGroup.
type LegacyOption ¶
type LegacyOption func(handler *LegacyHandler)
LegacyOption is a function that applies options to a new LegacyHandler. Pass instances of this function to NewHandler. Use functions like TimestampFormat to generate callbacks to apply variable values. Applying LegacyOption values outside the context of NewHandler is not supported.
func Level ¶
func Level(level slog.Leveler) LegacyOption
Level returns a LegacyOption that will configure a handler to filter out messages with a level lower than the given level.
Example ¶
handler := nblog.NewHandler(os.Stdout,
nblog.Level(slog.LevelWarn),
nblog.ReplaceAttrs(UniformOutput),
)
logger := slog.New(handler)
logger.Info("info message")
logger.Warn("warning message")
Output: 2006-01-02 15:04:05.000 [42] <WARN> ExampleLevel: warning message
func NumericSeverity ¶
func NumericSeverity() LegacyOption
NumericSeverity configures a handler to record the log level as a number instead of a text label. Numbers used correspond to NetBackup severity levels, not slog levels:
- LevelDebug: 2 - LevelInfo: 4 - LevelWarn: 8 - LevelError: 16
func ReplaceAttrs ¶
func ReplaceAttrs(replaceAttr ReplaceAttrFunc) LegacyOption
ReplaceAttrs returns a LegacyOption that configures a handler to include the given ReplaceAttrFunc callback function while processing log attributes prior to being recorded. During log-formatting, callbacks are called in the order they're added to the handler.
func TimestampFormat ¶
func TimestampFormat(format string) LegacyOption
TimestampFormat returns a LegacyOption that will configure a handler to use the given time format (à la time.Time.Format) for log timestamps at the start of each record. If left unset, the default used will be FullDateFormat. The classic NetBackup format is TimeOnlyFormat; use that if log rotation would make the repeated inclusion of the date redundant.
Example ¶
handler := nblog.NewHandler(os.Stdout,
nblog.TimestampFormat(time.RFC850),
nblog.ReplaceAttrs(UniformOutput),
)
logger := slog.New(handler)
logger.Info("info message")
Output: Monday, 02-Jan-06 15:04:05 UTC [42] <INFO> ExampleTimestampFormat: info message
func UseFullCallerName ¶
func UseFullCallerName(use bool) LegacyOption
UseFullCallerName returns a LegacyOption that will configure a handler to include or omit the package-name portion of the caller in log messages. The default is to omit the package, so only the function name will appear.
Example (False) ¶
handler := nblog.NewHandler(os.Stdout,
nblog.UseFullCallerName(false),
nblog.ReplaceAttrs(UniformOutput),
)
logger := slog.New(handler)
logger.Info("info message")
Output: 2006-01-02 15:04:05.000 [42] <INFO> ExampleUseFullCallerName_false: info message
Example (True) ¶
handler := nblog.NewHandler(os.Stdout,
nblog.UseFullCallerName(true),
nblog.ReplaceAttrs(UniformOutput),
)
logger := slog.New(handler)
logger.Info("info")
Output: 2006-01-02 15:04:05.000 [42] <INFO> github.com/rkennedy/nblog_test.ExampleUseFullCallerName_true: info
type ReplaceAttrFunc ¶
ReplaceAttrFunc is the type of callback used with ReplaceAttrs to allow editing, replacing, or removing of attributes nefore a log record is recorded. The function will be called for each non-group attribute, along with a list of the currently nested groups. The function can return the original attribute to log it as-is, return a different attribute to use it instead, or return an attribute with an empty Key value to omit the current attribute entirely.
type TraceStopper ¶
type TraceStopper interface {
Stop()
}
TraceStopper is the interface returned by Trace to allow callers to stop the trace. Use it with defer. For example:
defer nblog.Trace(logger).Stop()
func Trace ¶
func Trace(logger *slog.Logger) TraceStopper
Trace marks the start of a function and returns a TraceStopper that can be used to mark the end of the function. Trace logs the message “Entered” to the logger. Afterward, [TraceStopper.Stop] logs the message “Exited” along with a “duration” attribute to indicate how long the function ran.
Example ¶
logger := slog.New(nblog.NewHandler(os.Stdout,
nblog.Level(slog.LevelDebug),
nblog.ReplaceAttrs(UniformOutput)))
defer nblog.Trace(logger).Stop()
logger.Info("message")
Output:
Source Files