https://github.com/szapp/hydra-structlog
An opinionated hydra plugin to configure logging with structlog
https://github.com/szapp/hydra-structlog
hydra hydra-plugin hydra-zen plugin structlog
Last synced: 1 day ago
JSON representation
An opinionated hydra plugin to configure logging with structlog
- Host: GitHub
- URL: https://github.com/szapp/hydra-structlog
- Owner: szapp
- License: mit
- Created: 2026-03-29T20:19:38.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-03-30T09:42:09.000Z (2 months ago)
- Last Synced: 2026-05-07T23:34:41.219Z (22 days ago)
- Topics: hydra, hydra-plugin, hydra-zen, plugin, structlog
- Language: Python
- Homepage: https://pypi.org/project/hydra-structlog/
- Size: 63.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Hydra-Structlog
[](https://github.com/szapp/hydra-structlog/actions/workflows/ci.yml)
[](https://pypi.python.org/pypi/hydra-structlog)
[](https://github.com/szapp/hydra-structlog)
[](https://ko-fi.com/szapp)
An opinionated hydra plugin to configure logging with structlog.
## Usage
Structlog is fully integrated in Hydra through a config group named `structlog` for `hydra.job_logging`.
1. Install the plugin.
```sh
uv add hydra-structlog
```
2. Override the job logging with a default in your config.
```yaml
defaults:
- override hydra/job_logging=structlog
```
3. Hydra will now emit JSON logs (by default to `structured.log`) and print human readably logs to the console.
## Customization
Structlog comes configured with opinionated defaults.
To adjust the processors, use the hydra defaults as outlined above and overwrite individual config entries afterwards.
For example:
```yaml
defaults:
- override hydra/job_logging=structlog
# Change the storage location
hydra:
job_logging:
handlers:
json:
filename: ${hydra.runtime.cwd}/logs/structured.log
```
## Defaults
The configuration runs structlog through the standard library logging.
That has several advantages.
The use of structlog and logging, e.g. by third-party packages, are recorded and both exhibit structlog's bound contextvars.
The processor chain is conveniently exposed in the job_logging configuration and adjustable through hydra's config interface.
Because lists are not easily manipulated in hydra configs, the processor chains are defined as dictionaries.
The name of each processor does not matter as long as its unique in the chain.
The default processor chain can then be extended more comfortably.
To remove a processor set it to `null`. See example below.
Because structlog's ProcessorFormatter does not accept the processors as strings, the logging config contains `_target_` instantiation.
```yaml
defaults:
- override hydra/job_logging=structlog
# Remove a processor from the default chain and add another one
hydra:
job_logging:
formatters:
json:
foreign_pre_chain:
# Remove the add-log-level processor
add_logger_name: null
# Append a new processor
arbitrary_name:
# Follow hydra's instantiate syntax
_target_: structlog.stdlib.add_log_level_number
_partial_: true
```
## Notes
Python 3.14 is currently not supported as `hydra.main` causes a ValueError on argparse-validation, see .
It is recommended to use `hydra-zen` which does not have that problem and works well with Python 3.14.
Tracer injection is not implemented here as data science projects using hydra typically do not implement web apps.
Nevertheless, an appropriate structlog processor can be added to the job_logging config.