Feedback: Logging Levels and Channels - reference on messages by channel

[hand-crdb]

Steven Hand (hand-crdb) commented:

Page: https://cockroachlabs.com/docs/v23.1/logging.html

What is the reason for your feedback?

[x] Missing the information I need

[ ] Too complicated

[ ] Out of date

[ ] Something is broken

[ ] Other

Additional details

This page does not answer the question of what specific messages are logged in each channel. It only gives a generalized statement for each channel and a few examples. This page needs to be enhanced with, or it needs to link to, an authoritative reference that lists every message that can be emitted by each channel (for a default CockroachDB configuration).

This reference should be automatically generated to keep it up-to-date with code changes. This might require developers to put at least an initial version of documentation for each message in the CockroachDB source code itself. This, in turn, may require messages to be managed as objects instead of being free-form text. (This is a best-practice for applications that have support for internationalization anyways, but I don't know if that is a design goal for CockroachDB or is a current implementation practice.)

I don't know if a comprehensive reference exists for every CockroachDB message, but something like that should exist, or should be created if it does not exist. The documentation should be 2-way to document the relationship between channels and messages:

• A list of channels should have a list of messages for each channel, and
• A list of messages should have a list of channels for each message.

For an example from SQL Server, see: http://www.sql-server-helper.com/error-messages/msg-501-1000.aspx

A real-life customer needs an answer to the question "Is there any place in the logs where we can find out how long an upgrade took?" The docs were unable to answer this question.

Jira Issue: DOC-7759

[exalate-issue-sync[bot]]

shannonb (shannonbradshaw) commented: Michael Wang what’s your take on this? Interested in getting a sense for priority and the possibility of the engineering work required (probably code comments, perhaps some automation) to make this happen.

[exalate-issue-sync[bot]]

Michael Wang (mwang1026) commented: cc Tommy Truongchau who owns logging infra