lager

func AutoLock ¶

func AutoLock(l sync.Locker) func()

AutoLock() can be used on any sync.Locker (anything with Lock and Unlock methods, like a *sync.Mutex). Call it like:

defer lager.AutoLock(locker)()
//                          ^^ The 2nd set of parens is important!

and the Locker will be locked immediately and unlocked when your function ends.

If 'mu' is of type sync.Mutex, then you would have to call:

defer lager.AutoLock(&mu)()

as a *sync.Mutex is a Locker but a sync.Mutex is not.

func ExitNotExpected ¶

func ExitNotExpected(unexpected bool)

ExitNotExpected(true) causes any subsequent uses of lager.Exit() to include a full stack trace. You usually call ExitNotExpected() at the point where process initialization has completed. If you had not previously called 'defer lager.ExitViaPanic()()', then a warning is logged [catches accidentally writing 'defer lager.ExitViaPanic()'].

ExitNotExpected(false) disables the added stack trace [and never logs a warning].

func ExitViaPanic ¶

func ExitViaPanic() func(...func(*int))

ExitViaPanic() improves the way lager.Exit() works so that uses of it in inappropriate places are less problematic. Using lager.Exit() causes 'os.Exit(1)' to be called, which prevents any 'defer'ed code from doing important clean-up. One should only use lager.Exit() in code that will only run during process initialization, which means it should only be called when there is nothing important that needs to be cleaned up. But mistakes are sometimes made.

Doing:

defer lager.ExitViaPanic()()
//                        ^^ The 2nd set of parens is important!

very early in your main() function will mean that uses of lager.Exit() will only skip clean-up in items that were 'defer'ed before that point. The call to 'os.Exit(1)' will be done in the function returned from ExitViaPanic() rather than at the point where lager.Exit()'s return value was used. See also ExitNotExpected().

You can change the exit status or prevent the call to os.Exit() (such as for testing); see RecoverPanicToExit() for details.

If you would instead like lager.Exit() to terminate the process with a plain panic(), then omit the 'defer' and the 2nd set of parens:

_ = lager.ExitViaPanic()

func GcpFakeResponse ¶

func GcpFakeResponse(status int, size int64, desc string) *http.Response

GcpFakeResponse() creates an http.Response suitable for passing to GcpHttp() [or similar] when you just have a status code (and/or a response size) and not a http.Response.

Pass 'size' as -1 to omit this information. Passing 'status' as 0 will cause an explicit 0 to be logged. Pass 'status' as -1 to omit it. Pass 'desc' as "" to have it set based on 'status'.

func GcpFinishSpan ¶

func GcpFinishSpan(span spans.Factory, resp *http.Response) time.Duration

GcpFinishSpan() updates a span with the status information from a http.Response and Finish()es the span (which registers it with GCP).

func GcpHttpF ¶

func GcpHttpF(
	req *http.Request, resp *http.Response, start *time.Time,
) func() interface{}

GcpHttpF() can be used for logging just like GcpHttp(), it just returns a function so that the work is only performed if the logging level is enabled.

If you are including GcpHttp() information in a lot of log lines [which can be quite useful], then you can get even more efficiency by adding the pair ' "httpRequest", GcpHttp(req, nil, nil) ' to your Context [which you then pass to 'lager.Warn(ctx)', for example] so the data is only calculated once. You can add this to an *http.Request's Context by calling GcpRequestAddTrace().

For this to work best, you should specify "" as the key name for context information; which is automatically done if LAGER_GCP is non-empty in the environment and LAGER_KEYS is not set.

You'll likely include 'GcpHttp(req, resp, &start)' in one log line [to record the response information and latency, not just the request]. If you added "httpRequest" to your context, then that logging is best done via:

lager.Acc(
    lager.AddPairs(ctx, "httpRequest", GcpHttp(req, resp, &start)),
).List("Response sent")

so that the request-only information is not also output. Doing this via GcpLogAccess() is easier.

func GcpLevelName ¶

func GcpLevelName(lev string) string

GcpLevelName takes a Lager level name (only the first letter matters and it must be upper case) and returns the corresponding value GCP uses in structured logging to represent the severity of such logs. Levels are mapped as:

Not used: Alert ("700") and Emergency ("800")
Panic, Exit - Critical ("600")
Fail - Error ("500")
Warn - Warning ("400")
Note - Notice ("300")
Access, Info - Info ("200")
Trace, Debug, Obj, Guts - Debug ("100")
If an invalid level name is passed: Default ("0")

If the environment variable LAGER_GCP is not empty, then lager.LevelNotation will be initalized to lager.GcpLevelName.

