trace.tex

柯老师网站上找到的

%
% personal commentary:
%        DRAFT DRAFT DRAFT
%        - KFALL
%
\chapter{Trace and Monitoring Support}
\label{chap:trace}

The procedures and functions described in this chapter can be found in
\nsf{trace.\{cc, h\}},
\nsf{tcl/lib/ns-trace.tcl},
\nsf{queue-monitor.\{cc, h\}},
\nsf{tcl/lib/ns-link.tcl},
\nsf{packet.h},
\nsf{flowmon.cc}, and
\nsf{classifier-hash.cc}.

There are a number of ways of collecting output or
trace data on a simulation.
Generally, trace data is either displayed directly during execution
of the simulation, or (more commonly) stored in a file to be
post-processed and analyzed.
There are two primary but distinct types of monitoring capabilities
currently supported by the simulator.
The first, called {\em traces}, record each individual packet
as it arrives, departs, or is dropped at a link or queue.
Trace objects are configured into a simulation as nodes in the
network topology, usually with a Tcl ``Channel'' object
hooked to them, representing the destination of collected data
(typically a trace file in the current directory).
The other types of objects, called {\em monitors}, record counts
of various interesting quantities such as packet and byte arrivals,
departures, etc.
Monitors can monitor counts associated with all packets,
or on a per-flow basis using a 
\href{{\em flow monitor} below}{Section}{sec:flowmon}.

To support traces, there is a special {\em common} header
included in each packet (this format is defined in \nsf{packet.h}
as \code{hdr_cmn}).
It presently includes a unique identifier on each packet, a
packet type field (set by agents when they generate packets),
a packet size field (in bytes, used to determine the transmission
time for packets), and an interface label (used for computing
multicast distribution trees).

Monitors are supported by a separate
set of objects that are created and inserted into the network topology
around queues.
They provide a place where
arrival statistics and times are gathered and make use of the
\clsref{Integrator}{../ns-2/integrator.h} (Section~\ref{sec:integral})
to compute statistics over time intervals.

\section{Trace Support}
\label{sec:otcltrace}

The trace support in OTcl consists of a number of specialized
classes visible in OTcl but implemented in C++, combined
with a set of Tcl helper procedures and classes defined in the \ns\ library.

All following OTcl classes are supported by underlying C++
classes defined in \nsf{trace.cc}.
Objects of the following types are inserted directly in-line in the
network topology:

\begin{tabularx}{\linewidth}{rX}
Trace/Hop & trace a ``hop'' (XXX what does this mean exactly; it is not really used XXX) \\
Trace/Enque & a packet arrival (usually at a queue) \\
Trace/Deque & a packet departure (usually at a queue) \\
Trace/Drop & packet drop (packet delivered to drop-target) \\
Trace/Recv & packet receive event at the destination node of a link \\
SnoopQueue/In & on input, collect a time/size sample (pass packet on) \\
SnoopQueue/Out & on output, collect a time/size sample (pass packet on) \\
SnoopQueue/Drop & on drop, collect a time/size sample (pass packet on) \\
SnoopQueue/EDrop & on an "early" drop, collect a time/size sample (pass packet on) \\
\end{tabularx}

Objects of the following types are added in the simulation and a referenced
by the objects listed above.  They are used to aggregate statistics collected
by the SnoopQueue objects:

\begin{tabularx}{\linewidth}{rX}
QueueMonitor & receive and aggregate collected samples from snoopers \\
QueueMonitor/ED & queue-monitor capable of distinguishing between ``early'' and standard packet drops \\
QueueMonitor/ED/Flowmon & per-flow statistics monitor (manager) \\
QueueMonitor/ED/Flow & per-flow statistics container \\
QueueMonitor/Compat & a replacement for a standard QueueMonitor when \ns~v1 compatibility is in use \\
\end{tabularx}

\subsection{OTcl Helper Functions}
\label{sec:helptrace}

The following helper functions may be used within simulation
scripts to help in attaching trace elements (see \nsf{tcl/lib/ns-lib.tcl});
they are instance procedures of the class Simulator:

\begin{tabularx}{\linewidth}{rX}
\code{flush-trace \{\}} & flush buffers
        for all trace objects in simulation \\
