oct.mcp.metrics module

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 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.

• 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.

class oct.mcp.metrics.McpMetrics(registry: CollectorRegistry | None = None)

Bases: object

Prometheus instrumentation for the oct-mcp pipeline.

All record methods are no-ops when prometheus_client is absent. Instantiate once per server session and pass into ServerState.

record_call(tool: str, decision: str, duration_s: float, redactions: int) → None

Record a completed (or denied) tool call.

Parameters:

• tool – MCP tool name, e.g. "oct_lint".

• decision – Pipeline decision: "allowed", "denied", or "requires_confirmation".

• duration_s – Wall-clock duration in seconds.

• redactions – Number of redaction substitutions applied to the output.

record_rate_limit_hit(tool: str) → None

Increment the rate-limit rejection counter for tool.

record_validation_failure(tool: str) → None

Increment the validation-failure counter for tool.

start_server(port: int) → None

Start the Prometheus /metrics HTTP server on port.

Runs in a daemon background thread so it does not block the MCP event loop. Silently no-ops when prometheus_client is absent.

Parameters:

port – TCP port to bind. Must be in the range 1–65535.