func GcpProjectID ¶

func GcpProjectID(ctx Ctx) (string, error)

GcpProjectID() returns the current GCP project ID [which is not the project number]. Once the lookup succeeds, that value is saved and returned for subsequent calls. The lookup times out after 0.1s.

Set GCP_PROJECT_ID in your environment to avoid the more complex lookup.

func GcpReceivedRequest ¶

func GcpReceivedRequest(pReq **http.Request) spans.Factory

GcpReceivedRequest() gets the Context from '*pReq' and uses it to call GcpContextReceivedRequest(). Then it replaces '*pReq' with a version of the request with the new Context attached. Then it returns the Factory.

It is usually called in a manner similar to:

defer spans.FinishSpan(lager.GcpReceivedRequest(&req))

or

var resp *http.Response // Will be set in later code
defer lager.GcpSendingResponse(
    lager.GcpReceivedRequest(&req), req, resp)

Using GcpContextReceivedRequest() can be slightly more efficient if you either start with a Context different from the one attached to the Request or will not attach the new Context to the Request (or will adjust it further before attaching it) since each time WithContext() is called on a Request, the Request must be copied.

func GcpReceivedResponse ¶

func GcpReceivedResponse(
	span spans.Factory,
	req *http.Request,
	resp *http.Response,
	pairs ...interface{},
)

GcpReceivedResponse() combines GcpLogAccess() and GcpFinishSpan(). The access log line written will use the message "Received response" and will include the passed-in 'pairs' which should be zero or more pairs of a string key followed by an arbitrary value. However, logging every response received from a dependent service may be excessive.

func GcpSendingRequest ¶

func GcpSendingRequest(pReq **http.Request) spans.Factory

GcpSendingRequest() does several things that are useful when a server is about to send a request to a dependent service, by calling GcpContextSendingRequest(). It uses the Context from '*pReq' and then replaces '*pReq' with a copy of the original Request but with the new Context attached.

It is usually called in a manner similar to:

defer spans.FinishSpan(lager.GcpSendingRequest(&req))

func GcpSendingResponse ¶

func GcpSendingResponse(
	span spans.Factory,
	req *http.Request,
	resp *http.Response,
	pairs ...interface{},
)

GcpSendingResponse() does several things that are useful when a server is about to send a response to a request it received. It combines GcpLogAccess() and GcpFinishSpan(). The access log line written will use the message "Sending response" and will include the passed-in 'pairs' which should be zero or more pairs of a string key followed by an arbitrary value.

'resp' will often be constructed via GcpFakeResponse().

func GetModuleLevels ¶

func GetModuleLevels(name string) string

En-/disables log levels for the named module. If no module by that name exists yet, then "n/a" is returned. Otherwise returns the enabled levels.

func GetModules ¶

func GetModules() map[string]string

Returns a map[string]string where the keys are all of the module names and the values are their enabled levels.

func GetSpanPrefix ¶

func GetSpanPrefix() string

GetSpanPrefix() returns a string to be used as the prefix for the Display Name of trace spans. It defaults to os.Getenv("LAGER_SPAN_PREFIX") or, if that is not set, to the basename of 'os.Args[0]'.

func Init ¶

func Init(levels string)

Init() en-/disables log levels. Pass in a string of letters from "FWNAITDOG" to indicate which log levels should be the only ones that produce output. Each letter is the first letter of a log level (Fail, Warn, Note, Acc, Info, Trace, Debug, Obj, or Guts). Levels Panic and Exit are always enabled. Init("") acts like Init("FWNA"), the default setting. To disable all optional logs, you can use Init("-") as any characters not from "FWNAITDOG" are silently ignored. So you can also call Init("Fail Warn Note Access Info").

Rather than calling Init(), you may prefer to set enabled levels via the LAGER_LEVELS environment variable since that initialization is guaranteed to happen before any logging takes place, even if logging ends up being done in code called from initialization code.

func Keys ¶

func Keys(when, lev, msg, args, ctx, mod string)

Keys() provides keys to be used to write each JSON log line as a map (object or hash) instead of as a list (array).

'when' is used for the timestamp. 'lev' is used for the log level name. 'msg' is either "" or will be used for the first argument to MMap() or MList() (and similar methods). 'msg' is also used when a single argument is passed to List(). 'args' is used for the arguments to List() when 'msg' is not. 'mod' is used for the module name (if any).

