Skip to main content

CRM Identity Metrics

Track A settlement admission now emits explicit Prometheus counters for CRM identity resolution and alias lifecycle.

Metrics​

pos_identity_resolution_total{outcome}​

Resolver-seam counter emitted by SettlementIdentityResolver.resolveIdentifiers().

Outcomes:

  • dual_id_validated: request carried both identifiers and passed the trusted-alias conflict gate (this can include cases where no trusted alias existed yet)
  • dual_id_conflict: request carried both identifiers and conflicted with trusted alias evidence
  • quote_only_enriched: quote-only request was enriched from an active trusted alias
  • quote_only_unenriched: quote-only request remained exact-only because no trusted alias existed
  • reservation_only_enriched: reservation-only request was enriched from an active trusted alias
  • reservation_only_unenriched: reservation-only request remained exact-only because no trusted alias existed

pos_settlement_alias_total{event}​

Alias lifecycle counter emitted at the settlement alias repository boundary.

Events:

  • upserted: a durable dual-ID outcome created or refreshed a trusted alias (atomic upsert — create vs update is not distinguished because Prisma upsert cannot reliably report which path ran)
  • invalidated: an active trusted alias was invalidated

Dashboard​

Grafana dashboard:

  • POS / CRM Identity
  • uid: pos-crm-identity

Use it to answer:

  • Are one-sided admissions actually happening in production?
  • Are they mostly quote_only_unenriched or reservation_only_unenriched?
  • Is trusted alias upsert activity keeping pace, or are unresolved admissions accumulating?
  • Are dual-ID conflicts appearing, indicating upstream data drift or alias issues?

Reconciliation report evidence​

GET /api/admin/pos/reconciliation/report includes an unresolvedCrmIdentity section for operator inspection of unresolved one-sided legacy CRM settlements. It is built from persisted settlement_requests rows where exactly one of quoteId or reservationId is present, no canonicalBookingId was supplied, and no active trusted SettlementAlias currently resolves the observed identifier.

That section is observational only. It is not used by settlement admission, replay normalization, or alias promotion. SettlementAlias remains the only trusted quote-to-reservation authority.

Alert thresholds​

Prometheus alert rules:

  • PosOneSidedCrmAdmissionsWarning
    • threshold: more than 5 unresolved one-sided admissions in 30m
  • PosOneSidedCrmAdmissionsCritical
    • threshold: more than 20 unresolved one-sided admissions in 30m

These thresholds are intentionally tied to unresolved one-sided admissions:

sum(increase(pos_identity_resolution_total{outcome=~"quote_only_unenriched|reservation_only_unenriched"}[30m]))

Interpretation​

  • Near-zero unresolved one-sided volume means the double-debit window is mostly theoretical.
  • Sustained unresolved one-sided volume means the exact-only admission window is materially present in production.
  • If the warning or critical alert fires repeatedly, accelerate canonical booking identity work in #14050.

Scrape contract​

  • metrics endpoint: GET /api/admin/pos/metrics
  • endpoint auth: PartnerAdminKeyGuard
  • emitted by: prom-client global registry
  • scraped via: ServiceMonitor on the pos-partner-api service using the required POS_PARTNER_ADMIN_KEY from pos-partner-api-secret