github.com/mongodb/grip@v0.0.0-20240213223901-f906268d82b9/send/interface.go (about)

     1  // Package send provides an interface for defining "senders" for
     2  // different logging backends, as well as basic implementations for
     3  // common logging approaches to use with the Grip logging
     4  // interface. Backends currently include: syslog, systemd's journal,
     5  // standard output, and file baased methods.
     6  package send
     7  
     8  import (
     9  	"context"
    10  	"log"
    11  
    12  	"github.com/mongodb/grip/level"
    13  	"github.com/mongodb/grip/message"
    14  )
    15  
    16  // The Sender interface describes how the Journaler type's method in primary
    17  // "grip" package's methods interact with a logging output method. The
    18  // Journaler type provides Sender() and SetSender() methods that allow client
    19  // code to swap logging backend implementations dependency-injection style.
    20  type Sender interface {
    21  	// Name returns the name of the logging system. Typically this
    22  	// corresponds directly with the underlying logging capture system.
    23  	Name() string
    24  	//SetName sets the name of the logging system.
    25  	SetName(string)
    26  
    27  	// Method that actually sends messages (the string) to the logging
    28  	// capture system. The Send() method filters out logged messages based
    29  	// based on priority, typically using the generic
    30  	// MessageInfo.ShouldLog() function.
    31  	Send(message.Composer)
    32  
    33  	// Flush flushes any potential buffered messages to the logging capture
    34  	// system. If the Sender is not buffered, this function should noop and
    35  	// return nil.
    36  	Flush(context.Context) error
    37  
    38  	// SetLevel allows you to modify the level configuration. Returns an
    39  	// error if you specify impossible values.
    40  	SetLevel(LevelInfo) error
    41  
    42  	// Level returns the level configuration document.
    43  	Level() LevelInfo
    44  
    45  	// SetErrorHandler provides a method to inject error handling behavior
    46  	// to a sender. Not all sender implementations use the error handler,
    47  	// although some, use a default handler to write logging errors to
    48  	// standard output.
    49  	SetErrorHandler(ErrorHandler) error
    50  	ErrorHandler() ErrorHandler
    51  
    52  	// SetFormatter allows users to inject formatting functions to modify
    53  	// the output of the log sender by providing a function that takes a
    54  	// message and returns string and error.
    55  	SetFormatter(MessageFormatter) error
    56  	Formatter() MessageFormatter
    57  
    58  	// If the logging sender holds any resources that require desecration
    59  	// they should be cleaned up in the Close() method. Close() is called
    60  	// by the SetSender() method before changing loggers. Sender implementations
    61  	// that wrap other Senders may or may not close their underlying Senders.
    62  	Close() error
    63  }
    64  
    65  // LevelInfo provides a sender-independent structure for storing information
    66  // about a sender's configured log levels.
    67  type LevelInfo struct {
    68  	Default   level.Priority `json:"default" bson:"default"`
    69  	Threshold level.Priority `json:"threshold" bson:"threshold"`
    70  }
    71  
    72  // Valid checks that the priorities stored in the LevelInfo document are valid.
    73  func (l LevelInfo) Valid() bool { return l.Default.IsValid() && l.Threshold.IsValid() }
    74  
    75  // ShouldLog checks to see if the log message should be logged, and returns
    76  // false if there is no message or if the message's priority is below the
    77  // logging threshold.
    78  func (l LevelInfo) ShouldLog(m message.Composer) bool {
    79  	// priorities are 0 = Emergency; 7 = debug
    80  	return m.Loggable() && (m.Priority() >= l.Threshold)
    81  }
    82  
    83  func setup(s Sender, name string, l LevelInfo) (Sender, error) {
    84  	if err := s.SetLevel(l); err != nil {
    85  		return nil, err
    86  	}
    87  
    88  	s.SetName(name)
    89  
    90  	return s, nil
    91  }
    92  
    93  // MakeStandardLogger creates a standard library logging instance that logs all
    94  // messages to the underlying sender directly at the specified level.
    95  func MakeStandardLogger(s Sender, p level.Priority) *log.Logger {
    96  	return log.New(MakeWriterSender(s, p), "", 0)
    97  }