events

events ¶

Canonical registry of external analytics events.

Single source of truth for every event name and property the OpenJarvis analytics module is allowed to send. Any event not declared here is dropped at send time. Any property not declared on a known event is also dropped. This is the fail-closed half of the PII guardrail — see :mod:openjarvis.analytics.redaction for the value-level filters.

Keeping the catalog in code (not config) means PR review is the gate for adding a new event, and docs/telemetry.md can render from this module as the source of truth.

Classes¶

EventSpec `dataclass` ¶

EventSpec(name: str, description: str, properties: dict[str, PropertyValidator])

Declaration for one analytics event.

Functions¶

validate_event ¶

validate_event(name: str, properties: dict[str, Any]) -> dict[str, Any] | None

Return cleaned properties or None if the event name is unknown.

Unknown properties are silently dropped. Properties whose values fail the spec's validator are silently dropped. Empty result is valid (the event itself is still recorded).

Source code in src/openjarvis/analytics/events.py

def validate_event(name: str, properties: dict[str, Any]) -> dict[str, Any] | None:
    """Return cleaned properties or ``None`` if the event name is unknown.

    Unknown properties are silently dropped. Properties whose values
    fail the spec's validator are silently dropped. Empty result is
    valid (the event itself is still recorded).
    """
    spec = REGISTRY.get(name)
    if spec is None:
        return None
    cleaned: dict[str, Any] = {}
    for key, value in properties.items():
        validator = spec.properties.get(key)
        if validator is None:
            continue
        if not validator(value):
            continue
        cleaned[key] = value
    return cleaned

known_event_names ¶

known_event_names() -> tuple[str, ...]

All event names declared in the catalog (for docs and tests).