Merge pull request #747 from lightninglabs/docs-lnd

Update lnd documentation

Author: github-actions[bot]

docs/lnd/INSTALL.md

@@ -93,23 +93,24 @@ 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:
 
 <details>
   <summary>Linux (x86-64)</summary>
 
   ```
   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
   `999805bed7d9039ec3da1a53bfbcafc13e367da52aa823cb60b68ba22d44c616`. If it
   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
   ```
 </details>
@@ -118,16 +119,16 @@ the following commands for your OS:
   <summary>Linux (ARMv6)</summary>
 
   ```
-  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
   `b566484fe89a54c525dd1a4cbfec903c1f6e8f0b7b3dbaf94c79bc9145391083`. If it
   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
   ```  
 

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 

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`