road24-artifacthub 0.1.0__tar.gz

road24_artifacthub-0.1.0/.claude/CLAUDE.md

@@ -0,0 +1,151 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**road24-artifacthub** is a shared Python SDK providing logging and metrics utilities for Road24 microservices. It follows a Sentry SDK-like pattern with framework-specific integrations.
+
+**Stack:** Python 3.12+, dataclasses, prometheus_client
+
+**Dependencies:**
+- `prometheus-client` - For Prometheus metrics
+- `httpx` - For HTTPX client integration
+- `redis` - For Redis client integration
+- `sqlalchemy` - For SQLAlchemy database integration
+
+## Installation
+
+```bash
+# Core library
+pip install road24-artifacthub
+
+# Development
+pip install road24-artifacthub[dev]
+```
+
+## Commands
+
+```bash
+# Testing
+pytest                        # Run all tests
+pytest -v                     # Verbose output
+pytest tests/                 # Test specific module
+pytest --cov=road24_sdk       # Coverage report
+
+# Code Quality
+ruff check .                  # Linting
+ruff format .                 # Formatting
+```
+
+## Architecture
+
+### Module Structure
+
+```
+road24_sdk/                   # Main package
+├── __init__.py               # Public API: init(), configure(), enums
+├── _types.py                 # ArtifactHubConfig + StrEnum definitions (internal)
+├── _schemas.py               # Dataclass schemas for log attributes (internal)
+├── _formatter.py             # LogFormatter, setup_logging(), trace context, ExceptionLogger (internal)
+├── _sanitizer.py             # Body sanitization utilities (internal)
+├── metrics/                  # Prometheus metrics utilities
+│   ├── __init__.py           # Public exports
+│   ├── http.py               # HTTP request metrics
+│   ├── db.py                 # Database query metrics
+│   └── redis.py              # Redis command metrics
+└── integrations/             # Framework-specific integrations (logging + metrics)
+    ├── __init__.py            # Exports all integrations + Integration base
+    ├── _base.py              # Integration ABC with setup_once() pattern
+    ├── fastapi.py            # FastApiLoggingIntegration + HttpInputLogger
+    ├── httpx.py              # HttpxLoggingIntegration + HttpOutputLogger
+    ├── sqlalchemy.py         # SqlalchemyLoggingIntegration + DbLogger
+    └── redis.py              # RedisLoggingIntegration + RedisLogger + LoggedRedis
+```
+
+### Key Patterns
+
+**SDK-like Initialization:** Uses `init()` function similar to Sentry SDK with `integrations=[]` for auto-instrumentation:
+```python
+import road24_sdk
+from road24_sdk.integrations.httpx import HttpxLoggingIntegration
+from road24_sdk.integrations.redis import RedisLoggingIntegration
+
+road24_sdk.init(
+    service_name="my-service",
+    log_level="INFO",
+    integrations=[
+        HttpxLoggingIntegration(),
+        RedisLoggingIntegration(),
+    ],
+)
+```
+
+**Integration Pattern:** All integrations inherit from `Integration` ABC and implement `setup_once()` for class-level patching (called via `init()`) and `.setup(client)` for instance-level patching.
+- `setup_once()` patches at class level so all new instances are auto-instrumented.
+- `.setup(client)` patches a specific client instance (backwards compatible).
+- `FastApiLoggingIntegration` requires `.setup(app)` since it needs the app instance.
+
+**When adding new integrations**, implement both `setup_once()` (class-level patching) and `.setup(client)` (instance-level patching). Inherit from `Integration` ABC.
+
+**Trace Context Propagation:** Uses `ContextVar` for thread-safe trace ID propagation across async operations.
+
+**Metrics Recording:** All operations record both duration (Histogram) and count (Counter) with normalized labels.
+
+## Code Style Requirements
+
+- Full type hints on all functions (Python 3.12+ syntax)
+- Use `StrEnum` for all enum definitions
+- Use `ContextVar` for request-scoped state (not global variables)
+- Use dataclasses with `slots=True` for schemas
+- Guard clauses (early returns) over nested conditionals
+- Async/await for all async utilities
+- No comments except for complex logic
+- Keep functions under 20 lines
+- Use `TYPE_CHECKING` for optional dependencies
+
+## Consumer Integration
+
+Pass integrations to `init()` for auto-instrumentation. All new client instances are automatically patched.
+
+```python
+import road24_sdk
+from road24_sdk.integrations.fastapi import FastApiLoggingIntegration
+from road24_sdk.integrations.httpx import HttpxLoggingIntegration
+from road24_sdk.integrations.sqlalchemy import SqlalchemyLoggingIntegration
+from road24_sdk.integrations.redis import RedisLoggingIntegration
+
+# Initialize with integrations — auto-instruments all new client instances
+road24_sdk.init(
+    service_name="my-service",
+    log_level="INFO",
+    debug=False,
+    integrations=[
+        FastApiLoggingIntegration(),
+        HttpxLoggingIntegration(),
+        SqlalchemyLoggingIntegration(),
+        RedisLoggingIntegration(),
+    ],
+)
+
+# FastAPI still requires .setup(app) since it needs the app instance
+app = FastAPI()
+FastApiLoggingIntegration().setup(app)
+
+# All other clients are auto-instrumented — no .setup() needed
+client = AsyncClient(timeout=Timeout(25.0))  # already instrumented
+engine = create_async_engine(DATABASE_URL)    # already instrumented
+redis = Redis.from_url(REDIS_URL)            # already instrumented
+```
+
+The `.setup(client)` method still works for per-instance patching (backwards compatible).
+
+## Testing Guidelines
+
+- All tests must be async (`@pytest.mark.asyncio`)
+- Mock all external dependencies (AsyncMock for async, Mock for sync)
+- Use fixtures for test data in `tests/conftest.py`
+- Use `@pytest.mark.parametrize` with dataclasses for multiple scenarios
+- Follow AAA pattern (Arrange-Act-Assert)
+- Target >90% coverage
+- Test file structure mirrors source structure

