slog: document context support
Change-Id: I005c67045aabd4f76709909d26c592c095b21883
Reviewed-on: https://go-review.googlesource.com/c/exp/+/456622
Run-TryBot: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
diff --git a/slog/doc.go b/slog/doc.go
index 7f483b6..232bfff 100644
--- a/slog/doc.go
+++ b/slog/doc.go
@@ -203,6 +203,22 @@
# Contexts
+This package works with [context.Context] in two ways.
+
+Storing a Logger in a Context is a convenient way to pass it around,
+since many functions already take a Context as an argument.
+Create a Context that contains a Logger with [NewContext],
+and retrieve the Logger with [FromContext].
+
+Sometimes a Context holds information that a Handler would like to use.
+For example, tracing systems usually store span identifiers in Contexts.
+To provide a Context to a Handler, associate it with a Logger using [Logger.WithContext]:
+
+ logger.WithContext(ctx).Info("hello")
+
+That sets [Record.Context] to ctx so the Handler can access it.
+
+
# Advanced topics
