Skip to content

opensampl.metrics

Functions and objects for managing openSAMPL Metric Types

METRICS

Class for storing metric types

Source code in opensampl/metrics.py 
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
class METRICS:
    """Class for storing metric types"""

    # --- SUPPORTED METRICS ----
    PHASE_OFFSET = MetricType(
        name="Phase Offset",
        description="Difference in seconds between the probe's time reading and the reference time reading",
        unit="s",
        value_type=float,
    )
    EB_NO = MetricType(
        name="Eb/No",
        description=(
            "Energy per bit to noise power spectral density ratio measured at the clock probe. "
            "Indicates the quality of the received signal relative to noise."
        ),
        unit="dB",
        value_type=float,
    )
    UNKNOWN = MetricType(
        name="UNKNOWN",
        description="Unknown or unspecified metric type, with value_type of jsonb due to flexibility",
        unit="unknown",
        value_type=object,
    )
    DELAY = MetricType(
        name="Delay",
        description=(
            "Round-trip delay (RTD) or Round-Trip Time (RTT). The time in seconds it takes for a data signal to "
            "travel from a source to a destination and back, including acknowledgement."
        ),
        unit="s",
        value_type=float,
    )
    JITTER = MetricType(
        name="Jitter",
        description=("Jitter or offset variation in delay in seconds. Represents inconsistent response times."),
        unit="s",
        value_type=float,
    )
    STRATUM = MetricType(
        name="Stratum",
        description=(
            'Stratum level. Hierarchical layer defining the distance (or "hops") between device and reference.'
        ),
        unit="level",
        value_type=int,
    )
    REACHABILITY = MetricType(
        name="Reachability",
        description=(
            "Reachability register (0-255) as a scalar for plotting. Ability of a source node to communicate "
            "with a target node."
        ),
        unit="count",
        value_type=float,
    )
    DISPERSION = MetricType(
        name="Dispersion",
        description="Uncertainty in a clock's time relative to its reference source in seconds",
        unit="s",
        value_type=float,
    )
    NTP_ROOT_DELAY = MetricType(
        name="NTP Root Delay",
        description=(
            "Total round-trip network delay from the local system"
            " all the way to the primary reference clock (stratum 0)"
        ),
        unit="s",
        value_type=float,
    )
    NTP_ROOT_DISPERSION = MetricType(
        name="NTP Root Dispersion",
        description="The total accumulated clock uncertainty from the local system back to the primary reference clock",
        unit="s",
        value_type=float,
    )
    POLL_INTERVAL = MetricType(
        name="Poll Interval",
        description="Time between requests sent to a time server in seconds",
        unit="s",
        value_type=float,
    )
    SYNC_HEALTH = MetricType(
        name="Sync Health",
        description="1.0 if synchronized/healthy, 0.0 otherwise (probe-defined)",
        unit="ratio",
        value_type=float,
    )

MetricType

Bases: BaseModel

Object for defining different metric types

Source code in opensampl/metrics.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
class MetricType(BaseModel):
    """Object for defining different metric types"""

    name: str
    description: str
    unit: str
    value_type: type

    def convert_to_type(self, value: Any) -> Any:
        """Convert a given value to the expected type for the Metric"""
        return self.value_type(value)

    def is_numeric(self) -> bool:
        """Return True if the metric's value_type is numeric (int or float)"""
        return self.value_type in [int, float]

    @field_serializer("value_type")
    def serialize_type(self, value: type):
        """Return the name of value_type for serializing"""
        return value.__name__

    @field_validator("value_type", mode="before")
    @classmethod
    def validate_type(cls, value: str | type) -> Any:
        """Ensure the value_type field is converted to a type if provided as a string"""
        if isinstance(value, str):
            value = value.strip()
            if value in type_map:
                return type_map[value]
        return value

convert_to_type(value)

Convert a given value to the expected type for the Metric

Source code in opensampl/metrics.py 
20
21
22
def convert_to_type(self, value: Any) -> Any:
    """Convert a given value to the expected type for the Metric"""
    return self.value_type(value)

is_numeric()

Return True if the metric's value_type is numeric (int or float)

Source code in opensampl/metrics.py 
24
25
26
def is_numeric(self) -> bool:
    """Return True if the metric's value_type is numeric (int or float)"""
    return self.value_type in [int, float]

serialize_type(value)

Return the name of value_type for serializing

Source code in opensampl/metrics.py 
28
29
30
31
@field_serializer("value_type")
def serialize_type(self, value: type):
    """Return the name of value_type for serializing"""
    return value.__name__

validate_type(value) classmethod

Ensure the value_type field is converted to a type if provided as a string

Source code in opensampl/metrics.py 
33
34
35
36
37
38
39
40
41
@field_validator("value_type", mode="before")
@classmethod
def validate_type(cls, value: str | type) -> Any:
    """Ensure the value_type field is converted to a type if provided as a string"""
    if isinstance(value, str):
        value = value.strip()
        if value in type_map:
            return type_map[value]
    return value