https://github.com/reshinto/loggingsfactory
Logging wrapper library that uses different logger types
https://github.com/reshinto/loggingsfactory
Last synced: 2 months ago
JSON representation
Logging wrapper library that uses different logger types
- Host: GitHub
- URL: https://github.com/reshinto/loggingsfactory
- Owner: reshinto
- License: mit
- Created: 2022-04-25T08:46:36.000Z (about 4 years ago)
- Default Branch: master
- Last Pushed: 2025-10-09T17:23:11.000Z (8 months ago)
- Last Synced: 2026-01-14T09:04:56.968Z (5 months ago)
- Language: Python
- Homepage: https://pypi.org/project/loggingsfactory/
- Size: 41 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Loggingsfactory
Loggingsfactory provides a single entry point for writing application logs and issuing queries across Loguru, Elasticsearch, and AsyncElasticsearch. The `Loggers` factory inspects the arguments you provide at construction time and automatically returns the appropriate backend so teams can switch between local debugging and centralized ELK logging without changing call sites. Core behaviours such as log formatting, retry logic, and connection management are implemented once and reused across every logger type to keep logging consistent across services.
## Key features
- **Automatic logger selection** – Instantiating `Loggers` inspects the `debug` and `useasync` flags to decide whether to return the Loguru, synchronous Elasticsearch, or asynchronous Elasticsearch client, keeping your code focused on business logic instead of wiring. [`src/loggingsfactory/logging.py`](src/loggingsfactory/logging.py)
- **Consistent log formatting** – Helper utilities attach metadata such as app name, logger level, function name, version, and timestamp to every message by default. You can also supply custom payloads or override the function name used in the log entry. [`src/loggingsfactory/helpers/formats.py`](src/loggingsfactory/helpers/formats.py)
- **Elasticsearch integrations** – Synchronous and asynchronous wrappers share an interface for indexing logs, issuing search queries with optional custom payloads, and executing SQL queries through the Elasticsearch DB API. Connection helpers handle URL formatting, authentication, retry settings, and SSL verification. [`src/loggingsfactory/loggers/elk.py`](src/loggingsfactory/loggers/elk.py), [`src/loggingsfactory/loggers/asyncelk.py`](src/loggingsfactory/loggers/asyncelk.py), [`src/loggingsfactory/helpers/decorators.py`](src/loggingsfactory/helpers/decorators.py)
- **Loguru enhancements** – When running in debug mode, the Loguru wrapper persists messages to `logs/logfile.log`, enforces supported levels, and keeps a running counter of emitted logs for quick sanity checks. [`src/loggingsfactory/loggers/loguru.py`](src/loggingsfactory/loggers/loguru.py), [`src/loggingsfactory/helpers/singletons.py`](src/loggingsfactory/helpers/singletons.py)
- **Search-friendly defaults** – Built-in query builders provide a sensible default payload that filters by application name and time range while allowing callers to override any portion of the Elasticsearch request. [`src/loggingsfactory/helpers/formats.py`](src/loggingsfactory/helpers/formats.py)
## Repository structure
```
src/
└── loggingsfactory/
├── logging.py # Factory that chooses the correct logger implementation
├── loggers/ # Loguru, Elasticsearch, and AsyncElasticsearch wrappers
├── helpers/ # Formatting utilities, decorators, and singletons
└── constants/ # Shared enums and configuration values
```
Automated tests covering the factory selection logic, required configuration keys, and backend integrations live under `tests/`. [`tests/test_loggingsfactory`](tests/test_loggingsfactory)
## Getting started
1. **Set up Python** – Loggingsfactory targets Python 3.6 or later. [`setup.cfg`](setup.cfg)
2. **Create a virtual environment** (optional but recommended):
```bash
python -m venv .venv
source .venv/bin/activate
```
3. **Install dependencies**:
```bash
pip install -r requirements.txt
```
The package itself can also be installed directly with:
```bash
pip install .
```
## Usage
### Selecting a backend
```python
from loggingsfactory.logging import Loggers
# Loguru for local development (writes to logs/logfile.log)
logger = Loggers(appname="myapp")
# Elasticsearch for production clusters
elk_logger = Loggers(
appname="myapp",
debug=False,
host="https://elasticsearch.example.com:9201",
index="appindex",
username="user1",
pw="password",
)
# AsyncElasticsearch for asyncio applications
async_elk_logger = Loggers(
appname="myapp",
debug=False,
useasync=True,
host="https://elasticsearch.example.com:9201",
index="appindex",
username="user1",
pw="password",
)
```
### Writing logs
```python
# Default structure with inferred function name and ISO timestamp
logger.log("info", "log data")
# Override the function name used in the log entry
logger.log("info", "log data", custom_func_name="worker.process")
# Send a custom payload (will be JSON-encoded for Elasticsearch)
custom_payload = {"custom_log": "this is a custom log"}
logger.log("info", custom_payload, use_custom_logdata=True)
# Provide a specific timestamp
logger.log("info", "log data", date="2022-04-27T00:00:00Z")
```
For asynchronous contexts:
```python
await async_elk_logger.async_log("info", "async log data")
```
### Querying logs
```python
# Default query payload filters by app name and recent timestamps
elk_logger.query(custompayload=None, size=1000, cache=True)
# Custom payload example
payload = {
"query": {
"bool": {
"filter": [
{"match_phrase": {"app_name.keyword": "myapp"}},
{"range": {"timestamp": {"gte": "2021-09-24T02:58:43.647Z"}}},
]
}
}
}
elk_logger.query(custompayload=payload)
# Async search
await async_elk_logger.async_query(custompayload=payload)
# SQL query via Elasticsearch DB API (synchronous only)
rows = elk_logger.sql_query("SELECT * FROM appindex")
```
### Configuration helpers
- Supported log levels are defined in `constants.config.LogLevels` and validated before dispatching. [`src/loggingsfactory/constants/config.py`](src/loggingsfactory/constants/config.py)
- Host, index, username, password, and other keys are enumerated in `constants.keys.LoggerKeys`, making it clear which parameters are required. [`src/loggingsfactory/constants/keys.py`](src/loggingsfactory/constants/keys.py)
- Connection decorators automatically configure retries, SSL settings, and URL formatting when contacting Elasticsearch clusters. [`src/loggingsfactory/helpers/decorators.py`](src/loggingsfactory/helpers/decorators.py)
## Running tests
Run the automated test suite with pytest:
```bash
pytest
```
Tests cover factory selection, validation of required parameters, and logging behaviour for each backend. [`tests/test_loggingsfactory/test_logging.py`](tests/test_loggingsfactory/test_logging.py)
## Support and contributions
Issues and feature requests are tracked on GitHub at [https://github.com/reshinto/loggingsfactory](https://github.com/reshinto/loggingsfactory). Contributions are welcome—feel free to open a pull request after discussing substantial changes.