backups/grapevine
1
0
Fork 0
mirror of https://gitlab.computer.surgery/matrix/grapevine.git synced 2025-12-16 23:31:24 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

update style guide for new logging style

Browse source
This commit is contained in:
Olivia Lee 2024-12-14 18:05:53 -08:00
parent 165ff0b50c
commit 414feb0455
No known key found for this signature in database
GPG key ID: 54D568A15B9CD1F9
1 changed files with 30 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

36
book/contributing/style-guide.md
View file

@ -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