logging

README

go-logging

Logging library for Go programs.

Documentation

Documentation

Index

• func SaveToContext(l Logger, base context.Context) context.Context
• type Level
• type Logger
  • func LogFromContext(c context.Context) Logger
  • func LogToFile(level Level, path string, sentry string, sentryTags map[string]string) (Logger, error)
  • func LogToStdout(level Level, sentry string, sentryTags map[string]string) (Logger, error)
  • func New(level Level, out io.Writer, sentry string, sentryTags map[string]string) (Logger, error)
  • func (l Logger) AddMeta(meta ...raven.Interface) Logger
  • func (l Logger) AddTags(tags map[string]string) Logger
  • func (l Logger) Close()
  • func (l Logger) Debug(msg ...interface{})
  • func (l Logger) Debugf(format string, msg ...interface{})
  • func (l Logger) Error(msg ...interface{})
  • func (l Logger) Errorf(format string, msg ...interface{})
  • func (l Logger) GetLevel() Level
  • func (l Logger) Info(msg ...interface{})
  • func (l Logger) Infof(format string, msg ...interface{})
  • func (l Logger) Warn(msg ...interface{})
  • func (l Logger) Warnf(format string, msg ...interface{})
  • func (l Logger) WithCallDepth(depth int) Logger
  • func (l Logger) WithLevel(lvl Level) Logger
  • func (l Logger) WithOutput(out io.Writer) Logger
  • func (l Logger) WithPackagePrefixes(prefixes []string) Logger
  • func (l Logger) WithRelease(release string) Logger
  • func (l Logger) WithSentry(dsn string, tags map[string]string) (Logger, error)

Functions

func SaveToContext

func SaveToContext(l Logger, base context.Context) context.Context

SaveToContext adds a Logger to the supplied Context, returning the new Context that contains the Logger. SaveToContext should generally be called during application startup, when the Logger is instantiated. Once a Logger is stored with SaveToContext, it can be retrieved using LogFromContext.

Types

type Level

type Level string

Level is a threshold used to constrain which logs are written in which environments. When set to DebugLvl, all output is written. When set to InfoLvl, all output except DebugLvl statements are written. When set to WarnLvl, all output except DebugLvl and InfoLvl statements are written. When set to ErrorLvl, all output except DebugLvl, InfoLvl, and WarnLvl statements are written. When set to any other value, all output is written.

Choosing which Level to use is a bit of an art. As a guideline: anything that Ops cannot use to investigate an issue in production should be at DebugLvl. ErrorLvl is for fatal errors that result in a 500. WarnLvl is for recoverable errors that you can gracefully degrade from, but which are not expected occurrences.

An example of an ErrorLvl scenario may be that your binary can't reach the database. An example of a WarnLvl scenario may be that you temporarily couldn't reach an external service, but are retrying. (If your retrying logic fails, escalate it to an ErrorLvl.) An example of an InfoLvl scenario may be the port and address a host is listening on. An example of a DebugLvl scenario may be an incoming request, a cache miss, the response from an external service, the database query ran, etc. Things that are useful when writing software, but too noisy to have on in production.

const (
	// DebugLvl indicates messages for local development
	DebugLvl Level = "DEBUG"
	// InfoLvl indicates non-error messages useful to Ops
	InfoLvl Level = "INFO"
	// WarnLvl indicates recoverable error messages
	WarnLvl Level = "WARN"
	// ErrorLvl indicates non-recoverable error messages
	ErrorLvl Level = "ERROR"
)

type Logger

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

Logger is an instance of a log handler, used to write files to the designated output if they meet the specified Level. It is concurrency-safe. Each Logger should have its Close method called when you're done with it.

func LogFromContext

func LogFromContext(c context.Context) Logger

LogFromContext returns a Logger that is ready to use from the Context provided. In a case where a Logger has not been stored in the Context previously (using SaveToContext), LogFromContext will fall back on a Logger that writes to stderr, is set to InfoLvl, and has no Sentry configuration. This is to help debug Logger configuration errors; in production, SaveToContext should always be used before trying to retrieve the Logger wtih LogFromContext. Normally, SaveToContext should be called as part of application startup when the Logger is instantiated.

func LogToFile

func LogToFile(level Level, path string, sentry string, sentryTags map[string]string) (Logger, error)

LogToFile creates a new Logger that writes to a file specified by path. If the file doesn't exist, it will be created. If it does exist, new log lines will be appended to it.

If sentry is non-empty, it will be used as a DSN to connect to a Sentry error collector. The sentryTags are a key/value mapping that will be applied to your Sentry errors. You can use them to set things like the version of your software running, etc.

func LogToStdout

func LogToStdout(level Level, sentry string, sentryTags map[string]string) (Logger, error)

LogToStdout creates a new Logger that writes to stdout.

If sentry is non-empty, it will be used as a DSN to connect to a Sentry error collector. The sentryTags are a key/value mapping that will be applied to your Sentry errors. You can use them to set things like the version of your software running, etc.

func New

