# python-logging-rabbitmq
[](https://travis-ci.org/albertomr86/python-logging-rabbitmq)
Logging handler to ships logs to RabbitMQ. Compatible with Django.
## Installation
Install using pip.
```sh
pip install python_logging_rabbitmq
```
### Versions
| Version | Dependency |
|--------------|-----------------|
| >= 2.x | Pika == 0.13 |
| <= 1.1.1 | Pika <= 0.10 |
## Handlers
This package has two built-in handlers that you can import as follows:
```python
from python_logging_rabbitmq import RabbitMQHandler
```
or (thanks to [@wallezhang](https://github.com/wallezhang))
```python
from python_logging_rabbitmq import RabbitMQHandlerOneWay
```
| Handler | Description |
|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| RabbitMQHandler | Basic handler for sending logs to RabbitMQ. Every record will be delivered directly to RabbitMQ using the exchange configured. |
| RabbitMQHandlerOneWay | High throughput handler. Initializes an internal queue where logs are stored temporarily. A thread is used to deliver the logs to RabbitMQ using the exchange configured. Your app doesn't need to wait until the log is delivered. Notice that if the main thread dies you might lose logs. |
## Standalone python
To use with python first create a logger for your app, then create an instance of the handler and add it to the logger created.
```python
import logging
from python_logging_rabbitmq import RabbitMQHandler
logger = logging.getLogger('myapp')
logger.setLevel(logging.DEBUG)
rabbit = RabbitMQHandler(host='localhost', port=5672)
logger.addHandler(rabbit)
logger.debug('test debug')
```
As result, a similar message as follows will be sent to RabbitMQ:
```json
{
"relativeCreated":280.61580657958984,
"process":13105,
"args":[],
"module":"test",
"funcName":"<module>",
"host":"albertomr86-laptop",
"exc_text":null,
"name":"myapp",
"thread":140032818181888,
"created":1482290387.454017,
"threadName":"MainThread",
"msecs":454.01692390441895,
"filename":"test.py",
"levelno":10,
"processName":"MainProcess",
"pathname":"test.py",
"lineno":11,
"msg":"test debug",
"exc_info":null,
"levelname":"DEBUG"
}
```
## Sending logs
By default, logs will be sent to RabbitMQ using the exchange **'log'**, this should be of **type topic**. The **routing key** used is formed by concatenating the *logger name* and the *log level*. For example:
```python
import logging
from python_logging_rabbitmq import RabbitMQHandler
logger = logging.getLogger('myapp')
logger.setLevel(logging.DEBUG)
logger.addHandler(RabbitMQHandler(host='localhost', port=5672))
logger.info('test info')
logger.debug('test debug')
logger.warning('test warning')
```
The messages will be sent using the following routing keys:
- myapp.INFO
- myapp.DEBUG
- myapp.WARNING
For an explanation about topics and routing keys go to https://www.rabbitmq.com/tutorials/tutorial-five-python.html
When create the handler, you're able to specify different parameters in order to connect to RabbitMQ or configure the handler behavior.
## Overriding routing-key creation
If you wish to override routing-key format entirely, you can pass
`routing_key_formatter` function which takes `LogRecord` objects and returns
routing-key. For example:
```python
RabbitMQHandler(
host='localhost',
port=5672,
routing_key_formatter=lambda r: (
'some_exchange_prefix.{}'.format(r.levelname.lower())
)
)
```
## Configuration
These are the configuration allowed:
| Parameter | Description | Default |
|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------|
| host | RabbitMQ Server hostname or ip address. | localhost |
| port | RabbitMQ Server port. | 5672 |
| username | Username for authentication. | None |
| password | Provide a password for the username. | None |
| exchange | Name of the exchange to publish the logs. This exchange is considered of type topic. | log |
| declare_exchange | Whether or not to declare the exchange. | False |
| remove_request | If True (default), remove request & exc info. | True |
| routing_key_format | Customize how messages are routed to the queues. | {name}.{level} |
| routing_key_formatter | Customize how routing-key is constructed. | None |
| connection_params | Allow extra params to connect with RabbitMQ. | None |
| formatter | Use custom formatter for the logs. | python_logging_rabbitmq.JSONFormatter |
| close_after_emit | Close the active connection after send a log. A new connection is open for the next log. | False |
| fields | Dict to add as a field in each logs send to RabbitMQ. This is useful when you want fields in each log but without pass them every time. | None |
| fields_under_root | When is True, each key in parameter 'fields' will be added as an entry in the log, otherwise they will be logged under the key 'fields'. | True |
| message_headers | A dictionary of headers to be published with the message. | None |
| record_fields | A set of attributes that should be preserved from the record object. | None |
| exclude_record_fields | A set of attributes that should be ignored from the record object. | None |
| heartbeat | Lower bound for heartbeat timeout. | 60 |
| content_type | The format of the message sent to the queue. | text/plain |
### Examples
#### RabbitMQ Connection
```python
rabbit = RabbitMQHandler(
host='localhost',
port=5672,
username='guest',
password='guest',
connection_params={
'virtual_host': '/',
'connection_attempts': 3,
'socket_timeout': 5000
}
)
```
#### Custom fields
```python
rabbit = RabbitMQHandler(
host='localhost',
port=5672,
fields={
'source': 'MyApp',
'env': 'production'
},
fields_under_root=True
)
```
#### Custom formatter
By default, python_logging_rabbitmq implements a custom JSONFormatter; but if you prefer to format your own message you could do it as follow:
```python
import logging
from python_logging_rabbitmq import RabbitMQHandler
FORMAT = '%(asctime)-15s %(message)s'
formatter = logging.Formatter(fmt=FORMAT)
rabbit = RabbitMQHandler(formatter=formatter)
```
For a custom JSON Formatter take a look at https://github.com/madzak/python-json-logger
## Django
To use with Django add the handler in the [logging config](https://docs.djangoproject.com/en/1.9/topics/logging/#configuring-logging).
```python
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'handlers': {
'rabbit': {
'level': 'DEBUG',
'class': 'python_logging_rabbitmq.RabbitMQHandler',
'host': 'localhost'
}
},
'loggers': {
'myapp': {
'handlers': ['rabbit'],
'level': 'DEBUG',
'propagate': False
}
}
}
```
## Configuration
Same as when use it with standalone python, you could configure the handle directly when declaring it in the config:
```python
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'handlers': {
'rabbit': {
'level': 'DEBUG',
'class': 'python_logging_rabbitmq.RabbitMQHandler',
'host': 'localhost',
'port': 5672,
'username': 'guest',
'password': 'guest',
'exchange': 'log',
'declare_exchange': False,
'connection_params': {
'virtual_host': '/',
'connection_attempts': 3,
'socket_timeout': 5000
},
'fields': {
'source': 'MainAPI',
'env': 'production'
},
'fields_under_root': True
}
},
'loggers': {
'myapp': {
'handlers': ['rabbit'],
'level': 'DEBUG',
'propagate': False
}
}
}
```
#### Custom formatter
```python
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'formatters': {
'standard': {
'format': '%(levelname)-8s [%(asctime)s]: %(message)s'
}
},
'handlers': {
'rabbit': {
'level': 'DEBUG',
'class': 'python_logging_rabbitmq.RabbitMQHandler',
'host': 'localhost',
'formatter': 'standard'
}
},
'loggers': {
'myapp': {
'handlers': ['rabbit'],
'level': 'DEBUG',
'propagate': False
}
}
}
```
#### JSON formatter
```sh
pip install python-json-logger
```
```python
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'formatters': {
'json': {
'()': 'pythonjsonlogger.jsonlogger.JsonFormatter',
'fmt': '%(name)s %(levelname) %(asctime)s %(message)s'
}
},
'handlers': {
'rabbit': {
'level': 'DEBUG',
'class': 'python_logging_rabbitmq.RabbitMQHandler',
'host': 'localhost',
'formatter': 'json'
}
},
'loggers': {
'myapp': {
'handlers': ['rabbit'],
'level': 'DEBUG',
'propagate': False
}
}
}
```
## Releases
[CHANGELOG](./CHANGELOG.md)
## Similar efforts
- MQHandler (https://github.com/ziXiong/MQHandler)
- http://stackoverflow.com/a/25479008/2716524
- LogBook (http://pydoc.net/Python/Logbook/0.12.5/logbook.queues/)
- https://pypi.python.org/pypi/py-amqp-logging/0.1
Raw data
{
"_id": null,
"home_page": "https://github.com/albertomr86/python-logging-rabbitmq",
"name": "python-logging-rabbitmq",
"maintainer": "",
"docs_url": "https://pythonhosted.org/python-logging-rabbitmq/",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*",
"maintainer_email": "",
"keywords": "logging rabbitmq logs",
"author": "Alberto Menendez Romero",
"author_email": "albertomr86@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5e/ce/c1d2415a6508f778d933ede9d8e9245d02748d6d623a3ae13147aa4ab71b/python-logging-rabbitmq-2.3.0.tar.gz",
"platform": null,
"description": "# python-logging-rabbitmq\n\n[](https://travis-ci.org/albertomr86/python-logging-rabbitmq)\n\nLogging handler to ships logs to RabbitMQ. Compatible with Django.\n\n## Installation\nInstall using pip.\n\n```sh\npip install python_logging_rabbitmq\n```\n\n### Versions\n\n| Version | Dependency |\n|--------------|-----------------|\n| >= 2.x | Pika == 0.13 |\n| <= 1.1.1 | Pika <= 0.10 |\n\n\n## Handlers\nThis package has two built-in handlers that you can import as follows:\n\n```python\nfrom python_logging_rabbitmq import RabbitMQHandler\n```\n\nor (thanks to [@wallezhang](https://github.com/wallezhang))\n\n```python\nfrom python_logging_rabbitmq import RabbitMQHandlerOneWay\n```\n\n| Handler | Description |\n|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| RabbitMQHandler | Basic handler for sending logs to RabbitMQ. Every record will be delivered directly to RabbitMQ using the exchange configured. |\n| RabbitMQHandlerOneWay | High throughput handler. Initializes an internal queue where logs are stored temporarily. A thread is used to deliver the logs to RabbitMQ using the exchange configured. Your app doesn't need to wait until the log is delivered. Notice that if the main thread dies you might lose logs. |\n\n## Standalone python\nTo use with python first create a logger for your app, then create an instance of the handler and add it to the logger created.\n\n```python\nimport logging\nfrom python_logging_rabbitmq import RabbitMQHandler\n\nlogger = logging.getLogger('myapp')\nlogger.setLevel(logging.DEBUG)\n\nrabbit = RabbitMQHandler(host='localhost', port=5672)\nlogger.addHandler(rabbit)\n\nlogger.debug('test debug')\n```\n\nAs result, a similar message as follows will be sent to RabbitMQ:\n\n```json\n{\n\t\"relativeCreated\":280.61580657958984,\n\t\"process\":13105,\n\t\"args\":[],\n\t\"module\":\"test\",\n\t\"funcName\":\"<module>\",\n\t\"host\":\"albertomr86-laptop\",\n\t\"exc_text\":null,\n\t\"name\":\"myapp\",\n\t\"thread\":140032818181888,\n\t\"created\":1482290387.454017,\n\t\"threadName\":\"MainThread\",\n\t\"msecs\":454.01692390441895,\n\t\"filename\":\"test.py\",\n\t\"levelno\":10,\n\t\"processName\":\"MainProcess\",\n\t\"pathname\":\"test.py\",\n\t\"lineno\":11,\n\t\"msg\":\"test debug\",\n\t\"exc_info\":null,\n\t\"levelname\":\"DEBUG\"\n}\n```\n\n## Sending logs\nBy default, logs will be sent to RabbitMQ using the exchange **'log'**, this should be of **type topic**. The **routing key** used is formed by concatenating the *logger name* and the *log level*. For example:\n\n```python\nimport logging\nfrom python_logging_rabbitmq import RabbitMQHandler\n\nlogger = logging.getLogger('myapp')\nlogger.setLevel(logging.DEBUG)\nlogger.addHandler(RabbitMQHandler(host='localhost', port=5672))\n\nlogger.info('test info')\nlogger.debug('test debug')\nlogger.warning('test warning')\n```\n\nThe messages will be sent using the following routing keys:\n- myapp.INFO\n- myapp.DEBUG\n- myapp.WARNING\n\nFor an explanation about topics and routing keys go to https://www.rabbitmq.com/tutorials/tutorial-five-python.html\n\nWhen create the handler, you're able to specify different parameters in order to connect to RabbitMQ or configure the handler behavior.\n\n## Overriding routing-key creation\n\nIf you wish to override routing-key format entirely, you can pass\n`routing_key_formatter` function which takes `LogRecord` objects and returns\nrouting-key. For example:\n\n```python\nRabbitMQHandler(\n\thost='localhost',\n\tport=5672,\n\trouting_key_formatter=lambda r: (\n\t\t'some_exchange_prefix.{}'.format(r.levelname.lower())\n\t)\n)\n```\n\n## Configuration\nThese are the configuration allowed:\n\n| Parameter | Description | Default |\n|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------|\n| host | RabbitMQ Server hostname or ip address. | localhost |\n| port | RabbitMQ Server port. | 5672 |\n| username | Username for authentication. | None |\n| password | Provide a password for the username. | None |\n| exchange | Name of the exchange to publish the logs. This exchange is considered of type topic. | log |\n| declare_exchange | Whether or not to declare the exchange. | False |\n| remove_request | If True (default), remove request & exc info. | True |\n| routing_key_format | Customize how messages are routed to the queues. | {name}.{level} |\n| routing_key_formatter | Customize how routing-key is constructed. | None |\n| connection_params | Allow extra params to connect with RabbitMQ. | None |\n| formatter | Use custom formatter for the logs. | python_logging_rabbitmq.JSONFormatter |\n| close_after_emit | Close the active connection after send a log. A new connection is open for the next log. | False |\n| fields | Dict to add as a field in each logs send to RabbitMQ. This is useful when you want fields in each log but without pass them every time. | None |\n| fields_under_root | When is True, each key in parameter 'fields' will be added as an entry in the log, otherwise they will be logged under the key 'fields'. | True |\n| message_headers | A dictionary of headers to be published with the message. | None |\n| record_fields | A set of attributes that should be preserved from the record object. | None |\n| exclude_record_fields | A set of attributes that should be ignored from the record object. | None |\n| heartbeat | Lower bound for heartbeat timeout. | 60 |\n| content_type | The format of the message sent to the queue. | text/plain |\n\n\n### Examples\n#### RabbitMQ Connection\n\n```python\nrabbit = RabbitMQHandler(\n\thost='localhost',\n\tport=5672,\n\tusername='guest',\n\tpassword='guest',\n\tconnection_params={\n\t\t'virtual_host': '/',\n\t\t'connection_attempts': 3,\n\t\t'socket_timeout': 5000\n\t}\n)\n```\n\n#### Custom fields\n\n```python\nrabbit = RabbitMQHandler(\n\thost='localhost',\n\tport=5672,\n\tfields={\n\t\t'source': 'MyApp',\n\t\t'env': 'production'\n\t},\n\tfields_under_root=True\n)\n```\n\n#### Custom formatter\nBy default, python_logging_rabbitmq implements a custom JSONFormatter; but if you prefer to format your own message you could do it as follow:\n\n```python\nimport logging\nfrom python_logging_rabbitmq import RabbitMQHandler\n\nFORMAT = '%(asctime)-15s %(message)s'\nformatter = logging.Formatter(fmt=FORMAT)\nrabbit = RabbitMQHandler(formatter=formatter)\n```\n\nFor a custom JSON Formatter take a look at https://github.com/madzak/python-json-logger\n\n## Django\nTo use with Django add the handler in the [logging config](https://docs.djangoproject.com/en/1.9/topics/logging/#configuring-logging).\n\n```python\nLOGGING = {\n\t'version': 1,\n\t'disable_existing_loggers': False,\n\t'handlers': {\n\t\t'rabbit': {\n\t\t\t'level': 'DEBUG',\n\t\t\t'class': 'python_logging_rabbitmq.RabbitMQHandler',\n\t\t\t'host': 'localhost'\n\t\t}\n\t},\n\t'loggers': {\n\t\t'myapp': {\n\t\t\t'handlers': ['rabbit'],\n\t\t\t'level': 'DEBUG',\n\t\t\t'propagate': False\n\t\t}\n\t}\n}\n```\n\n## Configuration\nSame as when use it with standalone python, you could configure the handle directly when declaring it in the config:\n\n```python\nLOGGING = {\n\t'version': 1,\n\t'disable_existing_loggers': False,\n\t'handlers': {\n\t\t'rabbit': {\n\t\t\t'level': 'DEBUG',\n\t\t\t'class': 'python_logging_rabbitmq.RabbitMQHandler',\n\t\t\t'host': 'localhost',\n\t\t\t'port': 5672,\n\t\t\t'username': 'guest',\n\t\t\t'password': 'guest',\n\t\t\t'exchange': 'log',\n\t\t\t'declare_exchange': False,\n\t\t\t'connection_params': {\n\t\t\t\t'virtual_host': '/',\n\t\t\t\t'connection_attempts': 3,\n\t\t\t\t'socket_timeout': 5000\n\t\t\t},\n\t\t\t'fields': {\n\t\t\t\t'source': 'MainAPI',\n\t\t\t\t'env': 'production'\n\t\t\t},\n\t\t\t'fields_under_root': True\n\t\t}\n\t},\n\t'loggers': {\n\t\t'myapp': {\n\t\t\t'handlers': ['rabbit'],\n\t\t\t'level': 'DEBUG',\n\t\t\t'propagate': False\n\t\t}\n\t}\n}\n```\n\n#### Custom formatter\n\n```python\nLOGGING = {\n\t'version': 1,\n\t'disable_existing_loggers': False,\n\t'formatters': {\n\t\t'standard': {\n\t\t\t'format': '%(levelname)-8s [%(asctime)s]: %(message)s'\n\t\t}\n\t},\n\t'handlers': {\n\t\t'rabbit': {\n\t\t\t'level': 'DEBUG',\n\t\t\t'class': 'python_logging_rabbitmq.RabbitMQHandler',\n\t\t\t'host': 'localhost',\n\t\t\t'formatter': 'standard'\n\t\t}\n\t},\n\t'loggers': {\n\t\t'myapp': {\n\t\t\t'handlers': ['rabbit'],\n\t\t\t'level': 'DEBUG',\n\t\t\t'propagate': False\n\t\t}\n\t}\n}\n```\n\n#### JSON formatter\n\n```sh\npip install python-json-logger\n```\n\n```python\nLOGGING = {\n\t'version': 1,\n\t'disable_existing_loggers': False,\n\t'formatters': {\n\t\t'json': {\n\t\t\t'()': 'pythonjsonlogger.jsonlogger.JsonFormatter',\n\t\t\t'fmt': '%(name)s %(levelname) %(asctime)s %(message)s'\n\t\t}\n\t},\n\t'handlers': {\n\t\t'rabbit': {\n\t\t\t'level': 'DEBUG',\n\t\t\t'class': 'python_logging_rabbitmq.RabbitMQHandler',\n\t\t\t'host': 'localhost',\n\t\t\t'formatter': 'json'\n\t\t}\n\t},\n\t'loggers': {\n\t\t'myapp': {\n\t\t\t'handlers': ['rabbit'],\n\t\t\t'level': 'DEBUG',\n\t\t\t'propagate': False\n\t\t}\n\t}\n}\n```\n\n## Releases\n\n[CHANGELOG](./CHANGELOG.md)\n\n## Similar efforts\n- MQHandler (https://github.com/ziXiong/MQHandler)\n- http://stackoverflow.com/a/25479008/2716524\n- LogBook (http://pydoc.net/Python/Logbook/0.12.5/logbook.queues/)\n- https://pypi.python.org/pypi/py-amqp-logging/0.1\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Send logs to RabbitMQ from Python/Django",
"version": "2.3.0",
"project_urls": {
"Homepage": "https://github.com/albertomr86/python-logging-rabbitmq"
},
"split_keywords": [
"logging",
"rabbitmq",
"logs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "08700e36bb8a726c4e26b5ef9207c77672f13f6f24603e87591c3b8db5c63348",
"md5": "601cc668c2bb390c11ed6286d8c5ec9a",
"sha256": "0f4d4a1884cff18fcf63952fa13fd8398d83b387b985c0ab9b971d017b389130"
},
"downloads": -1,
"filename": "python_logging_rabbitmq-2.3.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "601cc668c2bb390c11ed6286d8c5ec9a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*",
"size": 12825,
"upload_time": "2023-09-28T04:07:49",
"upload_time_iso_8601": "2023-09-28T04:07:49.911791Z",
"url": "https://files.pythonhosted.org/packages/08/70/0e36bb8a726c4e26b5ef9207c77672f13f6f24603e87591c3b8db5c63348/python_logging_rabbitmq-2.3.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5ecec1d2415a6508f778d933ede9d8e9245d02748d6d623a3ae13147aa4ab71b",
"md5": "a1107b9ab4bb6fc0381afb491fe1634e",
"sha256": "f55029170084dd9c007ae911069e2dff27169614176e5207b186a841450f5363"
},
"downloads": -1,
"filename": "python-logging-rabbitmq-2.3.0.tar.gz",
"has_sig": false,
"md5_digest": "a1107b9ab4bb6fc0381afb491fe1634e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*",
"size": 14026,
"upload_time": "2023-09-28T04:07:51",
"upload_time_iso_8601": "2023-09-28T04:07:51.390187Z",
"url": "https://files.pythonhosted.org/packages/5e/ce/c1d2415a6508f778d933ede9d8e9245d02748d6d623a3ae13147aa4ab71b/python-logging-rabbitmq-2.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-28 04:07:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "albertomr86",
"github_project": "python-logging-rabbitmq",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "python-logging-rabbitmq"
}
JSON
