Event trace data collector for the DES Metrics project. More...

#include "des-metrics.h"

Inheritance diagram for ns3::DesMetrics:

Collaboration diagram for ns3::DesMetrics:

Public Member Functions
	~DesMetrics () override
	Destructor, closes the trace file. More...

void	Initialize (std::vector< std::string > args, std::string outDir="")
	Open the DesMetrics trace file and print the header. More...

void	Trace (const Time &now, const Time &delay)
	Trace an event to self at the time it is scheduled. More...

void	TraceWithContext (uint32_t context, const Time &now, const Time &delay)
	Trace an event (with context) at the time it is scheduled. More...

Public Member Functions inherited from ns3::Singleton< DesMetrics >
	Singleton (const Singleton< DesMetrics > &)=delete

Singleton &	operator= (const Singleton< DesMetrics > &)=delete

Private Member Functions
void	Close ()
	Close the output file. More...

Private Attributes
bool	m_initialized
	Have we been initialized. More...

std::mutex	m_mutex
	Mutex to control access to the output file. More...

std::ofstream	m_os
	The output JSON trace file stream. More...

char	m_separator
	The separator between event records. More...

Static Private Attributes
static std::string	m_outputDir
	Cache the last-used output directory. More...

Additional Inherited Members
Static Public Member Functions inherited from ns3::Singleton< DesMetrics >
static DesMetrics *	Get ()
	Get a pointer to the singleton instance. More...

Protected Member Functions inherited from ns3::Singleton< DesMetrics >
	Singleton ()
	Constructor. More...

virtual	~Singleton ()
	Destructor. More...

Detailed Description

Event trace data collector for the DES Metrics project.

This feature generates a JSON file with event trace data, including the source and destination context for each event, and the (virtual) times when the event was scheduled and when it will execute.

See the DES Metrics Project page: https://github.com/wilseypa/desMetrics for more information and analysis tools.

If enabled (see below), ns-3 scripts should use CommandLine to parse arguments, which will open the JSON file with the same name as the script, and write the JSON header. Failure to use CommandLine when DES Metrics is enabled will put the trace data in the file desTraceFile.json instead. All examples accessible from test.py use CommandLine, and so generate JSON files.

Output from scripts ends up in the current working directory (normally the top level directory). When test.py is used to run tests or examples the trace files are generated in a time-stamped subdirectory of testpy-output/, which test.py normally deletes. To keep the output of examples, use the –retain argument to test.py.

The output file has the following form:

{
 "simulator_name" : "ns-3",
 "model_name" : "ipv4-raw",
 "capture_date" : "Fri May 27 00:34:27 2016",
 "command_line_arguments" : "ipv4-raw [ns3-dev-test-runner-debug] --test-name=ipv4-raw
--stop-on-failure --fullness=QUICK --xml --tempdir=testpy-output/2016-05-27-04-33-35-CUT
--out=testpy-output/2016-05-27-04-33-35-CUT/ipv4-raw.xml", "events" : [
  ["0",0,"0",0],
  ["1",0,"0",0],
  ["0",0,"0",0],
  ...
  ["0",0,"0",0]
 ]
}

The first few fields are self-explanatory. The event record consists of the source context, the event send time, the destination context, and the event execution time. Times are given in the current Time resolution.

Enabling DES Metrics

Enable DES Metrics at configure time with

   $ ns3 configure ... --enable-des-metrics

Working with DES Metrics

Some useful shell pipelines:

Run everything, retaining the results directory:

./test.py --nobuild --retain
Example traces end up in testpy-output/, so move there:

cd testpy-output/$(date +"%F")*_/

(Remove the ‘_’, which is to work around a Doxygen limitation.)
Remove the traces with less than 10 events:

wc -l *.json | sort -nr | grep "^ *[789] " | cut -d ' ' -f 9 | xargs rm -f

f
double f(double x, void *params)
Definition: 80211b.c:70
Show the largest file, and total number of trace files:

wc -l *.json | sort -n | tail -2