lg 0.1.0
Python logging with sensible default values
License: MIT

Installation
------------

```pip install -U lg```

Why
---

Q: Why not use Python's logging module in stdlib?

A: You certainly can, but Python stdlib logging tends to be confusing to newcomers, and it has corner-case default behavior.

In this module, I tried to make logs easy to configure, with useful default 
behavior:

* Rotate and compress logs by default (using gzip compression).  zip is also supported
* Useful defaults for log-line and time formats (manual formatting is possible)
* Aggregate log lines in a memory buffer to minimize disk write operations
* Write json logs without significant CPU overhead

Multiple Logfile Caveat
-----------------------

If you want to log to different files in different parts of your scripts, you need to configure the different log objects with unique `log_ref` values.

Simple Usage: write json logs
-----------------------------

This example writes python dictionaries to json logs with compressed backups.

```python
from lg import Log

mylog = Log(
    log_ref="json_log01",
    log_path="mylog.log",
    line_fmt="auto_json", # json-compatible logs, use "auto_string" for text
                          #    json logs have an embedded timestamp on 
                          #    each logline.
    when="midnight",      # "D": days, "H": hours, "S": seconds, or "midnight"
    interval=1,           # Rotate every night at midnight
    backup_count=10,      # Number of logfiles to keep
    log_buffer=10*1024,   # 10KB memory buffer
    log_stdout=True       # Also write to stdout
    )

ii = 0
while True:
    mylog.log(
        {"this": "hello", "index": ii},
        loglevel="debug",
    )
    ii += 1
    if ii>100000:
        break

mylog.close()  # Close all logging handlers
```

A note regarding json logs.  Due to an optimization I made in json log format, 
be aware that you'll have to do some reformatting of the json logs when you read them as json.  The "auto_json" option logs individual lines in json log format.  However, the logfile itself will not be json-compliant until you add opening 
and closing square brackets to the contents of the logfile (to make the file 
look like a json list).

This example writes raw string log messages without a prepended datestamp on 
each line...

```python
from lg import Log

mylog = Log(
    log_ref="string_log01",# This is an arbitrary log identifier
    log_path="mylog.log",
    # line_fmt="auto_string" and "auto_json" use automatic line formatters
    # manual line_fmt reference:
    #    https://docs.python.org/3/library/logging.html#logrecord-attributes
    line_fmt="auto_string",
    when="S",              # "D": days, "H": hours, "S": seconds, or "midnight"
    interval=5,            # Rotate the log file every 5 seconds 
    log_compression="gzip",# Use gzip compression (gzip is the default)
    backup_count=10,       # Number of logfiles to keep
    log_buffer=10*1024,    # 10KB memory buffer
    log_stdout=True        # Also write to stdout
    )

ii = 0
while True:
    mylog.log("Test log message number".format(ii),
        loglevel="debug",
    )
    ii += 1
    if ii>100000:
        break

mylog.close()  # Close all logging handlers
```