Sift Log - JSON logging adapter for Python (now in color)
===============
## Features
* Tag log statements with arbitrary values for easier grouping and analysis
* Add keyword arguments that are converted to JSON values
* Variable substitution
* Specifies where log calls are made from
* Meant to be used with core Python logging (formatters, handlers, etc)
* Colorized logs on a console (POSIX only)
* `TRACE` log level built-in
## Examples
#### A simple log message
```python
log.info('Hello')
```
`{"msg": "Hello", "time": "12-12-14 10:12:01 EST", "level": "INFO", "loc": "test:log_test:20"}`
#### Logging with tags
```python
log.debug('Creating new user', 'MONGO', 'STORAGE')
```
`{"msg": "Creating new user", "time": "12-12-14 10:12:09 EST", "tags": ["MONGO", "STORAGE"], "level": "DEBUG", "loc": "test:log_test:20"}`
#### Appending more data
```python
log.debug('Some key', is_admin=True, username='papito')
```
`{"msg": "Some key", "is_admin": true, "username": "papito", "time": "12-12-14 10:12:04 EST", "level": "DEBUG", "loc": "test:log_test:20"}`
#### String substitution
```python
log.debug('User "$username" admin? $is_admin', is_admin=False, username='fez')
```
`{"msg": "User \"fez\" admin? False", "username": "fez", "is_admin": false, "time": "12-12-14 10:12:18 EST", "level": "DEBUG", "loc": "test:log_test:20"}`
## Setup
#### Logging to console
```python
import sys
import logging
from siftlog import SiftLog
logger = logging.getLogger()
logger.setLevel(logging.INFO)
handler = logging.StreamHandler(sys.stdout)
logger.addHandler(handler)
log = SiftLog(logger)
```
In this fashion, you can direct the JSON logs to [any logging handler](https://docs.python.org/2/library/logging.handlers.html).
#### Color
For enhanced flamboyancy, attach the `ColorStreamHandler` to your logger. The output will not have color if the logs
are being output to a file, or on systems that are not POSIX (will not work on Windows for now).
```python
from siftlog import SiftLog, ColorStreamHandler
logger = logging.getLogger()
handler = ColorStreamHandler(sys.stdout)
logger.addHandler(handler)
log = SiftLog(logger)
```
For development, you can opt in to use `ColorPlainTextStreamHandler`, for logs that are easier to parse visually.
##### Performance
While the above should play, it's highly recommended that the color handler is only
attached conditionally for local development.
##### Different colors
You can change font background, text color, and boldness:
```python
from siftlog import ColorStreamHandler
handler = ColorStreamHandler(sys.stdout)
handler.set_color(
logging.DEBUG, bg=handler.WHITE, fg=handler.BLUE, bold=True
)
```
##### Supported colors
* ColorStreamHandler.BLACK
* ColorStreamHandler.RED
* ColorStreamHandler.GREEN
* ColorStreamHandler.YELLOW
* ColorStreamHandler.BLUE
* ColorStreamHandler.MAGENTA
* ColorStreamHandler.CYAN
* ColorStreamHandler.WHITE
#### Constants (re-occurring values)
You can define constants that will appear in every single log message. This is useful, for example, if you'd like to log process PID and hostname with every log message. This is done upon log adapter initialization:
```python
import os
from siftlog import SiftLog
log = SiftLog(logger, pid=os.getpid(), env='INTEGRATION')
```
`{"msg": "And here I am", "time": "12-12-14 11:12:24 EST", "pid": 37463, "env": "INTEGRATION", "level": "INFO"}`
### Dynamic logging context - callbacks
Often you need to add dynamic contextual data to log statements, as opposed to simple constants/literals. You can
pass methods to SiftLog on initialization that will be called on every logging call.
Logging request ids or user ids are very common use cases, so to log a thread-local property with Flask, for example,
we can do the following:
```python
import flask
def get_user_id():
if flask.has_request_context():
return flask.g.user_id
user_aware_logger = SiftLog(u_id=get_user_id)
```
#### Custom time format
```python
log = SiftLog(logger)
SiftLog.TIME_FORMAT = '%Y/%m/%d %H:%M:%S.%f'
```
Define the format as accepted by [strftime()](https://strftime.org/)
#### Custom location format
```python
log = SiftLog(logger)
SiftLog.LOCATION_FORMAT = '$module:$method:$line_no'
```
The format should be a string containing any of the following variables:
* `$file`
* `$line_no`
* `$method`
* `$module`
#### Custom core key names
Core keys, such as `msg` and `level` can be overridden, if they clash with common keys you might be using.
The following can be redefined:
* SiftLog.MESSAGE (default `msg`)
* SiftLog.LEVEL (default `level`)
* SiftLog.LOCATION (default `loc`)
* SiftLog.TAGS (default `tags`)
* SiftLog.TIME (default `time`)
As in:
```python
log = SiftLog(logger)
SiftLog.log.MESSAGE = "MESSAGE"
```
## Development flow
`Poetry` is used to manage the dependencies.
Most things can be accessed via the Makefile, if you have Make installed.
Without Make, just inspect the Makefile for the available commands.
# use the right Python
poetry use path/to/python/3.8-ish
# make sure correct Python is used
make info
# install dependencies
make install
# run tests
make test
# run visual tests (same as tests but with output)
make visual
# formatting, linting, and type checking
make lint
### Running a single test
In the standard Nose tests way:
poetry run nosetests siftlog/tests/test_log.py:TestLogger.test_tags
Raw data
{
"_id": null,
"home_page": "https://github.com/papito/siftlog-py",
"name": "siftlog-py",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "logging,logs,structured",
"author": "Andrei Taranchenko",
"author_email": "drey10@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5e/d5/8dc8528a6df0a0015c248e7ec376b28e5ae1dd17ccc581210cf87ddba9e3/siftlog_py-0.9.5.tar.gz",
"platform": null,
"description": "Sift Log - JSON logging adapter for Python (now in color)\n===============\n\n\n\n## Features\n* Tag log statements with arbitrary values for easier grouping and analysis\n* Add keyword arguments that are converted to JSON values\n* Variable substitution\n* Specifies where log calls are made from\n* Meant to be used with core Python logging (formatters, handlers, etc)\n* Colorized logs on a console (POSIX only)\n* `TRACE` log level built-in\n \n## Examples\n#### A simple log message\n```python\nlog.info('Hello')\n```\n`{\"msg\": \"Hello\", \"time\": \"12-12-14 10:12:01 EST\", \"level\": \"INFO\", \"loc\": \"test:log_test:20\"}`\n\n#### Logging with tags\n```python\nlog.debug('Creating new user', 'MONGO', 'STORAGE')\n```\n`{\"msg\": \"Creating new user\", \"time\": \"12-12-14 10:12:09 EST\", \"tags\": [\"MONGO\", \"STORAGE\"], \"level\": \"DEBUG\", \"loc\": \"test:log_test:20\"}`\n\n#### Appending more data\n```python\nlog.debug('Some key', is_admin=True, username='papito')\n```\n`{\"msg\": \"Some key\", \"is_admin\": true, \"username\": \"papito\", \"time\": \"12-12-14 10:12:04 EST\", \"level\": \"DEBUG\", \"loc\": \"test:log_test:20\"}`\n\n#### String substitution\n```python\nlog.debug('User \"$username\" admin? $is_admin', is_admin=False, username='fez')\n```\n`{\"msg\": \"User \\\"fez\\\" admin? False\", \"username\": \"fez\", \"is_admin\": false, \"time\": \"12-12-14 10:12:18 EST\", \"level\": \"DEBUG\", \"loc\": \"test:log_test:20\"}`\n\n\n## Setup\n#### Logging to console\n```python\nimport sys\nimport logging\nfrom siftlog import SiftLog\n\nlogger = logging.getLogger()\nlogger.setLevel(logging.INFO)\nhandler = logging.StreamHandler(sys.stdout)\nlogger.addHandler(handler)\n\nlog = SiftLog(logger)\n```\nIn this fashion, you can direct the JSON logs to [any logging handler](https://docs.python.org/2/library/logging.handlers.html).\n\n#### Color\nFor enhanced flamboyancy, attach the `ColorStreamHandler` to your logger. The output will not have color if the logs\nare being output to a file, or on systems that are not POSIX (will not work on Windows for now).\n\n```python\nfrom siftlog import SiftLog, ColorStreamHandler\n\nlogger = logging.getLogger()\nhandler = ColorStreamHandler(sys.stdout)\nlogger.addHandler(handler)\n\nlog = SiftLog(logger)\n```\n\nFor development, you can opt in to use `ColorPlainTextStreamHandler`, for logs that are easier to parse visually.\n\n##### Performance\n\nWhile the above should play, it's highly recommended that the color handler is only \nattached conditionally for local development.\n\n\n##### Different colors\nYou can change font background, text color, and boldness:\n\n```python\nfrom siftlog import ColorStreamHandler\n\nhandler = ColorStreamHandler(sys.stdout)\nhandler.set_color(\n logging.DEBUG, bg=handler.WHITE, fg=handler.BLUE, bold=True\n)\n```\n\n##### Supported colors\n * ColorStreamHandler.BLACK\n * ColorStreamHandler.RED\n * ColorStreamHandler.GREEN\n * ColorStreamHandler.YELLOW\n * ColorStreamHandler.BLUE\n * ColorStreamHandler.MAGENTA\n * ColorStreamHandler.CYAN\n * ColorStreamHandler.WHITE\n\n#### Constants (re-occurring values)\nYou can define constants that will appear in every single log message. This is useful, for example, if you'd like to log process PID and hostname with every log message. This is done upon log adapter initialization:\n\n```python\nimport os\nfrom siftlog import SiftLog\nlog = SiftLog(logger, pid=os.getpid(), env='INTEGRATION')\n```\n`{\"msg\": \"And here I am\", \"time\": \"12-12-14 11:12:24 EST\", \"pid\": 37463, \"env\": \"INTEGRATION\", \"level\": \"INFO\"}`\n\n### Dynamic logging context - callbacks\nOften you need to add dynamic contextual data to log statements, as opposed to simple constants/literals. You can\npass methods to SiftLog on initialization that will be called on every logging call.\n\nLogging request ids or user ids are very common use cases, so to log a thread-local property with Flask, for example,\nwe can do the following:\n\n```python\nimport flask\n\ndef get_user_id():\n if flask.has_request_context():\n return flask.g.user_id\n\nuser_aware_logger = SiftLog(u_id=get_user_id)\n```\n\n#### Custom time format\n```python\nlog = SiftLog(logger)\nSiftLog.TIME_FORMAT = '%Y/%m/%d %H:%M:%S.%f'\n```\nDefine the format as accepted by [strftime()](https://strftime.org/)\n\n#### Custom location format\n```python\nlog = SiftLog(logger)\nSiftLog.LOCATION_FORMAT = '$module:$method:$line_no'\n```\nThe format should be a string containing any of the following variables:\n\n * `$file`\n * `$line_no`\n * `$method`\n * `$module`\n\n#### Custom core key names\nCore keys, such as `msg` and `level` can be overridden, if they clash with common keys you might be using.\n\nThe following can be redefined:\n\n * SiftLog.MESSAGE (default `msg`)\n * SiftLog.LEVEL (default `level`)\n * SiftLog.LOCATION (default `loc`)\n * SiftLog.TAGS (default `tags`)\n * SiftLog.TIME (default `time`)\n\nAs in:\n\n```python\nlog = SiftLog(logger)\nSiftLog.log.MESSAGE = \"MESSAGE\"\n```\n\n## Development flow\n\n`Poetry` is used to manage the dependencies.\n\nMost things can be accessed via the Makefile, if you have Make installed.\nWithout Make, just inspect the Makefile for the available commands.\n\n # use the right Python\n poetry use path/to/python/3.8-ish\n \n # make sure correct Python is used\n make info\n \n # install dependencies\n make install\n \n # run tests\n make test\n \n # run visual tests (same as tests but with output)\n\tmake visual\n \n # formatting, linting, and type checking\n make lint\n\n### Running a single test\n\nIn the standard Nose tests way:\n\n poetry run nosetests siftlog/tests/test_log.py:TestLogger.test_tags\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "JSON and human-readable logging with context",
"version": "0.9.5",
"split_keywords": [
"logging",
"logs",
"structured"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "e0a7eb148d4e742d177c3d6ceea982c2",
"sha256": "f8ca4f5bbe1d5742e8beb109c263d5621a9025e431a5b6c930199695696ec93c"
},
"downloads": -1,
"filename": "siftlog_py-0.9.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e0a7eb148d4e742d177c3d6ceea982c2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 12708,
"upload_time": "2022-12-12T11:36:59",
"upload_time_iso_8601": "2022-12-12T11:36:59.156024Z",
"url": "https://files.pythonhosted.org/packages/55/5e/1b10681508ca9a47791350f97dde0713c2a67f76c5ef33d10cd70867b7d5/siftlog_py-0.9.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "b3180c64558693a3a0609a8b494d7b0d",
"sha256": "e977eb9c9701bcf2cb8c011e3bf98de1598bf19a77ac36b895e633c54fddb3a1"
},
"downloads": -1,
"filename": "siftlog_py-0.9.5.tar.gz",
"has_sig": false,
"md5_digest": "b3180c64558693a3a0609a8b494d7b0d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 10578,
"upload_time": "2022-12-12T11:37:01",
"upload_time_iso_8601": "2022-12-12T11:37:01.621111Z",
"url": "https://files.pythonhosted.org/packages/5e/d5/8dc8528a6df0a0015c248e7ec376b28e5ae1dd17ccc581210cf87ddba9e3/siftlog_py-0.9.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-12 11:37:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "papito",
"github_project": "siftlog-py",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "siftlog-py"
}
JSON
