.. include:: replace.txt

Design
******

The DCF consists of three basic classes:

* *Probe* is a mechanism to instrument and control the output of
  simulation data that is used to monitor interesting events. It
  produces output in the form of one or more |ns3| trace sources.
  Probe objects are hooked up to one or more trace *sinks* (called
  *Collectors*), which process samples on-line and prepare them for
  output.

* *Collector* consumes the data generated by one or more Probe objects. 
  It performs transformations on the data, such as normalization, reduction, and 
  the computation of basic statistics. Collector objects do not produce
  data that is directly output by the ns-3 run; instead, they output data
  downstream to another type of object, called *Aggregator*, which performs
  that function.  Typically, Collectors output their data in the form of
  trace sources as well, allowing collectors to be chained in series.

* *Aggregator* is the end point of the data collected by a network of Probes and Collectors. 
  The main responsibility of the Aggregator is to marshal data and their
  corresponding metadata, into different output 
  formats such as plain text files, spreadsheet files, or databases.

All three of these classes provide the capability to dynamically turn themselves on or off throughout a simulation.

Any standalone |ns3| simulation run that uses the DCF will typically create 
at least one instance of each of the three classes above. 

.. _dcf-overview:

.. figure:: figures/dcf-overview.*
   
   Data Collection Framework overview 

The overall flow of data processing is depicted in :ref:`dcf-overview`.  On
the left side, a running |ns3| simulation is depicted.  In the course
of running the simulation, data is made available by models through
trace sources, or via other means.  The diagram depicts that probes
can be connected to these trace sources to receive data asynchronously,
or probes can poll for data.  Data is then passed to a collector object
that transforms the data.  Finally, an aggregator can be connected
to the outputs of the collector, to generate plots, files, or databases.

.. _dcf-overview-with-aggregation:

.. figure:: figures/dcf-overview-with-aggregation.*
   
   Data Collection Framework aggregation

A variation on the above figure is provided 
in :ref:`dcf-overview-with-aggregation`.
This second figure illustrates that the DCF objects may be chained
together in a manner that downstream objects take inputs from multiple
upstream objects.  The figure conceptually shows that multiple probes
may generate output that is fed into a single collector; as an example,
a collector that outputs a ratio of two counters would typically acquire
each counter data from separate probes.  Multiple collectors can also
feed into a single aggregator, which (as its name implies) may collect
a number of data streams for inclusion into a single plot, file, or
database.