1
2
3
4
5
6
7
8
9
10
11
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
42
43
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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
# 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)
|
