backups/grapevine
1
0
Fork 0
mirror of https://gitlab.computer.surgery/matrix/grapevine.git synced 2025-12-18 08:11: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 ## 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: `tracing` events should:
1. Start with a capital letter (when applicable). 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 **Why?** Consistency is good. Also, interpolating values into the event message
essentially defeats the point of structured logging. 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 ### Examples
#### 1 #### 1
```rust,ignore ```rust,ignore
// This does not conform because it does not start with a capital letter. // 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: // Do this instead:
info!("Started pentametric fan"); t::info!("Started pentametric fan");
``` ```
#### 2 #### 2
```rust,ignore ```rust,ignore
// This does not conform because it ends with punctuation. // This does not conform because it ends with punctuation.
info!("Started pentametric fan."); t::info!("Started pentametric fan.");
// Do this instead: // Do this instead:
info!("Started pentametric fan"); t::info!("Started pentametric fan");
``` ```
#### 3 #### 3
@ -129,10 +143,20 @@ info!("Started pentametric fan");
```rust,ignore ```rust,ignore
// This does not conform because it interpolates values into the event's // This does not conform because it interpolates values into the event's
// message. // message.
warn!("Noticed {} discombobulated waneshafts", count); t::warn!("Noticed {} discombobulated waneshafts", count);
// Do this instead: // 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 ## Services