sql-dialect-master 1.1.7__tar.gz → 1.1.8__tar.gz

{sql_dialect_master-1.1.7/sql_dialect_master.egg-info → sql_dialect_master-1.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-dialect-master
-Version: 1.1.7
+Version: 1.1.8
 Summary: SQL Dialect Master - Multi-database SQL conversion engine
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -10,6 +10,7 @@ Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn>=0.30.0
 Requires-Dist: pydantic>=2.9.0
 Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: prometheus-client<1.0.0,>=0.20.0
 Provides-Extra: dev
 Requires-Dist: hypothesis>=6.112.0; extra == "dev"
 Requires-Dist: pytest>=8.3.0; extra == "dev"
@@ -35,7 +36,7 @@ Dynamic: license-file
 
 Enterprise-grade multi-database SQL conversion engine supporting 12 database dialects.
 
-Current release: 1.1.7
+Current release: 1.1.8
 
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -372,3 +373,4 @@ public catalog responses use short `private` caching. Full deployment details
 will be documented in `docs/deployment.md`.
 
 See [`docs/deployment.md`](docs/deployment.md) for production deployment guidance.
+Metrics configuration and scraping guidance are documented in the same guide.

{sql_dialect_master-1.1.7 → sql_dialect_master-1.1.8}/README.md

@@ -2,7 +2,7 @@
 
 Enterprise-grade multi-database SQL conversion engine supporting 12 database dialects.
 
-Current release: 1.1.7
+Current release: 1.1.8
 
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -339,3 +339,4 @@ public catalog responses use short `private` caching. Full deployment details
 will be documented in `docs/deployment.md`.
 
 See [`docs/deployment.md`](docs/deployment.md) for production deployment guidance.
+Metrics configuration and scraping guidance are documented in the same guide.

{sql_dialect_master-1.1.7 → sql_dialect_master-1.1.8}/backend/api/main.py

@@ -30,6 +30,7 @@ from fastapi.responses import JSONResponse
 from pydantic import BaseModel, ConfigDict, Field
 
 from backend.api.auth import require_api_access
+from backend.api.metrics import MetricsMiddleware, configure_runtime_metrics, metrics_response, record_transpile_request
 from backend.api.rate_limit_store import InMemoryRateLimitStore
 from backend.api.readiness import health_probe_response
 from backend.api.workers import BoundedWorkerPool, WorkerCapacityError
@@ -303,6 +304,12 @@ func_encyclopedia = FunctionEncyclopedia()
 type_mapper = TypeMapper()
 nl2sql_generator = NL2SQLGenerator()
 
+configure_runtime_metrics(
+    transpiler_provider=lambda: transpiler,
+    worker_provider=_get_worker_pool,
+    limiter_provider=lambda: rate_limiter,
+)
+
 # Request timing middleware with logging
 @app.middleware("http")
 async def add_process_time_header(request: Request, call_next):
@@ -320,6 +327,11 @@ async def add_process_time_header(request: Request, call_next):
                     response.status_code, process_time)
     return response
 
+
+# This is the outermost application middleware, so it also observes short
+# circuit responses returned by rate limiting and worker-capacity guards.
+app.add_middleware(MetricsMiddleware)
+
 # Dialect info for enhanced responses (from centralized config)
 DIALECT_INFO = get_dialect_api_info()
 
@@ -460,6 +472,10 @@ class APIResponse(BaseModel):
 
 # === API Endpoints ===
 
