send

package
v0.0.0-...-863240d Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 14, 2022 License: Apache-2.0 Imports: 34 Imported by: 0

Documentation

Overview

Call Site Sender

Call site loggers provide a way to record the line number and file name where the logging call was made, which is particularly useful in tracing down log messages.

This sender does *not* attach this data to the Message object, and the call site information is only logged when formatting the message itself. Additionally the call site includes the file name and its enclosing directory.

When constructing the Sender you must specify a "depth" argument This sets the offset for the call site relative to the Sender's Send() method. Grip's default logger (e.g. the grip.Info() methods and friends) requires a depth of 2, while in *most* other cases you will want to use a depth of 1. The LogMany, and Emergency[Panic,Fatal] methods also include an extra level of indirection.

Create a call site logger with one of the following constructors: 

NewCallSiteConsoleLogger(<name>, <depth>, <LevelInfo>)
MakeCallSiteConsoleLogger(<depth>)
NewCallSiteFileLogger(<name>, <fileName>, <depth>, <LevelInfo>)
MakeCallSiteFileLogger(<fileName>, <depth>)

Package send provides an interface for defining "senders" for different logging backends, as well as basic implementations for common logging approaches to use with the Grip logging interface. Backends currently include: syslog, systemd's journal, standard output, and file baased methods.

Index

Constants

This section is empty.

Variables

View Source 
var ErrorTruncated = errors.New("buffer was truncated")

ErrorTruncated means that the limited buffer capacity was overwritten.

Functions

func AddToMulti 

func AddToMulti(multi Sender, s Sender) error

AddToMulti is a helper function that takes two Sender instances, the first of which must be a multi sender. If this is true, then AddToMulti adds the second Sender to the first Sender's list of Senders.

Returns an error if the first instance is not a multi sender.

func MakeStandardLogger 

func MakeStandardLogger(s Sender, p level.Priority) *log.Logger

MakeStandardLogger creates a standard library logging instance that logs all messages to the underlying sender directly at the specified level.

Types

type Base 

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

Base provides most of the functionality of the Sender interface, except for the Send method, to facilitate writing novel Sender implementations. All implementations of the functions

func MakeBase 

func MakeBase(n string, reseter func(), closer func() error) *Base

MakeBase constructs a Base structure that allows callers to specify the reset and caller function.

func NewBase 

func NewBase(n string) *Base

NewBase constructs a basic Base structure with no op functions for reset, close, and error handling.

func (*Base) Close 

func (b *Base) Close() error

Close calls the closer function if it is defined and it has not already been closed.

func (*Base) ErrorHandler 

func (b *Base) ErrorHandler() ErrorHandler

ErrorHandler returns an error handling functioncalls the error handler, and is a wrapper around the embedded ErrorHandler function.

func (*Base) Flush 

func (b *Base) Flush(ctx context.Context) error

Flush provides a default implementation of the Flush method for senders that don't cache messages locally.

func (*Base) Formatter 

func (b *Base) Formatter() MessageFormatter

Formatter returns the formatter, defaulting to using the string form of the message if no formatter is configured.

func (*Base) Level 

func (b *Base) Level() LevelInfo

Level reports the currently configured level for the Sender.

func (*Base) Name 

func (b *Base) Name() string

Name returns the name of the Sender.

func (*Base) SetErrorHandler 

func (b *Base) SetErrorHandler(eh ErrorHandler) error

SetErrorHandler configures the error handling function for this Sender.

func (*Base) SetFormatter 

func (b *Base) SetFormatter(mf MessageFormatter) error

SetFormatter users to set the formatting function used to construct log messages.

func (*Base) SetLevel 

func (b *Base) SetLevel(l LevelInfo) error

SetLevel configures the level (default levels and threshold levels) for the Sender.

func (*Base) SetName 

func (b *Base) SetName(name string)

SetName allows clients to change the name of the Sender.

type BuildloggerConfig 

type BuildloggerConfig struct {
	// CreateTest controls
	CreateTest bool   `json:"create_test" bson:"create_test"`
	URL        string `json:"url" bson:"url"`

	// The following values are used by the buildlogger service to
	// attach metadata to the logs. The GetBuildloggerConfig
	// method populates Number, Phase, Builder, and Test from
	// environment variables, though you can set them directly in
	// your application. You must set the Command value directly.
	Number  int    `json:"number" bson:"number"`
	Phase   string `json:"phase" bson:"phase"`
	Builder string `json:"builder" bson:"builder"`
	Test    string `json:"test" bson:"test"`
	Command string `json:"command" bson:"command"`

	// Configure a local sender for "fallback" operations and to
	// collect the location (URLS) of the buildlogger output
	Local Sender `json:"-" bson:"-"`
	// contains filtered or unexported fields
}

BuildloggerConfig describes the configuration needed for a Sender instance that posts log messages to a buildlogger service (e.g. logkeeper.)

func GetBuildloggerConfig 

func GetBuildloggerConfig() (*BuildloggerConfig, error)

GetBuildloggerConfig produces a BuildloggerConfig object, reading default values from environment variables, although you can set these options yourself.

