# ulogger
[](https://github.com/spotify/ulogger/actions/workflows/main.yml) [](https://codecov.io/github/spotify/ulogger)
A micro Python logging library.
Supported handlers:
* stream (stdout)
* syslog
* [stackdriver](https://cloud.google.com/logging/) (_optional_)
## Requirements
* Python 3.7. Tests also pass on Python 3.8. PyPy support has been removed due to upstream issues with the grpcio module.
* Support for Linux & OS X
## To Use
```sh
(env) $ pip install ulogger
# To use the stackdriver handler, you need to specify an extra dependency:
(env) $ pip install "ulogger[stackdriver]"
```
```python
import logging
from ulogger import setup_logging
# one handler
setup_logging('my_program', 'INFO', ['syslog'])
# multiple handlers
setup_logging('my_program', 'INFO', ['syslog', 'stream'])
# use a different logging facility for syslog (default 16/LOG_LOCAL0)
setup_logging('my_program', 'INFO', ['syslog'], facility=1)
setup_logging('my_program', 'INFO', ['syslog'], facility=logging.handlers.SysLogHandler.LOG_USER)
# then log messages normally
logging.info('ohai')
```
To just setup a specific handler, e.g. Syslog:
```python
import logging
from ulogger import syslog
logger = logging.getLogger('my_logger')
handler = syslog.get_handler('my_program')
logger.addHandler(handler)
```
To setup a Syslog handler with a specific address:
```python
import logging
from ulogger import syslog
logger = logging.getLogger('my_logger')
syslog_addr = ('10.99.0.1', 9514) # (host, port) tuple
# if just a host is given, the default port 514 is used
syslog_addr = ('localhost', None) # (host, port)
# filepath is supported
syslog_addr = '/dev/log'
handler = syslog.get_handler('my_program', address=syslog_addr)
# env vars are also supported, but will be overwritten if `address` is explicitly given
os.environ['SYSLOG_HOST'] = 'localhost'
os.environ['SYSLOG_PORT'] = 325
handler = syslog.get_handler('my_program')
# TCP & UDP are supported
proto = 1 # TCP
proto = socket.SOCK_STREAM # TCP
proto = 2 # UDP - default
proto = socket.SOCK_DGRAM # UDP - default
handler = syslog.get_handler('my_program', address=syslog_addr, proto=proto)
logger.addHandler(handler)
```
### Formatting
#### Default
The default date format for all handlers is the following: `'%Y-%m-%dT%H:%M:%S'` (example `2017-11-02T09:51:33.792`).
The default log format is slightly different depending on the handler you select:
##### Stream Handler Log Format
```python
'%(asctime)s.%(msecs)03dZ <PROGNAME> (%(process)d) %(levelname)s: %(message)s'
```
Example:
```text
2017-11-02T09:51:33.792Z my_awesome_program (63079) INFO: Beginning awesome program v3.
```
##### Syslog Handler Log Format on Linux
```python
'%(asctime)s.%(msecs)03dZ <PROGNAME> (%(process)d): %(message)s'
```
Example:
```text
2017-11-02T09:51:33.792Z my_awesome_program (63079): Beginning awesome program v3.
```
##### Syslog Handler Log Format on OS X
```python
'<PROGNAME> (%(process)d): %(message)s'
```
Example:
```text
Aug 25 13:00:51 my-host.example.net my_awesome_program (63079): Beginning awesome program v3.
```
**NOTE**: Default syslog on OS X appends the date and hostname to the log record.
##### Stackdriver Handler Log Format
```python
'%(asctime)s.%(msecs)03d <HOST> <PROGNAME> (%(process)d): %(message)s'
```
Example:
```text
2017-11-02T19:00:55.850 my-gcp-host my_awesome_program (63079): Beginning awesome program v3"
```
#### Custom
To add your custom log and/or date formatter:
```python
import logging
from ulogger import setup_logging
log_fmt = '%(created)f %(levelno)d %(message)s'
log_date_fmt = '%Y-%m-%dT%H:%M:%S'
setup_logging('my_program', 'INFO', ['syslog'], log_fmt, log_date_fmt)
```
## Development
For development and running tests, your system must have all supported versions of Python installed. We suggest using [pyenv](https://github.com/yyuu/pyenv).
### Setup
```sh
$ git clone git@github.com:spotify/ulogger.git && cd ulogger
# make a virtualenv
(env) $ pip install -r dev-requirements.txt
```
### Running tests
To run the entire test suite:
```sh
# outside of the virtualenv
# if tox is not yet installed
$ pip install tox
$ tox
```
If you want to run the test suite for a specific version of Python:
```sh
# outside of the virtualenv
$ tox -e py37
```
To run an individual test, call `pytest` directly:
```sh
# inside virtualenv
(env) $ pytest tests/test_syslog.py
```
## Code of Conduct
This project adheres to the [Open Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code.
[code-of-conduct]: https://github.com/spotify/code-of-conduct/blob/master/code-of-conduct.md
Raw data
{
"_id": null,
"home_page": "https://github.com/spotify/ulogger",
"name": "ulogger",
"maintainer": "Lynn Root",
"docs_url": null,
"requires_python": "",
"maintainer_email": "lynn@spotify.com",
"keywords": "logging",
"author": "Lynn Root",
"author_email": "lynn@spotify.com",
"download_url": "https://files.pythonhosted.org/packages/c8/14/f680f77d277050bc223d6a46b4f7d6a9d9ae5807f0d03ae8eb112a3df223/ulogger-3.0.0.tar.gz",
"platform": null,
"description": "# ulogger\n\n[](https://github.com/spotify/ulogger/actions/workflows/main.yml) [](https://codecov.io/github/spotify/ulogger)\n\nA micro Python logging library.\n\nSupported handlers:\n\n* stream (stdout)\n* syslog\n* [stackdriver](https://cloud.google.com/logging/) (_optional_)\n\n## Requirements\n\n* Python 3.7. Tests also pass on Python 3.8. PyPy support has been removed due to upstream issues with the grpcio module.\n* Support for Linux & OS X\n\n## To Use\n\n ```sh\n (env) $ pip install ulogger\n # To use the stackdriver handler, you need to specify an extra dependency:\n (env) $ pip install \"ulogger[stackdriver]\"\n ```\n\n ```python\n import logging\n from ulogger import setup_logging\n\n # one handler\n setup_logging('my_program', 'INFO', ['syslog'])\n\n # multiple handlers\n setup_logging('my_program', 'INFO', ['syslog', 'stream'])\n\n # use a different logging facility for syslog (default 16/LOG_LOCAL0)\n setup_logging('my_program', 'INFO', ['syslog'], facility=1)\n setup_logging('my_program', 'INFO', ['syslog'], facility=logging.handlers.SysLogHandler.LOG_USER)\n\n # then log messages normally\n logging.info('ohai')\n ```\n\nTo just setup a specific handler, e.g. Syslog:\n\n ```python\n import logging\n from ulogger import syslog\n\n logger = logging.getLogger('my_logger')\n handler = syslog.get_handler('my_program')\n logger.addHandler(handler)\n ```\n\nTo setup a Syslog handler with a specific address:\n\n ```python\n import logging\n from ulogger import syslog\n\n logger = logging.getLogger('my_logger')\n\n syslog_addr = ('10.99.0.1', 9514) # (host, port) tuple\n # if just a host is given, the default port 514 is used\n syslog_addr = ('localhost', None) # (host, port)\n # filepath is supported\n syslog_addr = '/dev/log'\n\n handler = syslog.get_handler('my_program', address=syslog_addr)\n\n # env vars are also supported, but will be overwritten if `address` is explicitly given\n os.environ['SYSLOG_HOST'] = 'localhost'\n os.environ['SYSLOG_PORT'] = 325\n handler = syslog.get_handler('my_program')\n\n # TCP & UDP are supported\n proto = 1 # TCP\n proto = socket.SOCK_STREAM # TCP\n proto = 2 # UDP - default\n proto = socket.SOCK_DGRAM # UDP - default\n\n handler = syslog.get_handler('my_program', address=syslog_addr, proto=proto)\n logger.addHandler(handler)\n ```\n\n### Formatting\n\n#### Default\n\nThe default date format for all handlers is the following: `'%Y-%m-%dT%H:%M:%S'` (example `2017-11-02T09:51:33.792`).\n\nThe default log format is slightly different depending on the handler you select:\n\n##### Stream Handler Log Format\n\n ```python\n '%(asctime)s.%(msecs)03dZ <PROGNAME> (%(process)d) %(levelname)s: %(message)s'\n ```\n\nExample:\n\n ```text\n 2017-11-02T09:51:33.792Z my_awesome_program (63079) INFO: Beginning awesome program v3.\n ```\n\n##### Syslog Handler Log Format on Linux\n\n ```python\n '%(asctime)s.%(msecs)03dZ <PROGNAME> (%(process)d): %(message)s'\n ```\n\nExample:\n\n ```text\n 2017-11-02T09:51:33.792Z my_awesome_program (63079): Beginning awesome program v3.\n ```\n\n##### Syslog Handler Log Format on OS X\n\n ```python\n '<PROGNAME> (%(process)d): %(message)s'\n ```\n\nExample:\n\n ```text\n Aug 25 13:00:51 my-host.example.net my_awesome_program (63079): Beginning awesome program v3.\n ```\n\n**NOTE**: Default syslog on OS X appends the date and hostname to the log record.\n\n##### Stackdriver Handler Log Format\n\n ```python\n '%(asctime)s.%(msecs)03d <HOST> <PROGNAME> (%(process)d): %(message)s'\n ```\n\nExample:\n\n ```text\n 2017-11-02T19:00:55.850 my-gcp-host my_awesome_program (63079): Beginning awesome program v3\"\n ```\n\n#### Custom\n\nTo add your custom log and/or date formatter:\n\n ```python\n import logging\n from ulogger import setup_logging\n\n log_fmt = '%(created)f %(levelno)d %(message)s'\n log_date_fmt = '%Y-%m-%dT%H:%M:%S'\n\n setup_logging('my_program', 'INFO', ['syslog'], log_fmt, log_date_fmt)\n ```\n\n## Development\n\nFor development and running tests, your system must have all supported versions of Python installed. We suggest using [pyenv](https://github.com/yyuu/pyenv).\n\n### Setup\n\n ```sh\n $ git clone git@github.com:spotify/ulogger.git && cd ulogger\n # make a virtualenv\n (env) $ pip install -r dev-requirements.txt\n ```\n\n### Running tests\n\nTo run the entire test suite:\n\n ```sh\n # outside of the virtualenv\n # if tox is not yet installed\n $ pip install tox\n $ tox\n ```\n\nIf you want to run the test suite for a specific version of Python:\n\n ```sh\n # outside of the virtualenv\n $ tox -e py37\n ```\n\nTo run an individual test, call `pytest` directly:\n\n ```sh\n # inside virtualenv\n (env) $ pytest tests/test_syslog.py\n ```\n\n## Code of Conduct\n\nThis project adheres to the [Open Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code.\n\n[code-of-conduct]: https://github.com/spotify/code-of-conduct/blob/master/code-of-conduct.md\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Micro logging library",
"version": "3.0.0",
"project_urls": {
"Homepage": "https://github.com/spotify/ulogger"
},
"split_keywords": [
"logging"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "27fd22cf870147ac302500880c132633817c405ca05e1a8db2e68b853cf1c343",
"md5": "f79c85755f5fb18cdf383f6d80cd0853",
"sha256": "3cc570e86a19546a01e154c0682bf3a8e38a97e085996acd9c01bf88b17dc442"
},
"downloads": -1,
"filename": "ulogger-3.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "f79c85755f5fb18cdf383f6d80cd0853",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 14967,
"upload_time": "2023-12-01T21:37:08",
"upload_time_iso_8601": "2023-12-01T21:37:08.270079Z",
"url": "https://files.pythonhosted.org/packages/27/fd/22cf870147ac302500880c132633817c405ca05e1a8db2e68b853cf1c343/ulogger-3.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c814f680f77d277050bc223d6a46b4f7d6a9d9ae5807f0d03ae8eb112a3df223",
"md5": "bd9a9804eebe14b901fe85058839f4de",
"sha256": "7ef36641d429efb406afb3bdbfa9f75000d9ae87c2ede044ac6059f99fc512b6"
},
"downloads": -1,
"filename": "ulogger-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "bd9a9804eebe14b901fe85058839f4de",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 17569,
"upload_time": "2023-12-01T21:37:10",
"upload_time_iso_8601": "2023-12-01T21:37:10.002047Z",
"url": "https://files.pythonhosted.org/packages/c8/14/f680f77d277050bc223d6a46b4f7d6a9d9ae5807f0d03ae8eb112a3df223/ulogger-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-01 21:37:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "spotify",
"github_project": "ulogger",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "ulogger"
}
JSON
