Module glean.metrics.event

Classes

class EventExtras

Expand source code

class EventExtras:
    """
    A class that can be converted into key-value pairs of event extras.
    This will be automatically implemented for event properties of an [EventMetricType].
    """

    def to_ffi_extra(self) -> Dict[str, str]:
        """
        Convert the event extras into a key-value dict:
        """
        return {}

A class that can be converted into key-value pairs of event extras. This will be automatically implemented for event properties of an [EventMetricType].

Methods

def to_ffi_extra(self) ‑> Dict[str, str]

Expand source code

def to_ffi_extra(self) -> Dict[str, str]:
    """
    Convert the event extras into a key-value dict:
    """
    return {}

Convert the event extras into a key-value dict:

class EventMetricType (common_metric_data: glean._uniffi.glean.CommonMetricData,
allowed_extra_keys: List[str])

Expand source code

class EventMetricType:
    """
    This implements the developer facing API for recording events.

    Instances of this class type are automatically generated by
    `glean.load_metrics`, allowing developers to record values that were
    previously registered in the metrics.yaml file.

    The event API only exposes the `EventMetricType.record` method, which
    takes care of validating the input data and making sure that limits are
    enforced.
    """

    def __init__(
        self,
        common_metric_data: CommonMetricData,
        allowed_extra_keys: List[str],
    ):
        self._inner = EventMetric(common_metric_data, allowed_extra_keys)

    def record(self, extra: Optional[EventExtras] = None) -> None:
        """
        Record an event by using the information provided by the instance of
        this class.

        Args:
            extra: optional. The extra keys and values for this event.
                   The maximum length for values is 100.
        """

        if isinstance(extra, EventExtras):
            inner_extra = extra.to_ffi_extra()
        else:
            inner_extra = {}

        self._inner.record(inner_extra)

    def test_get_value(self, ping_name: Optional[str] = None) -> Optional[List[RecordedEvent]]:
        """
        Returns the stored value for testing purposes only.

        Args:
            ping_name (str): (default: first value in send_in_pings) The name
                of the ping to retrieve the metric for.

        Returns:
            value (list of RecordedEventData): value of the stored events.
        """
        # Translate NO extras into an empty dictionary,
        # to simplify handling.
        recordings = self._inner.test_get_value(ping_name)
        if recordings:
            for recording in recordings:
                if recording.extra is None:
                    recording.extra = {}

        return recordings

    def test_get_num_recorded_errors(self, error_type: ErrorType) -> int:
        """
        Returns the number of errors recorded for the given metric.

        Args:
            error_type (ErrorType): The type of error recorded.
            ping_name (str): (default: first value in send_in_pings) The name
                of the ping to retrieve the metric for.

        Returns:
            num_errors (int): The number of errors recorded for the metric for
                the given error type.
        """
        return self._inner.test_get_num_recorded_errors(error_type)

This implements the developer facing API for recording events.

Instances of this class type are automatically generated by load_metrics(), allowing developers to record values that were previously registered in the metrics.yaml file.

The event API only exposes the EventMetricType.record() method, which takes care of validating the input data and making sure that limits are enforced.

Methods

def record(self,
extra: EventExtras | None = None) ‑> None

Expand source code

def record(self, extra: Optional[EventExtras] = None) -> None:
    """
    Record an event by using the information provided by the instance of
    this class.

    Args:
        extra: optional. The extra keys and values for this event.
               The maximum length for values is 100.
    """

    if isinstance(extra, EventExtras):
        inner_extra = extra.to_ffi_extra()
    else:
        inner_extra = {}

    self._inner.record(inner_extra)

Record an event by using the information provided by the instance of this class.

Args

extra

optional. The extra keys and values for this event. The maximum length for values is 100.

def test_get_num_recorded_errors(self, error_type: glean._uniffi.glean.ErrorType) ‑> int

Expand source code

def test_get_num_recorded_errors(self, error_type: ErrorType) -> int:
    """
    Returns the number of errors recorded for the given metric.

    Args:
        error_type (ErrorType): The type of error recorded.
        ping_name (str): (default: first value in send_in_pings) The name
            of the ping to retrieve the metric for.

    Returns:
        num_errors (int): The number of errors recorded for the metric for
            the given error type.
    """
    return self._inner.test_get_num_recorded_errors(error_type)

Returns the number of errors recorded for the given metric.

Args

error_type : ErrorType

The type of error recorded.

ping_name : str

(default: first value in send_in_pings) The name of the ping to retrieve the metric for.

Returns

num_errors (int): The number of errors recorded for the metric for the given error type.

def test_get_value(self, ping_name: str | None = None) ‑> List[glean._uniffi.glean.RecordedEvent] | None

Expand source code

def test_get_value(self, ping_name: Optional[str] = None) -> Optional[List[RecordedEvent]]:
    """
    Returns the stored value for testing purposes only.

    Args:
        ping_name (str): (default: first value in send_in_pings) The name
            of the ping to retrieve the metric for.

    Returns:
        value (list of RecordedEventData): value of the stored events.
    """
    # Translate NO extras into an empty dictionary,
    # to simplify handling.
    recordings = self._inner.test_get_value(ping_name)
    if recordings:
        for recording in recordings:
            if recording.extra is None:
                recording.extra = {}

    return recordings

Returns the stored value for testing purposes only.

Args

ping_name : str

(default: first value in send_in_pings) The name of the ping to retrieve the metric for.

Returns

value (list of RecordedEventData): value of the stored events.

class RecordedEvent (*,
timestamp: "'int'",
category: "'str'",
name: "'str'",
extra: "'typing.Optional[dict[str, str]]'")

Expand source code

class RecordedEvent:
    timestamp: "int"
    category: "str"
    name: "str"
    extra: "typing.Optional[dict[str, str]]"
    def __init__(self, *, timestamp: "int", category: "str", name: "str", extra: "typing.Optional[dict[str, str]]"):
        self.timestamp = timestamp
        self.category = category
        self.name = name
        self.extra = extra

    def __str__(self):
        return "RecordedEvent(timestamp={}, category={}, name={}, extra={})".format(self.timestamp, self.category, self.name, self.extra)

    def __eq__(self, other):
        if self.timestamp != other.timestamp:
            return False
        if self.category != other.category:
            return False
        if self.name != other.name:
            return False
        if self.extra != other.extra:
            return False
        return True

Class variables

var category : str

var extra : dict[str, str] | None

var name : str

var timestamp : int