Opened 10 years ago

Last modified 4 years ago

#4008 enhancement new

Most examples in documentation do not log messages and errors

Reported by: ivank Owned by: Thijs Triemstra
Priority: normal Milestone:
Component: core Keywords: documentation, logging
Cc: Thijs Triemstra, ivank, Richard Wall Branch: branches/examples-logging-4008-2
branch-diff, diff-cov, branch-cov, buildbot
Author: thijs

Description

Most of the examples in the documentation don't log anywhere. This is a problem because things often go wrong, and silent failures are bad.

Projects/Twisted/doc]# for i in */examples/*.py; do echo -n $i; echo -n "\t"; grep "startLogging" $i; echo; done
conch/examples/sshsimpleclient.py
conch/examples/sshsimpleserver.py       log.startLogging(sys.stderr)

core/examples/ampclient.py
core/examples/ampserver.py
core/examples/bananabench.py
core/examples/chatserver.py
core/examples/courier.py        log.startLogging(open(LOGFILE, 'a'))

core/examples/cred.py       log.startLogging(sys.stdout)

core/examples/dbcred.py     log.startLogging(sys.stdout)

core/examples/echoclient.py
core/examples/echoclient_ssl.py
core/examples/echoclient_udp.py
core/examples/echoserv.py
core/examples/echoserv_ssl.py       log.startLogging(sys.stdout)

core/examples/echoserv_udp.py
core/examples/filewatch.py
core/examples/ftpclient.py
core/examples/ftpserver.py
core/examples/gpsfix.py     log.startLogging(logFile)

core/examples/longex2.py
core/examples/longex.py     log.startLogging(sys.stdout)

core/examples/mouse.py      log.startLogging(logFile)

core/examples/pbbenchclient.py
core/examples/pbbenchserver.py
core/examples/pbechoclient.py
core/examples/pbecho.py
core/examples/pb_exceptions.py
core/examples/pbgtk2.py
core/examples/pbinterop.py
core/examples/pbsimpleclient.py
core/examples/pbsimple.py
core/examples/postfix.py        log.startLogging(sys.stdout)

core/examples/ptyserv.py
core/examples/pyuidemo.py
core/examples/rotatinglog.py    log.startLogging(f)

core/examples/row_example.py
core/examples/row_util.py
core/examples/shaper.py
core/examples/shoutcast.py
core/examples/simpleclient.py
core/examples/simpleserv.py
core/examples/stdin.py
core/examples/stdiodemo.py
core/examples/testlogging.py        log.startLogging(sys.stdout)
# after startLogging

core/examples/wxacceptance.py       log.startLogging(sys.stdout)

core/examples/wxdemo.py     log.startLogging(sys.stdout)

mail/examples/imap4client.py        log.startLogging(sys.stdout)

mail/examples/smtpclient_tls.py         log.startLogging(sys.stdout)

names/examples/dns-service.py
names/examples/gethostbyname.py
names/examples/testdns.py
pair/examples/pairudp.py
web2/examples/demo.py
web2/examples/hello.py
web/examples/advogato.py
web/examples/dlpage.py
web/examples/fortune.rpy.py
web/examples/getpage.py
web/examples/google.py
web/examples/hello.rpy.py
web/examples/httpclient.py
web/examples/lj.rpy.py
web/examples/proxy.py
web/examples/report.rpy.py
web/examples/rootscript.py
web/examples/silly-web.py
web/examples/soap.py
web/examples/users.rpy.py
web/examples/vhost.rpy.py
web/examples/webguard.py            log.startLogging(sys.stdout)

web/examples/web.py
web/examples/xmlrpcclient.py
web/examples/xmlrpc.py
words/examples/aimbot.py
words/examples/cursesclient.py
words/examples/ircLogBot.py         log.startLogging(sys.stdout)

words/examples/jabber_client.py
words/examples/minchat.py
words/examples/msn_example.py       log.startLogging(sys.stdout)

words/examples/oscardemo.py
words/examples/pb_client.py         log.startLogging(sys.stdout)

words/examples/xmpp_client.py

Change History (22)

comment:1 Changed 10 years ago by Jean-Paul Calderone

Proper handling of error cases is probably something that merits unit tests.

comment:2 Changed 10 years ago by ivank

My main worry was that a lot of new users will be running and modifying these examples, and might not be aware that Twisted is (intentionally) not showing log messages/errors.