\code{create-trace \{ type file src dst \}} & create
        a trace object of type {\em type}
        between the given src and dest nodes.
        If {\em file} is non-null, it is interpreted as a Tcl channel
        and is attached to the newly-created trace object. \
        The procedure returns the handle to the newly created trace object.\\
\code{trace-queue \{ n1 n2 file \}} & arrange for tracing on the link
        between nodes {\em n1} and {\em n2}.
        This function calls create-trace,
        so the same rules apply with respect to the {\em file} argument. \\
\code{trace-callback\{ ns command \}} & arranges to call \code{command}
        when a line is to be traced.
        The procedure treats \code{command}
        as a string and evaluates it for every line traced.
        See \nsf{tcl/ex/callback\_demo.tcl} for additional details on usage.\\
\code{monitor-queue \{ n1 n2 \}} & this function
        calls the {\tt init-monitor} function
        on the link between nodes {\em n1} and {\em n2}. \\
\code{drop-trace \{ n1 n2 trace \}} & the given {\em trace} object
        is made the drop-target of the queue
        associated with the link between nodes {\em n1} and {\em n2}.
\end{tabularx}

The \proc[]{create-trace} procedure is used to create a new \code{Trace}
object of the appropriate kind and attach an Tcl I/O channel to it
(typically a file handle).
The \code{src\_} and \code{dst\_} fields are are used by the underlying C++
object for producing the trace output file so that trace output
can include the node addresses defining the endpoints of the link which
is being traced.
Note that they are not used for {\em matching}.  Specifically, these
values in no way relate to the packet header \code{src} and \code{dst}
fields, which are also displayed when tracing.
\href{See the description of the \code{Trace} class below}{Section}{sec:tracemoncplus}.

The \code{trace-queue} function enables
\code{Enque}, \code{Deque}, and \code{Drop} tracing on the link
between nodes \code{n1} and \code{n2}.
\href{The Link \code{trace} procedure is described below}{Section}{sec:libexam}.

The \code{monitor-queue} function is constructed similarly to
\code{trace-queue}.
By calling the link's \code{init-monitor} procedure, it arranges
for the creation of objects (\code{SnoopQueue} and \code{QueueMonitor}
objects) which can, in turn, be used to ascertain time-aggregated
queue statistics.

The \code{drop-trace} function provides a way to specify a
\code{Queue}'s drop target without having a direct handle of
the queue.

\section{Library support and examples}
\label{sec:libexam}

The \code{Simulator} procedures described above require the \code{trace}
and \code{init-monitor} methods associated with the OTcl \code{Link} class.
Several subclasses of link are defined, the most common of which
is called \code{SimpleLink}.  Thus, the \code{trace} and \code{init-monitor}
methods are actually part of the \code{SimpleLink} class rather than
the \code{Link} base class.
The \code{trace} function is defined as follows (in \code{ns-link.tcl}):
\begin{program}
#
# {\cf Build trace objects for this link and}
# {\cf update the object linkage}
#
SimpleLink instproc trace \{ ns f \} \{
        $self instvar enqT_ deqT_ drpT_ queue_ link_ head_ fromNode_ toNode_
        $self instvar drophead_

        set enqT_ [$ns create-trace Enque $f $fromNode_ $toNode_]
        set deqT_ [$ns create-trace Deque $f $fromNode_ $toNode_]
        set drpT_ [$ns create-trace Drop $f $fromNode_ $toNode_]

        $drpT_ target [$drophead_ target]
        $drophead_ target $drpT_
        $queue_ drop-target $drpT_

        $deqT_ target [$queue_ target]
        $queue_ target $deqT_

        if \{ [$head_ info class] == "networkinterface" \} \{
            $enqT_ target [$head_ target]
            $head_ target $enqT_
            # puts "head is i/f"
        \} else \{
            $enqT_ target $head_
            set head_ $enqT_
            # puts "head is not i/f"
        \}
\}
\end{program}
This function establishes \code{Enque}, \code{Deque}, and \code{Drop}
traces in the simulator \code{$ns} and directs their
output to I/O handle \code{$f}.
The function assumes a queue has been associated with the link.
It operates by first creating three new trace objects
and inserting the \code{Enque} object before the queue, the
\code{Deque} object after the queue, and the \code{Drop} object
between the queue and its previous drop target.
Note that all trace output is directed to the same I/O handle.

