Skip to content

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

5.1 KB
Raw Blame
import re
import uuid
from dataclasses import dataclass
from datetime import UTC, datetime
from typing import Optional

import structlog
from rest_framework_dataclasses.serializers import DataclassSerializer

from posthog.kafka_client.client import ProduceResult
from posthog.kafka_client.routing import get_producer
from posthog.kafka_client.topics import KAFKA_CDP_INTERNAL_EVENTS

logger = structlog.get_logger(__name__)

# Single source of truth for the managed-alert event boundary. Also used as a Postgres regex
# filter (products/cdp hog_function queryset) and mirrored in the Node CDP consumer, so keep it
# POSIX-compatible (no (?:...) groups).
MANAGED_ALERT_EVENT_PATTERN = (
    r"^\$[a-z0-9_]+_alert_(firing|resolved|errored|auto_disabled|match|incident_opened|incident_closed)$"
)
LEGACY_INSIGHT_ALERT_EVENT = "$insight_alert_firing"
_MANAGED_ALERT_EVENT = re.compile(MANAGED_ALERT_EVENT_PATTERN)


WORKFLOW_STEP_RESUME_EVENT = "$workflow_step_resume"

# Internal events that only the product which emits them may consume. A user-created
# destination cannot subscribe to one, because its properties carry that product's data and
# forwarding them off-platform would bypass the read permission the product enforces on it.
RESERVED_INTERNAL_EVENTS = frozenset({WORKFLOW_STEP_RESUME_EVENT})


def is_reserved_internal_event(event_name: object) -> bool:
    """Return whether an internal event is closed to user-created destinations."""
    return isinstance(event_name, str) and event_name in RESERVED_INTERNAL_EVENTS


def is_managed_alert_internal_event(event_name: object) -> bool:
    """Return whether an internal event is reserved for an alert-owned destination."""
    return (
        isinstance(event_name, str)
        and event_name != LEGACY_INSIGHT_ALERT_EVENT
        and _MANAGED_ALERT_EVENT.fullmatch(event_name) is not None
    )


# Alert products whose destinations stay editable through the generic hog functions API, keyed by
# the prefix of their alert events and valued by the API scope object their own alert API checks.
# An edit through the generic API requires that product's write scope and editor access on top of
# the hog function ones, so a token or member that cannot touch the alert cannot touch its
# destination either. The other alert products stay read-only there.
GENERIC_API_EDITABLE_ALERT_EVENT_SCOPES: dict[str, str] = {"$logs_alert_": "logs"}


def generic_api_editable_alert_scope(event_name: object) -> str | None:
    """Return the scope object that guards generic-API edits of a managed alert event's destinations."""
    if not is_managed_alert_internal_event(event_name):
        return None
    return next(
        (
            scope
            for prefix, scope in GENERIC_API_EDITABLE_ALERT_EVENT_SCOPES.items()
            if str(event_name).startswith(prefix)
        ),
        None,
    )


@dataclass
class InternalEventEvent:
    event: str
    distinct_id: str
    properties: dict
    timestamp: Optional[str] = None
    url: Optional[str] = None
    uuid: Optional[str] = None


@dataclass
class InternalEventPerson:
    id: str
    properties: dict
    name: Optional[str] = None
    url: Optional[str] = None


@dataclass
class InternalEvent:
    team_id: int
    event: InternalEventEvent
    person: Optional[InternalEventPerson] = None


class InternalEventSerializer(DataclassSerializer):
    class Meta:
        dataclass = InternalEvent


def internal_event_to_dict(data: InternalEvent) -> dict:
    return InternalEventSerializer(data).data


def create_internal_event(
    team_id: int, event: InternalEventEvent, person: Optional[InternalEventPerson] = None
) -> InternalEvent:
    data = InternalEvent(team_id=team_id, event=event, person=person)

    if data.event.uuid is None:
        data.event.uuid = str(uuid.uuid4())
    if data.event.timestamp is None:
        data.event.timestamp = datetime.now(UTC).isoformat()

    return data


def produce_internal_event(
    team_id: int, event: InternalEventEvent, person: Optional[InternalEventPerson] = None
) -> ProduceResult:
    data = create_internal_event(team_id, event, person)
    serialized_data = internal_event_to_dict(data)
    kafka_topic = KAFKA_CDP_INTERNAL_EVENTS

    try:
        producer = get_producer(topic=kafka_topic)
        return producer.produce(topic=kafka_topic, data=serialized_data, key=data.event.uuid)
    except Exception as e:
        # Identify the event by ids, not payload: properties can carry credentials
        # (e.g. tokenized delivery URLs) and person data, which must not reach logs.
        logger.exception(
            "Failed to produce internal event",
            team_id=team_id,
            event_name=data.event.event,
            event_uuid=data.event.uuid,
            error=e,
        )
        raise


def flush_internal_events_producer(timeout: float) -> int:
    """Block until previously produced internal events are delivered (or `timeout`
    elapses), returning the number still undelivered. A zero only means all
    delivery callbacks have fired, not that they all succeeded — check each
    `ProduceResult` for per-message outcomes."""
    return get_producer(topic=KAFKA_CDP_INTERNAL_EVENTS).flush(timeout)