You must also populate the credentials seperatly using either the ReadCredentialsFromFile or SetCredentials methods. If the BUILDLOGGER_CREDENTIALS environment variable is set, GetBuildloggerConfig will read credentials from this file.

Buildlogger has a concept of a build, with a global log, as well as subsidiary "test" logs. To exercise this functionality, you will use a single Buildlogger config instance to create individual Sender instances that target each of these output formats.

The Buildlogger config has a Local attribute which is used by the logger config when: the Buildlogger instance cannot contact the messages sent to the buildlogger. Additional the Local Sender also logs the remote location of the build logs. This Sender implementation is used in the default ErrorHandler for this implementation.

Create a BuildloggerConfig instance, set up the crednetials if needed, and create a sender. This will be the "global" log, in buildlogger terminology. Then, set set the CreateTest attribute, and generate additional per-test senders. For example: 

conf := GetBuildloggerConfig()
global := MakeBuildlogger("<name>-global", conf)
// ... use global
conf.CreateTest = true
testOne := MakeBuildlogger("<name>-testOne", conf)

func (*BuildloggerConfig) GetBuildID 

func (c *BuildloggerConfig) GetBuildID() string

GetBuildID returns the build ID for the log currently in use.

func (*BuildloggerConfig) GetGlobalLogURL 

func (c *BuildloggerConfig) GetGlobalLogURL() string

GetGlobalLogURL returns the URL for the current global log in use. Must use after constructing the buildlogger instance.

func (*BuildloggerConfig) GetTestID 

func (c *BuildloggerConfig) GetTestID() string

GetTestID returns the test ID for the log currently in use.

func (*BuildloggerConfig) GetTestLogURL 

func (c *BuildloggerConfig) GetTestLogURL() string

GetTestLogURL returns the current URL for the test log currently in use. Must use after constructing the buildlogger instance.

func (*BuildloggerConfig) ReadCredentialsFromFile 

func (c *BuildloggerConfig) ReadCredentialsFromFile(fn string) error

ReadCredentialsFromFile parses a JSON file for buildlogger credentials and updates the config.

func (*BuildloggerConfig) SetCredentials 

func (c *BuildloggerConfig) SetCredentials(username, password string)

SetCredentials configures the username and password of the BuildLoggerConfig object. Use to programatically update the credentials in a configuration object instead of reading from the credentials file with ReadCredentialsFromFile(),

type ErrorHandler 

type ErrorHandler func(error, message.Composer)

ErrorHandler is a function that you can use define how a sender handles errors sending messages. Implementations of this type should perform a noop if the err object is nil.

func ErrorHandlerFromLogger 

func ErrorHandlerFromLogger(l *log.Logger) ErrorHandler

func ErrorHandlerFromSender 

func ErrorHandlerFromSender(s Sender) ErrorHandler

ErrorHandlerFromSender wraps an existing Sender for sending error messages.

type InMemorySender 

type InMemorySender struct {
	Base
	// contains filtered or unexported fields
}

InMemorySender represents an in-memory buffered sender with a fixed message capacity.

func (*InMemorySender) Get 

func (s *InMemorySender) Get() []message.Composer

Get returns all the current messages in the buffer.

func (*InMemorySender) GetCount 

func (s *InMemorySender) GetCount(count int) ([]message.Composer, int, error)

GetCount returns at most count messages in the buffer as a stream. It returns the messages and the number of messages returned. If the function is called and reaches the end of the buffer, it returns io.EOF. If the position it is currently reading at has been truncated, this returns ErrorTruncated. To continue reading, the read stream must be reset using ResetRead.

func (*InMemorySender) GetRaw 

func (s *InMemorySender) GetRaw() []interface{}

GetRaw returns all the current messages in the buffer as empty interfaces.

func (*InMemorySender) GetString 

func (s *InMemorySender) GetString() ([]string, error)

GetString returns all the current messages in the buffer as formatted strings.

func (*InMemorySender) ResetRead 

func (s *InMemorySender) ResetRead()

ResetRead resets the read stream used in GetCount.

func (*InMemorySender) Send 

func (s *InMemorySender) Send(msg message.Composer)

Send adds the given message to the buffer. If the buffer is at max capacity, it truncates the oldest message.

func (*InMemorySender) TotalBytesSent 

func (s *InMemorySender) TotalBytesSent() int64

TotalBytesSent returns the total number of bytes sent.

type InternalMessage 

type InternalMessage struct {
	Message message.Composer

	Level    LevelInfo
	Logged   bool
	Priority level.Priority
	Rendered string
}

InternalMessage provides a complete representation of all information associated with a logging event.

type InternalSender 

type InternalSender struct {
	*Base
	// contains filtered or unexported fields
}

InternalSender implements a Sender object that makes it possible to access logging messages, in the InternalMessage format without logging to an output method. The Send method does not filter out under-priority and unloggable messages. Used for testing purposes.

func MakeInternalLogger 

func MakeInternalLogger() *InternalSender

MakeInternalLogger constructs an internal sender object, typically for use in testing.

