--- /dev/null
+# Copyright (c) 2023 Cisco and/or its affiliates.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Module defining MeasurementResult class."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class MeasurementResult:
+ """Structure defining the result of a single trial measurement.
+
+ There are few primary (required) quantities. Various secondary (derived)
+ quantities are calculated and can be queried.
+
+ The constructor allows broader argument types,
+ the post init function converts to the stricter types.
+
+ Integer quantities (counts) are preferred, as float values
+ can suffer from rounding errors, and sometimes they are measured
+ at unknown (possibly very limited) precision and accuracy.
+
+ There are relations between the counts (e.g. offered count
+ should be equal to a sum of forwarding count and loss count).
+ This implementation does not perform consistency checks, but uses them
+ for computing quantities the caller left unspecified.
+
+ In some cases, the units of intended load are different from units
+ of loss count (e.g. load in transactions but loss in packets).
+ Quantities with relative_ prefix can be used to get load candidates
+ from forwarding results.
+
+ Sometimes, the measurement provider is unable to reach the intended load,
+ and it can react by spending longer than intended duration
+ to reach its intended count. To signal irregular situations like this,
+ several optional fields can be given, and various secondary quantities
+ are populated, so the measurement consumer can query the quantity
+ it wants to rely on in these irregular situations.
+
+ The current implementation intentionally limits the secondary quantities
+ to the few that proved useful in practice.
+ """
+
+ # Required primary quantities.
+ intended_duration: float
+ """Intended trial measurement duration [s]."""
+ intended_load: float
+ """Intended load [tps]. If bidirectional (or multi-port) traffic is used,
+ most users will put unidirectional (single-port) value here,
+ as bandwidth and pps limits are usually per-port."""
+ # Two of the next three primary quantities are required.
+ offered_count: int = None
+ """Number of packets actually transmitted (transactions attempted).
+ This should be the aggregate (bidirectional, multi-port) value,
+ so that asymmetric trafic profiles are supported."""
+ loss_count: int = None
+ """Number of packets transmitted but not received (transactions failed)."""
+ forwarding_count: int = None
+ """Number of packets successfully forwarded (transactions succeeded)."""
+ # Optional primary quantities.
+ offered_duration: float = None
+ """Estimate of the time [s] the trial was actually transmitting traffic."""
+ duration_with_overheads: float = None
+ """Estimate of the time [s] it took to get the trial result
+ since the measurement started."""
+ intended_count: int = None
+ """Expected number of packets to transmit. If not known,
+ the value of offered_count is used."""
+
+ def __post_init__(self) -> None:
+ """Convert types, compute missing values.
+
+ Current caveats:
+ A failing assumption looks like a conversion error.
+ Negative counts are allowed, which can lead to errors later.
+ """
+ self.intended_duration = float(self.intended_duration)
+ if self.offered_duration is None:
+ self.offered_duration = self.intended_duration
+ else:
+ self.offered_duration = float(self.offered_duration)
+ if self.duration_with_overheads is None:
+ self.duration_with_overheads = self.offered_duration
+ else:
+ self.duration_with_overheads = float(self.duration_with_overheads)
+ self.intended_load = float(self.intended_load)
+ if self.forwarding_count is None:
+ self.forwarding_count = int(self.offered_count) - int(
+ self.loss_count
+ )
+ else:
+ self.forwarding_count = int(self.forwarding_count)
+ if self.offered_count is None:
+ self.offered_count = self.forwarding_count + int(self.loss_count)
+ else:
+ self.offered_count = int(self.offered_count)
+ if self.loss_count is None:
+ self.loss_count = self.offered_count - self.forwarding_count
+ else:
+ self.loss_count = int(self.loss_count)
+ if self.intended_count is None:
+ self.intended_count = self.offered_count
+ else:
+ self.intended_count = int(self.intended_count)
+ # TODO: Handle (somehow) situations where offered > intended?
+
+ @property
+ def unsent_count(self) -> int:
+ """How many packets were not transmitted (transactions not started).
+
+ :return: Intended count minus offered count.
+ :rtype: int
+ """
+ return self.intended_count - self.offered_count
+
+ @property
+ def loss_ratio(self) -> float:
+ """Bad count divided by overall count, zero if the latter is zero.
+
+ The bad count includes not only loss count, but also unsent count.
+ If unsent count is negative, its absolute value is used.
+ The overall count is intended count or offered count,
+ whichever is bigger.
+
+ Together, the resulting formula tends to increase loss ratio
+ (but not above 100%) in irregular situations,
+ thus guiding search algorithms towards lower loads
+ where there should be less irregularities.
+ The zero default is there to prevent search algorithms from
+ getting stuck on a too low intended load.
+
+ :returns: Bad count divided by overall count.
+ :rtype: float
+ """
+ overall = max(self.offered_count, self.intended_count)
+ bad = abs(self.loss_count) + abs(self.unsent_count)
+ return bad / overall if overall else 0.0
+
+ @property
+ def relative_forwarding_rate(self) -> float:
+ """Forwarding rate in load units as if duration and load was intended.
+
+ The result is based purely on intended load and loss ratio.
+ While the resulting value may be far from what really happened,
+ it has nice behavior with respect to common assumptions
+ of search algorithms.
+
+ :returns: Forwarding rate in load units estimated from loss ratio.
+ :rtype: float
+ """
+ return self.intended_load * (1.0 - self.loss_ratio)
Code Review / csit.git / blobdiff