Details
-
Type:
Bug
-
Status: Done
-
Resolution: Done
-
Fix Version/s: None
-
Component/s: log, pex_logging
-
Labels:None
-
Team:Data Release Production
Description
The logging documentation for the LSST stack is confusing. There are two packages, listed very far apart from each other, with no indication of why there are two packages nor which one should be used for our code.
I strongly suggest that each package's main.dox file be updated to address this issue. It should clearly mention the existence of other package and give a rough idea of which one is to be used.
Here is the original description of this ticket, which may clarify the initial comments:
The pex_logging main page, which has a useful overview and tutorial, seems to not match the actual implementation anymore, at least for the python interface. For instance main.dox http://lsst-web.ncsa.illinois.edu/doxygen/x_masterDoxyDoc/log.html says:
In Python, the following logging functions are available in the lsst.log module. These functions take a variable number of arguments following a format string in the style of printf(). The use of *args is recommended over the use of the % operator so that formatting of log messages that do not meet the level threshold can be avoided.
I didn't actually expect pex_logging to contain such a free function (though that's what the documentation says) but I did expect the Log function to contain that method. It doesn't. Instead it has a logdebug method (different name) that does not seem to accept the arguments described above (though naturally it does accept a single string).
Unless I'm missing something the overview needs some significant work.
Attachments
Activity
Why would pex_logging be in my domain? 
I never touched pex_logging, and logging in general is in NSCA wbs, we just happened to help with logging because we needed it sooner than other groups.
Sorry, I thought this was referring to the changes in lsst.log and referred it to you because that's where the initial work was done. Didn't realize it referred to pex_logging.
Russell Owen, I believe the pex_logging package is going away in the near future. Since it's going to be replaced by lsst.log it might be better to have work done on the docs there rather than in pex_logging.
My mistake. I hadn't realized that both the new logging package and the old one that most code still uses were documented in the main.dox page. I wanted some info and clicked on the first link about logging, and thus got very confused.
But I'm surely not going to be the only one confused. The current situation is that we have two logging packages with no hint as to why, and the older package is extensively used but deprecated.
I suggest using this ticket to add a note to main.dox in both logging packages giving a very brief explanation of the fact that one is in the process of being adopted and the other is deprecated. It would be even better if the main Doxygen page's table of contents had that same info (e.g. "deprecated" after pex::logging and "being adopted" after the new one).
In discussion with Kian-Tat Lim and Russell Owen, it became clear that lsst::log should not be used for development on the science pipelines at least until RFC-29 has been resolved. With their agreement, I pushed notes to Doxygen for lsst::log and pex::logging making that clear.
Russell Owen – since this was a minor doc update, I pushed straight to master. However, I think it probably addresses your complaint in this issue. Can this now be closed?
I think your changes will do the job. Please feel free to close this ticket (perhaps after reassigning it to yourself?)
I believe this is still in Jacek's domain