diff --git a/text/000-structured-logging.md b/text/000-structured-logging.md new file mode 100644 index 0000000000000..2866ee983022c --- /dev/null +++ b/text/000-structured-logging.md @@ -0,0 +1,106 @@ +- Start Date: 2019-02-26 +- RFC PR: (leave this empty) +- Gatsby Issue: (leave this empty) + +# Summary + +Add structured logging support to Gatsby. + +As Gatsby has evolved, it's outgrown its current log reporter. In order to fix existing issues, support the upcoming Gatsby Preview service and enable future features like a browser-based logger or indexed error messages, we need to improve the way Gatsby creates and outputs its logs. + +See this issue for a good overview of current logging limitations: https://github.com/gatsbyjs/gatsby/issues/11076. + +## Requirements + +- minimal (ideally 0) breaking changes +- support different log levels +- support multiple log formatters (e.g. output logs in json format, output logs to a file, output without colours and spinners for non-tty environments) +- maybe support custom user-provided log formatters? +- should be easier to use across all parts of Gatsby - e.g. within the sharp transformer or the createRemoteFileNode helper + +This doesn't, on its own, fix the concurrent log conflict issue (demo'd in the linked issue) but puts the pieces in place for that to be solved. + +# Basic example + +Example log message: + +```js +{ + "data": "I am a log message, this is freeform text", + "id": //optional, link related messages to each other + "time": "2019-02-03T19:02:57.534Z", + "type": "info", + "v": 0 // version so we can change the structure in future? +} +``` + +Example usage in a gatsby-node.js file: + +```js +exports.onCreateNode = ({ actions, reporter }) => { + // Supports the existing 'reporter' API + reporter.info(`I am a log message, this is freeform text`); + + // Using a new 'log' action instead of the existing reporter API + const { log } = actions; + log({ + message: `I am a log message, this is freeform text`, + type: `info` + }); +}; +``` + +[See this proof of concept for more examples](https://github.com/m-allanson/gatsby/pull/43/files?utf8=✓&diff=unified&w=1), including how activity timers could work. Note that these examples are not in any way final - the implementation of this RFC could take a totally different approach. + +# Motivation + +(see summary) + +# Detailed design + +See [this minimal proof-of-concept](https://github.com/m-allanson/gatsby/pull/43) for one approach at implementing this. + +This creates [a new `log` action](https://github.com/m-allanson/gatsby/pull/43/files#diff-f61af2b51837961d211c7ea1a4b91837) in Gatsby, and [replaces the existing reporter with a wrapper around the log action](https://github.com/m-allanson/gatsby/pull/43/files#diff-237d3207439e181589c4b0bfbc06a61b). New [log actions are handled](https://github.com/m-allanson/gatsby/pull/43/files#diff-8c8b888e741f1c31e97d4bf05894f50d) in one place. + +# Drawbacks + +There's the potential to create breaking changes with this work - these should be weighed very carefully before going ahead with them. + +This feature is blocking a series of future features and bug fixes. Maybe these issues can be tackled on a case-by-case basis without needing structured logs (although I think it would be difficult). + +The exact implementation for this hasn't been worked out, maybe there will be problems that haven't been thought about yet. + +Maybe there's an approach that provides the benefits of structured logging without needing to run logs through Gatsby's internal redux store. + +# Alternatives + +Related tools that have good log output: + +- [Expo CLI](https://github.com/expo/expo-cli) +- [Jest's CLI](https://github.com/facebook/jest) +- [Vue CLI](https://cli.vuejs.org/) + +# Adoption strategy + +This would mostly be an internal change. See next section for more details. + +# How we teach this + +Initially by ensuring compatibility with the existing reporter. + +Any changes will most likely affect plugin authors. If changes to plugins are required, we can update official plugins, create documentation and reach out directly to plugin maintainers. + +Existing Gatsby developers will be unaffected by this change unless they are maintaining a Gatsby plugin. Even then we should aim to avoid creating work for plugin maintainers wherever possible. + +# Unresolved questions + +- do we have to maintain backwards compatibility with the existing reporter? Probably large majority of usage is in Gatsby monorepo. +- there are some parts of Gatsby that use the existing reporter before the redux store is available. What do we do there? +- should we use something like winston or bunyan to output logs? +- how do we make this easier to use in plugins / helper functions? +- should we monkey patch console.log to point people towards this logger instead, or automatically forward console messages to this new log format? +- should this remain as part of gatsby-cli, move into the gatsby package, or have its own package? + +--- + +Thanks @oorestisime for writing up [issue #11076](https://github.com/gatsbyjs/gatsby/issues/11076)