Categorygithub.com/Unity-Technologies/go-lager-internal

# README

Lager

Logs (in golang) that are easy for computers to parse, easy for people to read, and easy for programmers to generate. It also encourages logging data over messages, which tends to make logs more useful as well as easier to generate.

You don't need to pass around a logging object so you can log information from any code. You can decorate a Go context.Context with additional data to be added to each log line written when that context applies.

The logs are written in JSON format but the items in JSON are written in a controlled order, preserving the order used in the program code. This makes the logs pretty easy for humans to scan even with no processing or tooling.

Typical logging code like:

lager.Fail(ctx).MMap("Can't merge", "dest", dest, "err", err)
// MMap() takes a message followed by a map of key/value pairs.

could output (especially when running interactively):

["2019-12-31 23:59:59.1234Z", "FAIL", "Can't merge",
    {"dest":"localhost", "err":"refused"}]

(but as a single line). If you declare that the code is running inside Google Cloud Platform (GCP), it could instead output:

{"time":"2019-12-31T23:59:59.1234Z", "severity":"500",
    "message":"Can't merge", "dest":"localhost", "err":"refused"}

(as a single line) which GCP understands well. Note that it is still easy for a human to read with the consistent order used.

Lager is efficient but not to the point of making it inconvenient to write code that uses Lager.

It also provides more granularity when controlling which log lines to write and which to suppress. It offers 11 log levels, most of which can be enabled individually (enabling "Trace" does not force you to also enable "Debug"). You can also easily allow separate log levels for specific packages or any other logical division you care to use.

Forks

If you use a fork of this repository and want to have changes you make accepted upstream, you should use the fork by adding (to go.mod in modules where you use the fork) a line like:

replace github.com/Unity-Technologies/go-lager-internal => github.com/your/lager v1.2.3

And then use "github.com/Unity-Technologies/go-lager-internal" in 'import' statements and in a 'require' directive in the go.mod. (See "replace directive" in https://go.dev/ref/mod.)

# Packages

No description provided by the author
This package is still in beta and the public interface may undergo changes without a full deprecation cycle.
grpc_lager is package for gRPC logging middlewares for the Lager library.

# Functions

Acc() returns a Lager object.
Add/update Lager key/value pairs to/in a context.Context.
AutoLock() can be used on any sync.Locker (anything with Lock and Unlock methods, like a *sync.Mutex).
Fetches the lager key/value pairs stored in a context.Context.
Debug() returns a Lager object.
Exit() returns a Lager object that writes to os.Stderr, incorporating pairs from any contexts passed in, then calls os.Exit(1).
ExitNotExpected(true) causes any subsequent uses of lager.Exit() to include a full stack trace.
ExitViaPanic() improves the way lager.Exit() works so that uses of it in inappropriate places are less problematic.
Fail() returns a Lager object.
GcpContextAddTrace() takes a Context and returns one that has the span added as 2 pairs that will be logged and recognized by GCP when that Context is passed to lager.Warn() or similar methods.
GcpContextReceivedRequest() does several things that are useful when a server receives a new request.
GcpContextSendingRequest() does several things that are useful when a server is about to send a request to a dependent service.
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.
GcpFinishSpan() updates a span with the status information from a http.Response and Finish()es the span (which registers it with GCP).
GcpHtttp() returns a value for logging that GCP will recognize as details about an HTTP(S) request (and perhaps its response), if placed under the key "httpRequest".
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.
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.
GcpLogAccess() creates a standard "access log" entry.
GcpProjectID() returns the current GCP project ID [which is not the project number].
GcpReceivedRequest() gets the Context from '*pReq' and uses it to call GcpContextReceivedRequest().
GcpReceivedResponse() combines GcpLogAccess() and GcpFinishSpan().
GcpSendingNewRequest() does several things that are useful when a server is about to send a request to a dependent service, by calling GcpContextSendingRequest().
GcpSendingRequest() does several things that are useful when a server is about to send a request to a dependent service, by calling GcpContextSendingRequest().
GcpSendingResponse() does several things that are useful when a server is about to send a response to a request it received.
En-/disables log levels for the named module.
Returns a map[string]string where the keys are all of the module names and the values are their enabled levels.
GetSpanPrefix() returns a string to be used as the prefix for the Display Name of trace spans.
Guts() returns a Lager object.
Info() returns a Lager object.
Init() en-/disables log levels.
Keys() provides keys to be used to write each JSON log line as a map (object or hash) instead of as a list (array).
Level() takes one letter from "PEFWNAITDOG" and returns a Lager object that either logs or doesn't, depending on whether the specified log level is enabled, incorporating any key/value pairs from the passed-in contexts.
lager.List() returns a slice (lager.AList) that can be passed as an argument to a Lager's [C][M]Map() or [C][M]List() method to construct nested data that can be quickly serialized to JSON.
lager.Map() returns a raw list of key/value pairs (lager.RawMap) that can be passed as an argument to a Lager's [C][M]Map() or [C][M]List() method to construct nested data that can be quickly serialized to JSON.
Create a new Module with the given name.
Note() returns a Lager object.
Obj() returns a Lager object.
lager.Pairs() returns a (processed) list of key/value pairs (lager.AMap) that can be added to a context.Context to specify additional data to append to each log line.
Panic() returns a Lager object that calls panic(), incorporating pairs from any contexts passed in.
RecoverPanicToExit is the func pointer that is returned by ExitViaPanic().
RequestUrl() returns a *url.URL more appropriate for logging, based on an *http.Request.
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).
S() converts an arbitrary value to a string.
SetLevelNotation() installs a function to map from Lager's level names (like "DEBUG") to other values to indicate log levels.
En-/disables log levels for the named module.
SetOutput() causes all future log lines to be written to the passed-in io.Writer.
SetPathParts() sets how many path components to include in the source code file names when recording caller information or a stack trace.
SetSpanPrefix() sets the span name prefix [see GetSpanPrefix()].
Trace() returns a Lager object.
Unless() is used to pass an optional label+value pair to Map().
Warn() returns a Lager object.

# Constants

No description provided by the author
No description provided by the author
InlinePairs can be used as a "label" to indicate that the following value that contains label-subvalue pairs (a value of type AMap or RawMap) should be treated as if the pairs had been passed in at that higher level.
SkipThisPair can be used as a "label" to indicate that the following value should just be ignored.

# Structs

Flusher is an io.Writer that will use a Lager to log each buffer written to it.
Storage for an ordered list of key/value pairs (without duplicate keys).
A named module that allows separate log levels to be en-/disabled.

# Interfaces

'Lager' is the interface returned from lager.Warn() and the other log-level selectors.
A Stringer just has a String() method that returns its stringification.

# Type aliases

A list type that we efficiently convert to JSON.
Ctx is just an alias for context.Context that takes up less space in function signatures.
A raw list of key/value pairs we can efficiently convert to JSON as a map.