Metadata-Version: 2.3
Name: hestia-logger
Version: 1.2.3
Summary: HESTIA is a high-performance, structured logging system for Python applications. Supports async logging, Elastic Stack integration, structured JSON logs, and colorized console output.
License: Apache-2.0
Keywords: logging,async,fastapi,elasticsearch,microservices
Author: FOX Techniques
Author-email: ali.nabbi@fox-techniques.com
Requires-Python: >=3.10
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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: Topic :: System :: Logging
Requires-Dist: aiofiles (>=24.1.0,<25.0.0)
Requires-Dist: coloredlogs (>=15.0.1,<16.0.0)
Requires-Dist: colorlog (>=6.9.0,<7.0.0)
Requires-Dist: elasticsearch (>=8.17.2,<9.0.0)
Requires-Dist: fastapi (>=0.115.11,<0.116.0)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
Requires-Dist: python-json-logger (>=3.2.1,<4.0.0)
Requires-Dist: requests (>=2.32.3,<3.0.0)
Requires-Dist: sqlalchemy (>=2.0.41,<3.0.0)
Requires-Dist: structlog (>=25.1.0,<26.0.0)
Project-URL: Documentation, https://fox-techniques.github.io/hestia-logger
Project-URL: Homepage, https://github.com/fox-techniques/hestia-logger
Project-URL: Repository, https://github.com/fox-techniques/hestia-logger
Description-Content-Type: text/markdown

# HESTIA Logger 

[![Python](https://img.shields.io/badge/Python-3.10%2B-darkcyan)](https://pypi.org/project/hestia-logger/)
[![PyPI - Version](https://img.shields.io/pypi/v/hestia-logger?label=PyPI%20Version&color=green)](https://pypi.org/project/hestia-logger/)
[![PyPI Downloads](https://static.pepy.tech/badge/hestia-logger)](https://pepy.tech/projects/hestia-logger)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache2.0-orange.svg)](https://github.com/fox-techniques/hestia-logger/blob/main/LICENSE)
[![GitHub](https://img.shields.io/badge/GitHub-hestia--logger-181717?logo=github)](https://github.com/fox-techniques/hestia-logger)


**A high-performance, structured logging system for Python applications.**  
Supports **async logging, Elastic Stack integration, structured JSON logs, and colorized console output.**

## Key Features

- **Structured JSON & Human-Readable Logs** (Optimized for Elastic Stack)  
- **Dynamic Metadata Support** (`user_id`, `request_id`, etc.)  
- **Application-Aware Logging** (`get_logger("my_app")`)  
- **Multi-Thread & Multi-Process Friendly** (`thread_id`, `process_id`)  
- **Colored Console Output** (`INFO` in green, `ERROR` in red, etc.)  
- **Internal Logger for Debugging the Logging System**  
- **Supports File Rotation & Future Cloud Integration**  

---

## Documentation

The full documentation is available on [GitHub Pages](https://fox-techniques.github.io/hestia-logger/).

---

##  Installation

```bash
pip install hestia-logger
```

##  Usage

**1. Basic Setup**

```python
from hestia_logger import get_logger

# Get a logger instance
logger = get_logger("development")

# Log messages with different levels
logger.debug("This is a DEBUG log")
logger.info("Application started successfully")
logger.warning("Low disk space warning")
logger.error("Failed to connect to database")
logger.critical("System is down!")
```

**2. Decorator Example**

```python 
from hestia_logger import get_logger
from hestia_logger.decorators import log_execution

# Initialize the logger
logger = get_logger("decorator")

@log_execution
def add_numbers(a, b):
     """Adds two numbers and returns the result."""
     return a + b

@log_execution
def simulate_task():
     """Simulates a task that takes time."""
     import time
     time.sleep(2)
     return "Task completed!"

# Call the functions
if __name__ == "__main__":
     result = add_numbers(5, 10)
     logger.info(f"Result: {result}")

     task_status = simulate_task()
     logger.info(f"Task Status: {task_status}")

```


**3. Adding Custom Metadata**

```python
from hestia_logger import get_logger

logger = get_logger("my_application", metadata={"user_id": "12345", 
                                                "request_id": "abcd-xyz"})

logger.info("User login successful")
```

## Log File Structure

HESTIA Logger creates two main log files:


|File|	Format|	Purpose|
|---|---|---|
|**app.log**	|JSON	|Machine-readable (Elastic Stack)|
|**all.log**	|Text	|Human-readable debug logs|

## Log Colors (Console Output)

|Log Level|	Color|
|---|---|
|DEBUG|	🔵 Blue|
|INFO|	⚫ Black|
|WARNING|	🟡 Yellow|
|ERROR|	🔴 Red|
|CRITICAL|	🔥 Bold Red|

## Configuration

HESTIA Logger supports environment-based configuration via .env or export:

```bash
# Environment Variables
ENVIRONMENT=local
LOG_LEVEL=INFO
```

## Example Log Output

### Console (Colorized) +  all.log (Text Format)

```yaml
2025-03-06 20:40:23 - my_application - INFO - Application started!
```

### app.log (JSON Format - Elastic Stack Ready)

```json
{
    "timestamp": "2025-03-06T20:40:23.286Z",
    "level": "INFO",
    "hostname": "server-1",
    "container_id": "N/A",
    "application": "my_application",
    "event": "Application started successfully!",
    "thread": 12345,
    "process": 56789,
    "uuid": "d3f5b2c1-4f27-46a8-b3d2-f4a7a5c3ef29",
    "metadata": {
        "user_id": "12345",
        "request_id": "abcd-xyz"
    }
}
```

## License

This project is licensed under the Apache 2.0 License - see the [LICENSE](https://github.com/fox-techniques/hestia-logger/blob/main/LICENSE) file for details.
