Opened 4 years ago

Closed 23 months ago

#16228 closed Cleanup/optimization (duplicate)

"Using logging" needs clarification?

Reported by: shige.abe@… Owned by: nobody
Component: Documentation Version: 1.3
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

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...

Change History (4)

comment:1 in reply to: ↑ description Changed 4 years ago by aaugustin

  • Easy pickings unset
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

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...

comment:2 Changed 4 years ago by aaugustin

  • Triage Stage changed from Unreviewed to Accepted

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?

comment:3 Changed 4 years ago by 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

comment:4 Changed 23 months ago by timo

  • Resolution set to duplicate
  • Status changed from new to closed

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.

Note: See TracTickets for help on using tickets.
Back to Top