Metadata-Version: 2.1
Name: redis-logs
Version: 1.1.0
Summary: Python log handler to forward logs to Redis database
Home-page: https://github.com/Iglesys347/redis-log-handler
Author: Iglesys347
Author-email: g.imbert34@gmail.com
License: MIT
Project-URL: Documentation, https://redis-log-handler.readthedocs.io/en/latest
Project-URL: Changes, https://github.com/Iglesys347/redis-log-handler/releases
Project-URL: Code, https://github.com/Iglesys347/redis-log-handler
Project-URL: Issue tracker, https://github.com/Iglesys347/redis-log-handler/issues
Keywords: Redis,logging
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE

# redis-log-handler

Log handler to forward logs to Redis.

| [Installation](#installation) | [Usage](#usage) | [Handler classes](#handlers-classes) | [Documentation](https://redis-log-handler.readthedocs.io/en/stable/) |
| :---------------------------: | :-------------: | :----------------------------------: | :------------------------------------------------------------------: |

## Installation

Installation with `pip`:

```bash
pip install redis-logs
```

## Usage

### Basic example

Setup log forwarding to a redis stream:

```python
from rlh import RedisStreamLogHandler

# define your logger
logger = logging.getLogger('my_app')

# define the Redis log handler
handler = RedisStreamLogHandler()
# add the handler to the logger
logger.addHandler(handler)
```

After that, all the logs emitted with the logger will be forwarded to a [Redis Stream](https://redis.io/docs/data-types/streams/); by default the logs are forwarded to a Redis instance running at `localhost:6379` in a stream named `logs`.

### Use a different stream name

```python
from rlh import RedisStreamLogHandler

# define your logger
logger = logging.getLogger('my_app')

# define the Redis log handler
handler = RedisStreamLogHandler(stream_name="custom_stream_name")
# add the handler to the logger
logger.addHandler(handler)
```

### Specify a custom Redis client

To use a custom Redis client, you can either define your own client with `redis.Redis` and then pass it to the handler:

```python
from redis import Redis
from rlh import RedisStreamLogHandler

# define a custom Redis client
client = Redis(host="redis", port=6380, db=1)

# define your logger
logger = logging.getLogger('my_app')

# define the Redis log handler with custom Redis client
handler = RedisStreamLogHandler(redis_client=client)
# add the handler to the logger
logger.addHandler(handler)
```

Or dirrectly call the handler constructor with your custom Redis settings:

```python
from rlh import RedisStreamLogHandler

# define your logger
logger = logging.getLogger('my_app')

# define the Redis log handler with custom Redis client
handler = RedisStreamLogHandler(host="redis", port=6380, db=1)
# add the handler to the logger
logger.addHandler(handler)
```

### Specify custom log fields to save

By default the handler only saves the logs fieds `msg`, `levelname` and `created`. You can however change this default behaviour by setting your own desired fields (see the full list of fields in [logging documentation](https://docs.python.org/3/library/logging.html#logrecord-attributes)):

```python
from rlh import RedisStreamLogHandler

# define your logger
logger = logging.getLogger('my_app')

# define the Redis log handler with custom fields
handler = RedisStreamLogHandler(fields=["msg", "name", "module", "levelno"])
# add the handler to the logger
logger.addHandler(handler)
```

### Save `LogRecord` as pickle format

Logs can also be saved in DB as [pickle format](https://docs.python.org/3/library/pickle.html):

```python
from rlh import RedisStreamLogHandler

# define your logger
logger = logging.getLogger('my_app')

# define the Redis log handler with custom fields
handler = RedisStreamLogHandler(as_pkl=True)
# add the handler to the logger
logger.addHandler(handler)
```

This can be useful if you need to re-use the logs with another python program.

## Handlers classes

Currently `rlh` implements two classes of handlers:

- [`RedisStreamLogHandler`](#redisstreamloghandler)
- [`RedisPubSubLogHandler`](#redispubsubloghandler)

### `RedisStreamLogHandler`

Handler used to forward logs to a [Redis stream](https://redis.io/docs/data-types/streams/).

### `RedisPubSubLogHandler`

Handler used to publish logs to a [Redis pub/sub](https://redis.io/docs/manual/pubsub/) channel.

> :warning: Before using `RedisPubSubLogHandler`, make sure to define at least one listener to the channel, otherwise the logs emitted will be lost

