ns3::DesMetrics Class Reference

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.
void	Initialize (std::vector< std::string > args, std::string outDir="")
	Open the DesMetrics trace file and print the header.
void	Trace (const Time &now, const Time &delay)
	Trace an event to self at the time it is scheduled.
void	TraceWithContext (uint32_t context, const Time &now, const Time &delay)
	Trace an event (with context) at the time it is scheduled.
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.

Private Attributes
bool	m_initialized
	Have we been initialized.
std::mutex	m_mutex
	Mutex to control access to the output file.
std::ofstream	m_os
	The output JSON trace file stream.
char	m_separator
	The separator between event records.

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

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

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 

• Show the largest file, and total number of trace files:
  

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

Definition at line 98 of file des-metrics.h.

Constructor & Destructor Documentation

~DesMetrics()

ns3::DesMetrics::~DesMetrics ( )

override

Destructor, closes the trace file.

Definition at line 126 of file des-metrics.cc.

References Close().

Here is the call graph for this function:

Member Function Documentation

Close()

void ns3::DesMetrics::Close ( )

private

Close the output file.

Definition at line 132 of file des-metrics.cc.

References m_initialized, and m_os.

Referenced by ~DesMetrics(), and Initialize().

Here is the caller graph for this function:

Initialize()

void ns3::DesMetrics::Initialize	(	std::vector< std::string >	args,
		std::string	outDir = "" )

Open the DesMetrics trace file and print the header.

The trace file will have the same base name as the main program, '.json' as the extension.

Parameters

args	[in] Command line arguments.
outDir	[in] Directory where the trace file should be written.

Definition at line 31 of file des-metrics.cc.

References ns3::SystemPath::Append(), Close(), m_initialized, m_os, m_outputDir, m_separator, and ns3::SystemPath::Split().

Referenced by ns3::CommandLine::Parse(), ns3::TestRunnerImpl::Run(), and TraceWithContext().

Here is the call graph for this function:

Here is the caller graph for this function:

Trace()

void ns3::DesMetrics::Trace	(	const Time &	now,
		const Time &	delay )

Trace an event to self at the time it is scheduled.

Parameters

now	[in] The local simulation time.
delay	[in] The delay to the event.

Definition at line 90 of file des-metrics.cc.

References ns3::Simulator::GetContext(), and TraceWithContext().

Referenced by ns3::Simulator::DoSchedule(), and ns3::Simulator::DoScheduleNow().

Here is the call graph for this function:

Here is the caller graph for this function:

TraceWithContext()

void ns3::DesMetrics::TraceWithContext	(	uint32_t	context,
		const Time &	now,
		const Time &	delay )

Trace an event (with context) at the time it is scheduled.

Parameters

context	[in] The context (NodeId) which will receive the event.
now	[in] The local simulation time.
delay	[in] The delay to the event.

Definition at line 96 of file des-metrics.cc.

References ns3::Simulator::GetContext(), ns3::Time::GetTimeStep(), Initialize(), m_initialized, m_mutex, m_os, m_separator, and ns3::Simulator::NO_CONTEXT.

Referenced by ns3::Simulator::ScheduleWithContext(), and Trace().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

m_initialized

bool ns3::DesMetrics::m_initialized

private

Have we been initialized.

Definition at line 146 of file des-metrics.h.

Referenced by Close(), Initialize(), and TraceWithContext().

m_mutex

std::mutex ns3::DesMetrics::m_mutex

private

Mutex to control access to the output file.

Definition at line 151 of file des-metrics.h.

Referenced by TraceWithContext().

m_os

std::ofstream ns3::DesMetrics::m_os

private

The output JSON trace file stream.

Definition at line 147 of file des-metrics.h.

Referenced by Close(), Initialize(), and TraceWithContext().

m_outputDir

std::string ns3::DesMetrics::m_outputDir

staticprivate

Cache the last-used output directory.

This is enables repeated/re-entrant use of CommandLine, for example in command-line-test-suite.cc

Definition at line 144 of file des-metrics.h.

Referenced by Initialize().

m_separator

char ns3::DesMetrics::m_separator

private

The separator between event records.

Definition at line 148 of file des-metrics.h.

Referenced by Initialize(), and TraceWithContext().

---

The documentation for this class was generated from the following files:

• src/core/model/des-metrics.h
• src/core/model/des-metrics.cc