README
¶
The Clues Logger!
Regular logging
Infow/Debugw/Errorw are also supported.
So are the *f variations. Because I'm trying to be nice.
Warn is not included. Because I'm not that nice.
clog.Ctx(ctx).Info("information")
clog.Ctx(ctx).Label(clog.ExampleDebugLabel).Debug("debugging")
clog.Ctx(ctx).Err(err).Error("badness")
Labeling your logs
Labeling is intended to make categorical lookup of logs much easier.
Many times we build unintentional colloquialisms into our log vocabulary and try to filter on those when looking for info. Ex: logs that say "recoverable error" are "the important error logs". No, none of that.
If you have a set of loging that you always want to include or exclude, put a label on it. "How was this run configured?" -> filter clabel like /clabel_configuration/ "What caused the process to fail?" -> filter clabel like /clabel_error_origin/
clog.CtxErr(ctx, err).
Label(clog.LStartOfRun, clog.LFailureSource).
Info("couldn't start up process")
Commenting your logs
clog.Ctx(ctx).
Comment(`I could just add this in code... but now we can pull double duty!
whatever I say here is readable to anyone who is looking at the logs (which is good
if I'm trying to tell them what they need to know about due to this log occurring);
it's also a regular comment, as if in code, so the code is now also commented!`).
Info("information")
Automatically adds structured data from clues
ctx := clues.Add(ctx, "foo", "bar")
err := clues.New("a bad happened").With("fnords", "smarf")
clog.CtxErr(ctx, err).
With("beaux", "regarde").
Debug("all the info!")
// this produces a log containing:
// {
// "msg": "all the info!",
// "foo": "bar",
// "fnords": "smarf",
// "beaux": "regarde",
// }
Setting up logs
set := clog.Settings{
Format: clog.FormatForHumans,
Level: clog.LevelInfo,
}
ctx := clog.Init(ctx, set)
Filtering Debug Logs (aka, improved debug levels)
You're using labels to categorize your logs, right? Right? Well then you've already built out your debug logging levels! Want to only include a certain set of your very noisy debug logs? Just specify which label you want included in the debug level.
set := clog.Settings{
Format: clog.LFHuman,
Level: clog.LLDebug,
OnlyLogDebugIfContainsLabel: []string{clog.APICall},
}
ctx := clog.Init(ctx, set)
Documentation
¶
Index ¶
- Constants
- Variables
- func Ctx(ctx context.Context) *builder
- func CtxErr(ctx context.Context, err error) *builder
- func Flush(ctx context.Context)
- func GetLogFileOrDefault(useThisFile string) string
- func Init(ctx context.Context, set Settings) context.Context
- func PlantLogger(ctx context.Context, seed *zap.SugaredLogger) context.Context
- func Singleton() *builder
- type Settings
- type Writer
Constants ¶
const ( // good for categorizing debugging-level api call info. APICall = "clabel_api_call" // when you want your log to cause a lot of noise. AlarmOnThis = "clabel_alarm_on_this" // for info about end-of-run resource cleanup. Cleanup = "clabel_cleanup" // for showcasing the runtime configuration of your app Configuration = "clabel_configuration" // everything that you want to know about the process // at the time of its conclusion. EndOfRunResults = "clabel_end_of_run_results" // good for marking the the error logs that you need to review // when debugging "what exactly failed in this run?" FailureOrigin = "clabel_failure_origin" // when you want debug logging to include info about every item // that gets handled through the process. IndividualItemDetails = "clabel_individual_item_details" // when debugging the progress of a process and you want to // include logs that track the completion of long running // processes. ProgressTicker = "clabel_progress_ticker" // everything that you want to know about the state of the // application when you kick off a new process. StartOfRun = "clabel_start_of_run" // who needs a logging level when you can use a label instead? Warning = "clabel_warning" )
Default / Example labels
const ( LevelDebug logLevel = "debug" LevelInfo logLevel = "info" LevelError logLevel = "error" LevelDisabled logLevel = "disabled" )
const ( // use for cli/terminal FormatForHumans logFormat = "human" // use for cloud logging FormatToJSON logFormat = "json" )
const ( HashSensitiveInfo sensitiveInfoHandlingAlgo = "hash" MaskSensitiveInfo sensitiveInfoHandlingAlgo = "mask" ShowSensitiveInfoInPlainText sensitiveInfoHandlingAlgo = "plaintext" )
const ( Stderr = "stderr" Stdout = "stdout" )
Variables ¶
var ResolvedLogFile string
ResolvedLogFile is the first log file established by the caller. It gets eagerly populated on the first act of ensuring settings defaults, which normally occurs during the Init call.
If Init gets called more than once, or different settings are ensured, it's possible to override this value by manually specifying the log file in the settings used for that action. But if no file is provided, the default will fall back to this resolved file first.
Functions ¶
func Ctx ¶
Ctx retrieves the logger embedded in the context. It also extracts any clues from the ctx and adds all k:v pairs to that log instance.
func Flush ¶
Flush writes out all buffered logs. Probably good to do before shutting down whatever instance had initialized the singleton.
func GetLogFileOrDefault ¶
GetLogFileOrDefault finds the log file in the users local system. Uses the env var declaration, if populated, else defaults to stderr. If this has already been called once before, uses the result of that prior call.
func Init ¶
Init embeds a logger within the context for later retrieval. It is a preferred, but not necessary, initialization step. If you don't call this and you start logging, or you call Singleton(), then the package will initialize a logger instance with the default values. If you need to configure your logs, make sure to embed this first.
func PlantLogger ¶
PlantLogger allows users to embed their own zap.SugaredLogger within the context. It's good for inheriting a logger instance that was generated elsewhere, in case you have a downstream package that wants to clog the code with a different zsl.
func Singleton ¶
func Singleton() *builder
Singleton is a shorthand for .Ctx(context.Background()). IE: it'll use the singleton logger directly; building one if necessary. You should avoid this and use .Ctx or .CtxErr if possible. Likelihood is that you're somewhere deep in a func chain that doesn't accept a ctx, and you still want to add a quick log; maybe for debugging purposes.
That's fine! Everything should work great.
Unless you call this before initialization. Then it'll panic. We do want you to init the logger first, else you'll potentially lose these logs due different buffers.
Types ¶
type Settings ¶
type Settings struct {
// core settings
File string // what file to log to (alt: stderr, stdout)
Format logFormat // whether to format as text (console) or json (cloud)
Level logLevel // what level to log at
// more fiddly bits
SensitiveInfoHandling sensitiveInfoHandlingAlgo // how to obscure pii
// when non-empty, only debuglogs with a label that matches
// the provided labels will get delivered. All other debug
// logs get dropped. Good way to expose a little bit of debug
// logs without flooding your system.
OnlyLogDebugIfContainsLabel []string
}
Settings records the user's preferred logging settings.
func (Settings) EnsureDefaults ¶
EnsureDefaults sets any non-populated settings to their default value. exported for testing without circular dependencies.
Source Files