Purpose
-------
Optional Prometheus instrumentation for the ``oct-mcp`` server (Phase 5C).
Exposes five metrics:
* ``oct_mcp_tool_calls_total`` — Counter; labels ``tool``, ``decision``.
* ``oct_mcp_tool_duration_seconds`` — Histogram; label ``tool``.
* ``oct_mcp_rate_limit_hits_total`` — Counter; label ``tool``.
* ``oct_mcp_redactions_total`` — Counter; label ``tool``.
* ``oct_mcp_validation_failures_total`` — Counter; label ``tool``.
All public methods are **no-ops** when ``prometheus_client`` is not
installed, so the rest of the pipeline never needs to guard with
``if metrics is not None``.
Enabling metrics
----------------
Install the optional extra::
pip install 'oct[metrics]'
Then start the server with ``--metrics-port``::
python -m oct.mcp --project-root /path/to/project --metrics-port 9090
Diagnostics
-----------
Domain: MCP
Levels:
L1 — errors: metrics server startup failures
L2 — lifecycle: metrics server started
Contracts
---------
- This module never raises for the caller — all methods swallow errors
and degrade gracefully.
- When ``prometheus_client`` is absent, ``PROMETHEUS_AVAILABLE`` is
``False`` and :class:`McpMetrics` is a lightweight no-op stub.
- The metrics HTTP server is started in a **daemon** background thread
so it does not prevent process exit.
- :class:`McpMetrics` accepts an optional ``registry`` parameter
(``CollectorRegistry``). The default is the module-level
``prometheus_client.REGISTRY`` so production ``/metrics`` works
without any caller change. Tests and multi-tenant callers pass a
private ``CollectorRegistry()`` to avoid ``Duplicated timeseries``
collisions across instances.
1.15.0