func NewInternalLogger 

func NewInternalLogger(name string, l LevelInfo) (*InternalSender, error)

NewInternalLogger creates and returns a Sender implementation that does not log messages, but converts them to the InternalMessage format and puts them into an internal channel, that allows you to access the massages via the extra "GetMessage" method. Useful for testing.

func (*InternalSender) GetMessage 

func (s *InternalSender) GetMessage() *InternalMessage

GetMessage pops the first message in the queue and returns.

func (*InternalSender) GetMessageSafe 

func (s *InternalSender) GetMessageSafe() (*InternalMessage, bool)

func (*InternalSender) HasMessage 

func (s *InternalSender) HasMessage() bool

HasMessage returns true if there is at least one message that has not be removed.

func (*InternalSender) Len 

func (s *InternalSender) Len() int

Len returns the number of sent messages that have not been retrieved.

func (*InternalSender) Send 

func (s *InternalSender) Send(m message.Composer)

Send sends a message. Unlike all other sender implementations, all messages are sent, but the InternalMessage format tracks "loggability" for testing purposes.

type LevelInfo 

type LevelInfo struct {
	Default   level.Priority `json:"default" bson:"default"`
	Threshold level.Priority `json:"threshold" bson:"threshold"`
}

LevelInfo provides a sender-independent structure for storing information about a sender's configured log levels.

func (LevelInfo) Loggable 

func (l LevelInfo) Loggable(p level.Priority) bool

Loggable returns true only when passed an argument that is equal to or greater than the threshold.

func (LevelInfo) ShouldLog 

func (l LevelInfo) ShouldLog(m message.Composer) bool

ShouldLog checks to see if the log message should be logged, and returns false if there is no message or if the message's priority is below the logging threshold.

This calls the messages' Loggable method.

func (LevelInfo) Valid 

func (l LevelInfo) Valid() bool

Valid checks that the priorities stored in the LevelInfo document are valid.

type MessageFormatter 

type MessageFormatter func(message.Composer) (string, error)

MessageFormatter is a function type used by senders to construct the entire string returned as part of the output. This makes it possible to modify the logging format without needing to implement new Sender interfaces.

func MakeCallSiteFormatter 

func MakeCallSiteFormatter(depth int) MessageFormatter

MakeCallSiteFormatter returns a MessageFormater that formats messages with the following format: 

[p=<levvel>] [<fileName>:<lineNumber>]: <message>

It can never error.

func MakeDefaultFormatter 

func MakeDefaultFormatter() MessageFormatter

MakeDefaultFormatter returns a MessageFormatter that will produce a message in the following format: 

[p=<level>]: <message>

It can never error.

func MakeJSONFormatter 

func MakeJSONFormatter() MessageFormatter

MakeJSONFormatter returns a MessageFormatter, that returns messages as the string form of a JSON document built using the Raw method of the Composer. Returns an error if there was a problem marshalling JSON.

func MakePlainFormatter 

func MakePlainFormatter() MessageFormatter

MakePlainFormatter returns a MessageFormatter that simply returns the string format of the log message.

func MakeXMPPFormatter 

func MakeXMPPFormatter(name string) MessageFormatter

MakeXMPPFormatter returns a MessageFormatter that will produce messages in the following format, used primarily by the xmpp logger: 

[<name>] (p=<priority>) <message>

It can never error.

type SMTPOptions 

type SMTPOptions struct {
	// Name controls both the name of the logger, and the name on
	// the from header field.
	Name string
	// From specifies the address specified.
	From string
	// Server, Port, and UseSSL control how we connect to the SMTP
	// server. If unspecified, these options default to
	// "localhost", port, and false.
	Server string
	Port   int
	UseSSL bool
	// Username and password define how the client authenticates
	// to the SMTP server. If no Username is specified, the client
	// will not authenticate to the server.
	Username string
	Password string

	// These options control the output behavior. You must specify
	// a subject for the emails, *or* one of the bool options that
	// specify how to generate the subject (e.g. NameAsSubject,
	// MessageAsSubject) you can specify a non-zero value to
	// TruncatedMessageSubjectLength to use a fragment of the
	// message as the subject. The use of these options is
	// depended on the implementation of the GetContents function.
	//
	// The GetContents function returns a pair of strings (subject,
	// body), and defaults to an implementation that generates a
	// plain text email according to the (Subject,
	// TruncatedMessageSubjectLength, NameAsSubject, and
	// MessageAsSubject). If you use the default GetContents
	// implementation, PlainTextContents is set to false.
	//
	// You can define your own implementation of the GetContents
	// function, to use a template, or to generate an HTML email
	// as needed, you must also set PlainTextContents as needed.
	GetContents                   func(*SMTPOptions, message.Composer) (string, string)
	Subject                       string
	TruncatedMessageSubjectLength int
	NameAsSubject                 bool
	MessageAsSubject              bool
	PlainTextContents             bool
	// contains filtered or unexported fields
}