'ctx' is used for the key/value pairs added from contexts. Specify "" for 'ctx' to have any context key/value pairs included in-line in the top-level JSON map. In this case, care should be taken to avoid using the same key name both in a context pair and in a pair being passed to, for example, MMap(). If you do that, both pairs will be output but anything parsing the log line will only remember one of the pairs.

If the environment variable LAGER_KEYS is set it must contain 6 key names separated by commas and those become the keys to use. Otherwise, if the environment variable LAGER_GCP is not empty, then it is as if you had the following set (among other changes):

LAGER_KEYS="time,severity,message,data,,module"

Pass in 6 empty strings to revert to logging a JSON list (array).

func RecoverPanicToExit ¶

func RecoverPanicToExit(handlers ...func(*int))

RecoverPanicToExit is the func pointer that is returned by ExitViaPanic(). It must be called via 'defer' and will call os.Exit(1) if lager.Exit() has invoked panic() because of ExitViaPanic().

If you pass in one or more 'func(*int)' arguments, then they will each be called and passed a pointer to the exit status (initially 1) so that they can change it or just note the impending Exit. If the final value is negative, then os.Exit() will not be called (useful when testing).

func RequestUrl ¶

func RequestUrl(req *http.Request) *url.URL

RequestUrl() returns a *url.URL more appropriate for logging, based on an *http.Request. For server Requests, the missing Host and Scheme are populated. Any query parameters are omitted (but the trailing "?" is preserved, if present).

func RunningInGcp ¶

func RunningInGcp()

RunningInGcp() tells Lager to log messages in a format that works best when running inside of the Google Cloud Platform (when using GCP Cloud Logging). You can call this so you don't have to set LAGER_GCP=1 in your environment, but note that it will be possible for logging to happen before this call is executed [such as some logging triggered, perhaps indirectly, by some code in an Init() function] and such logs would not be in the desired format. Even calling RunningInGcp() from your own Init() function will not guarantee it happens before any logging. For this reason, using LAGER_GCP=1 is preferred.

In particular, RunningInGcp() is equivalent to running:

if "" == os.Getenv("LAGER_KEYS") {
    // LAGER_KEYS has precedence over LAGER_GCP.
    lager.Keys("time", "severity", "message", "data", "", "module")
}
lager.SetLevelNotation(lager.GcpLevelName)

It also arranges for an extra element to be added to the JSON if nothing but a message is logged so that jsonPayload.message does not get transformed into textPayload when the log is ingested into Cloud Logging.

func S ¶

func S(arg interface{}) string

S() converts an arbitrary value to a string. It is very similar to 'fmt.Sprintf("%v", arg)' but treats []byte values the same as strings rather then dumping them as a list of byte values in base 10.

func SetLevelNotation ¶

func SetLevelNotation(mapper func(string) string)

SetLevelNotation() installs a function to map from Lager's level names (like "DEBUG") to other values to indicate log levels. An example of such a function is GcpLevelName(). If you write such a function, you would usually just key off the first letter of the passed-in level name.

Passing in 'nil' for 'mapper' resets to the default behavior.

func SetModuleLevels ¶

func SetModuleLevels(name, levels string) bool

En-/disables log levels for the named module. If no module by that name exists yet, then false is returned.

func SetOutput ¶

func SetOutput(writer io.Writer) func()

SetOutput() causes all future log lines to be written to the passed-in io.Writer. If 'nil' is passed in, then log lines return to being written to os.Stdout (for most log levels) and to os.Stderr (for Panic and Exit levels).

You can temporarily redirect logs via:

defer lager.SetOutput(writer)()
//                           ^^ Note required final parens!

func SetPathParts ¶

func SetPathParts(pathParts int)

SetPathParts() sets how many path components to include in the source code file names when recording caller information or a stack trace. Passing in 1 will cause only the source code file name to be included. A 2 will include the file name and the name of the directory it is in. A 3 adds the directory above that, etc. A value of 0 (or -1) will include the full path.

If you have not called SetPathParts(), it defaults to 3.

func SetSpanPrefix ¶

func SetSpanPrefix(prefix string)

SetSpanPrefix() sets the span name prefix [see GetSpanPrefix()].

func Unless ¶

func Unless(cond bool, label string) interface{}

Unless() is used to pass an optional label+value pair to Map(). Use Unless() to specify the label and, if the value is unsafe or expensive to compute, then wrap it in a deferring function:

lager.Debug().Map(
    "Ran", stage,
    // Don't include `"Error": null,` in the log:
    lager.Unless(nil == err, "Error"), err,
    // Don't call config.Proxy() if config is nil:
    lager.Unless(nil == config, "Proxy"),
        func() interface{} { return config.Proxy() },
)