Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-2548

logging documentation is confusing, due to having two packages

    XMLWordPrintable

    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

          Hide
          spietrowicz Steve Pietrowicz added a comment -

          I believe this is still in Jacek's domain

          Show
          spietrowicz Steve Pietrowicz added a comment - I believe this is still in Jacek's domain
          Hide
          jbecla Jacek Becla added a comment -

          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.

          Show
          jbecla Jacek Becla added a comment - 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.
          Hide
          spietrowicz Steve Pietrowicz added a comment -

          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.

          Show
          spietrowicz Steve Pietrowicz added a comment - 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.
          Hide
          spietrowicz Steve Pietrowicz added a comment -

          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.

          Show
          spietrowicz Steve Pietrowicz added a comment - 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.
          Hide
          rowen Russell Owen added a comment -

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

          Show
          rowen Russell Owen added a comment - 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).
          Hide
          swinbank John Swinbank added a comment - - edited

          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?

          Show
          swinbank John Swinbank added a comment - - edited 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?
          Hide
          rowen Russell Owen added a comment -

          I think your changes will do the job. Please feel free to close this ticket (perhaps after reassigning it to yourself?)

          Show
          rowen Russell Owen added a comment - I think your changes will do the job. Please feel free to close this ticket (perhaps after reassigning it to yourself?)

            People

            Assignee:
            swinbank John Swinbank
            Reporter:
            rowen Russell Owen
            Watchers:
            Jacek Becla, John Swinbank, Kian-Tat Lim, Russell Owen, Steve Pietrowicz
            Votes:
            0 Vote for this issue
            Watchers:
            5 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved: