A Discrete-Event Network Simulator
Home
Tutorials ▼
English
Documentation ▼
Installation
Manual
Models
Contributing
Wiki
Development ▼
API Docs
Issue Tracker
Merge Requests
API
Loading...
Searching...
No Matches
des-metrics.h
Go to the documentation of this file.
1
/*
2
* Copyright (c) 2016 LLNL
3
*
4
* This program is free software; you can redistribute it and/or modify
5
* it under the terms of the GNU General Public License version 2 as
6
* published by the Free Software Foundation;
7
*
8
* This program is distributed in the hope that it will be useful,
9
* but WITHOUT ANY WARRANTY; without even the implied warranty of
10
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
* GNU General Public License for more details.
12
*
13
* You should have received a copy of the GNU General Public License
14
* along with this program; if not, write to the Free Software
15
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
16
*
17
* Author: Peter D. Barnes, Jr. <pdbarnes@llnl.gov>
18
*/
19
20
#ifndef DESMETRICS_H
21
#define DESMETRICS_H
22
23
/**
24
* @file
25
* @ingroup simulator
26
* ns3::DesMetrics declaration.
27
*/
28
29
#include "
nstime.h
"
30
#include "
singleton.h
"
31
32
#include <fstream>
33
#include <mutex>
34
#include <stdint.h>
// uint32_t
35
#include <string>
36
#include <vector>
37
38
namespace
ns3
39
{
40
41
/**
42
* @ingroup simulator
43
*
44
* @brief Event trace data collector for the DES Metrics project.
45
*
46
* This feature generates a JSON file with event trace data,
47
* including the source and destination context for each
48
* event, and the (virtual) times when the event was scheduled and
49
* when it will execute.
50
*
51
* See the DES Metrics Project page: https://github.com/wilseypa/desMetrics
52
* for more information and analysis tools.
53
*
54
* If enabled (see below), ns-3 scripts should use CommandLine to
55
* parse arguments, which will open the JSON file with the same name
56
* as the script, and write the JSON header. Failure to use CommandLine when
57
* DES Metrics is enabled will put the trace data in the file
58
* \c desTraceFile.json instead. All examples accessible from \c test.py
59
* use CommandLine, and so generate JSON files.
60
*
61
* Output from scripts ends up in the current working directory (normally the
62
* top level directory). When \c test.py is used to run tests or examples
63
* the trace files are generated in a time-stamped subdirectory of
64
* \c testpy-output/, which \c test.py normally deletes.
65
* To keep the output of examples, use the \c --retain argument to \c test.py.
66
*
67
* The output file has the following form:
68
* \verbatim
69
{
70
"simulator_name" : "ns-3",
71
"model_name" : "ipv4-raw",
72
"capture_date" : "Fri May 27 00:34:27 2016",
73
"command_line_arguments" : "ipv4-raw [ns3-dev-test-runner-debug] --test-name=ipv4-raw
74
--stop-on-failure --fullness=QUICK --xml --tempdir=testpy-output/2016-05-27-04-33-35-CUT
75
--out=testpy-output/2016-05-27-04-33-35-CUT/ipv4-raw.xml", "events" : [
76
["0",0,"0",0],
77
["1",0,"0",0],
78
["0",0,"0",0],
79
...
80
["0",0,"0",0]
81
]
82
} \endverbatim
83
* The first few fields are self-explanatory. The \c event record consists of
84
* the source context, the event send time, the destination context,
85
* and the event execution time. Times are given in the
86
* current Time resolution.
87
*
88
* <b> Enabling DES Metrics </b>
89
*
90
* Enable DES Metrics at configure time with
91
* \verbatim
92
$ ns3 configure ... --enable-des-metrics \endverbatim
93
*
94
* <b> Working with DES Metrics </b>
95
*
96
* Some useful shell pipelines:
97
*
98
* \li Run everything, retaining the results directory: <br/>
99
* \code ./test.py --nobuild --retain \endcode
100
* \li Example traces end up in \c testpy-output/, so move there: <br/>
101
* \code cd testpy-output/$(date +"%F")*_/ \endcode
102
* (Remove the `_', which is to work around a Doxygen limitation.)
103
* \li Remove the traces with less than 10 events: <br/>
104
* \code wc -l *.json | sort -nr | grep "^ *[789] " | cut -d ' ' -f 9 | xargs rm -f \endcode
105
* \li Show the largest file, and total number of trace files: <br/>
106
* \code wc -l *.json | sort -n | tail -2 \endcode
107
*
108
*/
109
class
DesMetrics
:
public
Singleton
<DesMetrics>
110
{
111
public
:
112
/**
113
* Open the DesMetrics trace file and print the header.
114
*
115
* The trace file will have the same base name as the main program,
116
* '.json' as the extension.
117
*
118
* \param args [in] Command line arguments.
119
* \param outDir [in] Directory where the trace file should be written.
120
*/
121
void
Initialize
(std::vector<std::string> args, std::string outDir =
""
);
122
123
/**
124
* Trace an event to self at the time it is scheduled.
125
*
126
* \param now [in] The local simulation time.
127
* \param delay [in] The delay to the event.
128
*/
129
void
Trace
(
const
Time
& now,
const
Time
& delay);
130
131
/**
132
* Trace an event (with context) at the time it is scheduled.
133
*
134
* \param context [in] The context (NodeId) which will receive the event.
135
* \param now [in] The local simulation time.
136
* \param delay [in] The delay to the event.
137
*/
138
void
TraceWithContext
(
uint32_t
context,
const
Time
& now,
const
Time
& delay);
139
140
/**
141
* Destructor, closes the trace file.
142
*/
143
~DesMetrics
()
override
;
144
145
private
:
146
/** Close the output file. */
147
void
Close
();
148
149
/**
150
* Cache the last-used output directory.
151
*
152
* This is enables repeated/re-entrant use of CommandLine, for example
153
* in \c command-line-test-suite.cc
154
*/
155
static
std::string
m_outputDir
;
156
157
bool
m_initialized
;
//!< Have we been initialized.
158
std::ofstream
m_os
;
//!< The output JSON trace file stream.
159
char
m_separator
;
//!< The separator between event records.
160
161
/** Mutex to control access to the output file. */
162
std::mutex
m_mutex
;
163
164
};
// class DesMetrics
165
166
}
// namespace ns3
167
168
#endif
/* DESMETRICS_H */
ns3::DesMetrics
Event trace data collector for the DES Metrics project.
Definition:
des-metrics.h:110
ns3::DesMetrics::~DesMetrics
~DesMetrics() override
Destructor, closes the trace file.
Definition:
des-metrics.cc:137
ns3::DesMetrics::m_initialized
bool m_initialized
Have we been initialized.
Definition:
des-metrics.h:157
ns3::DesMetrics::m_mutex
std::mutex m_mutex
Mutex to control access to the output file.
Definition:
des-metrics.h:162
ns3::DesMetrics::Initialize
void Initialize(std::vector< std::string > args, std::string outDir="")
Open the DesMetrics trace file and print the header.
Definition:
des-metrics.cc:42
ns3::DesMetrics::Close
void Close()
Close the output file.
Definition:
des-metrics.cc:143
ns3::DesMetrics::m_separator
char m_separator
The separator between event records.
Definition:
des-metrics.h:159
ns3::DesMetrics::Trace
void Trace(const Time &now, const Time &delay)
Trace an event to self at the time it is scheduled.
Definition:
des-metrics.cc:101
ns3::DesMetrics::TraceWithContext
void TraceWithContext(uint32_t context, const Time &now, const Time &delay)
Trace an event (with context) at the time it is scheduled.
Definition:
des-metrics.cc:107
ns3::DesMetrics::m_os
std::ofstream m_os
The output JSON trace file stream.
Definition:
des-metrics.h:158
ns3::DesMetrics::m_outputDir
static std::string m_outputDir
Cache the last-used output directory.
Definition:
des-metrics.h:155
ns3::Singleton
A template singleton.
Definition:
singleton.h:68
ns3::Time
Simulation virtual time values and global simulation resolution.
Definition:
nstime.h:105
uint32_t
ns3
Every class exported by the ns3 library is enclosed in the ns3 namespace.
nstime.h
Declaration of classes ns3::Time and ns3::TimeWithUnit, and the TimeValue implementation classes.
singleton.h
ns3::Singleton declaration and template implementation.
src
core
model
des-metrics.h
Generated on Tue May 28 2024 23:34:28 for ns-3 by
1.9.6