Repository files navigation

A Go linter that ensures consistent code style when usinglog/slog.

Thelog/slog API allows two different types of arguments: key-value pairs and attributes.While people may have different opinions about which one is better, most seem to agree on one thing: it should be consistent.Withsloglint you can enforce various rules forlog/slog based on your preferred code style.

• Enforce not mixing key-value pairs and attributes (default)
• Enforce using either key-value pairs only or attributes only (optional)
• Enforce not using global loggers (optional)
• Enforce using methods that accept a context (optional)
• Enforce using static messages (optional)
• Enforce message style (optional)
• Enforce using constants instead of raw keys (optional)
• Enforce key naming convention (optional)
• Enforce not using specific keys (optional)
• Enforce putting arguments on separate lines (optional)

sloglint is integrated intogolangci-lint, and this is the recommended way to use it.

To enable the linter, add the following lines to.golangci.yml:

linters:enable:    -sloglint

Alternatively, you can download a prebuilt binary from theReleases page to usesloglint standalone.

Rungolangci-lint withsloglint enabled.See the list ofavailable options to configure the linter.

When usingsloglint standalone, pass the options as flags of the same name.

Theno-mixed-args option causessloglint to report mixing key-values pairs and attributes within a single function call:

slog.Info("a user has logged in","user_id",42,slog.String("ip_address","192.0.2.0"))// sloglint: key-value pairs and attributes should not be mixed

It is enabled by default.

Thekv-only option causessloglint to report any use of attributes:

slog.Info("a user has logged in",slog.Int("user_id",42))// sloglint: attributes should not be used

In contrast, theattr-only option causessloglint to report any use of key-value pairs:

slog.Info("a user has logged in","user_id",42)// sloglint: key-value pairs should not be used

Some projects prefer to pass loggers as explicit dependencies.Theno-global option causessloglint to report the use of global loggers.

slog.Info("a user has logged in","user_id",42)// sloglint: global logger should not be used

Possible values areall (report all global loggers) anddefault (report only the defaultslog logger).

Someslog.Handler implementations make use of the givencontext.Context (e.g. to access context values).For them to work properly, you need to pass a context to all logger calls.Thecontext-only option causessloglint to report the use of methods without a context:

slog.Info("a user has logged in")// sloglint: InfoContext should be used instead

Possible values areall (report all contextless calls) andscope (report only if a context exists in the scope of the outermost function).

To get the most out of structured logging, you may want to require log messages to be static.Thestatic-msg option causessloglint to report non-static messages:

slog.Info(fmt.Sprintf("a user with id %d has logged in",42))// sloglint: message should be a string literal or a constant

The report can be fixed by moving dynamic values to arguments:

slog.Info("a user has logged in","user_id",42)

Themsg-style option causessloglint to check log messages for a particular style.

Possible values arelowercased (report messages that begin with an uppercase letter)...

slog.Info("Msg")// sloglint: message should be lowercased

...andcapitalized (report messages that begin with a lowercase letter):

slog.Info("msg")// sloglint: message should be capitalized

Special cases such as acronyms (e.g.HTTP,U.S.) are ignored.

To prevent typos, you may want to forbid the use of raw keys altogether.Theno-raw-keys option causessloglint to report the use of strings as keys(includingslog.Attr calls, e.g.slog.Int("user_id", 42)):

slog.Info("a user has logged in","user_id",42)// sloglint: raw keys should not be used

This report can be fixed by using either constants...

constUserId="user_id"slog.Info("a user has logged in",UserId,42)

...or customslog.Attr constructors:

funcUserId(valueint) slog.Attr {returnslog.Int("user_id",value) }slog.Info("a user has logged in",UserId(42))

To ensure consistency in logs, you may want to enforce a single key naming convention.Thekey-naming-case option causessloglint to report keys written in a case other than the given one:

slog.Info("a user has logged in","user-id",42)// sloglint: keys should be written in snake_case

Possible values aresnake,kebab,camel, orpascal.

To prevent accidental use of reserved log keys, you may want to forbid specific keys altogether.Theforbidden-keys option causessloglint to report the use of forbidden keys:

slog.Info("a user has logged in","reserved",42)// sloglint: "reserved" key is forbidden and should not be used

For example, when using the standardslog.JSONHandler andslog.TextHandler,you may want to forbid thetime,level,msg, andsource keys, as these are used by the handlers.

To improve code readability, you may want to put arguments on separate lines, especially when using key-value pairs.Theargs-on-sep-lines option causessloglint to report 2+ arguments on the same line:

slog.Info("a user has logged in","user_id",42,"ip_address","192.0.2.0")// sloglint: arguments should be put on separate lines

This report can be fixed by reformatting the code:

slog.Info("a user has logged in","user_id",42,"ip_address","192.0.2.0",)