# VedaTrace Python SDK
Production-grade logging SDK for VedaTrace (Python 3.10+).

## Table of Contents
- [Features](#features)
- [Stability](#stability)
- [Installation](#installation)
- [Quickstart](#quickstart)
- [Configuration](#configuration)
- [Transports](#transports)
- [Batching (Opt-in)](#batching-opt-in)
- [Retry (HTTP only)](#retry-http-only)
- [Child Loggers](#child-loggers)
- [Error Handling & Safety](#error-handling--safety)
- [Resource Management (flush/close)](#resource-management-flushclose)
- [API Reference](#api-reference)
- [Release Process (Maintainers)](#release-process-maintainers)
- [License](#license)

## Features
- Log levels aligned to parity: `debug`, `info`, `warning`, `error`, `fatal`
- Structured log records with UTC ISO-8601 timestamps
- Default transports: Console (optional) + HTTP ingest
- Custom transport support via `config.transports`
- Opt-in batching with threshold + interval flush
- HTTP-only fixed-delay retries
- Child loggers with metadata precedence support
- Safe public API: logger methods do not raise user-facing exceptions

## Stability
Version `0.1.0` introduces a stable public API for:
- Logger
- Config
- Transports
- Batching
- Retry
- Child loggers

Breaking changes may still occur before `1.0`.

## Installation
```bash
python -m pip install vedatrace
```

For local development:
```bash
python -m pip install -e .
```

## Quickstart
```python
from vedatrace import VedaTrace

logger = VedaTrace(api_key="YOUR_API_KEY", service="my-service")
logger.info("hello from vedatrace")
```

## Configuration
```python
from vedatrace import BatchingConfig, RetryConfig, VedaTrace, VedaTraceConfig

config = VedaTraceConfig(
    api_key="YOUR_API_KEY",
    service="my-service",
    console_enabled=True,
    batching=BatchingConfig(enabled=False, batch_size=10, flush_interval_seconds=5.0),
    retry=RetryConfig(max_retries=0, retry_delay_seconds=0.0),
)

logger = VedaTrace(api_key="YOUR_API_KEY", service="my-service", config=config)
```

## Transports
Default behavior:
- Console transport is enabled when `config.console_enabled` is `True`
- HTTP transport is enabled by default

Custom transports:
- Provide `config.transports` to fully override default transport creation

## Batching (Opt-in)
Batching is disabled by default and must be enabled in `BatchingConfig`.

```python
from vedatrace import BatchingConfig, VedaTrace, VedaTraceConfig

config = VedaTraceConfig(
    api_key="YOUR_API_KEY",
    service="my-service",
    batching=BatchingConfig(enabled=True, batch_size=10, flush_interval_seconds=5.0),
)

logger = VedaTrace(api_key="YOUR_API_KEY", service="my-service", config=config)
logger.info("batched log")
logger.flush()
```

## Retry (HTTP only)
Retries are fixed-delay and apply only to the default HTTP transport.

```python
from vedatrace import RetryConfig, VedaTrace, VedaTraceConfig

config = VedaTraceConfig(
    api_key="YOUR_API_KEY",
    service="my-service",
    retry=RetryConfig(max_retries=3, retry_delay_seconds=1.0),
    console_enabled=False,
)

logger = VedaTrace(api_key="YOUR_API_KEY", service="my-service", config=config)
```

If retries are exhausted, `on_error` receives the final failure.

## Child Loggers
```python
from vedatrace import VedaTrace

parent = VedaTrace(api_key="YOUR_API_KEY", service="my-service")
api_logger = parent.child({"module": "api"})
api_logger.info("request handled", {"request_id": "123"})
```

Metadata precedence:
- parent defaults < child defaults < per-call metadata

`child.close()` does not tear down shared engine resources.

## Error Handling & Safety
- Public logger methods are non-throwing (`debug/info/warning/error/fatal/flush/close`)
- Internal failures are routed to `on_error(Exception)` when configured
- SDK avoids exposing API keys in logs/errors

## Resource Management (flush/close)
- `flush()` forces pending batches to be sent
- `close()` flushes and then closes owned resources
- Child loggers share engine resources; parent logger owns teardown

## API Reference
Factory:
- `VedaTrace(api_key: str, service: str, *, config: VedaTraceConfig | None = None) -> Logger`

Logger:
- `debug(message: str, metadata: Metadata | None = None) -> None`
- `info(message: str, metadata: Metadata | None = None) -> None`
- `warning(message: str, metadata: Metadata | None = None) -> None`
- `error(message: str, metadata: Metadata | None = None) -> None`
- `fatal(message: str, metadata: Metadata | None = None) -> None`
- `child(default_metadata: Metadata | None = None, *, service: str | None = None) -> Logger`
- `flush() -> None`
- `close() -> None`

Config classes:
- `VedaTraceConfig(api_key, service, console_enabled=True, batching=BatchingConfig(...), retry=RetryConfig(...), transports=None, on_error=None)`
- `BatchingConfig(enabled=False, batch_size=10, flush_interval_seconds=5.0)`
- `RetryConfig(max_retries=0, retry_delay_seconds=0.0)`

Transport types:
- `Transport` protocol:
  - `emit(records: list[LogRecord]) -> None`
  - `close() -> None`
- Included transports:
  - `ConsoleTransport`
  - `HttpTransport`

Behavior notes:
- Public log methods never raise.
- Internal failures route to `on_error(Exception)` when configured.
- Batching is opt-in.
- Retry applies to HTTP transport only.
- `child.close()` does not tear down the shared engine.

## Release Process (Maintainers)
1. Bump version in:
- `src/vedatrace/__init__.py`
- `pyproject.toml`
- `CHANGELOG.md`
2. Run:
- `python -m unittest -v`
- `python -m compileall src`
3. Build:
- `python -m build`
4. Validate:
- `twine check dist/*`
5. Publish (when ready):
- `python -m pip install twine`
- `twine upload dist/*`

Notes:
- Never force push release commits.
- Tag releases using:
- `git tag v0.1.0`
- `git push origin v0.1.0`

## License
MIT