+@app.get("/metrics", include_in_schema=False)
+async def metrics_endpoint(request: Request):
+    return await metrics_response(request)
+
 @app.get("/", tags=["system"])
 async def root():
     """
@@ -560,11 +576,13 @@ async def convert_sql(request: ConvertRequest):
     source_dialect = request.source_dialect.strip().lower()
     target_dialect = request.target_dialect.strip().lower()
     if source_dialect not in SUPPORTED_DIALECTS:
+        record_transpile_request("unknown", "unknown", "validation_error")
         raise HTTPException(
             status_code=400,
             detail=f"Unsupported source dialect: {request.source_dialect}. Supported: {SUPPORTED_DIALECTS}"
         )
     if target_dialect not in SUPPORTED_DIALECTS:
+        record_transpile_request(source_dialect, "unknown", "validation_error")
         raise HTTPException(
             status_code=400,
             detail=f"Unsupported target dialect: {request.target_dialect}. Supported: {SUPPORTED_DIALECTS}"
@@ -572,12 +590,21 @@ async def convert_sql(request: ConvertRequest):
 
     # sqlglot parsing/transpilation is CPU-bound.  Keep it off the event loop
     # so one large request cannot stall unrelated async requests.
-    result = await _run_cpu_bound(
-        transpiler.transpile,
-        request.sql,
+    try:
+        result = await _run_cpu_bound(
+            transpiler.transpile,
+            request.sql,
+            source_dialect,
+            target_dialect,
+            request.pretty,
+        )
+    except HTTPException:
+        record_transpile_request(source_dialect, target_dialect, "error")
+        raise
+    record_transpile_request(
         source_dialect,
         target_dialect,
-        request.pretty,
+        "success" if result.success else "error",
     )
     return ConvertResponse(
         success=result.success,

sql_dialect_master-1.1.8/backend/api/metrics.py

@@ -0,0 +1,171 @@
+"""Protected Prometheus metrics for the API process."""
+
+from __future__ import annotations
+
+import secrets
+from collections.abc import Callable
+
+from fastapi import Request
+from fastapi.responses import PlainTextResponse, Response
+from prometheus_client import (
+    CONTENT_TYPE_LATEST,
+    CollectorRegistry,
+    Counter,
+    Gauge,
+    Histogram,
+    generate_latest,
+)
+from prometheus_client.core import CounterMetricFamily, GaugeMetricFamily
+
+from backend.core.config import settings
+from backend.core.metadata import PROJECT_VERSION
+
+REGISTRY = CollectorRegistry(auto_describe=True)
+
+BUILD_INFO = Gauge("sdm_build_info", "SQL Dialect Master build information", ["version"], registry=REGISTRY)
+BUILD_INFO.labels(version=PROJECT_VERSION).set(1)
+
+HTTP_REQUESTS = Counter(
+    "sdm_http_requests_total",
+    "HTTP requests handled by the API",
+    ["method", "route", "status_class"],
+    registry=REGISTRY,
+)
+HTTP_DURATION = Histogram(
+    "sdm_http_request_duration_seconds",
+    "HTTP request duration in seconds",
+    ["method", "route", "status_class"],
+    registry=REGISTRY,
+)
+RATE_LIMIT_REJECTIONS = Counter(
+    "sdm_rate_limit_rejections_total",
+    "Rate-limited requests",
+    registry=REGISTRY,
+)
+TRANSPILE_REQUESTS = Counter(
+    "sdm_transpile_requests_total",
+    "Conversion requests by dialect pair and result",
+    ["source", "target", "result"],
+    registry=REGISTRY,
+)
+
+_transpiler_provider: Callable[[], object] | None = None
+_worker_provider: Callable[[], object] | None = None
+_limiter_provider: Callable[[], object] | None = None
+
+
+def configure_runtime_metrics(*, transpiler_provider=None, worker_provider=None, limiter_provider=None) -> None:
+    """Register process-local runtime providers used when /metrics is scraped."""
+    global _transpiler_provider, _worker_provider, _limiter_provider
+    _transpiler_provider = transpiler_provider
+    _worker_provider = worker_provider
+    _limiter_provider = limiter_provider
+
+
+class RuntimeCollector:
+    """Read low-frequency runtime snapshots without copying them per request."""
+
+    def collect(self):
+        if _transpiler_provider is not None:
+            try:
+                stats = _transpiler_provider().get_stats()
+                cache = stats.get("cache", {})
+                if cache.get("enabled", True) is not False:
+                    yield CounterMetricFamily("sdm_transpile_cache_hits_total", "Transpiler cache hits", value=cache.get("hits", 0))
+                    yield CounterMetricFamily("sdm_transpile_cache_misses_total", "Transpiler cache misses", value=cache.get("misses", 0))
+                    yield CounterMetricFamily("sdm_transpile_cache_evictions_total", "Transpiler cache evictions", value=cache.get("evictions", 0))
+                    yield GaugeMetricFamily("sdm_transpile_cache_size", "Current transpiler cache size", value=cache.get("size", 0))
+            except Exception:
+                pass
+
+        if _worker_provider is not None:
+            try:
+                stats = _worker_provider().stats()
+                yield GaugeMetricFamily("sdm_api_worker_capacity", "API worker pool capacity", value=stats["capacity"])
+                yield GaugeMetricFamily("sdm_api_worker_in_use", "API worker slots in use", value=stats["in_use"])
+                yield CounterMetricFamily("sdm_api_worker_rejections_total", "API worker capacity rejections", value=stats["rejections"])
+                yield CounterMetricFamily("sdm_api_request_timeouts_total", "API request timeouts", value=stats["timeouts"])
+            except Exception:
+                pass
+
+        if _limiter_provider is not None:
+            try:
+                stats = _limiter_provider().get_stats()
+                if stats.get("backend") == "memory":
+                    yield GaugeMetricFamily("sdm_rate_limit_active_clients", "Active in-memory rate-limit clients", value=stats.get("active_clients", 0))
+            except Exception:
+                pass
+
+
+REGISTRY.register(RuntimeCollector())
+
+
+def normalize_method(method: str) -> str:
+    return method if method in {"GET", "POST", "HEAD", "OPTIONS"} else "other"
+
+
+def route_template(request: Request) -> str:
+    route = request.scope.get("route")
+    template = getattr(route, "path_format", None) or getattr(route, "path", None)
+    return template if template else "other"
+
+
+def status_class(status_code: int) -> str:
+    return f"{status_code // 100}xx" if 100 <= status_code < 600 else "other"
+
+
+def record_http_request(request: Request, status_code: int, duration: float) -> None:
+    if request.url.path == "/metrics":
+        return
+    labels = (normalize_method(request.method), route_template(request), status_class(status_code))
+    HTTP_REQUESTS.labels(*labels).inc()
+    HTTP_DURATION.labels(*labels).observe(duration)
+
+
+def record_rate_limit_rejection() -> None:
+    RATE_LIMIT_REJECTIONS.inc()
+
+
+def record_transpile_request(source: str, target: str, result: str) -> None:
+    TRANSPILE_REQUESTS.labels(source=source, target=target, result=result).inc()
+
+
+def _authorized(request: Request) -> bool:
+    configured = settings.metrics_token
+    expected = configured.get_secret_value().strip() if configured else ""
+    supplied = request.headers.get("X-Metrics-Token", "")
+    return bool(expected and supplied and secrets.compare_digest(supplied, expected))
+
+
+async def metrics_response(request: Request) -> Response:
+    if not settings.metrics_enabled:
+        return Response(status_code=404)
+    if not _authorized(request):
+        return Response(status_code=401, content="Metrics token required")
+    return PlainTextResponse(generate_latest(REGISTRY), media_type=CONTENT_TYPE_LATEST)
+
+
+class MetricsMiddleware:
+    """ASGI middleware that records final HTTP status and elapsed time."""
+
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+        import time
+
+        started = time.perf_counter()
+        status_code = 500
+
+        async def send_wrapper(message):
+            nonlocal status_code
+            if message.get("type") == "http.response.start":
+                status_code = message.get("status", 500)
+            await send(message)
+
+        await self.app(scope, receive, send_wrapper)
+        request = Request(scope)
+        record_http_request(request, status_code, time.perf_counter() - started)

{sql_dialect_master-1.1.7 → sql_dialect_master-1.1.8}/backend/api/middleware.py

@@ -20,6 +20,7 @@ from starlette.concurrency import run_in_threadpool
 from backend.core.exceptions import ErrorCode
 
 from .client_identity import resolve_client_ip
+from .metrics import record_rate_limit_rejection
 from .rate_limit_store import InMemoryRateLimitStore, RateLimitStore, create_rate_limit_store
 from .readiness import health_probe_response
 
@@ -108,7 +109,7 @@ class RateLimitMiddleware(BaseHTTPMiddleware):
 
     async def dispatch(self, request: Request, call_next) -> Response:
         is_health_probe = (
-            request.url.path in {"/health", "/", "/ready", "/health/deep"}
+            request.url.path in {"/health", "/", "/ready", "/health/deep", "/metrics"}
             and request.method in {"GET", "HEAD"}
         )
         # Browser CORS preflight requests carry no business payload and are
@@ -133,6 +134,7 @@ class RateLimitMiddleware(BaseHTTPMiddleware):
             is_allowed, remaining, reset_time = await run_in_threadpool(self.limiter.is_allowed, client_id)
             rate_limit_checked = True
             if not is_allowed:
+                record_rate_limit_rejection()
                 logger.warning("Rate limit exceeded for client: %s", _sanitize_log_value(client_id))
                 return JSONResponse(
                     status_code=429,
@@ -164,6 +166,9 @@ class RateLimitMiddleware(BaseHTTPMiddleware):
         if is_health_probe:
             if request.url.path in {"/ready", "/health/deep"}:
                 return await health_probe_response(request)
+            if request.url.path == "/metrics":
+                from .metrics import metrics_response
+                return await metrics_response(request)
             return await call_next(request)
         response = await call_next(request)
         if rate_limit_checked:
@@ -386,6 +391,8 @@ class CacheControlMiddleware(BaseHTTPMiddleware):
         if request.method == "OPTIONS":
             return None
         path = request.url.path
+        if path == "/metrics":
+            return "no-store"
         if path in {"/docs", "/redoc", "/openapi.json"}:
             return None
         if request.method == "POST" and path.startswith("/api/"):

{sql_dialect_master-1.1.7 → sql_dialect_master-1.1.8}/backend/api/workers.py

@@ -24,22 +24,54 @@ class BoundedWorkerPool:
         self._slots = BoundedSemaphore(workers + queue_size)
         self._executor = ThreadPoolExecutor(max_workers=workers, thread_name_prefix="sdm-api")
         self._shutdown_lock = Lock()
+        self._stats_lock = Lock()
+        self._capacity = workers + queue_size
+        self._in_use = 0
+        self._rejections = 0
+        self._timeouts = 0
         self._shutdown = False
 
     async def run(self, function, *args, timeout: float):
         if not self._slots.acquire(blocking=False):
+            with self._stats_lock:
+                self._rejections += 1
             raise WorkerCapacityError("Request processing capacity is exhausted")
+        with self._stats_lock:
+            self._in_use += 1
         try:
             future = self._executor.submit(function, *args)
         except BaseException:
             self._slots.release()
+            with self._stats_lock:
+                self._in_use -= 1
             raise
-        future.add_done_callback(lambda _future: self._slots.release())
+
+        def release_slot(_future):
+            self._slots.release()
+            with self._stats_lock:
+                self._in_use -= 1
+
+        future.add_done_callback(release_slot)
         wrapped = asyncio.wrap_future(future)
         # A timed-out caller no longer awaits this result. Retrieve exceptions
         # to avoid an unhandled-future warning when background work later fails.
         wrapped.add_done_callback(lambda completed: None if completed.cancelled() else completed.exception())
-        return await asyncio.wait_for(asyncio.shield(wrapped), timeout=timeout)
+        try:
+            return await asyncio.wait_for(asyncio.shield(wrapped), timeout=timeout)
+        except asyncio.TimeoutError:
+            with self._stats_lock:
+                self._timeouts += 1
+            raise
+
+    def stats(self) -> dict[str, int]:
+        """Return a thread-safe snapshot of pool capacity counters."""
+        with self._stats_lock:
+            return {
+                "capacity": self._capacity,
+                "in_use": self._in_use,
+                "rejections": self._rejections,
+                "timeouts": self._timeouts,
+            }
 
     def shutdown(self) -> None:
         """Cancel queued work; already-running calls retain their slots."""

{sql_dialect_master-1.1.7 → sql_dialect_master-1.1.8}/backend/core/config.py

@@ -276,6 +276,10 @@ class AppSettings(BaseSettings):
     # Readiness probes.  SecretStr keeps the value out of settings reprs and
     # structured logs while still allowing deployment through SDM_ env vars.
     health_probe_token: Optional[SecretStr] = None
+
+    # Prometheus metrics are opt-in and use a dedicated secret.
+    metrics_enabled: bool = False
+    metrics_token: Optional[SecretStr] = None
     
     # Security settings
     security_check_enabled: bool = True
@@ -292,6 +296,14 @@ class AppSettings(BaseSettings):
             self.parser_max_sql_length = self.transpiler_max_sql_length
         return self
 
+    @model_validator(mode="after")
+    def _validate_metrics_token(self) -> "AppSettings":
+        """Require a non-blank dedicated token when metrics are enabled."""
+        token = self.metrics_token.get_secret_value().strip() if self.metrics_token else ""
+        if self.metrics_enabled and not token:
+            raise ValueError("metrics_token is required when metrics_enabled is true")
+        return self
+
     @field_validator("log_level", mode="before")
     @classmethod
     def _normalize_log_level(cls, value: str) -> str:

{sql_dialect_master-1.1.7 → sql_dialect_master-1.1.8}/backend/core/metadata.py

@@ -17,8 +17,8 @@ Design rules:
 from __future__ import annotations
 
 # ── Release version facts (sole source of truth) ────────────────────────
-PROJECT_VERSION = "1.1.7"
-API_VERSION = "1.1.7"
+PROJECT_VERSION = "1.1.8"
+API_VERSION = "1.1.8"
 # Frontend v2 architecture — independent of the product release version.
 FRONTEND_ARCHITECTURE_VERSION = 2
 

{sql_dialect_master-1.1.7 → sql_dialect_master-1.1.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sql-dialect-master"
-version = "1.1.7"
+version = "1.1.8"
 description = "SQL Dialect Master - Multi-database SQL conversion engine"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -10,6 +10,7 @@ dependencies = [
     "uvicorn>=0.30.0",
     "pydantic>=2.9.0",
     "pydantic-settings>=2.0.0",
+    "prometheus-client>=0.20.0,<1.0.0",
 ]
 
 [project.optional-dependencies]
@@ -51,3 +52,19 @@ exclude = ["backend.tests*", "backend.benchmarks*"]
 testpaths = ["backend/tests"]
 python_files = ["test_*.py"]
 addopts = "-v --tb=short"
+
+[tool.coverage.run]
+source = ["backend"]
+omit = [
+    "backend/tests/*",
+    "backend/benchmarks/*",
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+fail_under = 93
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.:",
+]

{sql_dialect_master-1.1.7 → sql_dialect_master-1.1.8/sql_dialect_master.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sql-dialect-master
-Version: 1.1.7
+Version: 1.1.8
 Summary: SQL Dialect Master - Multi-database SQL conversion engine
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -10,6 +10,7 @@ Requires-Dist: fastapi>=0.115.0
 Requires-Dist: uvicorn>=0.30.0
 Requires-Dist: pydantic>=2.9.0
 Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: prometheus-client<1.0.0,>=0.20.0
 Provides-Extra: dev
 Requires-Dist: hypothesis>=6.112.0; extra == "dev"
 Requires-Dist: pytest>=8.3.0; extra == "dev"
@@ -35,7 +36,7 @@ Dynamic: license-file
 
 Enterprise-grade multi-database SQL conversion engine supporting 12 database dialects.
 
-Current release: 1.1.7
+Current release: 1.1.8
 
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -372,3 +373,4 @@ public catalog responses use short `private` caching. Full deployment details
 will be documented in `docs/deployment.md`.
 
 See [`docs/deployment.md`](docs/deployment.md) for production deployment guidance.
+Metrics configuration and scraping guidance are documented in the same guide.

{sql_dialect_master-1.1.7 → sql_dialect_master-1.1.8}/sql_dialect_master.egg-info/SOURCES.txt

@@ -6,6 +6,7 @@ backend/api/__init__.py
 backend/api/auth.py
 backend/api/client_identity.py
 backend/api/main.py
+backend/api/metrics.py
 backend/api/middleware.py
 backend/api/rate_limit_store.py
 backend/api/readiness.py

{sql_dialect_master-1.1.7 → sql_dialect_master-1.1.8}/sql_dialect_master.egg-info/requires.txt

@@ -3,6 +3,7 @@ fastapi>=0.115.0
 uvicorn>=0.30.0
 pydantic>=2.9.0
 pydantic-settings>=2.0.0
+prometheus-client<1.0.0,>=0.20.0
 
 [dev]
 hypothesis>=6.112.0