:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
"""Tell the team when a model starts failing its checks.
Only the pass-to-fail edge notifies, and only for error-severity checks. A check that keeps failing
run after run is already known about; re-notifying every run is how an inbox gets ignored.
"""
from collections.abc import Sequence
from urllib.parse import quote
from uuid import UUID
import structlog
from posthog.hogql.database.database import unentitled_system_tables
from posthog.models import Team, User
from products.access_control.backend.facade.user_access_control import UserAccessControl
from products.data_modeling.backend.facade import api as data_modeling_facade
from products.notifications.backend.facade.api import (
NotificationData,
NotificationType,
Priority,
RecipientsResolver,
TargetType,
create_notification,
)
from products.warehouse_sources.backend.facade import api as warehouse_facade
from ..facade.enums import CheckRunStatus, SubjectType
from ..models import DataQualityCheck, DataQualityCheckRun, DataQualitySuiteRun
from . import posthog_tables
from .checks import checks_for_subject
from .subject_access import (
NoticeReferences,
ReferenceGate,
can_be_object_denied,
notice_references,
reference_gate,
referenced_subject_names,
referencing_check_types,
)
from .subjects import resolve_subject
LOGGER = structlog.get_logger(__name__)
_OBJECT_GATED_SUBJECT_TYPES = frozenset({SubjectType.TABLE, SubjectType.VIEW})
class _WarehouseSubjectResolver(RecipientsResolver):
"""Drop members who must not receive this check's warehouse metadata or its failing-row count.
Three gates on top of the built-in resource-level `warehouse_objects` filter that
`create_notification` runs:
- **Object-level** access to *this* table or view. The resource-level filter only asks whether a
member can see warehouse objects at all, so a member with general warehouse access but an
explicit denial on the subject would still receive its name, column, check type, and count.
- **Referenced-subject** access. A `relationships` check reads a second subject and a `custom_sql`
check reads arbitrary tables, so a failure count is an oracle over those too. A member denied
any of the names passed in must be dropped, matching how the run-history API gates them.
- **Query** viewer access. The body's `failed_row_count` is a count oracle over the underlying
warehouse rows that the run-history API gates behind query access, so a member denied `query`
must not read it from the notification either.
"""
def __init__(
self,
team: Team,
subject_type: str,
subject_uuid: str,
referenced_names: list[str] | None = None,
executed_references: Sequence[dict[str, str]] = (),
references_unknown: bool = False,
access_cache: dict[int, UserAccessControl] | None = None,
) -> None:
self._team = team
self._subject_type = subject_type
self._subject_uuid = subject_uuid
self._referenced_names = referenced_names or []
self._executed_references = executed_references
self._references_unknown = references_unknown
# One access-control object per member, reused across both gates below (and the warehouse
# database build the referenced-subject gate runs) so a single failing check doesn't rebuild
# it -- and its membership, role, and access-control lookups -- once per pass.
self._access: dict[int, UserAccessControl] = access_cache if access_cache is not None else {}
self._references: NoticeReferences | None = None
self._unentitled: frozenset[str] | None = None
def _access_of(self, user: User) -> UserAccessControl:
access = self._access.get(user.id)
if access is None:
access = UserAccessControl(user, self._team)
self._access[user.id] = access
return access
def _access_controls_supported(self, user_ids: list[int]) -> bool:
# When access controls aren't available for the org, the built-in filter lets everyone
# through and neither gate below can deny anyone; the callers skip their per-member work.
sample = User.objects.filter(id__in=user_ids).first()
return sample is not None and self._access_of(sample).access_controls_supported
def resolve(self, target_type: TargetType, target_id: str, team_id: int | None) -> list[int]:
user_ids = super().resolve(target_type, target_id, team_id)
return self._filter_by_subject_access(user_ids)
def _filter_by_subject_access(self, user_ids: list[int]) -> list[int]:
# Both gates below are per-member, so they share one member query, one access-control object
# and one denial snapshot each rather than a pass apiece.
if not self._access_controls_supported(user_ids):
return user_ids
return [user.id for user in User.objects.filter(id__in=user_ids) if self._may_receive(user)]
def _object_gate_applies(self) -> bool:
return SubjectType(self._subject_type) in _OBJECT_GATED_SUBJECT_TYPES
def _reference_gate_applies(self) -> bool:
# The declared subject isn't the only one the count depends on: a relationships check reads
# its target and a custom_sql check reads arbitrary tables.
return bool(self._referenced_names) or bool(self._executed_references) or self._references_unknown
def _may_receive(self, user: User) -> bool:
access = self._access_of(user)
if not access.check_access_level_for_resource("query", "viewer"):
return False
if self._subject_type == SubjectType.METRIC and not access.check_access_level_for_resource(
"data_catalog", "viewer"
):
return False
if self._subject_type == SubjectType.POSTHOG_TABLE and not access.check_access_level_for_resource(
posthog_tables.RESOURCE, "viewer"
):
return False
if self._object_gate_applies() and not self._has_object_access(access):
return False
if not self._reference_gate_applies():
return True
if self._references_unknown and can_be_object_denied(access):
return False
return self._gate_of(user).admits(self._notice_references())
def _has_object_access(self, access: UserAccessControl) -> bool:
object_id = UUID(self._subject_uuid)
allowed_ids = (
warehouse_facade.allowed_table_ids(self._team.id, access, ids=[object_id])
if self._subject_type == SubjectType.TABLE
else data_modeling_facade.allowed_saved_query_ids(self._team.id, access, ids=[object_id])
)
return object_id in allowed_ids
def _notice_references(self) -> NoticeReferences:
if self._references is None:
self._references = notice_references(
self._team.id, executed_references=self._executed_references, names=self._referenced_names
)
return self._references
def _gate_of(self, user: User) -> ReferenceGate:
if self._unentitled is None:
self._unentitled = unentitled_system_tables(self._team)
return reference_gate(
self._team,
user,
self._access_of(user),
references=self._notice_references(),
unentitled=self._unentitled,
)
def _source_url(team_id: int, subject_type: str, subject_name: str) -> str:
if subject_type == SubjectType.METRIC:
return f"/project/{team_id}/data-catalog/metrics/{quote(subject_name, safe='')}?tab=data-quality"
if subject_type == SubjectType.POSTHOG_TABLE:
return f"/project/{team_id}/models?tab=data-quality"
return ""
def notify_check_started_failing(
check: DataQualityCheck,
failed_row_count: int | None,
*,
executed_references: Sequence[dict[str, str]] | None = (),
idempotency_key: str | None = None,
access_cache: dict[int, UserAccessControl] | None = None,
) -> int:
"""How many members were told. Best-effort: a failure here must never fail the run behind it."""
try:
if check.subject_uuid is None:
return 0
team = Team.objects.get(id=check.team_id)
subject = resolve_subject(team.id, check.subject_type, check.subject_uuid)
if not subject.exists:
return 0
is_metric = check.subject_type == SubjectType.METRIC
is_posthog_table = check.subject_type == SubjectType.POSTHOG_TABLE
subject_name = subject.name if is_metric or is_posthog_table else check.subject_name
event = create_notification(
NotificationData(
team_id=check.team_id,
notification_type=NotificationType.DATA_QUALITY_CHECK_FAILURE,
priority=Priority.NORMAL,
title=f"Data quality check failed on {subject_name}",
body=_body(check, failed_row_count),
target_type=TargetType.TEAM,
target_id=str(check.team_id),
# The body names a warehouse table or view and one of its columns, so it points at
# the subject object (not the check) and the resolver filters recipients down to
# members with object-level access to it, plus query access for the count.
resource_type="data_catalog" if is_metric else "warehouse_objects",
resource_id=str(check.subject_uuid),
source_url=_source_url(team.id, check.subject_type, subject_name),
idempotency_key=idempotency_key,
resolver=_WarehouseSubjectResolver(
team,
check.subject_type,
str(check.subject_uuid),
referenced_names=referenced_subject_names(team.id, check.check_type, check.config, subject=subject),
executed_references=executed_references or (),
references_unknown=executed_references is None,
access_cache=access_cache,
),
)
)
return len(event.resolved_user_ids) if event is not None else 0
except Exception:
LOGGER.exception("Could not send a data quality failure notification", check_id=str(check.id))
return 0
def notify_materialization_blocked(
team_id: int, saved_query_id: str, view_name: str, blocking_failures: int, job_id: str
) -> None:
"""Tell the team a refresh was not published because its checks failed. Best-effort."""
try:
team = Team.objects.get(id=team_id)
checks = "check" if blocking_failures == 1 else "checks"
create_notification(
NotificationData(
team_id=team_id,
notification_type=NotificationType.DATA_QUALITY_CHECK_FAILURE,
priority=Priority.NORMAL,
title=f"Materialization of {view_name} was not published",
body=f"{blocking_failures} data quality {checks} failed, so the previous version keeps "
"serving. Fix the data or the checks, then materialize again.",
target_type=TargetType.TEAM,
target_id=str(team_id),
resource_type="warehouse_objects",
resource_id=saved_query_id,
# Keyed on the blocked materialization job: the block activity can run twice when a
# slow attempt hits its start-to-close timeout, and the unique constraint behind this
# key collapses the retry to one notice while a genuinely new block notifies again.
idempotency_key=f"matview-blocked-{job_id}",
resolver=_WarehouseSubjectResolver(
team,
SubjectType.VIEW,
saved_query_id,
referenced_names=_blocking_referenced_names(team_id, saved_query_id, job_id),
),
)
)
except Exception:
LOGGER.exception("Could not send a materialization-blocked notification", saved_query_id=saved_query_id)
def _blocking_referenced_names(team_id: int, saved_query_id: str, job_id: str) -> list[str]:
"""Every further subject the checks behind a blocked materialization read.
The body's failure count aggregates those checks, so it is an oracle over everything they read,
not just over the view the recipient is already allowed to see.
Read off the suite's persisted check runs, not the definitions' current state. ``enabled``,
``severity``, ``last_status`` and ``deleted`` are all writable by anyone who can edit the view --
including a member denied a subject the check reads, since the write path only authorizes the
declared subject. Selecting on them would let that member edit their own denial out of this
filter in the window between the suite finishing and this notice being written, while the count
still counts their check. A run row is immutable, so it cannot be edited out of the set it
belongs to. The suite is the one the blocked job triggered, so the names and the count come from
the same batch, across every subject the batch covered.
"""
names: set[str] = set()
runs = (
DataQualityCheckRun.objects.for_team(team_id)
.filter(
suite_run__data_modeling_job_id=job_id,
status=CheckRunStatus.FAILED,
# No severity on the run row, so this takes warn-severity failures too. They did not
# block, so the set is wider than the count -- which over-filters rather than leaks.
check_type__in=referencing_check_types(),
)
.select_related("quality_check")
)
# A run records which check ran, never the config it ran with. A definition that has since been
# hard-deleted or re-pointed at other tables leaves nothing to enumerate, and so does a suite
# retention already swept. Widen to every referencing check on the subject: wider than this
# block, but it can only drop more recipients, never admit one the count would leak to.
unbindable = not DataQualitySuiteRun.objects.for_team(team_id).filter(data_modeling_job_id=job_id).exists()
for run in runs:
check = run.quality_check
if check is None or check.fingerprint != run.check_fingerprint:
unbindable = True
continue
names.update(referenced_subject_names(team_id, check.check_type, check.config))
if unbindable:
for check in checks_for_subject(team_id, SubjectType.VIEW, saved_query_id, include_deleted=True).filter(
check_type__in=referencing_check_types()
):
names.update(referenced_subject_names(team_id, check.check_type, check.config))
return sorted(names)
def _body(check: DataQualityCheck, failed_row_count: int | None) -> str:
subject = f"{check.check_type} check"
if check.column_name:
subject = f"{check.check_type} check on {check.subject_name}.{check.column_name}"
if failed_row_count:
rows = "row" if failed_row_count == 1 else "rows"
return f"The {subject} found {failed_row_count} failing {rows}. It was passing on the previous run."
return f"The {subject} started failing. It was passing on the previous run."