road24_artifacthub-0.1.0/.claude/agents/engineer.md

@@ -0,0 +1,256 @@
+---
+name: engineer
+description: Senior Python developer for road24-artifacthub shared library. Provides logging and metrics utilities for microservices. Framework-agnostic. MUST run tests after changes.
+tools: Read, Edit, Write, Bash, Grep, Glob, Task
+model: opus
+---
+
+## Critical Rules
+
+1. **ALWAYS** follow SOLID principles and existing patterns
+2. **ALWAYS** run tests after changes: `pytest`
+3. **ALWAYS** use full type hints (Python 3.12+)
+4. **ALWAYS** use async/await for async utilities
+5. **ALWAYS** use structured logging patterns
+6. **ALWAYS** maintain backwards compatibility for consumer services
+7. **ALWAYS** use `TYPE_CHECKING` for optional dependencies (httpx, redis, sqlalchemy)
+8. **NEVER** write comments except for complex logic
+9. **NEVER** add unrequested features (YAGNI)
+
+## Documentation Reference
+
+**IMPORTANT:** For comprehensive project documentation, architecture details, and complete guidelines, refer to:
+- **`.claude/CLAUDE.md`** - Main project guide with stack details, architecture, and coding standards
+
+This agent guide is a condensed development reference. Always consult CLAUDE.md for authoritative project information.
+
+## Project: road24-artifacthub
+
+Shared Python SDK providing logging and metrics utilities for Road24 microservices. Follows a Sentry SDK-like pattern with framework-specific integrations.
+
+**Stack:** Python 3.12+, dataclasses, prometheus_client
+
+**Optional:** httpx, redis, sqlalchemy
+
+## Library Structure
+
+```
+road24_sdk/                   # Main package
+├── __init__.py               # Public API: init(), configure(), enums
+├── _types.py                 # ArtifactHubConfig + StrEnum definitions (internal)
+├── _schemas.py               # Dataclass schemas for log attributes (internal)
+├── _formatter.py             # LogFormatter, setup_logging(), trace context, ExceptionLogger (internal)
+├── _sanitizer.py             # Body sanitization utilities (internal)
+├── metrics/                  # Prometheus metrics utilities
+│   ├── __init__.py           # Public exports
+│   ├── http.py               # HTTP request metrics
+│   ├── db.py                 # Database query metrics
+│   └── redis.py              # Redis command metrics
+└── integrations/             # Framework-specific integrations (logging + metrics)
+    ├── __init__.py            # Exports all integrations + Integration base
+    ├── _base.py              # Integration ABC with setup_once() pattern
+    ├── fastapi.py            # FastApiLoggingIntegration + HttpInputLogger
+    ├── httpx.py              # HttpxLoggingIntegration + HttpOutputLogger
+    ├── sqlalchemy.py         # SqlalchemyLoggingIntegration + DbLogger
+    └── redis.py              # RedisLoggingIntegration + RedisLogger
+```
+
+## Integration Pattern
+
+All integrations inherit from `Integration` ABC and support two patching modes:
+- `setup_once()` — class-level patching, called automatically by `init(integrations=[...])`
+- `.setup(client)` — instance-level patching (backwards compatible)
+
+```python
+# Auto-instrumentation via init()
+road24_sdk.init(
+    service_name="my-service",
+    integrations=[HttpxLoggingIntegration()],
+)
+# All new AsyncClient instances are auto-patched
+
+# Per-instance patching (still works)
+client = AsyncClient(timeout=Timeout(25.0))
+HttpxLoggingIntegration().setup(client)
+```
+
+When adding new integrations, inherit from `Integration` and implement both `setup_once()` and `.setup(client)`.
+
+## Key Components
+
+**LogFormatter** (`_formatter.py`):
+- JSON output with structured format
+- Trace ID context propagation via ContextVar
+- Automatic exception formatting
+
+**Integrations** (`integrations/*.py`):
+- Each integration has a Logger class (e.g., `DbLogger`, `RedisLogger`)
+- Each integration has a `*LoggingIntegration` class with `.setup(client)` method
+- Logger classes handle: operation extraction, table/key extraction, metrics recording, structured logging
+- `.setup()` monkey-patches client methods to add timing, logging, and metrics
+
+**Metrics** (`metrics/*.py`):
+- Prometheus Histogram for durations
+- Prometheus Counter for totals
+- Labeled metrics (operation, table/key/url)
+
+## Consumer Integration
+
+```python
+import road24_sdk
+from road24_sdk.integrations.fastapi import FastApiLoggingIntegration
+from road24_sdk.integrations.httpx import HttpxLoggingIntegration
+from road24_sdk.integrations.sqlalchemy import SqlalchemyLoggingIntegration
+from road24_sdk.integrations.redis import RedisLoggingIntegration
+
+road24_sdk.init(
+    service_name="my-service",
+    log_level="INFO",
+    integrations=[
+        FastApiLoggingIntegration(),
+        HttpxLoggingIntegration(),
+        SqlalchemyLoggingIntegration(),
+        RedisLoggingIntegration(),
+    ],
+)
+
+# FastAPI still requires .setup(app)
+FastApiLoggingIntegration().setup(app)
+
+# Other clients are auto-instrumented — no .setup() needed
+```
+
+## Workflow
+
+1. **Read** existing code first (`Read` tool)
+2. **Search** patterns (`Grep`/`Glob`)
+3. **Implement** following existing patterns
+4. **Test** changes: `pytest`
+5. **Check** quality: `ruff check .`
+
+## Code Style (Mandatory)
+
+**Type Hints:**
+```python
+def record_db_query(
+    operation: DbOperation,
+    table: str,
+    duration_seconds: float,
+) -> None:
+    ...
+```
+
+**Optional Dependencies with TYPE_CHECKING:**
+```python
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from redis.asyncio import Redis
+
+def setup(self, client: "Redis") -> None:
+    ...
+```
+
+**Guard Clauses (Early Returns):**
+```python
+def extract_operation(self, statement: str) -> DbOperation:
+    statement_upper = statement.strip().upper()
+    if statement_upper.startswith("SELECT"):
+        return DbOperation.SELECT
+    if statement_upper.startswith("INSERT"):
+        return DbOperation.INSERT
+    return DbOperation.OTHER
+```
+
+**Dataclasses with slots:**
+```python
+@dataclass(slots=True)
+class DbAttributes:
+    operation: DbOperation
+    table: str
+    duration_seconds: float
+    statement: str = ""
+```
+
+**StrEnum for all enums:**
+```python
+class DbOperation(StrEnum):
+    SELECT = "select"
+    INSERT = "insert"
+    OTHER = "other"
+```
+
+## Naming Conventions
+
+- **Loggers**: `{Domain}Logger` (e.g., `DbLogger`, `RedisLogger`)
+- **Integrations**: `{Framework}LoggingIntegration` (e.g., `SqlalchemyLoggingIntegration`)
+- **Schemas**: `{Domain}Attributes` (e.g., `DbAttributes`, `RedisAttributes`)
+- **Metrics**: `UPPER_SNAKE_CASE` (e.g., `DB_QUERY_DURATION`)
+- **Enums**: `{Domain}Operation` using `StrEnum`
+- **Functions**: `snake_case` (e.g., `record_db_query`)
+- **Private**: `_prefix`
+
+## Commands
+
+```bash
+pytest                      # Run all tests
+pytest -v                   # Verbose output
+pytest --cov=road24_sdk     # Coverage report
+ruff check .                # Linting
+ruff format .               # Formatting
+```
+
+## Dependencies
+
+**Required:**
+- `prometheus-client` - Prometheus metrics
+
+**Optional (extras):**
+- `httpx` - HTTPX client integration
+- `redis` - Redis client integration
+- `sqlalchemy` - SQLAlchemy database integration
+
+## Anti-Patterns
+
+- Don't break backwards compatibility without notice
+- Don't add framework-specific logic (keep generic)
+- Don't use `print()` anywhere
+- Don't skip type hints
+- Don't use synchronous I/O in async hooks
+- Don't import optional deps at module level (use TYPE_CHECKING)
+- Don't use Pydantic for schemas — use dataclasses with `slots=True`
+- Don't use global variables — use `ContextVar` for request-scoped state
+
+## Testing
+
+- All tests must be async (`@pytest.mark.asyncio`, auto mode configured)
+- Mock all external dependencies (AsyncMock for async, Mock for sync)
+- Use fixtures for test data in `tests/conftest.py`
+- Use `@pytest.mark.parametrize` with dataclasses for multiple scenarios
+- Follow AAA pattern (Arrange-Act-Assert)
+- Target >90% coverage
+- Test file structure mirrors source structure
+
+## Log Output Format
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:00.123Z",
+  "trace_id": "abc123...",
+  "log_level": "INFO",
+  "type": "db_query",
+  "service_name": "my-service",
+  "attributes": {
+    "operation": "select",
+    "table": "users",
+    "duration_seconds": 0.023,
+    "statement": "SELECT * FROM users WHERE id = 1"
+  }
+}
+```
+
+## Prometheus Metrics
+
+- `http_request_duration_seconds` / `http_requests_total` — Labels: `method`, `url`, `status_code`, `direction`
+- `db_query_duration_seconds` / `db_queries_total` — Labels: `operation`, `table`
+- `redis_command_duration_seconds` / `redis_commands_total` — Labels: `operation`, `key`