This function performs one other  additional tasks.
It checks to see if a link contains a network interface,
and if so, leaves it as the first object in the chain of objects
in the link, but otherwise inserts the \code{Enque} object as
the first one.
%The second additional task check to see if link dynamics
%(see \ref{linkdynamics}) are enabled for links in the simulation
%and if so, enables tracing of the link's up/down status.
% While the code still does this, and it should be fixed,
% This is not strictly essential, as link dynamics is only
% created just before runtime now, and hence will not
% be defined when the simulation starts.
%

The following functions, \code{init-monitor} and
\code{attach-monitor}, are used to create a set of
objects used to monitor queue sizes of a queue associated
with a link.
They are defined as follows:
\begin{program}
        SimpleLink instproc attach-monitors \{ insnoop outsnoop dropsnoop qmon \} \{
                $self instvar queue_ head_ snoopIn_ snoopOut_ snoopDrop_
                $self instvar drophead_ qMonitor_

                set snoopIn_ $insnoop
                set snoopOut_ $outsnoop
                set snoopDrop_ $dropsnoop

                $snoopIn_ target $head_
                set head_ $snoopIn_

                $snoopOut_ target [$queue_ target]
                $queue_ target $snoopOut_

                $snoopDrop_ target [$drophead_ target]
                $drophead_ target $snoopDrop_

                $snoopIn_ set-monitor $qmon
                $snoopOut_ set-monitor $qmon
                $snoopDrop_ set-monitor $qmon
                set qMonitor_ $qmon
        \}

        #
        # {\cf Insert objects that allow us to monitor the queue size}
        # {\cf of this link.  Return the name of the object that}
        # {\cf can be queried to determine the average queue size.}
        #
        SimpleLink instproc init-monitor \{ ns qtrace sampleInterval\} \{
                $self instvar qMonitor_ ns_ qtrace_ sampleInterval_

                set ns_ $ns
                set qtrace_ $qtrace
                set sampleInterval_ $sampleInterval
                set qMonitor_ [new QueueMonitor]

                $self attach-monitors [new SnoopQueue/In] \bs
                        [new SnoopQueue/Out] [new SnoopQueue/Drop] $qMonitor_

                set bytesInt_ [new Integrator]
                $qMonitor_ set-bytes-integrator $bytesInt_
                set pktsInt_ [new Integrator]
                $qMonitor_ set-pkts-integrator $pktsInt_
                return $qMonitor_
        \}
\end{program}
These functions establish queue monitoring on the \code{SimpleLink} object
in the simulator \code{ns}.
Queue monitoring is implemented by constructing three \code{SnoopQueue}
objects and one \code{QueueMonitor} object.
The \code{SnoopQueue} objects are linked in around a \code{Queue} in a way
similar to \code{Trace} objects.
The \code{SnoopQueue/In(Out)} object monitors packet arrivals(departures)
and reports them to an associated \code{QueueMonitor} agent.
In addition, a \code{SnoopQueue/Out} object is also used to accumulate
packet drop statistics to an associated \code{QueueMonitor} object.
For \code{init-monitor} the same \code{QueueMonitor} object is used
in all cases.
The C++ definitions of the \code{SnoopQueue} and \code{QueueMonitor}
classes are described below.

\section{The C++ Trace Class}
\label{sec:tracemoncplus}

Underlying C++ objects are created in support of the interface specified
in Section~\ref{sec:tracemoncplus} and are linked into the network topology
as network elements.
The single C++ \code{Trace} class is used to implement the OTcl
classes \code{Trace/Hop}, \code{Trace/Enque}, \code{Trace/Deque},
and \code{Trace/Drop}.
The \code{type\_} field is used to differentiate among the
various types of
traces any particular \code{Trace} object might implement.
Currently, this field may contain one of the following symbolic characters:
{\bf +} for enque, {\bf -} for deque, {\bf h} for hop, and
{\bf d} for drop.
The overall class is defined as follows in \nsf{trace.cc}:
\begin{program}
        class Trace : public Connector \{
         protected:
                int type_;
                nsaddr_t src_;
                nsaddr_t dst_;
                Tcl_Channel channel_;
                int callback_;
                char wrk_[256];
                void format(int tt, int s, int d, Packet* p);
                void annotate(const char* s);
                int show_tcphdr_;  // {\cf bool flags; backward compat}