EEP! 1 - Standard for the use of logging in Eppy - DRAFT

[jamiebull1]

I find logging really useful when developing. Are there any reasons why there isn't any logging at the moment? The only issue I've come across in the past is difficulty using it in conjunction with multiprocessing (though it's not impossible). That doesn't seem to be an issue in eppy though.

If this sounds useful, would it be possible to start a new branch to start adding logging code? I'm happy to make a logging config module and contribute new logging to bits I touch as I try to find my way around the code a bit better. It may also be useful to have some kind of a standard (or an EEP!) on what level of logging is appropriate for various situations and I can help out with that too.

[santoshphilip]

Can you articulate this a little more. May be flesh out a use case.
I am not fully groking this.

This may be the start of an EEP!

[jamiebull1]

EEP!: 1
Title: Standard for the use of logging in Eppy
Version: 0.0.1
Last-Modified: 17 Jun 2015
Author: Jamie Bull jamie.bull@oco-carbon.com
Status: Draft
Type: Standards Track
Created: 17-Jun-2015
Eppy-Version: >=0.4.6.4a

Abstract
This inaugural Eppy Enhancement Proposal (EEP) puts forward use cases
for logging, from both a developer and a user perspective.

The proposal is not that logging is made a requirement, just that logging
can be implemented easily and consistently where a developer sees a need.

Rationale
Logging has two main use cases, each of which has unique characteristics
that mean it should be treated differently.

In the case of developers, when errors arise, the stack trace often does not
contain enough information to understand what has caused the problem. In
these situations, logging can reveal not only the call stack, but also
information about the data and parameters. Unexpected values could suggest
the need for additional tests and/or input validation.

This could be followed in real time by viewing the tail of a log file or by
viewing the output to stdout.

For users, a track of what is happening in their program can be useful when
learning how Eppy software does what it does. They may also appreciate being
able to submit a log along with a bug report, and this should allow
contributors to understand the source of errors more quickly.

A user may also want to refer to more detailed logs to at a later time,
particularly useful when using Eppy to generate large numbers of IDFs from
variable and perhaps invalid inputs.

Proposed standards

1. Logging module
   All logging should use a logging configuration file. This could either be
   directly in a python file (quicker to code), or alternatively an .ini
   file (easier for users to edit). This will help to ensure a consistent
   logging format is followed across modules. To implement logging within a
   module, all that needs to be added is the following code:

   import eppy.log_config  # module location tbd
   
   # create a module-level logger 
   logger = log_config.get_logger(__name__)
   
   # used as follows
   logger.debug("This is a DEBUG level message")
   logger.info("This is an INFO level message")

2. Log levels
   The level for a logging call should generally follow those recommended by
   the logging module documentation, "Logging HOWTO" [1] in the Python
   documentation. For the most part, developers will be interested in the
   DEBUG level messages which contain details of data and parameters,
   while users will likely be more concerned with INFO level messages which
   track the 10000 ft view of activity.

3. Verbosity
   Given that there are at least two use cases, and that logs can grow
   very large, there should be a verbosity flag that can be set to hide
   messages below a given level. Messages could be hidden either in a log
   file for a specific logging level, or by not logging them at all (e.g.
   not logging at the debug level for general users). This should be set in
   the config file and should be configurable during runtime.

References
[1] Logging HOWTO, Vinay Sajip
https://docs.python.org/2/howto/logging.html

Copyright
This document has been placed in the public domain.

[santoshphilip]

Jamie, This is an awesome start.
Now I grok what you are going after.

Some further thoughts:

• each eppy function could be log-enabled
• Meaning it would know how to make a log of it's actions
• the logging ability is turned off by default, to be turned on when needed.

Another idea:

• The log can be in many formats:
  • standard log format
  • json format
• The json log can be treated as a recording of the script's actions
• If you send the json-log to someone, they can replay the actions of that script (maybe on another file set)
• Maybe json-log could be a way of building Ashrae Baseline buildings from a model

[santoshphilip]

EEP!

I think there should be an exclamation mark after it !
just because it looks and sounds cool :-)

I notice that the copyright is public domain
Shall we put some thought into this. Should it be one of the Creative Commons licenses?
What does PEP do for it's license ?

[jamiebull1]

Some good suggestions there. I like the idea of a full record of actions. It could be switched on and off as with recording a macro in Excel/Word. It also opens up the possibility of an "undo"/"redo" function if Eppy is used as the backend of an editor. Another benefit of having comprehensive logging/replayability is it makes the whole process of using Eppy auditable, which could be of value to engineers.

For making every function log-enabled, this decorator might be a good start. It just needs modifying to include the parameters and return value.

Also agree with off by default.

The licence credit is exactly the same as you find at the bottom of any PEP. See item 3 on this list. Their other recommendation is an Open Publication Licence which is more restrictive. I see no reason to have a problem with it being reused by others for their logging policies, and if a CC licence encourages that it's fine by me.

[santoshphilip]

The "undo/redo" for an editor is cool. Now you get it for free with eppy :-)

Good thinking about using a decorator.
Not all changes made by eppy is through functions. Some changes are simple assignments.

Bunilding.Name  = "White House"

Of course, in python even simple assignments are really functions.

__getattr__ and __setattr__ 

are called behind the scenes and you can see how eppy overrides it in eppy/bunch_subclass.py
(There are times I really love python)

[santoshphilip]

Regarding the license, you have sensitized me about copyright issues.
I am putting a lot more thought into it and will have further comments in issue #47

If PEP is using Public Domain I am good with it for EEP!

[eayoungs]

I think this is a great idea, I could use it right about now, and I think it would lower the barrier to entry for new contributors.

Great idea, jamiebull1

[jamiebull1]

I've started a branch i50_logging to work on this draft EEP! and then implement the logging module.
The EEP! is here for comments, edits, etc.

[santoshphilip]

Looks like you branched from master
Based on our discussion in
#51 (comment)
develop is a better place to branch from

It is good to have you roll up your sleeves and get into this.

[jamiebull1]

Understood. Although it shouldn't cause any conflicts if we keep this is just for the EEP!

[jamiebull1]

This is now implemented as a draft if anyone wants to take a look. I still need to write some more tests to see how we handle objects being passed into the logs, but this gives an idea of what I was getting at. Usage documentation is in the EEP!.

[santoshphilip]

I see a

• from pythonjsonlogger import jsonlogger
• in eppylog

where can I find "pythonjsonlogger".
"pip install pythonjsonlogger" did not find it.

I also see that you use "testfixtures"
I have never used that. I should take a look

I have no comments on the EEP! yet :-). I am still digesting it.

[jamiebull1]

That's "pip install python-json-logger".

As for testfixtures, I'd not used them before myself, but searching for a way of testing logging code it came out as the simplest approach.

[santoshphilip]

Jamie,
you may want to do a
git pull origin i50_logging
before you start working on that branch.

I did a merge when I checked out i50_logging from origin.
It affected only one file and it was not a file you were working on.
(got a merge conflict on that file)
Somehow my local version of i50_logging had diverged from the remote version

It is 4am in the morning and I am not sure how that happened :-(
I probably should have left your branch alone and not merged into it.

[jamiebull1]

I've been thinking that it ought to be sufficient to have a log of all API-level calls to achieve the "playback" function, as well as for repeating actions on a second data set. To do that we'd need to define which functions are counted as part of the API, and which are "internals". That might be something for further down the line though as I think just having a standardised logging module available for developers is of value in itself.

[jamiebull1]

Looking back at this it also seems to be working as expected. Should I put together a bit of documentation? There's probably something can pulled out of the EEP!