Metadata-Version: 2.4
Name: logforge-py
Version: 0.2.0
Summary: Official Python SDK for LogForge — self-hosted log management and monitoring
Author-email: LogForge <contact@logforge.dev>
License: MIT
Project-URL: Homepage, https://github.com/loickadjiwanou/logforge-py-sdk
Project-URL: Repository, https://github.com/loickadjiwanou/logforge-py-sdk
Project-URL: Issues, https://github.com/loickadjiwanou/logforge-py-sdk/issues
Keywords: logging,log,monitoring,logforge,observability,error-tracking
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENCE
Provides-Extra: requests
Requires-Dist: requests>=2.28; extra == "requests"
Provides-Extra: httpx
Requires-Dist: httpx>=0.24; extra == "httpx"
Provides-Extra: all
Requires-Dist: requests>=2.28; extra == "all"
Requires-Dist: httpx>=0.24; extra == "all"
Dynamic: license-file

# logforge-py

Official Python SDK for LogForge, self-hosted log management and monitoring.

Compatible with **Python 3.8+**. Logs are batched and sent in a background thread.

## Installation

```bash
# With requests (recommended)
pip install logforge-py[requests]

# With httpx
pip install logforge-py[httpx]

# With both
pip install logforge-py[all]
```

## Quick Start

```python
from logforge import LogForge

logger = LogForge(
    api_key="YOUR_API_KEY",           # from LogForge dashboard → Project Settings
    endpoint="https://logs.myapp.com", # your LogForge backend URL
    environment="production",
    channel="default",
)

logger.info("App started")
logger.warning("Cache miss rate high", metadata={"rate": 0.42})
logger.error("DB write failed", metadata={"table": "orders"}, tags=["database"])

# Capture exceptions with full traceback
try:
    1 / 0
except ZeroDivisionError as e:
    logger.capture_exception(e, channel="math")

# Flush remaining logs and stop the background thread before exit
logger.shutdown()
```

### Auto-register shutdown

```python
import atexit
atexit.register(logger.shutdown)
```

## Constructor Options

| Option | Type | Default | Description |
|---|---|---|---|
| `api_key` | `str` | **required** | Project API key |
| `endpoint` | `str` | **required** | LogForge backend base URL |
| `environment` | `str` | `'production'` | Environment tag |
| `channel` | `str` | `'default'` | Default log channel |
| `batch_size` | `int` | `10` | Max logs per flush batch |
| `flush_interval` | `float` | `5.0` | Seconds between auto-flushes |
| `retry_attempts` | `int` | `3` | Retry attempts on failure |
| `timeout` | `float` | `10.0` | HTTP request timeout (seconds) |
| `debug` | `bool` | `False` | Log SDK errors via Python `logging` |

## API

### Logging

```python
logger.info(message, **options)
logger.warning(message, **options)   # alias: warn()
logger.error(message, **options)
logger.debug(message, **options)
logger.critical(message, **options)
logger.capture_exception(exc, **options)
```

Every method accepts keyword options:

```python
logger.error(
    "Payment failed",
    channel="payments",
    environment="staging",
    metadata={"order_id": "ORD-456"},
    tags=["payments", "critical-path"],
)
```

### User Context

```python
logger.set_user("user_123", "john@example.com", name="John Doe")
logger.clear_user()
```

### Channel / Environment

```python
logger.set_channel("auth")
logger.set_environment("staging")
```

### Flush / Shutdown

```python
logger.flush()     # block until current queue is sent
logger.shutdown()  # flush + stop background thread
```

## Django Integration Example

```python
# settings.py (or apps.py AppConfig.ready())
from logforge import LogForge
import atexit

log = LogForge(api_key="YOUR_KEY", endpoint="https://logs.myapp.com")
atexit.register(log.shutdown)

# In views.py
import traceback

def my_view(request):
    try:
        do_something()
    except Exception as exc:
        log.capture_exception(exc, metadata={"path": request.path})
        raise
```

## FastAPI / async usage

The SDK is synchronous and thread-safe. It works fine alongside async frameworks — the background flush thread runs independently.

```python
from contextlib import asynccontextmanager
from fastapi import FastAPI
from logforge import LogForge

logger = LogForge(api_key="KEY", endpoint="https://logs.myapp.com")

@asynccontextmanager
async def lifespan(app: FastAPI):
    yield
    logger.shutdown()

app = FastAPI(lifespan=lifespan)
```

## License

MIT — see [LICENCE](LICENCE)
