A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
flow-monitor.h
Go to the documentation of this file.
1//
2// Copyright (c) 2009 INESC Porto
3//
4// SPDX-License-Identifier: GPL-2.0-only
5//
6// Author: Gustavo J. A. M. Carneiro <gjc@inescporto.pt> <gjcarneiro@gmail.com>
7//
8
9#ifndef FLOW_MONITOR_H
10#define FLOW_MONITOR_H
11
12#include "flow-classifier.h"
13#include "flow-probe.h"
14
15#include "ns3/event-id.h"
16#include "ns3/histogram.h"
17#include "ns3/nstime.h"
18#include "ns3/object.h"
19#include "ns3/ptr.h"
20
21#include <map>
22#include <vector>
23
24namespace ns3
25{
26
27/**
28 * \defgroup flow-monitor Flow Monitor
29 * \brief Collect and store performance data from a simulation
30 */
31
32/**
33 * \ingroup flow-monitor
34 * \brief An object that monitors and reports back packet flows observed during a simulation
35 *
36 * The FlowMonitor class is responsible for coordinating efforts
37 * regarding probes, and collects end-to-end flow statistics.
38 *
39 */
40class FlowMonitor : public Object
41{
42 public:
43 /// \brief Structure that represents the measured metrics of an individual packet flow
44 struct FlowStats
45 {
46 /// Contains the absolute time when the first packet in the flow
47 /// was transmitted, i.e. the time when the flow transmission
48 /// starts
50
51 /// Contains the absolute time when the first packet in the flow
52 /// was received by an end node, i.e. the time when the flow
53 /// reception starts
55
56 /// Contains the absolute time when the last packet in the flow
57 /// was transmitted, i.e. the time when the flow transmission
58 /// ends
60
61 /// Contains the absolute time when the last packet in the flow
62 /// was received, i.e. the time when the flow reception ends
64
65 /// Contains the sum of all end-to-end delays for all received
66 /// packets of the flow.
67 Time delaySum; // delayCount == rxPackets
68
69 /// Contains the sum of all end-to-end delay jitter (delay
70 /// variation) values for all received packets of the flow. Here
71 /// we define _jitter_ of a packet as the delay variation
72 /// relatively to the last packet of the stream,
73 /// i.e. \f$Jitter\left\{P_N\right\} = \left|Delay\left\{P_N\right\} -
74 /// Delay\left\{P_{N-1}\right\}\right|\f$. This definition is in accordance with the
75 /// Type-P-One-way-ipdv as defined in IETF \RFC{3393}.
76 Time jitterSum; // jitterCount == rxPackets - 1
77
78 /// Contains the last measured delay of a packet
79 /// It is stored to measure the packet's Jitter
81 /// Contains the largest measured delay of a received packet
83 /// Contains the smallest measured delay of a received packet
85
86 /// Total number of transmitted bytes for the flow
87 uint64_t txBytes;
88 /// Total number of received bytes for the flow
89 uint64_t rxBytes;
90 /// Total number of transmitted packets for the flow
92 /// Total number of received packets for the flow
94
95 /// Total number of packets that are assumed to be lost,
96 /// i.e. those that were transmitted but have not been reportedly
97 /// received or forwarded for a long time. By default, packets
98 /// missing for a period of over 10 seconds are assumed to be
99 /// lost, although this value can be easily configured in runtime
101
102 /// Contains the number of times a packet has been reportedly
103 /// forwarded, summed for all received packets in the flow
105
106 /// Histogram of the packet delays
108 /// Histogram of the packet jitters
110 /// Histogram of the packet sizes
112
113 /// This attribute also tracks the number of lost packets and
114 /// bytes, but discriminates the losses by a _reason code_. This
115 /// reason code is usually an enumeration defined by the concrete
116 /// FlowProbe class, and for each reason code there may be a
117 /// vector entry indexed by that code and whose value is the
118 /// number of packets or bytes lost due to this reason. For
119 /// instance, in the Ipv4FlowProbe case the following reasons are
120 /// currently defined: DROP_NO_ROUTE (no IPv4 route found for a
121 /// packet), DROP_TTL_EXPIRE (a packet was dropped due to an IPv4
122 /// TTL field decremented and reaching zero), and
123 /// DROP_BAD_CHECKSUM (a packet had bad IPv4 header checksum and
124 /// had to be dropped).
125 std::vector<uint32_t>
126 packetsDropped; // packetsDropped[reasonCode] => number of dropped packets
127
128 /// This attribute also tracks the number of lost bytes. See also
129 /// comment in attribute packetsDropped.
130 std::vector<uint64_t> bytesDropped; // bytesDropped[reasonCode] => number of dropped bytes
131 Histogram flowInterruptionsHistogram; //!< histogram of durations of flow interruptions
132 };
133
134 // --- basic methods ---
135 /**
136 * \brief Get the type ID.
137 * \return the object TypeId
138 */
139 static TypeId GetTypeId();
140 TypeId GetInstanceTypeId() const override;
141 FlowMonitor();
142
143 /// Add a FlowClassifier to be used by the flow monitor.
144 /// \param classifier the FlowClassifier
145 void AddFlowClassifier(Ptr<FlowClassifier> classifier);
146
147 /// Set the time, counting from the current time, from which to start monitoring flows.
148 /// This method overwrites any previous calls to Start()
149 /// \param time delta time to start
150 void Start(const Time& time);
151 /// Set the time, counting from the current time, from which to stop monitoring flows.
152 /// This method overwrites any previous calls to Stop()
153 /// \param time delta time to stop
154 void Stop(const Time& time);
155 /// Begin monitoring flows *right now*
156 void StartRightNow();
157 /// End monitoring flows *right now*
158 void StopRightNow();
159
160 // --- methods to be used by the FlowMonitorProbe's only ---
161 /// Register a new FlowProbe that will begin monitoring and report
162 /// events to this monitor. This method is normally only used by
163 /// FlowProbe implementations.
164 /// \param probe the probe to add
165 void AddProbe(Ptr<FlowProbe> probe);
166
167 /// FlowProbe implementations are supposed to call this method to
168 /// report that a new packet was transmitted (but keep in mind the
169 /// distinction between a new packet entering the system and a
170 /// packet that is already known and is only being forwarded).
171 /// \param probe the reporting probe
172 /// \param flowId flow identification
173 /// \param packetId Packet ID
174 /// \param packetSize packet size
175 void ReportFirstTx(Ptr<FlowProbe> probe,
176 FlowId flowId,
177 FlowPacketId packetId,
179 /// FlowProbe implementations are supposed to call this method to
180 /// report that a known packet is being forwarded.
181 /// \param probe the reporting probe
182 /// \param flowId flow identification
183 /// \param packetId Packet ID
184 /// \param packetSize packet size
186 FlowId flowId,
187 FlowPacketId packetId,
189 /// FlowProbe implementations are supposed to call this method to
190 /// report that a known packet is being received.
191 /// \param probe the reporting probe
192 /// \param flowId flow identification
193 /// \param packetId Packet ID
194 /// \param packetSize packet size
195 void ReportLastRx(Ptr<FlowProbe> probe,
196 FlowId flowId,
197 FlowPacketId packetId,
199 /// FlowProbe implementations are supposed to call this method to
200 /// report that a known packet is being dropped due to some reason.
201 /// \param probe the reporting probe
202 /// \param flowId flow identification
203 /// \param packetId Packet ID
204 /// \param packetSize packet size
205 /// \param reasonCode drop reason code
206 void ReportDrop(Ptr<FlowProbe> probe,
207 FlowId flowId,
208 FlowPacketId packetId,
210 uint32_t reasonCode);
211
212 /// Check right now for packets that appear to be lost
213 void CheckForLostPackets();
214
215 /// Check right now for packets that appear to be lost, considering
216 /// packets as lost if not seen in the network for a time larger
217 /// than maxDelay
218 /// \param maxDelay the max delay for a packet
219 void CheckForLostPackets(Time maxDelay);
220
221 // --- methods to get the results ---
222
223 /// Container: FlowId, FlowStats
224 typedef std::map<FlowId, FlowStats> FlowStatsContainer;
225 /// Container Iterator: FlowId, FlowStats
226 typedef std::map<FlowId, FlowStats>::iterator FlowStatsContainerI;
227 /// Container Const Iterator: FlowId, FlowStats
228 typedef std::map<FlowId, FlowStats>::const_iterator FlowStatsContainerCI;
229 /// Container: FlowProbe
230 typedef std::vector<Ptr<FlowProbe>> FlowProbeContainer;
231 /// Container Iterator: FlowProbe
232 typedef std::vector<Ptr<FlowProbe>>::iterator FlowProbeContainerI;
233 /// Container Const Iterator: FlowProbe
234 typedef std::vector<Ptr<FlowProbe>>::const_iterator FlowProbeContainerCI;
235
236 /// Retrieve all collected the flow statistics. Note, if the
237 /// FlowMonitor has not stopped monitoring yet, you should call
238 /// CheckForLostPackets() to make sure all possibly lost packets are
239 /// accounted for.
240 /// \returns the flows statistics
241 const FlowStatsContainer& GetFlowStats() const;
242
243 /// Get a list of all FlowProbe's associated with this FlowMonitor
244 /// \returns a list of all the probes
245 const FlowProbeContainer& GetAllProbes() const;
246
247 /// Serializes the results to an std::ostream in XML format
248 /// \param os the output stream
249 /// \param indent number of spaces to use as base indentation level
250 /// \param enableHistograms if true, include also the histograms in the output
251 /// \param enableProbes if true, include also the per-probe/flow pair statistics in the output
252 void SerializeToXmlStream(std::ostream& os,
253 uint16_t indent,
254 bool enableHistograms,
255 bool enableProbes);
256
257 /// Same as SerializeToXmlStream, but returns the output as a std::string
258 /// \param indent number of spaces to use as base indentation level
259 /// \param enableHistograms if true, include also the histograms in the output
260 /// \param enableProbes if true, include also the per-probe/flow pair statistics in the output
261 /// \return the XML output as string
262 std::string SerializeToXmlString(uint16_t indent, bool enableHistograms, bool enableProbes);
263
264 /// Same as SerializeToXmlStream, but writes to a file instead
265 /// \param fileName name or path of the output file that will be created
266 /// \param enableHistograms if true, include also the histograms in the output
267 /// \param enableProbes if true, include also the per-probe/flow pair statistics in the output
268 void SerializeToXmlFile(std::string fileName, bool enableHistograms, bool enableProbes);
269
270 /// Reset all the statistics
271 void ResetAllStats();
272
273 protected:
274 void NotifyConstructionCompleted() override;
275 void DoDispose() override;
276
277 private:
278 /// Structure to represent a single tracked packet data
280 {
281 Time firstSeenTime; //!< absolute time when the packet was first seen by a probe
282 Time lastSeenTime; //!< absolute time when the packet was last seen by a probe
283 uint32_t timesForwarded; //!< number of times the packet was reportedly forwarded
284 };
285
286 /// FlowId --> FlowStats
288
289 /// (FlowId,PacketId) --> TrackedPacket
290 typedef std::map<std::pair<FlowId, FlowPacketId>, TrackedPacket> TrackedPacketMap;
291 TrackedPacketMap m_trackedPackets; //!< Tracked packets
292 Time m_maxPerHopDelay; //!< Minimum per-hop delay
293 FlowProbeContainer m_flowProbes; //!< all the FlowProbes
294
295 // note: this is needed only for serialization
296 std::list<Ptr<FlowClassifier>> m_classifiers; //!< the FlowClassifiers
297
298 EventId m_startEvent; //!< Start event
299 EventId m_stopEvent; //!< Stop event
300 bool m_enabled; //!< FlowMon is enabled
301 double m_delayBinWidth; //!< Delay bin width (for histograms)
302 double m_jitterBinWidth; //!< Jitter bin width (for histograms)
303 double m_packetSizeBinWidth; //!< packet size bin width (for histograms)
304 double m_flowInterruptionsBinWidth; //!< Flow interruptions bin width (for histograms)
305 Time m_flowInterruptionsMinTime; //!< Flow interruptions minimum time
306
307 /// Get the stats for a given flow
308 /// \param flowId the Flow identification
309 /// \returns the stats of the flow
311
312 /// Periodic function to check for lost packets and prune statistics
314};
315
316} // namespace ns3
317
318#endif /* FLOW_MONITOR_H */
An identifier for simulation events.
Definition event-id.h:45
An object that monitors and reports back packet flows observed during a simulation.
FlowStats & GetStatsForFlow(FlowId flowId)
Get the stats for a given flow.
FlowProbeContainer m_flowProbes
all the FlowProbes
void StopRightNow()
End monitoring flows right now
void ResetAllStats()
Reset all the statistics.
const FlowProbeContainer & GetAllProbes() const
Get a list of all FlowProbe's associated with this FlowMonitor.
std::vector< Ptr< FlowProbe > > FlowProbeContainer
Container: FlowProbe.
FlowStatsContainer m_flowStats
FlowId --> FlowStats.
bool m_enabled
FlowMon is enabled.
void CheckForLostPackets()
Check right now for packets that appear to be lost.
void Start(const Time &time)
Set the time, counting from the current time, from which to start monitoring flows.
std::map< std::pair< FlowId, FlowPacketId >, TrackedPacket > TrackedPacketMap
(FlowId,PacketId) --> TrackedPacket
double m_flowInterruptionsBinWidth
Flow interruptions bin width (for histograms)
void SerializeToXmlFile(std::string fileName, bool enableHistograms, bool enableProbes)
Same as SerializeToXmlStream, but writes to a file instead.
void AddFlowClassifier(Ptr< FlowClassifier > classifier)
Add a FlowClassifier to be used by the flow monitor.
void ReportLastRx(Ptr< FlowProbe > probe, FlowId flowId, FlowPacketId packetId, uint32_t packetSize)
FlowProbe implementations are supposed to call this method to report that a known packet is being rec...
EventId m_startEvent
Start event.
std::list< Ptr< FlowClassifier > > m_classifiers
the FlowClassifiers
void AddProbe(Ptr< FlowProbe > probe)
Register a new FlowProbe that will begin monitoring and report events to this monitor.
void ReportForwarding(Ptr< FlowProbe > probe, FlowId flowId, FlowPacketId packetId, uint32_t packetSize)
FlowProbe implementations are supposed to call this method to report that a known packet is being for...
Time m_flowInterruptionsMinTime
Flow interruptions minimum time.
std::map< FlowId, FlowStats >::iterator FlowStatsContainerI
Container Iterator: FlowId, FlowStats.
std::map< FlowId, FlowStats > FlowStatsContainer
Container: FlowId, FlowStats.
double m_jitterBinWidth
Jitter bin width (for histograms)
std::string SerializeToXmlString(uint16_t indent, bool enableHistograms, bool enableProbes)
Same as SerializeToXmlStream, but returns the output as a std::string.
void Stop(const Time &time)
Set the time, counting from the current time, from which to stop monitoring flows.
void PeriodicCheckForLostPackets()
Periodic function to check for lost packets and prune statistics.
double m_packetSizeBinWidth
packet size bin width (for histograms)
Time m_maxPerHopDelay
Minimum per-hop delay.
void DoDispose() override
Destructor implementation.
std::map< FlowId, FlowStats >::const_iterator FlowStatsContainerCI
Container Const Iterator: FlowId, FlowStats.
void NotifyConstructionCompleted() override
Notifier called once the ObjectBase is fully constructed.
const FlowStatsContainer & GetFlowStats() const
Retrieve all collected the flow statistics.
TrackedPacketMap m_trackedPackets
Tracked packets.
TypeId GetInstanceTypeId() const override
Get the most derived TypeId for this Object.
double m_delayBinWidth
Delay bin width (for histograms)
void StartRightNow()
Begin monitoring flows right now
void ReportFirstTx(Ptr< FlowProbe > probe, FlowId flowId, FlowPacketId packetId, uint32_t packetSize)
FlowProbe implementations are supposed to call this method to report that a new packet was transmitte...
void SerializeToXmlStream(std::ostream &os, uint16_t indent, bool enableHistograms, bool enableProbes)
Serializes the results to an std::ostream in XML format.
EventId m_stopEvent
Stop event.
std::vector< Ptr< FlowProbe > >::const_iterator FlowProbeContainerCI
Container Const Iterator: FlowProbe.
static TypeId GetTypeId()
Get the type ID.
void ReportDrop(Ptr< FlowProbe > probe, FlowId flowId, FlowPacketId packetId, uint32_t packetSize, uint32_t reasonCode)
FlowProbe implementations are supposed to call this method to report that a known packet is being dro...
std::vector< Ptr< FlowProbe > >::iterator FlowProbeContainerI
Container Iterator: FlowProbe.
Class used to store data and make an histogram of the data frequency.
Definition histogram.h:35
A base class which provides memory management and object aggregation.
Definition object.h:78
Smart pointer class similar to boost::intrusive_ptr.
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
a unique identifier for an interface.
Definition type-id.h:48
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Structure that represents the measured metrics of an individual packet flow.
uint32_t rxPackets
Total number of received packets for the flow.
Histogram packetSizeHistogram
Histogram of the packet sizes.
Time timeLastTxPacket
Contains the absolute time when the last packet in the flow was transmitted, i.e.
uint32_t lostPackets
Total number of packets that are assumed to be lost, i.e.
Histogram jitterHistogram
Histogram of the packet jitters.
Time lastDelay
Contains the last measured delay of a packet It is stored to measure the packet's Jitter.
Time timeLastRxPacket
Contains the absolute time when the last packet in the flow was received, i.e.
Histogram flowInterruptionsHistogram
histogram of durations of flow interruptions
uint64_t rxBytes
Total number of received bytes for the flow.
Time maxDelay
Contains the largest measured delay of a received packet.
Time minDelay
Contains the smallest measured delay of a received packet.
Time delaySum
Contains the sum of all end-to-end delays for all received packets of the flow.
Time timeFirstRxPacket
Contains the absolute time when the first packet in the flow was received by an end node,...
uint32_t timesForwarded
Contains the number of times a packet has been reportedly forwarded, summed for all received packets ...
uint32_t txPackets
Total number of transmitted packets for the flow.
uint64_t txBytes
Total number of transmitted bytes for the flow.
Histogram delayHistogram
Histogram of the packet delays.
Time jitterSum
Contains the sum of all end-to-end delay jitter (delay variation) values for all received packets of ...
std::vector< uint64_t > bytesDropped
This attribute also tracks the number of lost bytes.
Time timeFirstTxPacket
Contains the absolute time when the first packet in the flow was transmitted, i.e.
std::vector< uint32_t > packetsDropped
This attribute also tracks the number of lost packets and bytes, but discriminates the losses by a re...
Structure to represent a single tracked packet data.
Time lastSeenTime
absolute time when the packet was last seen by a probe
Time firstSeenTime
absolute time when the packet was first seen by a probe
uint32_t timesForwarded
number of times the packet was reportedly forwarded
static const uint32_t packetSize
Packet size generated at the AP.