comment:3 Changed 10 years ago by Thijs Triemstra

Cc: Thijs Triemstra added
Owner: changed from Glyph to Thijs Triemstra
Status: newassigned

So is this ticket blocked by the fact the examples don't have unit tests, or can it be resolved by adding logging to the examples?

comment:4 Changed 10 years ago by ivank

I hope this ticket can be closed after adding logging to the examples. I think #84 is regarding unit tests for examples.

comment:5 Changed 9 years ago by Thijs Triemstra

Author: thijs
Branch: branches/examples-logging-4008

(In [30479]) Branching to 'examples-logging-4008'

comment:6 Changed 9 years ago by Thijs Triemstra

(In [30480]) add logging in conch example. refs #4008

comment:7 Changed 9 years ago by Thijs Triemstra

(In [30483]) add logging in names/pair examples. refs #4008

comment:8 Changed 9 years ago by Thijs Triemstra

(In [30484]) add logging in web/words examples. refs #4008

comment:9 Changed 9 years ago by Thijs Triemstra

Keywords: review added
Owner: Thijs Triemstra deleted
Status: assignednew

Updated logging and copyright in conch, names, pair, web and words examples. I skipped a couple of examples where I wasn't sure logging would work (gui examples) or have any benefit (simple/minimal examples).

comment:10 Changed 9 years ago by Thijs Triemstra

(In [30597]) add news file. refs #4008

comment:11 Changed 9 years ago by Stephen Thorne

Owner: set to Thijs Triemstra

Reading through the diff, I'm glad that this has been done. I note that the way logging is initialised isn't consistent.

12 examples start in 'main'/run()/main(), 10 import inside those area.

17 examples start in module scope, 19 import in module scope.

1 is exceptional, it logs to stderr instead of stdout. This is in doc/conch/examples/sshsimpleclient.py

Please update these examples so they are consistent. I think the best way to do this is to have the logging related lines together, i.e. if logging is initialized in name == 'main' the form that has been used like this is appropriate:

if __name__ == '__main__':
    import sys
    from twisted.python import log
    log.startLogging(sys.stdout)

When logging in the module scope, keeping things consistent isn't as important, I've read through a number of those examples and the consistency of order isn't as relevant.

Please update the examples so they are approximately of the form I've listed above. The only two ones that I think really require modification are ftpclient.py and ampclient.py. The rest read fine. I don't feel there's a big need to be totally consistent in every example.

comment:12 Changed 9 years ago by Stephen Thorne

Keywords: review removed

comment:13 Changed 9 years ago by <automation>

Owner: Thijs Triemstra deleted

comment:14 Changed 8 years ago by Thijs Triemstra

Branch: branches/examples-logging-4008branches/examples-logging-4008-2

(In [31984]) Branching to 'examples-logging-4008-2'

comment:15 Changed 8 years ago by Thijs Triemstra

(In [31985]) merge forward, address review comments. refs #4008

comment:16 Changed 8 years ago by Thijs Triemstra

Keywords: review added

Addressed feedback, up for review again.

comment:17 Changed 8 years ago by Thijs Triemstra

Cc: ivank added

comment:18 Changed 8 years ago by Glyph

Owner: set to Thijs Triemstra

I'm not entirely sure that this is a good idea. This may give people the impression that every Twisted program (i.e.: tac file, plugin) needs to have a startLogging call in it. None of the examples include any documentation. Plus, is stdout really the right place to do logging? Many of these programs are producing a couple messages to stdout. Some of them are referenced by howto documentation that describes their output. None of those howtos have been updated to explain why the lines that start logging are there.

At the very least, all of these examples should reference the logging tutorial, which should have a section explaining what they're doing and why.

comment:19 Changed 8 years ago by Glyph

Keywords: review removed

comment:20 Changed 8 years ago by Jean-Paul Calderone

The problem with the examples is only that if something about them breaks, it's not obvious. So we really only need to log exceptions and/or print error messages to stdout. Neither of these requires a startLogging call, fortunately.

comment:21 Changed 7 years ago by Richard Wall

Cc: Richard Wall added

Some examples can now be converted to use task.react which logs any uncaught exceptions to stderr.

I converted the twisted.names examples to use react and it works well.

See: #3270, #5596, #5989

comment:22 Changed 4 years ago by Wilfredo Sánchez Vega

Keywords: logging added
Note: See TracTickets for help on using tickets.