"Using logging" needs clarification?

[shige.abe@…]

I just got started with logging and following this paragraph:

​https://docs.djangoproject.com/en/dev/topics/logging/#using-logging

Is it true that you'll also need to add a logger in LOGGING called name to make it work?

If so, that's not clearly mentioned IMO.

Also, one would think it makes sense to put 'Using logging' after the documentation about configuring since it starts off with "Once you have configured..." and configuration hasn't been described at that point...

[Aymeric Augustin]

tl;dr Thanks for your feedback; however, I'm finding it hard to improve that section of the docs. I'll leave the ticket as Unreviewed so that someone else can take a look.

---

Replying to shige.abe@…:

Is it true that you'll also need to add a logger in LOGGING called name to make it work?

Technically, you can log directly with logging.error() and friends, but logging is best done through loggers.

Django's documentation contain a short intro to logging. It was added because Python's documentation of logging is large and intimidating. If you want the details (do I really need to do that?), you should read the reference. By design, a short intro will just cover the recommended use.

Replying to shige.abe@…:

If so, that's not clearly mentioned IMO.

Why the example uses __name__ and how to name loggers is discussed at length just below the example (Naming loggers). AFAICT, it's clear.

Replying to shige.abe@…:

Also, one would think it makes sense to put 'Using logging' after the documentation about configuring since it starts off with "Once you have configured..." and configuration hasn't been described at that point...

In order to strike a balance between, "Show me how it works quickly, I don't want to read the docs!" and "I don't understand the docs, there's not enough details!", the docs show a short example, and then gives the details. That's a common pattern in Python documentation. Sure, it's hard to please both top-down and bottom-up addicts...

[Aymeric Augustin]

We discussed this ticket on IRC, and we are going to accept it, but we're still usure of what to change exactly.

Could you upload a patch to show us how you would clarify this page?

[shige.abe@…]

Thanks for accepting this ticket.

I'm not an expert on how this works which is why I was confused, but I would think it should start off with the changes to settings followed by how to setup logging in models ending with some way to verify that something is being logged.

It would be super if the example showed emailing, logging to files and any other common use cases. For example, I'm not sure why logging to files as I have it set records useful info, but the emailed version is essentially blank!

It sounds like the Python docs talk about this in a lot more detail so we shouldn't duplicate that but I think it wouldn't be bad to expand the Django docs a little more to present a functional mini-tutorial.

Thanks again,
Shige

[Tim Graham]

I'm going to mark this as a duplicate of #19395 which suggests improving logging with a simple example and has some concrete proposals; it sounds like that's what's being requested here.