A Discrete-Event Network Simulator
API
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 (void)
 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< DesMetrics > & operator= (const Singleton< DesMetrics > &)=delete
 

Private Member Functions

void Close (void)
 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 DesMetricsGet (void)
 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://wilseypa.github.io/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
    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

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

Constructor & Destructor Documentation

◆ ~DesMetrics()

ns3::DesMetrics::~DesMetrics ( void  )

Destructor, closes the trace file.

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

References Close().

+ Here is the call graph for this function:

Member Function Documentation

◆ Close()

void ns3::DesMetrics::Close ( void  )
private

Close the output file.

Definition at line 147 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 42 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(), 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 102 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 108 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 158 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 163 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 159 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 156 of file des-metrics.h.

Referenced by Initialize().

◆ m_separator

char ns3::DesMetrics::m_separator
private

The separator between event records.

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

Referenced by Initialize(), and TraceWithContext().


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