SMTPOptions configures the behavior of the SMTP logger. There is no explicit constructor; however, the Validate method (which is called by the Sender's constructor) checks for incomplete configuration and sets default options if they are unset.

In additional to constructing this object with the necessary options. You must also set at least one recipient address using the AddRecipient or AddRecipients functions. You can add or reset the recipients after configuring the options or the sender.

func (*SMTPOptions) AddRecipient 

func (o *SMTPOptions) AddRecipient(name, address string) error

AddRecipient takes a name and email address as an argument and attempts to parse a valid email address from this data, and if valid adds this email address.

func (*SMTPOptions) AddRecipients 

func (o *SMTPOptions) AddRecipients(addresses ...string) error

AddRecipients accepts one or more string that can be, itself, comma separated lists of email addresses, which are then added to the recipients for the logger.

func (*SMTPOptions) ResetRecipients 

func (o *SMTPOptions) ResetRecipients()

ResetRecipients removes all recipients from the configuration object. You can reset the recipients at any time, but you must have at least one recipient configured when you use this options object to configure a sender *or* attempt to send a message.

func (*SMTPOptions) Validate 

func (o *SMTPOptions) Validate() error

Validate checks the contents of the SMTPOptions struct and sets default values in appropriate cases. Returns an error if the struct is not valid. The constructor for the SMTP sender calls this method to make sure that options struct is valid before initiating the sender.

type Sender 

type Sender interface {
	// Name returns the name of the logging system. Typically this
	// corresponds directly with the underlying logging capture system.
	Name() string
	//SetName sets the name of the logging system.
	SetName(string)

	// Method that actually sends messages (the string) to the logging
	// capture system. The Send() method filters out logged messages based
	// based on priority, typically using the generic
	// MessageInfo.ShouldLog() function.
	Send(message.Composer)

	// Flush flushes any potential buffered messages to the logging capture
	// system. If the Sender is not buffered, this function should noop and
	// return nil.
	Flush(context.Context) error

	// SetLevel allows you to modify the level configuration. Returns an
	// error if you specify impossible values.
	SetLevel(LevelInfo) error

	// Level returns the level configuration document.
	Level() LevelInfo

	// SetErrorHandler provides a method to inject error handling behavior
	// to a sender. Not all sender implementations use the error handler,
	// although some, use a default handler to write logging errors to
	// standard output.
	SetErrorHandler(ErrorHandler) error
	ErrorHandler() ErrorHandler

	// SetFormatter allows users to inject formatting functions to modify
	// the output of the log sender by providing a function that takes a
	// message and returns string and error.
	SetFormatter(MessageFormatter) error
	Formatter() MessageFormatter

	// If the logging sender holds any resources that require desecration
	// they should be cleaned up in the Close() method. Close() is called
	// by the SetSender() method before changing loggers. Sender implementations
	// that wrap other Senders may or may not close their underlying Senders.
	Close() error
}

The Sender interface describes how the Journaler type's method in primary "grip" package's methods interact with a logging output method. The Journaler type provides Sender() and SetSender() methods that allow client code to swap logging backend implementations dependency-injection style.

func MakeBuildlogger 

func MakeBuildlogger(name string, conf *BuildloggerConfig) (Sender, error)

MakeBuildlogger constructs a buildlogger targeting sender using the BuildloggerConfig object for configuration. Generally you will create a "global" instance, and then several subsidiary Senders that target specific tests. See the documentation of GetBuildloggerConfig for more information.

Upon creating a logger, this method will write, to standard out, the URL that you can use to view the logs produced by this Sender.

func MakeCallSiteConsoleLogger 

func MakeCallSiteConsoleLogger(depth int) Sender

MakeCallSiteConsoleLogger constructs an unconfigured call site logger that writes output to standard output. You must set the name of the logger using SetName or your Journaler's SetSender method before using this logger.

func MakeCallSiteFileLogger 

func MakeCallSiteFileLogger(fileName string, depth int) (Sender, error)

MakeCallSiteFileLogger constructs an unconfigured call site logger that writes output to the specified hours. You must set the name of the logger using SetName or your Journaler's SetSender method before using this logger.

func MakeDefaultSystem 

func MakeDefaultSystem() (Sender, error)

MakeDefaultSystem constructs a default logger that pushes to systemd on platforms where that's available and standard output otherwise.

func MakeDesktopNotify 

func MakeDesktopNotify(name string) (Sender, error)

MakeDesktopNotify constructs a default sender that pushes messages to local system notification.

func MakeErrorLogger 

func MakeErrorLogger() Sender

MakeErrorLogger returns an unconfigured Sender implementation that writes all logging output to standard error.

func MakeFileLogger 

func MakeFileLogger(filePath string) (Sender, error)

MakeFileLogger creates a file-based logger, writing output to the specified file. The Sender instance is not configured: Pass to Journaler.SetSender or call SetName before using.

func MakeJSONConsoleLogger 

func MakeJSONConsoleLogger() Sender

MakeJSONConsoleLogger returns an un-configured JSON console logging instance.

func MakeJSONFileLogger 

func MakeJSONFileLogger(file string) (Sender, error)

MakeJSONFileLogger creates an un-configured JSON logger that writes output to the specified file.

func MakeLocalSyslogLogger 

func MakeLocalSyslogLogger() Sender

MakeLocalSyslogLogger is a constructor for creating the same kind of Sender instance as NewSyslogLogger, except connecting directly to the local syslog service. If there is no local syslog service, or there are issues connecting to it, writes logging messages to standard error. Pass to Journaler.SetSender or call SetName before using.

func MakeNative 

func MakeNative() Sender

MakeNative returns an unconfigured native standard-out logger. You *must* call SetName on this instance before using it. (Journaler's SetSender will typically do this.)

func MakePlainErrorLogger 

func MakePlainErrorLogger() Sender

MakePlainErrorLogger returns an unconfigured sender without a prefix, using the plain log formatter. This Sender writes all output to standard error.

func MakePlainFileLogger 

func MakePlainFileLogger(filePath string) (Sender, error)

MakePlainFileLogger writes all output to a file, but does not prepend any log formatting to each message.

func MakePlainLogger 

func MakePlainLogger() Sender

MakePlainLogger returns an unconfigured sender without a prefix, using the plain log formatter. This Sender writes all output to standard error.

func MakeSMTPLogger 

func MakeSMTPLogger(opts *SMTPOptions) (Sender, error)

MakeSMTPLogger constructs an unconfigured (e.g. without level information) SMTP Sender implementation that delivers mail for every loggable message. The configuration of the outgoing SMTP server, and the formatting of the log message is handled by the SMTPOptions structure, which you must use to configure this sender.

func MakeSlackLogger 

func MakeSlackLogger(opts *SlackOptions) (Sender, error)

MakeSlackLogger is equivalent to NewSlackLogger, but constructs a Sender reading the slack token from the environment variable "GRIP_SLACK_CLIENT_TOKEN".

func MakeSplunkLogger 

func MakeSplunkLogger(name string) (Sender, error)

MakeSplunkLogger constructs a new Sender implementation that reads the hostname, username, and password from environment variables: 

GRIP_SPLUNK_SERVER_URL
GRIP_SPLUNK_CLIENT_TOKEN
GRIP_SPLUNK_CLIENT_CHANNEL

func MakeSplunkLoggerWithClient 

func MakeSplunkLoggerWithClient(name string, client *http.Client) (Sender, error)

MakeSplunkLoggerWithClient is identical to MakeSplunkLogger but allows you to pass in a http.Client.

func MakeStreamLogger 

func MakeStreamLogger(ws WriteStringer) Sender

MakeStreamLogger constructs an unconfigured stream sender that writes un-formatted log messages to the specified io.Writer, or instance that implements a conforming subset.

func MakeSysLogger 

func MakeSysLogger(network, raddr string) Sender

MakeSysLogger constructs a minimal and unconfigured logger that posts to systemd's journal. Pass to Journaler.SetSender or call SetName before using.

func MakeSystemdLogger 

func MakeSystemdLogger() (Sender, error)

MakeSystemdLogger constructs an unconfigured systemd journald logger. Pass to Journaler.SetSender or call SetName before using.

func MakeTesting 

func MakeTesting(t *testing.T, name string, l LevelInfo) Sender

MakeTesting produces a sender implementation that logs using the testing.T's logging facility for better integration with unit tests. Construct and register such a sender for grip.Journaler instances that you use inside of tests to have logging that correctly respects go test's verbosity.

func MakeTwitterLogger 

func MakeTwitterLogger(ctx context.Context, opts *TwitterOptions) (Sender, error)

MakeTwitterLogger constructs a default sender implementation that posts messages to a twitter account. The implementation does not rate limit outgoing messages, which should be the responsibility of the caller.

func MakeXMPP 

func MakeXMPP(target string) (Sender, error)

MakeXMPP constructs an XMPP logging backend that reads the hostname, username, and password from environment variables:

  • GRIP_XMPP_HOSTNAME
  • GRIP_XMPP_USERNAME
  • GRIP_XMPP_PASSWORD

The instance is otherwise unconquered. Call SetName or inject it into a Journaler instance using SetSender before using.

func NewAnnotatingSender 

func NewAnnotatingSender(s Sender, annotations map[string]interface{}) Sender

NewAnnotatingSender adds the annotations defined in the annotations map to every argument.

Calling code should assume that the sender owns the annotations map and it should not attempt to modify that data after calling the sender constructor. Furthermore, since it owns the sender, callin Close on this sender will close the underlying sender.

While you can wrap an existing sender with the annotator, changes to the annotating sender (e.g. level, formater, error handler) will propagate to the embedded sender.

func NewAsyncGroupSender 

func NewAsyncGroupSender(ctx context.Context, bufferSize int, senders ...Sender) Sender

NewAsyncGroupSender produces an implementation of the Sender interface that, like the MultiSender, distributes a single message to a group of underlying sender implementations.

This sender does not guarantee ordering of messages, and Send operations may if the underlying senders fall behind the buffer size.

The sender takes ownership of the underlying Senders, so closing this sender closes all underlying Senders.

func NewBufferedSender 

func NewBufferedSender(sender Sender, interval time.Duration, size int) Sender

NewBufferedSender provides a Sender implementation that wraps an existing Sender sending messages in batches, on a specified buffer size or after an interval has passed.

If the interval is 0, the constructor sets an interval of 1 minute, and if it is less than 5 seconds, the constructor sets it to 5 seconds. If the size threshold is 0, then the constructor sets a threshold of 100.

This Sender does not own the underlying Sender, so users are responsible for closing the underlying Sender if/when it is appropriate to release its resources.

func NewBuildlogger 

func NewBuildlogger(name string, conf *BuildloggerConfig, l LevelInfo) (Sender, error)

NewBuildlogger constructs a Buildlogger-targeted Sender, with level information set. See MakeBuildlogger and GetBuildloggerConfig for more information.

func NewCallSiteConsoleLogger 

func NewCallSiteConsoleLogger(name string, depth int, l LevelInfo) (Sender, error)

NewCallSiteConsoleLogger returns a fully configured Sender implementation that writes log messages to standard output in a format that includes the filename and line number of the call site of the logger.

func NewCallSiteFileLogger 

func NewCallSiteFileLogger(name, fileName string, depth int, l LevelInfo) (Sender, error)

NewCallSiteFileLogger returns a fully configured Sender implementation that writes log messages to a specified file in a format that includes the filename and line number of the call site of the logger.

func NewConfiguredMultiSender 

func NewConfiguredMultiSender(senders ...Sender) Sender

NewConfiguredMultiSender returns a multi sender implementation with Sender members, but does not force the senders to have conforming name or level values. Use NewMultiSender to construct a list of senders with consistent names and level configurations.

Use the AddToMulti helper to add additioanl senders to one of these multi Sender implementations after construction.

The Sender takes ownership of the underlying Senders, so closing this Sender closes all underlying Senders.

func NewDesktopNotify 

func NewDesktopNotify(name string, l LevelInfo) (Sender, error)

NewDesktopNotify constructs a sender that pushes messages to local system notification process.

func NewErrorLogger 

func NewErrorLogger(name string, l LevelInfo) (Sender, error)

NewErrorLogger constructs a configured Sender that writes all output to standard error.

func NewFileLogger 

func NewFileLogger(name, filePath string, l LevelInfo) (Sender, error)

NewFileLogger creates a Sender implementation that writes log output to a file. Returns an error but falls back to a standard output logger if there's problems with the file. Internally using the go standard library logging system.

func NewInMemorySender 

func NewInMemorySender(name string, info LevelInfo, capacity int) (Sender, error)

NewInMemorySender creates an in-memory buffered sender with the given capacity.

func NewInterceptor 

func NewInterceptor(sender Sender, ifn func(message.Composer)) Sender

NewInterceptor constructs an intercepting sender implementation that wraps another sender, and passes all messages (regardless of loggability or level,) through a filtering function.

This implementation and the filtering function exist mostly to be able to inject metrics collection into existing logging pipelines, though the interceptor may be used for filtering or pre-processing as well.

func NewJSONConsoleLogger 

func NewJSONConsoleLogger(name string, l LevelInfo) (Sender, error)

NewJSONConsoleLogger builds a Sender instance that prints log messages in a JSON formatted to standard output. The JSON formated message is taken by calling the Raw() method on the message.Composer and Marshalling the results.

func NewJSONFileLogger 

func NewJSONFileLogger(name, file string, l LevelInfo) (Sender, error)

NewJSONFileLogger builds a Sender instance that write JSON formated log messages to a file, with one-line per message. The JSON formated message is taken by calling the Raw() method on the message.Composer and Marshalling the results.

func NewMultiSender 

func NewMultiSender(name string, l LevelInfo, senders []Sender) (Sender, error)

NewMultiSender configures a new sender implementation that takes a slice of Sender implementations that dispatches all messages to all implementations. This constructor forces all member Senders to have the same name and Level configuration. Use NewConfiguredMultiSender to construct a similar Sender

Use the AddToMulti helper to add additioanl senders to one of these multi Sender implementations after construction.

The Sender takes ownership of the underlying Senders, so closing this Sender closes all underlying Senders.

func NewNativeLogger 

func NewNativeLogger(name string, l LevelInfo) (Sender, error)

NewNativeLogger creates a new Sender interface that writes all loggable messages to a standard output logger that uses Go's standard library logging system.

func NewPlainErrorLogger 

func NewPlainErrorLogger(name string, l LevelInfo) (Sender, error)

NewPlainErrorLogger returns a configured sender that has no prefix and uses a plain formatter for messages, using only the string format for each message. This sender writes all output to standard error.

func NewPlainFileLogger 

func NewPlainFileLogger(name, file string, l LevelInfo) (Sender, error)

NewPlainFileLogger creates a new configured logger that writes log data to a file.

func NewPlainLogger 

func NewPlainLogger(name string, l LevelInfo) (Sender, error)

NewPlainLogger returns a configured sender that has no prefix and uses a plain formatter for messages, using only the string format for each message. This sender writes all output to standard output.

func NewSMTPLogger 

func NewSMTPLogger(opts *SMTPOptions, l LevelInfo) (Sender, error)

NewSMTPLogger constructs a Sender implementation that delivers mail for every loggable message. The configuration of the outgoing SMTP server, and the formatting of the log message is handled by the SMTPOptions structure, which you must use to configure this sender.

func NewSlackLogger 

func NewSlackLogger(opts *SlackOptions, token string, l LevelInfo) (Sender, error)

NewSlackLogger constructs a Sender that posts messages to a slack, given a slack API token. Configure the slack sender using a SlackOptions struct.

func NewSplunkLogger 

func NewSplunkLogger(name string, info SplunkConnectionInfo, l LevelInfo) (Sender, error)

NewSplunkLogger constructs a new Sender implementation that sends messages to a Splunk event collector using the credentials specified in the SplunkConnectionInfo struct.

func NewSplunkLoggerWithClient 

func NewSplunkLoggerWithClient(name string, info SplunkConnectionInfo, l LevelInfo, client *http.Client) (Sender, error)

NewSplunkLoggerWithClient makes it possible to pass an existing http.Client to the splunk instance, but is otherwise identical to NewSplunkLogger.

func NewStreamLogger 

func NewStreamLogger(name string, ws WriteStringer, l LevelInfo) (Sender, error)

NewStreamLogger produces a fully configured Sender that writes un-formatted log messages to an io.Writer (or conforming subset).

func NewSyslogLogger 

func NewSyslogLogger(name, network, raddr string, l LevelInfo) (Sender, error)

NewSyslogLogger creates a new Sender object that writes all loggable messages to a syslog instance on the specified network. Uses the Go standard library syslog implementation that is only available on Unix systems. Use this constructor to return a connection to a remote Syslog interface, but will fall back first to the local syslog interface before writing messages to standard output.

func NewSystemdLogger 

func NewSystemdLogger(name string, l LevelInfo) (Sender, error)

NewSystemdLogger creates a Sender object that writes log messages to the system's systemd journald logging facility. If there's an error with the sending to the journald, messages fallback to writing to standard output.

func NewTesting 

func NewTesting(t *testing.T) Sender

NewTesting constructs a fully configured Sender implementation that logs using the testing.T's logging facility for better integration with unit tests. Construct and register such a sender for grip.Journaler instances that you use inside of tests to have logging that correctly respects go test's verbosity.

By default, this constructor creates a sender with a level threshold of "debug" and a default log level of "info."

func NewTwitterLogger 

func NewTwitterLogger(ctx context.Context, opts *TwitterOptions, l LevelInfo) (Sender, error)

NewTwitterLogger constructs a sender implementation that posts messages to a twitter account, with configurable level information. The implementation does not rate limit outgoing messages, which should be the responsibility of the caller.

func NewWrappedWriterLogger 

func NewWrappedWriterLogger(name string, wr io.Writer, l LevelInfo) (Sender, error)

NewWrappedWriterLogger constructs a fully configured Sender implementation that writes all data to the underlying writer. These loggers prepend time and logger name information to the beginning of log lines.

As a special case, if the writer is a *WriterSender, then this method will unwrap and return the underlying sender from the writer.

func NewXMPP 

func NewXMPP(name, target string, l LevelInfo) (Sender, error)

NewXMPP constructs an XMPP logging backend that reads the hostname, username, and password from environment variables:

  • GRIP_XMPP_HOSTNAME
  • GRIP_XMPP_USERNAME
  • GRIP_XMPP_PASSWORD

Otherwise, the semantics of NewXMPPDefault are the same as NewXMPPLogger.

func NewXMPPLogger 

func NewXMPPLogger(name, target string, info XMPPConnectionInfo, l LevelInfo) (Sender, error)

NewXMPPLogger constructs a new Sender implementation that sends messages to an XMPP user, "target", using the credentials specified in the XMPPConnectionInfo struct. The constructor will attempt to exablish a connection to the server via SSL, falling back automatically to an unencrypted connection if the the first attempt fails.

func WrapWriter 

func WrapWriter(wr io.Writer) Sender

WrapWriter produces a simple writer that does not modify the log lines passed to the writer.

As a special case, if the writer is a *WriterSender, then this method will unwrap and return the underlying sender from the writer.

func WrapWriterLogger 

func WrapWriterLogger(wr io.Writer) Sender

WrapWriterLogger constructs a new unconfigured sender that directly wraps any writer implementation. These loggers prepend time and logger name information to the beginning of log lines.

As a special case, if the writer is a *WriterSender, then this method will unwrap and return the underlying sender from the writer.

type SlackOptions 

type SlackOptions struct {
	// Channel, Name, and Hostname are basic configurations
	// options for the sender, and control where the messages are
	// sent, which hostname the sender reports itself as, and the
	// name of the journaler.
	Channel  string `bson:"channel" json:"channel" yaml:"channel"`
	Hostname string `bson:"hostname" json:"hostname" yaml:"hostname"`
	Name     string `bson:"name" json:"name" yaml:"name"`
	// Username and IconURL allow the slack sender to set a display
	// name and icon. Setting either parameter will force as_user to false.
	Username string `bson:"username" json:"username" yaml:"username"`
	IconURL  string `bson:"icon_url" json:"icon_url" yaml:"icon_url"`

	// Configuration options for appending structured data to the
	// message sent to slack. The BasicMetadata option appends
	// priority and host information to the message. The Fields
	// option appends structured data if the Raw method of a
	// Composer returns a message.Fields map. If you specify a set
	// of fields in the FieldsSet value, only those fields will be
	// attached to the message.
	BasicMetadata bool            `bson:"add_basic_metadata" json:"add_basic_metadata" yaml:"add_basic_metadata"`
	Fields        bool            `bson:"use_fields" json:"use_fields" yaml:"use_fields"`
	AllFields     bool            `bson:"all_fields" json:"all_fields" yaml:"all_fields"`
	FieldsSet     map[string]bool `bson:"fields" json:"fields" yaml:"fields"`
	// contains filtered or unexported fields
}

SlackOptions configures the behavior for constructing messages sent to slack.

func (*SlackOptions) Validate 

func (o *SlackOptions) Validate() error

Validate inspects the contents SlackOptions struct and returns an error that reports on missing required fields (e.g. Channel and Name); if the hostname is missing and the os.Hostname() syscall fails (but supplies the Hostname as reported by Hostname if there is no Hostname is specified). Validate also prepends a missing "#" to the channel setting if the "#" character is not set.

type SplunkConnectionInfo 

type SplunkConnectionInfo struct {
	ServerURL string `bson:"url" json:"url" yaml:"url"`
	Token     string `bson:"token" json:"token" yaml:"token"`
	Channel   string `bson:"channel" json:"channel" yaml:"channel"`
}

SplunkConnectionInfo stores all information needed to connect to a splunk server to send log messsages.

func GetSplunkConnectionInfo 

func GetSplunkConnectionInfo() SplunkConnectionInfo

GetSplunkConnectionInfo builds a SplunkConnectionInfo structure reading default values from the following environment variables: 

GRIP_SPLUNK_SERVER_URL
GRIP_SPLUNK_CLIENT_TOKEN
GRIP_SPLUNK_CHANNEL

func (SplunkConnectionInfo) Populated 

func (info SplunkConnectionInfo) Populated() bool

Populated validates a SplunkConnectionInfo, and returns false if there is missing data.

type TwitterOptions 

type TwitterOptions struct {
	Name           string
	ConsumerKey    string
	ConsumerSecret string
	AccessToken    string
	AccessSecret   string
}

TwitterOptions describes the credentials required to connect to the twitter API. While the name is used for internal reporting, the other values should be populated with credentials obtained from the Twitter API.

type WriteStringer 

type WriteStringer interface {
	WriteString(str string) (int, error)
}

WriteStringer captures the relevant part of the io.Writer interface useful for writing log messages to streams.

type WriterSender 

type WriterSender struct {
	Sender
	// contains filtered or unexported fields
}

WriterSender wraps another sender and also provides an io.Writer. (and because Sender is an io.Closer) the type also implements io.WriteCloser.

func MakeWriterSender 

func MakeWriterSender(s Sender, p level.Priority) *WriterSender

MakeWriterSender returns an sender interface that also implements io.Writer. Specify a priority used as the level for messages sent.

func NewWriterSender 

func NewWriterSender(s Sender) *WriterSender

NewWriterSender wraps another sender and also provides an io.Writer. (and because Sender is an io.Closer) the type also implements io.WriteCloser.

While WriteSender itself implements Sender, it also provides a Writer method, which allows you to use this Sender to capture file-like write operations.

Data sent via the Write method is buffered internally until its passed a byte slice that ends with the new line character. If the string form of the bytes passed to the write method (including all buffered messages) is only whitespace, then it is not sent.

If there are any bytes in the buffer when the Close method is called, this sender flushes the buffer. WriterSender does not own the underlying Sender, so users are responsible for closing the underlying Sender if/when it is appropriate to release its resources.

func (*WriterSender) Close 

func (s *WriterSender) Close() error

Close writes any buffered messages to the underlying Sender. This does not close the underlying sender.

func (*WriterSender) Write 

func (s *WriterSender) Write(p []byte) (int, error)

Write captures a sequence of bytes to the send interface. It never errors.

type XMPPConnectionInfo 

type XMPPConnectionInfo struct {
	Hostname string
	Username string
	Password string
	// contains filtered or unexported fields
}

XMPPConnectionInfo stores all information needed to connect to an XMPP (jabber) server to send log messages.

func GetXMPPConnectionInfo 

func GetXMPPConnectionInfo() XMPPConnectionInfo

GetXMPPConnectionInfo builds an XMPPConnectionInfo structure reading default values from the following environment variables: 

GRIP_XMPP_HOSTNAME
GRIP_XMPP_USERNAME
GRIP_XMPP_PASSWORD

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.