trace.tex

柯老师网站上找到的

%
% personal commentary:
%        DRAFT DRAFT DRAFT
%        - KFALL
%
\section{\shdr{Trace and Monitoring Support}{trace.h}{sec:trace}}

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 {\em flow monitor}
(see section \ref{flowmon} below).

To support traces, there is a special {\em common} header
included in each packet (this format is defined in \code{packet.h}
as {\tt 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 \code{Integrator} class (see \ref{sec:integclass}) to
compute statistics over time intervals.

\subsection{\shdr{Trace Support}{ns-lib.tcl}{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 \code{trace.cc}.
Objects of the following types are inserted directly in-line in the
network topology:
\begin{quote}
\begin{itemize}
	\item [Trace/Hop] - trace a ``hop'' (XXX what does this mean exactly; it is not really used XXX)
	\item [Trace/Enque] - a packet arrival (usually at a queue)
	\item [Trace/Deque] - a packet departure (usually at a queue)
	\item [Trace/Drop] - packet drop (packet delivered to drop-target)
	\item [SnoopQueue/In] - on input, collect a time/size sample (pass packet on)
	\item [SnoopQueue/Out] - on output, collect a time/size sample (pass packet on)
	\item [SnoopQueue/Drop] - on drop, collect a time/size sample (pass packet on)
	\item [SnoopQueue/EDrop] - on an "early" drop, collect a time/size sample (pass packet on)
\end{itemize}
\end{quote}
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{quote}
\begin{itemize}
	\item [QueueMonitor] - receive and aggregate collected samples from snoopers
	\item [QueueMonitor/ED] - queue-monitor capable of distinguishing between ``early'' and standard packet drops
	\item [QueueMonitor/ED/Flowmon] - per-flow statistics monitor (manager)
	\item [QueueMonitor/ED/Flow] - per-flow statistics container
	\item [QueueMonitor/Compat] - a replacement for a standard QueueMonitor when ns-1 compatibility is in use
\end{itemize}
\end{quote}

\subsubsection{\shdr{otcl helper functions}{ns-lib.tcl}{sec:helptrace}}

The following helper functions may be used within simulation
scripts to help in attaching trace elements (see \code{ns-lib.tcl}):
\begin{small}
\begin{itemize}
\item[Simulator instproc flush-trace \{\}] - flush buffers for all
trace objects in simulation
\item[Simulator instproc create-trace \{ type file src dst \}] - create a
trace object of type {\em type} betweek 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.
\item[Simulator instproc 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.
\item[DOES TRACE-ALL REALLY BELONG HERE] - XXXX
\item[Simulator instproc monitor-queue \{ n1 n2 \}] - this function
calls the {\tt init-monitor} function on the link between nodes {\em n1}
and {\em n2}.
\item[Simulator instproc 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{itemize}
\end{small}
The \code{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.
See the description of the \code{Trace}
class below (\ref{sec:traceclass}).

The \code{trace-queue} function enables
\code{Enque}, \code{Deque}, and \code{Drop} tracing on the link
between nodes \code{n1} and \code{n2}.
The Link \code{trace} procedure is described below (\ref{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.

\subsection{\shdr{Library support and examples}{ns-lib.tcl}{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{small}
\begin{verbatim}
#
# Build trace objects for this link and
# update the object linkage
#
SimpleLink instproc trace { ns f } {
        $self instvar enqT_ deqT_ drpT_ queue_ link_ head_ fromNode_ toNode_
        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 [$queue_ drop-target]
        $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"
        }

        $self instvar dynamics_
        if [info exists dynamics_] {
                $self trace-dynamics $ns $f
        }
}

\end{verbatim}
\end{small}

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 also performs two 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.



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{small}
\begin{verbatim}
	#
	# like init-monitor, but allows for specification of more of the items
	# attach-monitors $insnoop $inqm $outsnoop $outqm $dropsnoop $dropqm
	#
	SimpleLink instproc attach-monitors { insnoop outsnoop dropsnoop qmon } {
		$self instvar drpT_ queue_ head_ snoopIn_ snoopOut_ snoopDrop_
		$self instvar qMonitor_

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

		$snoopIn_ target $head_
		set head_ $snoopIn_

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

		if [info exists drpT_] {
			$snoopDrop_ target [$drpT_ target]
			$drpT_ target $snoopDrop_
			$queue_ drop-target $drpT_
		} else {
			$snoopDrop_ target [[Simulator instance] set nullAgent_]
			$queue_ drop-target $snoopDrop_
		}

		$snoopIn_ set-monitor $qmon
		$snoopOut_ set-monitor $qmon
		$snoopDrop_ set-monitor $qmon
		set qMonitor_ $qmon
	}
	# Insert objects that allow us to monitor the queue size
	# of this link.  Return the name of the object that
	# 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] \
			[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{verbatim}
\end{small}

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.

\subsection{\shdr{The C++ Trace Class}{trace.cc}{sec:tracemoncplus}}

Underlying C++ objects are created in support of the interface specified
in Section\ref{sec:traceclass} 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 \code{trace.cc}:
\begin{small}
\begin{verbatim}
        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_;  // bool flags; backward compat
         public:
                Trace(int type);
                ~Trace();
                int command(int argc, const char*const* argv);
                void recv(Packet* p, Handler*);
                void dump();
                inline char* buffer() { return (wrk_); }
        };
\end{verbatim}
\end{small}

The \code{src\_}, and \code{dst\_} internal state is used
to label trace output and is independent of the corresponding field
names in packet headers.
The main \code{recv} method is defined as follows:
\begin{small}
\begin{verbatim}
        void Trace::recv(Packet* p, Handler* h)
        {
                format(type_, src_, dst_, p);
                dump();
                /* hack: if trace object not attached to anything free packet */
                if (target_ == 0)
                        Packet::free(p);
                else
                        send(p, h); /* Connector::send() */
        }
\end{verbatim}
\end{small}
The function merely formats a trace entry using the source, destination,
and particular trace type character.
The \code{dump} function writes the formatted entry out to the
I/O handle associated with \code{channel\_}.
The \code{format} function, in effect, dictates the trace file format.

\subsection{\shdr{trace file format}{trace.cc}{sec:traceformat}}

The \code{Trace::format} function defines the trace file format used
in trace files produced by the \code{Trace} class.
It is constructed to maintain backward compatibility with output files
in earlier versions of the simulator (i.e. {\em ns-1}) so that ns-1
post-processing scripts continue to operate.
The important pieces of its implementation are as follows:
\begin{small}
\begin{verbatim}
	// this function should retain some backward-compatibility, so that
	// scripts don't break.
	void Trace::format(int tt, int s, int d, Packet* p)
	{
		hdr_cmn *th = (hdr_cmn*)p->access(off_cmn_);
		hdr_ip *iph = (hdr_ip*)p->access(off_ip_);
		hdr_tcp *tcph = (hdr_tcp*)p->access(off_tcp_);
		hdr_rtp *rh = (hdr_rtp*)p->access(off_rtp_);
		int t = th->ptype();
		const char* name = pt_names[t];

		if (name == 0)
			abort();

		int seqno;
		/* XXX */
			/* CBR's now have seqno's too */
		if (t == PT_RTP || t == PT_CBR)
			seqno = rh->seqno();
		else if (t == PT_TCP || t == PT_ACK)
			seqno = tcph->seqno();
		else
			seqno = -1;

                ....