docs(ocr): annotate metrics binding + /metrics exposure + pin client

Three small drops that pay back later:
- Note that main.metrics is import-time bound and tests must
  monkeypatch `main.metrics`, not the registry.
- Flag the /metrics endpoint as unauthenticated and cross-link the
  Caddy-block snippet in docs/OBSERVABILITY.md.
- Pin prometheus-client to the exact 0.25.0 patch version already
  resolved by prometheus-fastapi-instrumentator 7.0.0, so an upstream
  bump cannot silently slip in.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

ocr-service/main.py

@@ -43,6 +43,10 @@ logger = logging.getLogger(__name__)
 
 _models_ready = False
 
+# One-shot import-time binding to the default REGISTRY. Tests that need a
+# clean counter state must monkeypatch `main.metrics` with a container built
+# from a fresh CollectorRegistry — rebinding through the registry directly
+# will not retarget the references stored in the OcrMetrics dataclass.
 metrics: OcrMetrics = build_metrics(REGISTRY)
 
 ALLOWED_PDF_HOSTS = set(
@@ -117,6 +121,9 @@ async def lifespan(app: FastAPI):
 
 app = FastAPI(title="Familienarchiv OCR Service", lifespan=lifespan)
 
+# /metrics is unauthenticated — relies on Docker-internal-network exposure
+# only (CWE-200 risk if `ports:` ever maps 8000 to host). See
+# docs/OBSERVABILITY.md §Internal-only endpoints for the Caddy block snippet.
 Instrumentator(excluded_handlers=["/health", "/metrics"]).instrument(app).expose(app)
 
 

ocr-service/requirements.txt

@@ -11,3 +11,4 @@ httpx==0.28.1
 pyspellchecker==0.9.0
 opencv-python-headless==4.11.0.86
 prometheus-fastapi-instrumentator==7.0.0
+prometheus-client==0.25.0