Metadata-Version: 2.5
Name: vexioauth-logger
Version: 1.0.0
Summary: VexioAuth structured logging SDK — log events from any Python project.
Project-URL: Homepage, https://github.com/Honeykalra22/vaxioAuth#readme
Project-URL: Repository, https://github.com/Honeykalra22/vaxioAuth
Project-URL: Issues, https://github.com/Honeykalra22/vaxioAuth/issues
License: MIT
License-File: LICENSE
Keywords: logging,observability,structured-logs,vexioauth
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.13
Classifier: Topic :: System :: Logging
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# VexioAuth Logger

Send structured application logs to your VexioAuth service console from Python. Zero dependencies — standard library only. Python 3.8+.

## Installation

```bash
pip install vexioauth-logger
```

## Quick start

```python
import os
from vexioauth_logger import create_logger

logger = create_logger(
    account_key=os.environ["VEXIO_ACCOUNT_KEY"],
    service_id=os.environ["VEXIO_SERVICE_ID"],
    base_url="https://api-vexio.vidyahelp.in",
)

logger.info("user.checkout", plan="pro", user_id="user-42")
logger.error("payment.failed", {"code": "card_declined"}, user_id="user-42")
```

Metadata can be a dict, a string (stored as `message`), keyword arguments, or a mix. Keyword arguments win when a key appears in both. `user_id` is sent as a top-level field, not as metadata.

A background daemon thread owns all HTTP work, so logging never blocks your request path or an `asyncio` event loop. Events are buffered and sent in gzip-compressed batches.

Bind a user once with `with_user()`:

```python
user = logger.with_user("user-42")
user.info("user.login", ip="1.2.3.4")
```

## Use with Python's `logging`

`VexioAuthHandler` forwards standard `logging` records, so existing log calls reach VexioAuth without changes.

```python
import logging
import os
from vexioauth_logger import VexioAuthHandler

logging.getLogger().addHandler(VexioAuthHandler(
    account_key=os.environ["VEXIO_ACCOUNT_KEY"],
    service_id=os.environ["VEXIO_SERVICE_ID"],
    base_url="https://api-vexio.vidyahelp.in",
))

log = logging.getLogger("checkout")
log.info("Checkout completed", extra={"event_type": "user.checkout", "user_id": "user-42"})
log.exception("Charge failed", extra={"event_type": "payment.failed"})
```

- `extra={"event_type": ...}` sets the event name. Without it, the handler falls back to the logger's name — `logging.getLogger("checkout").info("done")` is stored as `info.checkout`.
- `extra={"user_id": ...}` sets the user. Any other `extra` keys are added to the metadata.
- The record's message, logger name, module, function and line number are always included. `log.exception(...)` also captures the exception type, message and stack trace.
- To share one background thread with the direct API, pass an existing logger: `VexioAuthHandler(logger=logger)`.

## Configuration

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `account_key` | `str` | Yes | - | VexioAuth account key, sent as `X-Account-Key`. Store it in an environment variable. |
| `service_id` | `str` | Yes | - | The service identifier registered in your console. |
| `base_url` | `str` | Yes | - | Base URL of your VexioAuth API. |
| `min_level` | `str` | No | `"debug"` | Lowest level sent: `trace`, `debug`, `info`, `warning`, `error`, or `critical`. |
| `buffer_capacity` | `int` | No | `5000` | Events held in memory. When full, the oldest are dropped. |
| `batch_size` | `int` | No | `100` | Events per request. Values above `500` are clamped to `500`. |
| `flush_interval` | `float` | No | `3.0` | **Seconds** between sends. The Node.js SDK uses milliseconds. |
| `compress` | `bool` | No | `True` | Gzip the request body. |
| `timeout` | `float` | No | `15.0` | **Seconds** allowed per HTTP attempt. |

Missing required options or an unknown `min_level` raise `ValueError` at startup.

## Log levels

```python
logger.trace("request.received", path="/orders")
logger.debug("cache.miss", key="order:123")
logger.info("order.created", order_id="order-123")
logger.warning("rate_limit.near_limit", remaining=5)   # logger.warn is an alias
logger.error("order.failed", order_id="order-123", reason="unavailable")
logger.critical("database.unavailable", region="ap-south-1")
```

On the wire the event type is `"<level>.<event_type>"`, for example `info.order.created`. The `logging` levels map as `DEBUG` → `debug`, `INFO` → `info`, `WARNING` → `warning`, `ERROR` → `error`, `CRITICAL` → `critical`, and levels below `DEBUG` → `trace`.

## Shutdown

```python
logger.close()                 # sends whatever is still buffered

with create_logger(account_key=..., service_id=..., base_url=...) as logger:
    logger.info("job.done")    # closed on exit
```

The SDK registers an `atexit` hook, and `VexioAuthHandler` drains on `logging.shutdown()`, so a normal interpreter exit already flushes the buffer. Call `close()` explicitly for hard shutdowns, and `flush()` to send early without closing.

## Error handling

The logger never raises into your code once it is running. If a batch cannot be delivered, the problem is written to `stderr` with a `[vexioauth-logger]` prefix — never through `logging`, so a handler on the root logger cannot feed its own failures back into the queue.

## License

MIT
