diff --git a/docs/lnd/INSTALL.md b/docs/lnd/INSTALL.md index 3b7f7cf4..88375529 100644 --- a/docs/lnd/INSTALL.md +++ b/docs/lnd/INSTALL.md @@ -93,15 +93,16 @@ following build dependencies are required: ### Installing Go -`lnd` is written in Go, with a minimum version of 1.19. To install, run one of -the following commands for your OS: +`lnd` is written in Go, with a minimum version of `1.22.6` (or, in case this +document gets out of date, whatever the Go version in the main `go.mod` file +requires). To install, run one of the following commands for your OS:
Linux (x86-64) ``` wget https://dl.google.com/go/go1.22.6.linux-amd64.tar.gz - sha256sum go1.22.5.linux-amd64.tar.gz | awk -F " " '{ print $1 }' + sha256sum go1.22.6.linux-amd64.tar.gz | awk -F " " '{ print $1 }' ``` The final output of the command above should be @@ -109,7 +110,7 @@ the following commands for your OS: isn't, then the target REPO HAS BEEN MODIFIED, and you shouldn't install this version of Go. If it matches, then proceed to install Go: ``` - sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.22.5.linux-amd64.tar.gz + sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.22.6.linux-amd64.tar.gz export PATH=$PATH:/usr/local/go/bin ```
@@ -118,8 +119,8 @@ the following commands for your OS: Linux (ARMv6) ``` - wget https://dl.google.com/go/go1.22.5.linux-armv6l.tar.gz - sha256sum go1.22.5.linux-armv6l.tar.gz | awk -F " " '{ print $1 }' + wget https://dl.google.com/go/go1.22.6.linux-armv6l.tar.gz + sha256sum go1.22.6.linux-armv6l.tar.gz | awk -F " " '{ print $1 }' ``` The final output of the command above should be @@ -127,7 +128,7 @@ the following commands for your OS: isn't, then the target REPO HAS BEEN MODIFIED, and you shouldn't install this version of Go. If it matches, then proceed to install Go: ``` - sudo rm -rf /usr/local/go && tar -C /usr/local -xzf go1.22.5.linux-armv6l.tar.gz + sudo rm -rf /usr/local/go && tar -C /usr/local -xzf go1.22.6.linux-armv6l.tar.gz export PATH=$PATH:/usr/local/go/bin ``` diff --git a/docs/lnd/code_formatting_rules.md b/docs/lnd/code_formatting_rules.md index 731bb640..ad58745d 100644 --- a/docs/lnd/code_formatting_rules.md +++ b/docs/lnd/code_formatting_rules.md @@ -178,6 +178,95 @@ be used for calls to formatting functions like `fmt.Errorf`, But not for statements that are important for the flow or logic of the code, like `require.NoErrorf()`. +#### Exceptions and additional styling for structured logging + +When making use of structured logging calls (there are any `btclog.Logger` +methods ending in `S`), a few different rules and exceptions apply. + +1) **Static messages:** Structured log calls take a `context.Context` as a first +parameter and a _static_ string as the second parameter (the `msg` parameter). +Formatted strings should ideally not be used for the construction of the `msg` +parameter. Instead, key-value pairs (or `slog` attributes) should be used to +provide additional variables to the log line. + +**WRONG** +```go +log.DebugS(ctx, fmt.Sprintf("User %d just spent %.8f to open a channel", userID, 0.0154)) +``` + +**RIGHT** +```go +log.InfoS(ctx, "Channel open performed", + slog.Int("user_id", userID), + btclog.Fmt("amount", "%.8f", 0.00154)) +``` + +2) **Key-value attributes**: The third parameter in any structured log method is +a variadic list of the `any` type but it is required that these are provided in +key-value pairs such that an associated `slog.Attr` variable can be created for +each key-value pair. The simplest way to specify this is to directly pass in the +key-value pairs as raw literals as follows: + +```go +log.InfoS(ctx, "Channel open performed", "user_id", userID, "amount", 0.00154) +``` +This does work, but it becomes easy to make a mistake and accidentally leave out +a value for each key provided leading to a nonsensical log line. To avoid this, +it is suggested to make use of the various `slog.Attr` helper functions as +follows: + +```go +log.InfoS(ctx, "Channel open performed", + slog.Int("user_id", userID), + btclog.Fmt("amount", "%.8f", 0.00154)) +``` + +3) **Line wrapping**: Structured log lines are an exception to the 80-character +line wrapping rule. This is so that the key-value pairs can be easily read and +reasoned about. If it is the case that there is only a single key-value pair +and the entire log line is still less than 80 characters, it is acceptable to +have the key-value pair on the same line as the log message. However, if there +are multiple key-value pairs, it is suggested to use the one line per key-value +pair format. Due to this suggestion, it is acceptable for any single key-value +pair line to exceed 80 characters for the sake of readability. + +**WRONG** +```go +// Example 1. +log.InfoS(ctx, "User connected", + "user_id", userID) + +// Example 2. +log.InfoS(ctx, "Channel open performed", "user_id", userID, + btclog.Fmt("amount", "%.8f", 0.00154), "channel_id", channelID) + +// Example 3. +log.InfoS(ctx, "Bytes received", + "user_id", userID, + btclog.Hex("peer_id", peerID.SerializeCompressed()), + btclog.Hex("message", []bytes{ + 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, + }))) +``` + +**RIGHT** +```go +// Example 1. +log.InfoS(ctx, "User connected", "user_id", userID) + +// Example 2. +log.InfoS(ctx, "Channel open performed", + slog.Int("user_id", userID), + btclog.Fmt("amount", "%.8f", 0.00154), + slog.String("channel_id", channelID)) + +// Example 3. +log.InfoS(ctx, "Bytes received", + "user_id", userID, + btclog.Hex("peer_id", peerID.SerializeCompressed()), + btclog.Hex("message", []bytes{0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08}))) +``` + ### Wrapping long function definitions If one is forced to wrap lines of function arguments that exceed the diff --git a/docs/lnd/release-notes/release-notes-0.19.0.md b/docs/lnd/release-notes/release-notes-0.19.0.md index a46832af..952804fb 100644 --- a/docs/lnd/release-notes/release-notes-0.19.0.md +++ b/docs/lnd/release-notes/release-notes-0.19.0.md @@ -163,7 +163,13 @@ a log line. The options for this include "off" (default), "short" (source file name and line number) and "long" (full path to source file and line number). Finally, the new `--logging.console.style` option can be used under the `dev` - build tag to add styling to console logging. + build tag to add styling to console logging. + +* [Start adding a commit hash fingerprint to log lines by + default](https://github.com/lightningnetwork/lnd/pull/9314). This can be + disabled with the new `--logging.no-commit-hash"` option. Note that this extra + info will currently only appear in a few log lines, but more will be added in + future as the structured logging change is propagated throughout LND. * [Add max files and max file size](https://github.com/lightningnetwork/lnd/pull/9233) options to the `logging` config namespace under new `--logging.file.max-files`