Metadata-Version: 2.4
Name: structlog-throttling
Version: 1.2.2
Summary: Log throttling utilities for structlog.
Keywords: structlog,throttling,throttle
License-Expression: MIT OR Apache-2.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: Apache Software License
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Logging
Classifier: Typing :: Typed
Requires-Dist: structlog>=25.5.0
Requires-Python: >=3.9
Project-URL: Codeberg, https://codeberg.org/tomasfarias/structlog-throttling
Description-Content-Type: text/markdown

# *structlog-throttling*: Throttling for *[structlog](https://www.structlog.org/)* loggers

<a href="https://pypi.org/project/structlog-throttling/"><img src="https://img.shields.io/pypi/pyversions/structlog-throttling.svg" alt="Supported Python versions from PyPI." /></a>

Logging offers a trade-off between visibility and performance. A particularly high performance cost can be incurred when logging in each iteration of a loop, common [hot spots](https://en.wikipedia.org/wiki/Hot_spot_%28computer_programming%29) in most programs. A solution to this problem is to space out the log calls such that they only happen every some time instead of on every iteration of the loop. By tweaking the time in between log calls we can move within the visibility-performance trade-off.

*structlog-throttling* brings this solution to *[structlog](https://www.structlog.org/)* in the form of processors to throttle log calls based on time, or call count.

## Getting started

### Installation

Install *structlog-throttling* from PyPI:

```sh
pip install structlog-throttling
```

### Configure

When configuring *structlog*, use one of the processors offered by *structlog-throttling*. I recommend putting the processor close to the beginning of your processor chain, to avoid processing logs that will ultimately be dropped:

```python
import structlog
from structlog_throttling.processors import LogTimeThrottler


structlog.configure(
    processors=[
        # Logs with the same 'event' will only be allowed through every 5 seconds.
        LogTimeThrottler("event", every_seconds=5),
        ...
    ]
)
```

## Examples

Configure *structlog* to throttle logs based on log level every 5 seconds:

```python
import structlog
from structlog_throttling.processors import LogTimeThrottler


structlog.configure(
    processors=[
        structlog.processors.add_log_level,
        LogTimeThrottler("level", every_seconds=5),
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.dev.ConsoleRenderer(),
    ],
)
```

![GIF of logs throttled every 5 seconds based on log level](examples/log_time_example.gif)

See [full code](examples/log_time_example.py).

Configure *structlog* to log only every other loop iteration:

```python
import structlog

from structlog_throttling.processors import LogCountThrottler

structlog.stdlib.recreate_defaults()

structlog.configure(
    processors=[
        LogCountThrottler("event", every=2),
        structlog.processors.add_log_level,
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.dev.ConsoleRenderer(),
    ],
)
```

![GIF of logs throttled every other loop iteration](examples/log_count_example.gif)

See [full code](examples/log_count_example.py).
