Fix db_time undercount diagnostics

[vladiant]

Summary

This merge request improves request-level DB diagnostics to address db_time undercount visibility gaps and updates operational documentation for remote deployment and latency expectations.

Problem

In some request traces, endpoint-level DB work appeared higher than db_time_ms, making it hard to distinguish:

• actual SQL execution time,
• connection acquisition time,
• and remaining request overhead.

This MR introduces explicit timing decomposition so production logs can explain latency more reliably.

What Changed

1. DB Timing Decomposition

Added request-scoped DB timing helpers and propagated them across key read paths.

• New file: app/observability/db_timing.py

  • Timed wrappers for common DB operations (get, execute+fetch, scalar reads).
  • Captures:
    • db_acquire_ms
    • db_execute_fetch_ms

• Updated context model: app/observability/context.py

  • Added fields to hold the new timing components per request.

• Updated middleware logging: app/observability/middleware.py

  • Emits:
    • db_acquire_ms
    • db_execute_fetch_ms
    • db_time_gap_ms (diagnostic delta between DB components and existing DB timer)
  • Keeps request logging/metrics behavior aligned with existing observability structure.

2. Applied Timing Wrappers to Endpoints/Services

Integrated new timing helpers into API/service DB paths:

• app/api/products.py
• app/api/categories.py
• app/services/product_service.py
• app/services/category_service.py

This improves consistency between measured DB phases and endpoint latency diagnostics.

3. Documentation Improvements

Expanded README guidance and operational runbook content:

• README.md
  • Implemented improvements summary.
  • Remote service/runtime configuration guidance.
  • Added section describing scenarios where 200ms end-to-end may not always be met and how to interpret/mitigate those cases.

Files Changed

• README.md
• app/api/categories.py
• app/api/products.py
• app/observability/context.py
• app/observability/db_timing.py (new)
• app/observability/middleware.py
• app/services/category_service.py
• app/services/product_service.py

Validation

• Existing automated tests pass after changes.
• New observability fields are now available in request logs for deeper latency analysis:
  • db_acquire_ms
  • db_execute_fetch_ms
  • db_time_gap_ms

Expected Impact

• Better attribution of request latency to DB acquisition vs execute/fetch phases.
• Faster root-cause analysis for remote latency outliers.
• Clearer operational expectations documented for environments where strict 200ms is not always achievable.