Add a custom stdlib logging.Formatter for MultiErrors

[nmalaguti]

This formatter will use format_exception to format all exceptions so that MultiError instances are logged properly.

Documentation is included showing how to register the formatter.

See gh-305.

[njsmith]

This is a great idea, thanks for looking at this.

I'm hesitant about two things:

• I'd like to keep the trio.* namespace as clean as possible, and trio.Formatter is pretty confusing. Really I'd rather not have to expose this at all -- see below -- but if we have to then trio.LoggingFormatter would be better.
• I'd really rather not force every Trio user have to paste in a bunch of boilerplate just to get useful logs. It would be much nicer if we could autoconfigure this for people -- it's not like anyone wants partial tracebacks, or that there are lots of different ways to do basic traceback formatting.

...so putting those together, I guess what I'm saying is... what do you think about monkeypatching logging.Formatter.formatException at import time?

I'm cringing just writing that, but we've kind of lost our innocence here already – we customize sys.excepthook at import time, and that interface really is just "hey we put this here so you can monkeypatch it". It also would have the advantage that it would automatically apply to subclasses who inherit the default formatException, so e.g. we don't have to make our own trio.BufferingFormatter. And as icky as it sounds, I can't really think of any situations where it would cause a problem -- mostly it would mean that people just get better logs automatically.

[codecov]

Codecov Report

Merging #344 into master will decrease coverage by 0.01%.
The diff coverage is 95.83%.

@@            Coverage Diff             @@
##           master     #344      +/-   ##
==========================================
- Coverage   99.24%   99.23%   -0.02%     
==========================================
  Files          87       87              
  Lines       10385    10806     +421     
  Branches      729      762      +33     
==========================================
+ Hits        10307    10723     +416     
- Misses         61       64       +3     
- Partials       17       19       +2

Impacted Files	Coverage Δ
trio/_toplevel_core_reexports.py	100% <ø> (ø)	⬆️
trio/_core/tests/test_multierror.py	100% <100%> (ø)	⬆️
trio/_core/_multierror.py	99.42% <87.5%> (-0.58%)	⬇️
trio/tests/test_socket.py	99.41% <0%> (-0.59%)	⬇️
trio/_core/tests/tutil.py	100% <0%> (ø)	⬆️
trio/tests/test_testing.py	100% <0%> (ø)	⬆️
trio/tests/test_highlevel_open_tcp_listeners.py	100% <0%> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d063d67...27155c4. Read the comment docs.

[njsmith]

(I think codecov is super-confused here because I merged #345 and then re-ran the travis tests, so there's some line mismatches between the Travis run and the Appveyor run. It should sort itself out if you push any more changes.)

[nmalaguti]

I think monkey patching on import makes it hard to opt out of the behavior. I don't think the behavior is bad or dangerous, but I can see it being irritating trying to avoid (we could rename the original so someone could put it back).

Ideally users would be able to do something similar to how django sets up its loggers, where they have specific handlers for everything under the django namespace. We could advocate something similar for trio that uses a specific formatter for those logs (trio.LoggingFormatter).

If we're looking to make it easy for people who just want it to work, offering a trio.monkey.patch_logging() that does the monkey patch seems like a reasonable compromise. You need to do slightly more than just import trio, but if you are already logging in the first place you probably have a config where adding trio.LoggingFormatter isn't a big deal.

If you're already using something like https://github.com/madzak/python-json-logger, then monkey patching really is your best option at that point.

[njsmith]

Obsoleted by #347