logger

Documentation

Index

• Constants
• func MarshalJSONData(data interface{}) []byte
• func Scan(dst *Message, src Message)
• func ToString(msg Message, f Formatter) (s string, err error)
• func UnmarshalJSONData(data string) interface{}
• type Buffer
  • func NewBuffer(l LogMessager, options ...BufferOption) *Buffer
  • func (b *Buffer) Close() error
  • func (b *Buffer) LogMessage(ctx context.Context, m Message) error
  • func (b *Buffer) NewLogger(identifier string, logName string) *Logger
• type BufferOption
  • func BufferFlushTimeout(d time.Duration) BufferOption
  • func BufferSendTimeout(d time.Duration) BufferOption
  • func BufferSize(size int) BufferOption
  • func BufferTimeout(d time.Duration) BufferOption
• type Formatter
• type LogMessager
• type Logger
  • func New(identifier string, logName string, f MessageFunc) *Logger
  • func (l *Logger) Identifier() string
  • func (l *Logger) JSON(data interface{}, format string, v ...interface{})
  • func (l *Logger) JSONContext(ctx context.Context, data interface{}, format string, v ...interface{}) error
  • func (l *Logger) LogName() string
  • func (l *Logger) Print(v ...interface{})
  • func (l *Logger) PrintContext(ctx context.Context, v ...interface{}) error
  • func (l *Logger) Printf(format string, v ...interface{})
  • func (l *Logger) PrintfContext(ctx context.Context, format string, v ...interface{}) error
  • func (l *Logger) Println(v ...interface{})
  • func (l *Logger) PrintlnContext(ctx context.Context, v ...interface{}) error
  • func (l *Logger) String() string
• type Message
  • func FromString(s string, f Formatter) (Message, error)
  • func (m Message) MarshalJSON() ([]byte, error)
  • func (m Message) String() string
• type MessageFunc

Constants

const (
	DefaultBufferSize    = 1024
	DefaultBufferTimeout = 3 * time.Millisecond
	DefaultSendTimeout   = 5 * time.Second
	DefaultFlushTimeout  = 10 * time.Second
)

The default option values.

const (
	UnableToMarshal   = "Unable to convert data to JSON"
	UnableToUnmarshal = "Unable to convert data from JSON"
)

Standard strings used to replace data that fails to convert to/from JSON.

const DefaultFormat = defaultFormat(0)

DefaultFormat is the default Formatter for log messages. Messages are formatted as:

identifier:message [DATA:JSON-encoded data]

The identifier is the Identifier of the message (and may be an empty string), but with every occurrence of ":" escaped as "\:". The message is equal to the Message (and may be an empty string). Any occurrence of the substring "DATA:" in the message is escaped as "\DATA:". The finally DATA section will only be included if the message has non-empty Data, and is presented in compact JSON format.

Functions

func MarshalJSONData

func MarshalJSONData(data interface{}) []byte

MarshalJSONData marshals the given data to JSON. If the data will not marshal then a standard JSON-encoded error message is returned in its place.

func Scan

func Scan(dst *Message, src Message)

Scan copies the contents of the Message src into dest. Any previously set data in dest will be deleted or overwritten. Note that the Data will be a shallow copy.

func ToString

func ToString(msg Message, f Formatter) (s string, err error)

ToString converts the given Message to a string using the given formatter.

func UnmarshalJSONData

func UnmarshalJSONData(data string) interface{}

UnmarshalJSONData unmarshals the given data from JSON. If the data will not unmarshal then a standard error message is returned in its place.

Types

type Buffer

type Buffer struct {
	// contains filtered or unexported fields
}

Buffer provides a buffer around a LogMessager.

func NewBuffer

func NewBuffer(l LogMessager, options ...BufferOption) *Buffer

NewBuffer returns a buffered logger to l.

func (*Buffer) Close

func (b *Buffer) Close() error

Close flushes and closes the buffer, preventing any further messages from being submitted. If the wrapped LogMessager satisfies the io.Closer interface then its Close method will also be called.

func (*Buffer) LogMessage

func (b *Buffer) LogMessage(ctx context.Context, m Message) error

LogMessage attempts to submit the given message. Note that no return error does not guarantee that the message was sent: messages may be silently discarded to avoid blocking.

func (*Buffer) NewLogger

func (b *Buffer) NewLogger(identifier string, logName string) *Logger

NewLogger returns a new logger with given identifier and log name.

