The term log_level is widely used in software applications to specify the granularity of log messages that should be captured, such as DEBUG, INFO, WARN, ERROR, and FATAL. This term, while prevalent, might not intuitively convey the hierarchical nature of these logging levels. @da2ce7’s suggestion to use the term threshold has merit and can be justified on several grounds.
Justification for threshold
RFC and Standard Documentation:
While specific RFCs for logging might not exist, relevant documentation such as the Syslog Protocol (RFC 5424) uses the term "Severity Level" to describe the importance of the messages. In this context, the concept of a "threshold" could be seen as the boundary at which messages of certain severity levels are logged.
Current Use of English:
The term "threshold" is defined as the level or point at which something starts or changes. In this case, it would represent the point at which messages become significant enough to be logged. This intuitively matches the concept of filtering log messages by their severity.
Conceptual Clarity:
Pros of threshold:
Intuitive Meaning: It clearly conveys the idea that messages below a certain importance level will not be logged.
Hierarchical Implication: It naturally implies a boundary, making it clear that anything above this boundary is included.
Precision: It reduces ambiguity and makes it easier for users to understand the filtering process.
Cons of threshold:
Less Familiarity: It might be less familiar to users who are accustomed to log_level, leading to a learning curve.
Inertia of Established Terms: Changing from a widely accepted term can cause confusion and require updates to existing documentation and practices.
Comparison with log_level
Pros of log_level:
Widespread Usage: It is a well-established term in the software industry, meaning users are likely already familiar with it.
Consistency: Many logging frameworks and tools use this term, providing consistency across different systems and documentation.
Cons of log_level:
Potential Ambiguity: The term does not inherently convey the idea of filtering or hierarchical inclusion, which might confuse new users.
Lack of Hierarchical Connotation: Users might not immediately understand that setting a log_level to INFO, for example, also includes WARN and ERROR messages.
Conclusion
Using threshold as the term for this configuration option can improve conceptual clarity and make the hierarchical nature of logging levels more apparent. However, adopting this term requires careful consideration of its potential impact on existing documentation, user familiarity, and industry standards. If your team decides to switch to threshold, it would be beneficial to provide clear documentation and possibly a transition guide to help users adapt to the new terminology.
Parent issue: https://github.com/torrust/torrust-tracker/issues/401 Relates to: https://github.com/torrust/torrust-tracker/issues/401#issuecomment-2180566059
@da2ce7 proposed to rename the
log_level
field in the configuration tothreshold
.It seems that
log_level
is a very common word, but I agree that it does not represent its true meaning.From:
To:
Links
ChatGTP
The term
log_level
is widely used in software applications to specify the granularity of log messages that should be captured, such as DEBUG, INFO, WARN, ERROR, and FATAL. This term, while prevalent, might not intuitively convey the hierarchical nature of these logging levels. @da2ce7’s suggestion to use the termthreshold
has merit and can be justified on several grounds.Justification for
threshold
RFC and Standard Documentation: While specific RFCs for logging might not exist, relevant documentation such as the Syslog Protocol (RFC 5424) uses the term "Severity Level" to describe the importance of the messages. In this context, the concept of a "threshold" could be seen as the boundary at which messages of certain severity levels are logged.
Current Use of English: The term "threshold" is defined as the level or point at which something starts or changes. In this case, it would represent the point at which messages become significant enough to be logged. This intuitively matches the concept of filtering log messages by their severity.
Conceptual Clarity:
threshold
:threshold
:log_level
, leading to a learning curve.Comparison with
log_level
log_level
:log_level
:log_level
to INFO, for example, also includes WARN and ERROR messages.Conclusion
Using
threshold
as the term for this configuration option can improve conceptual clarity and make the hierarchical nature of logging levels more apparent. However, adopting this term requires careful consideration of its potential impact on existing documentation, user familiarity, and industry standards. If your team decides to switch tothreshold
, it would be beneficial to provide clear documentation and possibly a transition guide to help users adapt to the new terminology.