Metadata-Version: 2.4
Name: road24-sdk
Version: 0.1.3
Summary: Shared logging and metrics library for Road24 FastAPI microservices
Requires-Python: >=3.12
Requires-Dist: build>=1.4.0
Requires-Dist: prometheus-client>=0.20.0
Requires-Dist: twine>=6.2.0
Provides-Extra: all
Requires-Dist: fastapi>=0.100.0; extra == 'all'
Requires-Dist: httpx>=0.27.0; extra == 'all'
Requires-Dist: redis>=5.0.0; extra == 'all'
Requires-Dist: sqlalchemy>=2.0.45; extra == 'all'
Requires-Dist: starlette>=0.27.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: faker>=25.0.0; extra == 'dev'
Requires-Dist: fastapi>=0.100.0; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: redis>=5.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: sqlalchemy>=2.0.45; extra == 'dev'
Requires-Dist: starlette>=0.27.0; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
Requires-Dist: starlette>=0.27.0; extra == 'fastapi'
Provides-Extra: httpx
Requires-Dist: httpx>=0.27.0; extra == 'httpx'
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == 'redis'
Provides-Extra: sqlalchemy
Requires-Dist: sqlalchemy>=2.0.45; extra == 'sqlalchemy'
Description-Content-Type: text/markdown

# road24-sdk

Shared logging and metrics SDK for Road24 microservices. Provides structured JSON logging, Prometheus metrics, and framework-specific integrations following a Sentry SDK-like pattern.

## Installation

```bash
# Core library
pip install road24-sdk

# With all integrations
pip install road24-sdk[all]

# Development (includes test tools)
pip install road24-sdk[dev]
```

## Quick Start

```python
import road24_sdk
from fastapi import FastAPI
from httpx import AsyncClient, Timeout
from road24_sdk.integrations.fastapi import FastApiLoggingIntegration
from road24_sdk.integrations.httpx import HttpxLoggingIntegration
from road24_sdk.integrations.redis import RedisLoggingIntegration
from road24_sdk.integrations.sqlalchemy import SqlalchemyLoggingIntegration

def setup_road24_sdk():
    road24_sdk.init(
        service_name="my-service",
        log_level="INFO",
        integrations=[
            HttpxLoggingIntegration(),
            SqlalchemyLoggingIntegration(),
            RedisLoggingIntegration(),
        ],
    )

# FastAPI requires .setup(app) since it needs the app instance
app = FastAPI()
setup_road24_sdk()
FastApiLoggingIntegration().setup(app)
```

## Available Integrations

| Integration | Extra | Description |
|---|---|---|
| `FastApiLoggingIntegration` | `fastapi` | Inbound HTTP request/response logging and metrics |
| `HttpxLoggingIntegration` | `httpx` | Outbound HTTP request/response logging and metrics |
| `SqlalchemyLoggingIntegration` | `sqlalchemy` | Database query logging and metrics |
| `RedisLoggingIntegration` | `redis` | Redis command logging and metrics |

## Manual Testing

Standalone scripts to inspect structured JSON logs and metrics (no server needed):

```bash
make test-logs-http-input    # Inbound HTTP request log
make test-logs-http-output   # Outbound HTTPX request log
make test-metrics-http       # Prometheus metrics after HTTP calls
make test-logs-redis         # Redis command logs (SET, GET, HSET, etc.)
make test-logs-db            # DB query logs (SELECT, INSERT, UPDATE, DELETE)
```

## Development

```bash
make install    # Install all dependencies (requires uv)
make test       # Run tests with coverage
make lint       # Lint with ruff
make format     # Format with ruff
make check      # Lint + test
```
