From 414feb045530203168c764e43dd6bb14d6ff3049 Mon Sep 17 00:00:00 2001
From: Olivia Lee <olivia@computer.surgery>
Date: Sat, 14 Dec 2024 18:05:53 -0800
Subject: [PATCH] update style guide for new logging style

---
 book/contributing/style-guide.md | 36 ++++++++++++++++++++++++++------
 1 file changed, 30 insertions(+), 6 deletions(-)

diff --git a/book/contributing/style-guide.md b/book/contributing/style-guide.md
index 957a13a1..a380bf90 100644
--- a/book/contributing/style-guide.md
+++ b/book/contributing/style-guide.md
@@ -89,6 +89,13 @@ in mind. Especially, keeping Cargo unit tests in a dedicated tests file
 
 ## Tracing
 
+Modules that emit tracing events should import
+`crate::observability::prelude::*`, which re-exports `tracing` as `t`, instead
+of importing tracing macros directly and using them without a path.
+
+**Why?** Avoiding name collisions and diff churn, since the set of tracing
+macros used by a module tends to change frequently.
+
 `tracing` events should:
 
 1. Start with a capital letter (when applicable).
@@ -102,26 +109,33 @@ in mind. Especially, keeping Cargo unit tests in a dedicated tests file
 **Why?** Consistency is good. Also, interpolating values into the event message
 essentially defeats the point of structured logging.
 
+When emitting tracing events containing errors, use the `<level>_err!` macros
+from `observability::prelude` instead of `t::<level>!`.
+
+**Why?** This will log the full source chain instead of just the `Display` impl
+of the first error in the chain, making it easier to identify the cause of
+errors in thelogs.
+
 ### Examples
 
 #### 1
 
 ```rust,ignore
 // This does not conform because it does not start with a capital letter.
-info!("started pentametric fan");
+t::info!("started pentametric fan");
 
 // Do this instead:
-info!("Started pentametric fan");
+t::info!("Started pentametric fan");
 ```
 
 #### 2
 
 ```rust,ignore
 // This does not conform because it ends with punctuation.
-info!("Started pentametric fan.");
+t::info!("Started pentametric fan.");
 
 // Do this instead:
-info!("Started pentametric fan");
+t::info!("Started pentametric fan");
 ```
 
 #### 3
@@ -129,10 +143,20 @@ info!("Started pentametric fan");
 ```rust,ignore
 // This does not conform because it interpolates values into the event's
 // message.
-warn!("Noticed {} discombobulated waneshafts", count);
+t::warn!("Noticed {} discombobulated waneshafts", count);
 
 // Do this instead:
-warn!(count, "Noticed discombobulated waneshafts");
+t::warn!(count, "Noticed discombobulated waneshafts");
+```
+
+#### 4
+
+```rust,ignore
+// This does not conform because it logs only the first error in the chain
+t::error!(%error, "Failed to automatically synchronize cardinal grammeters");
+
+// Do this instead:
+error_err!(error, "Failed to automatically synchronize cardinal grammeters");
 ```
 
 ## Services