func New(level Level, out io.Writer, sentry string, sentryTags map[string]string) (Logger, error)

New creates a new Logger that writes to the io.Writer specified. If the io.Writer is an io.WriteCloser, it will be automatically closed when the Logger's Close method is called.

If sentry is non-empty, it will be used as a DSN to connect to a Sentry error collector. The sentryTags are a key/value mapping that will be applied to your Sentry errors. You can use them to set things like the version of your software running, etc.

func (Logger) AddMeta

func (l Logger) AddMeta(meta ...raven.Interface) Logger

AddMeta copies the Logger, adds the specified Sentry metadata (expressed as the Interface type from the raven package) to the Logger, and returns the modified copy. It is meant to be used to add extra information to a Sentry message that it doesn't make sense to pass as an argument to the Warnf/Errorf call. The data is unused if Sentry is not configured on the logger.

func (Logger) AddTags

func (l Logger) AddTags(tags map[string]string) Logger

AddTags copies the Logger, adds the specified Sentry tags to the Logger, and returns the modified copy. It is meant to be used to add tags to a specific call on the logger that are unique to that log message. The tags are unused if Sentry is not configured on the Logger.

func (Logger) Close

func (l Logger) Close()

Close signifies that a Logger will no longer be used, and the resources allocated to it can be freed. Once the Close method is called, you should not write any more logs using that Logger. Create a new one instead.

func (Logger) Debug

func (l Logger) Debug(msg ...interface{})

Debug writes a log entry with the Level of DebugLvl, joining each argument passed with a space.

func (Logger) Debugf

func (l Logger) Debugf(format string, msg ...interface{})

Debugf writes a log entry with the Level of DebugLvl, interpolating the format string with the arguments passed. See fmt.Sprintf for information on variable placeholders in the format string.

func (Logger) Error

func (l Logger) Error(msg ...interface{})

Error writes a log entry with the Level of ErrorLvl, joining each argument passed with a space.

Any message logged with Error will automatically be sent to Sentry, if Sentry has been configured.

func (Logger) Errorf

func (l Logger) Errorf(format string, msg ...interface{})

Errorf writes a log entry with the Level of ErrorLvl, interpolating the format string with the arguments passed. See fmt.Sprintf for information on variable placeholders in the format string.

Any message logged with Errorf will automatically be sent to Sentry, if Sentry has been configured.

func (Logger) GetLevel

func (l Logger) GetLevel() Level

GetLevel returns the Level assigned to the Logger.

func (Logger) Info

func (l Logger) Info(msg ...interface{})

Info writes a log entry with the Level of InfoLvl, joining each argument passed with a space.

func (Logger) Infof

func (l Logger) Infof(format string, msg ...interface{})

Infof writes a log entry with the Level of InfoLvl, interpolating the format string with the arguments passed. See fmt.Sprintf for information on variable placeholders in the format string.

func (Logger) Warn

func (l Logger) Warn(msg ...interface{})

Warn writes a log entry with the Level of WarnLvl, joining each argument passed with a space.

Any message logged with Warn will automatically be sent to Sentry, if Sentry has been configured.

func (Logger) Warnf

func (l Logger) Warnf(format string, msg ...interface{})

Warnf writes a log entry with the Level of WarnLvl, interpolating the format string with the arguments passed. See fmt.Sprintf for information on variable placeholders in the format string.

Any message logged with Warnf will automatically be sent to Sentry, if Sentry has been configured.

func (Logger) WithCallDepth

func (l Logger) WithCallDepth(depth int) Logger

WithCallDepth is useful for helper libraries that wrap this, and call their helpers. The call depth is how many calls up the stack the Logger should look when deciding what file/line combo created the log statement. This defaults to 0, which is accurate if you're just calling the Logger directly. For every level of indirection, add 1. WithCallDepth returns a copy of l, but with the call depth set to `depth`.

func (Logger) WithLevel

func (l Logger) WithLevel(lvl Level) Logger

WithLevel returns a Logger identical to l, but with the passed Level assigned.

func (Logger) WithOutput

func (l Logger) WithOutput(out io.Writer) Logger

WithOutput returns a Logger identical to l, but with the log output going to `out` instead.

func (Logger) WithPackagePrefixes

func (l Logger) WithPackagePrefixes(prefixes []string) Logger

WithPackagePrefixes returns a copy of l with the package prefixes that will be used to determine if a package should be considered "in app" in sentry overridden with `prefixes`. Stacktraces will use this information to flag lines of stacktraces that are from the application, as opposed to being from a third party library or from the standard library.

func (Logger) WithRelease

func (l Logger) WithRelease(release string) Logger

WithRelease sets the release of the application (usually a git SHA1) that recorded the log. This is only used to tag the logs sent to Sentry, so we know which releases produced the errors.

func (Logger) WithSentry

func (l Logger) WithSentry(dsn string, tags map[string]string) (Logger, error)

WithSentry returns a copy of l, but with the DSN and tags that will be used to send errors to Sentry overwritten by dsn and tags.