Skip to content
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,27 @@ We're currently experimenting with hosting the majority of lodestar packages and
- Error: One or more main functionalities are not working, preventing some functions from working properly.
- Fatal: One or more main functionalities are not working and preventing the application from fulfilling its duties.

## Logging policy
Comment thread
dapplion marked this conversation as resolved.
Resolved

### Logging Levels

- `error`: Critical issues that prevent the application from functioning correctly or cause significant disruption to users. Examples include failed network connections, crashes, or data corruption.
Comment thread
dapplion marked this conversation as resolved.
Resolved
- `warn`: Situations that may lead to critical issues if not addressed but do not prevent the application from functioning. Examples include configuration issues, deprecated features, or temporary network disruptions.
- `info`: General sporadic informational about the node's state. Examples include initialization messages, infrequent periodic status updates, or high-level progress reports.
- `verbose`: _TBD_
Comment thread
dapplion marked this conversation as resolved.
Resolved
- `debug`: Detailed diagnostic information that can help developers or users troubleshoot specific issues. Examples include individual request logs for every REST API, networking interactions, or internal components status changes.

### Guideliness

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like we need a guideline about when/where to include a stack trace

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a good point. How could we summarize it? I would say that when the error message provides all possible location information the stack trace can be omitted. We do not support suppressing stack traces out of the box, and the uncontrolled nature of Javascript exceptions could be an issue if we start omitting stack traces. very relevant to this topic https://www.youtube.com/watch?v=6cap2HiBFVQ

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we ok with not adding a bit more details about stack traces? I think the ApiError is a pretty good example of when not to include the stack trace as changed in #5285

  • it is thrown on a higher level in the stack
  • it is explicitly thrown based on simple assertions
  • the error is expected to happen due to invalid client requests
  • the error message is usually good which makes it easy to find out where it was thrown

Not including the stack trace of course can come with a cost of not being able to easily debug an issue but this should be rarely the case if we are careful to only do it for some errors but let's not forget the cost of including the stack trace in terms of UX. Not being able to easily read the logs because of too much stack trace is also not ideal.

I would argue that debug logs can include stack traces more often/always but for levels higher than or equal info need to be more careful.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just approved the PR so this didn't sit for too long. Happy to merge more verbiage about when stack traces are acceptable. Totally agree with your comment.

Comment thread
dapplion marked this conversation as resolved.
Resolved

1. Always use the appropriate log level as defined above. Log messages should be clear and concise, providing enough information to understand the context and severity of the issue.
Comment thread
dapplion marked this conversation as resolved.
Resolved
2. Avoid excessive logging. Log only the information that is necessary for understanding and troubleshooting issues. Over-logging can make it more difficult for users to find relevant information.
3. Do not log sensitive data, such as private keys, user credentials, or personal information.
4. Do not log arbitrary data from the network as ASCII or UTF8 at levels higher or equal to the current default level.
Comment thread
dapplion marked this conversation as resolved.
Resolved
5. Use clear and concise language. Prefer to log variables in JSON format `log.debug("Action", {slot})` instead of formating the text yourself `log.debug('slot=${slot}')`.
Comment thread
dapplion marked this conversation as resolved.
Resolved
6. Include only relevant context in log messages, sufficient to debug the issue or action it refers to.

Contributors must chose the log level carefully to ensure a consistent experience for every type of user:
Comment thread
dapplion marked this conversation as resolved.
Resolved

## Contributing to Grafana dashboards

To edit or extend an existing Grafana dashboard with minimal diff:
Expand Down