Logging improvements

[aantron]

• Setting different levels for sub-logs.
• Neat multi-line logging.
• Log JSON, or write the whole log as JSON? This depends on JSON improvements.
• Log-anything.
• Document how to log to file or in real deployments.

See Logging.

[shonfeder]

Perhaps this goes here: I can't see any clear way of logging to a file (outside of redirecting stderr). Adding support for this, or documenting the expectations around how this would be achieved (even if redirecting stderr is the expected way) would be helpful!

[aantron]

@shonfeder Agreed. In the last few days, Dream has gotten 4 deployment setups, all of which handle logs, and give a log-viewing command. I haven't yet had a chance to "surface" them properly, but will do so soon. The systemd and Docker setups log to journald in production (on Ubuntu and similar systems). The Heroku setup logs to Heroku's logs, of course :) In all cases, though, the surrounding deployment "system" abstracts away the true log destination, and expects to capture stderr from the various processes it manages, some of which are OCaml programs running Dream. Could you describe a scenario in which you would log to file at the Dream level?

[shonfeder]

Oh I think those deployment setups are sufficient!

Since the docs call out the use of Logs, and since it's easy to configure Logs to log to multiple reporters, it might be worth noting in the docs that this kind of configuration isn't supported and that all persistent logging is meant to read from stderr? Or maybe not. Perhaps that'd be obvious to other readers, and in any case this exchange will server as a discoverable record :)

For my purposes, the deployment documentation is excellent and fully satisfying. Thank you!

[cemerick]

@aantron In logs.ml, the top comment says:

Among other things, this module wraps the Logs library so as to prepend request ids to log messages.

Can you expand on what other things the Logs library wrapper is intended to address? I need to add support for a custom logs reporter (to enable structured logging as expected by most cloud logging platforms), and it would be helpful to understand the full intent behind the logging wrapper.

(As a bonus, a custom reporter facility would make implementing #1 super easy 😜)