Merge pull request #4 from taotetek/master
initial draft of log rfc
Peter Bourgon
9 years ago
| 0 | 0 | --- |
| 1 | 1 | RFC: 004 |
| 2 | Author: Peter Bourgon <peter@bourgon.org> | |
| 2 | Authors: Brian Knox <bknox@digitalocean.com> | |
| 3 | 3 | Status: Draft |
| 4 | 4 | --- |
| 5 | 5 | |
| 11 | 11 | |
| 12 | 12 | ## Scope |
| 13 | 13 | |
| 14 | To be defined. | |
| 14 | ### Key / Value Pairs | |
| 15 | * Log SHALL use key / value pairs for structured data. | |
| 16 | * Log MAY preserve type safety when expressing logs in a structured format that supports types | |
| 17 | * Log SHALL provide a way to set a default k/v set per log context | |
| 18 | * Log MAY provide some pre-canned default keys (level, time, etc) for convenience | |
| 19 | * Log MAY allow multiple stored logging contexts each with a different set of k/v pairs. | |
| 20 | * Log MAY allow per log call adhoc k/v pairs (see Logrus as an example) | |
| 21 | ||
| 22 | ### Transport | |
| 23 | * Log SHALL be transport agnostic with pluggable transports. | |
| 24 | * Log MAY implement io.MultiWriters allowing broadcast of logs over multiple transports. | |
| 25 | * Log MAY use channels instead | |
| 26 | * Log MAY provide some built in transports such as syslog and logstash. | |
| 27 | * Log MAY use encoding.* above the transport level | |
| 28 | * Log MAY provide configurable back pressure handling strategies in the case of blocked Writers | |
| 29 | ||
| 30 | ### Formats | |
| 31 | * Log SHALL be format agnostic by providing an interface for log formatting. | |
| 32 | * Log MAY provide some built in formatters such as RFC3164, JSON, etc. | |
| 33 | ||
| 34 | ### Levels | |
| 35 | * Log MAY provide a set of defined severity levels that can be used (perhaps as a wrapper). | |
| 36 | * Log SHALL include severity as a k/v pair and allow setting it through the same mechanism as any other k/v pair | |
| 37 | * Log MAY provide wrapper types as a convenience for setting the severity level | |
| 38 | * Log MUST NOT intrinsicly tie severity levels to program actions - e.g., a call to a specific log level should not call a panic. | |
| 39 | * Log MAY allow tying program actions such as panic to a log level. | |
| 15 | 40 | |
| 16 | 41 | ## Implementation |
| 17 | 42 | |
| 18 | To be defined.⏎ | |
| 43 | * The initial implementation should be a minimal feature set focused only on the scope of the RFC. | |
| 44 | * Additional features and niceties may be added as there is demonstrable proof that the features solve real world problems. | |