shared_metrics_drift.py 3.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263
  1. """Rows an earlier build or catalog stored whose values the current contract no longer lists.
  2. Packaging re-checks every pending row against the current contract, so a value that left a closed
  3. set after it was recorded (a catalog entry removed, a built-in tool moved to a plugin) is conformed
  4. here instead of aborting the whole period's package (#133017).
  5. """
  6. from __future__ import annotations
  7. from typing import Any
  8. from .shared_metrics_contract import (
  9. _COUNTER_DIMENSION_VALUES,
  10. _IDENTIFIER_FIELDS,
  11. _LEGACY_METRIC_FIELDS,
  12. _METRIC_FIELDS,
  13. _metric_identifier,
  14. )
  15. def counter_dimensions_shape_is_known(metric_name: str, dimensions: dict[str, Any]) -> bool:
  16. """Whether the row's field set matches a current or legacy contract shape (values aside).
  17. A row that fails this is structurally unknown — that is tamper evidence, not drift, and
  18. packaging keeps failing closed on it (see test_package_builder_rejects_tampered_dimensions).
  19. """
  20. fields = frozenset(dimensions)
  21. return fields == _METRIC_FIELDS.get(metric_name) or fields in _LEGACY_METRIC_FIELDS.get(metric_name, ())
  22. def conform_counter_dimensions(metric_name: str, dimensions: dict[str, Any]) -> dict[str, Any] | None:
  23. """Re-bucket out-of-contract enum values into the field's closed fallback, else ``None``.
  24. Catalog-backed enums are repo data: a value that was a catalog entry when the row was
  25. recorded (and passed record-time validation) can legitimately fall out of the catalog by
  26. packaging time — the recording and packaging processes snapshot it independently (#133017).
  27. Exporting the stale value would leak exactly the out-of-enum payload the closed enum exists
  28. to prevent, so it is bucketed to ``custom``/``other``/``unknown`` (the first the field's enum
  29. defines), mirroring what the record-side normalizers do for names that were never in the
  30. catalog. Code constants drift too: a built-in tool moved to a plugin (Spotify, Home Assistant)
  31. or a removed reason value leaves rows an earlier build stored.
  32. Returns ``None`` when a value cannot be safely re-bucketed: fields whose enum defines no
  33. fallback bucket, non-string values, or identifier fields that no longer round-trip through
  34. ``_metric_identifier`` (record-time validation already guarantees they did once).
  35. """
  36. conformed = dict(dimensions)
  37. identifiers = _IDENTIFIER_FIELDS.get(metric_name, {})
  38. contract = _COUNTER_DIMENSION_VALUES[metric_name]
  39. for field, value in conformed.items():
  40. if not isinstance(value, str):
  41. return None
  42. if field in identifiers:
  43. if value != _metric_identifier(value, max_length=identifiers[field]):
  44. return None
  45. continue
  46. allowed = contract[field]
  47. if value in allowed:
  48. continue
  49. fallback = next((bucket for bucket in ("custom", "other", "unknown") if bucket in allowed), None)
  50. if fallback is None:
  51. return None
  52. conformed[field] = fallback
  53. return conformed