type BufferOption

type BufferOption interface {
	// contains filtered or unexported methods
}

BufferOption sets options on a Buffer.

func BufferFlushTimeout

func BufferFlushTimeout(d time.Duration) BufferOption

BufferFlushTimeout sets the timeout on flushing the buffer on Close.

func BufferSendTimeout

func BufferSendTimeout(d time.Duration) BufferOption

BufferSendTimeout sets the timeout on attempting to send a message to the wrapped LogMessager.

func BufferSize

func BufferSize(size int) BufferOption

BufferSize sets the size of the message buffer.

func BufferTimeout

func BufferTimeout(d time.Duration) BufferOption

BufferTimeout sets the timeout when attempting to add a message to a full buffer.

type Formatter

type Formatter interface {
	// WriteTo writes the given Message to w. The return value n is the
	// number of bytes written. Any error encountered during the write is also
	// returned.
	WriteTo(w io.Writer, msg Message) (n int64, err error)
	// Scan scans the given string s to the Message dest. Any previously set
	// data in dest will be deleted or overwritten.
	Scan(dest *Message, s string) error
}

Formatter provides a way of converting log messages to strings, and strings back to log messages.

type LogMessager

type LogMessager interface {
	LogMessage(context.Context, Message) error
}

LogMessager is the interface satisfied by a LogMessage method.

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger wraps a MessageFunc to provide a logger satisfying log.Interface.

func New

func New(identifier string, logName string, f MessageFunc) *Logger

New returns a new logger with given identifier and log name, where all generated log messages are passed to the given MessageFunc. A nil MessageFunc will discard all log messages.

func (*Logger) Identifier

func (l *Logger) Identifier() string

Identifier returns the identifier that will be included with every log message.

func (*Logger) JSON

func (l *Logger) JSON(data interface{}, format string, v ...interface{})

JSON prints a log message to the logger, including JSON data specified by the first argument. The first argument should be capable of being marshalled into JSON via json.Marshal in package "encoding/json". The last two arguments define a message to be logged alongside data, and are handled in the manner of fmt.Printf. The values passed in data overwrite any values with the same key names set using SetOption.

func (*Logger) JSONContext

func (l *Logger) JSONContext(ctx context.Context, data interface{}, format string, v ...interface{}) error

JSONContext is similar to JSON, except the provided context will be passed to the MessageFunc, and any error is returned.

func (*Logger) LogName

func (l *Logger) LogName() string

LogName returns the log name that will be included with every log message.

func (*Logger) Print

func (l *Logger) Print(v ...interface{})

Print logs the given message. Its arguments are handled in the manner of fmt.Print.

func (*Logger) PrintContext

func (l *Logger) PrintContext(ctx context.Context, v ...interface{}) error

PrintContext is similar to Print, except the provided context will be passed to the MessageFunc, and any error is returned.

func (*Logger) Printf

func (l *Logger) Printf(format string, v ...interface{})

Printf logs the given message. Its arguments are handled in the manner of fmt.Printf.

func (*Logger) PrintfContext

func (l *Logger) PrintfContext(ctx context.Context, format string, v ...interface{}) error

PrintfContext is similar to Printf, except the provided context will be passed to the MessageFunc, and any error is returned.

func (*Logger) Println

func (l *Logger) Println(v ...interface{})

Println logs the given message. Its arguments are handled in the manner of fmt.Println.

func (*Logger) PrintlnContext

func (l *Logger) PrintlnContext(ctx context.Context, v ...interface{}) error

PrintlnContext is similar to Println, except the provided context will be passed to the MessageFunc, and any error is returned.

func (*Logger) String

func (l *Logger) String() string

String returns a string representation of the logger.

type Message

type Message struct {
	Identifier string      // The process name
	LogName    string      // The destination log
	Message    string      // The message
	Data       interface{} // Optional extra data
}

Message describes a log message.

func FromString

func FromString(s string, f Formatter) (Message, error)

FromString converts the given string to a Message using the given formatter.

func (Message) MarshalJSON

func (m Message) MarshalJSON() ([]byte, error)

MarshalJSON returns a JSON description of the Message.

func (Message) String

func (m Message) String() string

String returns a string description of the Message.

type MessageFunc

type MessageFunc func(ctx context.Context, m Message) error

MessageFunc can be called to log a message. Note that no return error does not guarantee that the message was logged: a MessageFunc is free to silently discarded messages rather than block.