feat(testing): add contract marker, strict cardinality caps, and OTel GenAI aliases

[AdityaShome]

Summary

This PR is a direct extension of the initial Prometheus integration in #1633. It builds on that exporter foundation by adding schema version signaling, stricter cardinality safety controls, and OTel-aligned dual-publish aliases, without changing the existing mofa_llm_* contract.

This PR delivers three production-focused observability upgrades for Prometheus metrics in MoFA:

1. Metrics contract marker for schema stability
2. Strict cardinality safety caps for predictable Prometheus performance
3. OTel GenAI-aligned metric aliases (dual-publish, non-breaking)

All changes are implemented in:

• prometheus.rs

What Changed

1) Metrics contract stabilization marker

• Added exported contract info metric:
  • mofa_metrics_contract_info{version="v1alpha1"} 1
• This provides a machine-readable schema/version marker for dashboards, alerts, and downstream tooling.
• Added test assertion to verify marker presence in exporter output.

2) Strict label/cardinality controls

• Added hard per-dimension safety cap:
  • MAX_CARDINALITY_LIMIT_PER_DIMENSION = 1000
• Updated cardinality sanitization to clamp unsafe limits:
  • 0 -> 1 (existing behavior preserved)
  • > 1000 -> 1000 (new guard)
• Added test coverage ensuring all cardinality dimensions are clamped to safety max.

3) OTel GenAI metric alignment (non-breaking dual-publish)

• Added OTel-style aliases while keeping existing mofa_llm_* metrics intact:
  • gen_ai_client_operation_duration_seconds (histogram alias)
  • gen_ai_client_token_usage_total (counter alias, with token_type=input|output)
• This enables interoperability with standard observability stacks without breaking existing queries/dashboards.
• Added tests validating alias export lines.

Execution Flow:

flowchart TD
    A["Metrics snapshot"] --> B["Exporter render pipeline"]
    B --> C["Emit contract marker"]
    C --> C1["Contract info version v1alpha1"]

    B --> D["Apply cardinality sanitization"]
    D --> D1["Clamp lower bound to 1"]
    D --> D2["Clamp upper bound to 1000"]
    D1 --> E["Render bounded series"]
    D2 --> E

    E --> F["Render existing mofa llm metrics"]
    F --> F1["Input tokens total"]
    F --> F2["Output tokens total"]
    F --> F3["Request duration histogram"]

    E --> G["Dual publish OTel aliases"]
    G --> G1["Token usage total with token_type"]
    G --> G2["Operation duration histogram"]

    F --> H["Final metrics payload"]
    G --> H
    C1 --> H
    H --> I["Prometheus scrape and dashboards"]

Loading

Backward Compatibility

• Existing mofa_llm_* metrics are unchanged.
• OTel-aligned metrics are additive aliases (dual-publish approach).

Validation

• Ran targeted Prometheus exporter tests:
  • cargo test -p mofa-monitoring dashboard::prometheus::tests:: -- --nocapture
• Result: all targeted tests passed.

Why this matters

• Contract marker improves schema governance and change safety.
• Cardinality caps reduce risk of TSDB memory/query blowups from unsafe config.
• OTel aliasing improves ecosystem compatibility and eases future standardization.