Clarify ordering of log levels in the docs

DevJac commented

2020-10-30 17:00:19 -05:00

(Migrated from github.com)

It was not clear whether error or trace was the maximum log level.
The docs said "error! represents the highest-priority log messages and trace! the lowest".
Yet, set_max_level regards Trace to be the maximum level.

I attempted to clarify this by avoiding the terms "high" and "low" in the docs except for where
they are applicable to the Rust order as defined in Ord.

I spent about 30 minutes being confused by this. It seemed to me that set_max_level would be used to filter errors and warnings while emitting debug messages, which confused me.

I was going to create an issue first, but decided I would update the docs myself as an initial proposal of how to improve them, so I have created this PR instead.

It was not clear whether `error` or `trace` was the maximum log level. The docs said "`error!` represents the _highest_-priority log messages and `trace!` the _lowest_". Yet, `set_max_level` regards `Trace` to be the maximum level. I attempted to clarify this by avoiding the terms "high" and "low" in the docs except for where they are applicable to the Rust order as defined in `Ord`. I spent about 30 minutes being confused by this. It seemed to me that `set_max_level` would be used to filter errors and warnings while emitting debug messages, which confused me. I was going to create an issue first, but decided I would update the docs myself as an initial proposal of how to improve them, so I have created this PR instead.

👍 1

KodrAus commented

2020-12-20 23:43:26 -06:00

(Migrated from github.com)

Thanks @DevJac!

Hmm, I guess neither description is really capturing what log levels are all about. I think priority is probably a more accurate end-user description because info logs aren't necessarily less important than warnings or errors, they're just produced by different events occurring in your system. You probably care more about observing errors because they mean something is broken.

I guess what we're really trying to say in this section is that levels give you a hierarchy to tune the amount of noise being produced, with the assumption that you'll log fewer errors than warnings than infos than debugs than traces.

Perhaps we could avoid relating the log levels by priority or importance and just talk about ordering in terms of max levels so we say error represents the maximum log level that implies all the others and then list each level in order so it's clearer how they're ordered?

Thanks @DevJac! Hmm, I guess neither description is really capturing what log levels are all about. I think priority is probably a more accurate end-user description because info logs aren't necessarily less important than warnings or errors, they're just produced by different events occurring in your system. You _probably_ care more about observing errors because they mean something is broken. I guess what we're really trying to say in this section is that levels give you a hierarchy to tune the amount of noise being produced, with the assumption that you'll log fewer errors than warnings than infos than debugs than traces. Perhaps we could avoid relating the log levels by priority or importance and just talk about ordering in terms of max levels so we say error represents the maximum log level that implies all the others and then list each level in order so it's clearer how they're ordered?

DevJac commented

2020-12-21 12:20:23 -06:00

(Migrated from github.com)

Thanks for your thoughts @KodrAus.

I think priority is probably a more accurate end-user description because info logs aren't necessarily less important than warnings or errors

I agree that "priority" is a better description than "important". However, I do not like the word "highest" in the phrase "highest priority", because [in my opinion] "highest" and "maximum" are synonyms. I get confused reading that error is both "highest" and "minimum" - it seems contradictory to me, like saying "error is maximum and minimum".

I guess what we're really trying to say in this section is that levels give you a hierarchy to tune the amount of noise being produced, with the assumption that you'll log fewer errors than warnings than infos than debugs than traces.

I agree, and this was always clear to me having used logging libraries in other languages. My only point of confusion was what argument I should give to set_max_level.

Perhaps we could avoid relating the log levels by priority or importance and just talk about...

I think it will be difficult to talk about the log levels naturally without using min/max or some synonyms. For example, you said (emphasis mine)...

error represents the maximum log level

... but, (I gotcha 😉 ) error is, technically, the minimum log level. This is a great example of how difficult this is to talk about accurately.

One possible solution is to rename set_max_level to set_min_level. That would seem more natural to me. I can understand how others would see it differently though, and I don't know if it's worth changing.

Or we could just included a note like...

Note that Trace is the maximum level, because it provides the maximum amount of detail in the emitted logs.

... on set_max_level, as I have done. I would be 100% satisfied with only that note; that note would have saved me some time when I was first using log. We don't need to change any other wording.

What do you think?

Thanks for your thoughts @KodrAus. > I think priority is probably a more accurate end-user description because info logs aren't necessarily less important than warnings or errors I agree that "priority" is a better description than "important". However, I do not like the word "highest" in the phrase "_highest_ priority", because [in my opinion] "highest" and "maximum" are synonyms. I get confused reading that `error` is both "highest" and "minimum" - it seems contradictory to me, like saying "`error` is _maximum_ and _minimum_". > I guess what we're really trying to say in this section is that levels give you a hierarchy to tune the amount of noise being produced, with the assumption that you'll log fewer errors than warnings than infos than debugs than traces. I agree, and this was always clear to me having used logging libraries in other languages. My only point of confusion was what argument I should give to `set_max_level`. > Perhaps we could avoid relating the log levels by priority or importance and just talk about... I think it will be difficult to talk about the log levels naturally without using min/max or some synonyms. For example, you said (emphasis mine)... > error represents the **maximum** log level ... but, (I gotcha :wink: ) `error` is, technically, the **minimum** log level. This is a great example of how difficult this is to talk about accurately. One possible solution is to rename `set_max_level` to `set_min_level`. That would seem more natural _to me_. I can understand how others would see it differently though, and I don't know if it's worth changing. Or we could just included a note like... > Note that `Trace` is the maximum level, because it provides the maximum amount of detail in the emitted logs. ... on `set_max_level`, as I have done. I would be 100% satisfied with only that note; that note would have saved me some time when I was first using log. We don't need to change any other wording. What do you think?

👍 1

KodrAus commented

2020-12-23 16:41:13 -06:00

(Migrated from github.com)

It is all very tangled, isn't it. I think your last snippet on Trace though is very clear and understandable and I think that would be a great clarification.

It is all very tangled, isn't it. I think your last snippet on `Trace` though is very clear and understandable and I think that would be a great clarification.

DevJac commented

2020-12-26 23:21:19 -06:00

(Migrated from github.com)

Ok. I've reverted most of my wording changes, leaving only the note on set_max_level. Thanks again for your input on this. I think we are in agreement now?

Ok. I've reverted most of my wording changes, leaving only the note on `set_max_level`. Thanks again for your input on this. I think we are in agreement now?

KodrAus commented

2021-11-05 07:14:28 -05:00

(Migrated from github.com)

Sorry for never coming back to this! This looks good to me 🙇

Rows
Columns

Clarify ordering of log levels in the docs #420