Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
owstats(1)		    General Commands Manual		    owstats(1)

       owstats - Command line application used to parse	OWAMP data files.

       owstats [options] datafile.owp [datafile2.owp ...]

       owstats	is a command line application that is used to parse OWAMP data
       files. It is used to display the	results	in a number of different  tex-
       tual formats.

       OWAMP  supports three reporting formats.	A textual summary that was de-
       signed to be as similar to the results that ping	produces as  possible.
       A  machine  readable summary format (-M). And finally a raw format that
       prints out the data from	each and every packet in as compact of a  for-
       mat  as possible	(-R).  The textual summary also	allows the information
       from each packet	to be reported using the -v option. The	 default  tex-
       tual summary will be used if neither the	-M or the -R options are spec-
       ified.  It includes:

	      Session Identifier. This value is	unique for every test session.

       Sent, Lost, Duplicates
	      Number of	packets	that were sent,	lost, and duplicated  as  seen
	      by OWAMP.

       Min Delay, Median Delay,	Max Delay, Error Estimate
	      Minimum, median and maximum delay	seen for sample. Maximum error
	      estimate for the sample. (The median is determined using a  his-
	      togram, so the resolution	of this	value is bounded by the	-b pa-
	      rameter. This can	lead to	misleading results, for	 example,  for
	      very  small  values of latency it	is possible to see a value for
	      the median that is greater than the maximum, but this is	simply
	      due to the resolution of the median measurement.)

	      An estimate of how "stable" the delay samples are. OWAMP reports
	      the the 95th percentile of delay - 50th percentile of delay.

       Additional percentiles
	      If the -a	option is used,	those additional percentiles from  the
	      sample are displayed.

       TTL (hops) information
	      As  a  packet  traverses the network, the	IP TTL field is	decre-
	      mented each time the packet crosses a router. OWAMP has been de-
	      signed  to  collect  the	TTL  information from the packets. The
	      OWAMP sender sets	the TTL	of all outgoing	packets	 to  255.  The
	      OWAMP  receiver  retrieves  the  TTL from	the packet. The	normal
	      textual report uses this information to  report  the  number  of
	      hops  (number  of	 routers)  the packet traversed. The number of
	      distinct values is reported as well as the minimum  and  maximum
	      number  of  hops seen in the given session.  The other reporting
	      formats just report raw TTL values as seen in the	packets.   (It
	      should be	noted that if the number of hops reported seems	unusu-
	      ally large, it probably means the	OWAMP sender was not  able  to
	      set  the	TTL  value correctly. The traceroute(1)	program	can be
	      used to verify what OWAMP	is reporting.)

	      Finally OWAMP reports the	amount of re-ordering it  observed.  A
	      description of the metric	used to	report this can	be found at:

	      Print a usage message and	exit.


Output Options:
       -a percentile_list
	      percentile_list indicates	the list of quantiles to  be  reported
	      out  in addition to median. This is done by specifying a list of
	      percentiles in a comma separated	string	(spaces	 are  not  al-
	      lowed).  Each  percentile	is indicated by	a floating point value
	      between 0.0 and 100.0.

	      This value is only used if reporting summary statistics.


       -b bucket_width
	      A	histogram of delays is created to compute the summary  statis-
	      tics.  (This is used to compute percentiles of delay such	as me-
	      dian.) The bucket_width indicates	the resolution of the bins  in
	      the  histogram.  This  value is specified	using a	floating point
	      value and	the units are seconds.

	      Because a	histogram to compute the median	(and other percentiles
	      of  delay)  the results can be misleading	if the bucket_width is
	      not appropriate. For example, if all of the delays in the	sample
	      are  smaller than	the value of bucket_width then the median will
	      be reported as bucket_width, a value that	is  greater  than  the
	      maximum  delay in	the sample. To avoid this, bucket_width	should
	      be picked	to be smaller than (max	- min).	The default value  was
	      selected to be reasonable	for most real network paths, it	is not
	      appropriate for tests to the localhost however.

	      This value is only used if reporting summary statistics.

		     0.0001 (100 usecs)

       -d dir
	      dir indicates the	directory in which to save  summary  files  if
	      the -p option is used.

		     (current working directory)

	      Print  summary  information in a more computer pars-able format.
	      Specifically, values are printed out in a	key/value style. Units
	      are seconds for all time values.

	      The -M option is ignored if -Q is	set.


       -N count
	      Number of	test packets to	put in sub-session summaries when com-
	      puting statistics	on owamp session data.

	      This option is used to break  down  the  summary	statistics  in
	      smaller  sample  sizes  than a complete owp file.	This is	useful
	      when breaking up very long running sessions.

	      This option is only used for statistical output,	and  therefore
	      has no effect on the -R output mode.

		     Unset. (complete files are	treated	as the sample size)

       -n units
	      units  indicates	what  units time values	should be reported in.
	      units is specified using a single	character specifying the units

	      The available units are:

	      'n'   nanoseconds	(ns)
	      'u'   microseconds (us)
	      'm'   milliseconds (ms)
	      's'   seconds (s)

	      This  is only used for the human-readable	summary	statistics and
	      the -v mode of reporting individual records. In  particular,  it
	      is not used for the -R or	-M output modes.


	      Save  output  summary information	into files instead of printing
	      it to STDOUT. Also, print	the names of the files to STDOUT.  The
	      files will be saved in the directory specified by	the -d option.

	      The summary filenames are	in the format:


	      STARTTIME	 and  ENDTIME are the start and	end timestamps for the
	      session or sub-session. The timestamps are ASCII	representation
	      of  64 bit integers with the high-order 32 bits representing the
	      number of	seconds	since Jan 1, 1900 and the  low-order  32  bits
	      representing  fractional	seconds.   The	FILETYPE is sum	for -M
	      summary files, and txt for the  default  human-readable  summary

	      This option is ignored if	the -R option is specified.


	      Suppress	the printing of	all summary statistics and human-read-
	      able individual delays (-v).


	      Print individual packet records one per line in the raw format:


	      SEQNO	 Sequence number.
	      SENDTIME	 Send timestamp.
	      SSYNC	 Sending system	synchronized (0	or 1).
	      SERR	 Estimate of SENDTIME error.
	      RECVTIME	 Receive timestamp.

	      RSYNC	 Receiving system synchronized (0 or 1).
	      RERR	 Estimate of RECVTIME error.
	      TTL	 TTL IP	field.

	      The timestamps are ASCII representation of 64 bit	integers  with
	      the  high-order 32 bits representing the number of seconds since
	      Jan 1, 1900 and the low-order 32	bits  representing  fractional
	      seconds.	Lost packet records are	indicated with a RECVTIME of 0
	      (zero).  The sequence number is simply an	integer. The error es-
	      timates  are  printed as floating-point numbers using scientific
	      notation.	TTL is the IP field from the packet.  The TTL in send-
	      ing  packets should be initialized to 255, so the	number of hops
	      the packet traversed can be computed. If the receiving  host  is
	      not  able	 to  determine the TTL field, this will	be reported as
	      255. (Some socket	API's do not expose the	TTL field.)

	      The -R option implies -Q.


	      Print delays for individual packet records. This option is  dis-
	      abled by the -Q and -R options.


       owstats datafile.owp

	      Report the summary statistics from the file datafile.owp.

       owstats -a 5,95 datafile.owp

	      Report  the summary statistics from the file datafile.owp. Also,
	      report the 5th and 95th percentile of delay as an	extra  statis-

       owstats -R datafile.owp

	      Print  out the packets in	a more machine readable	format with no
	      statistics computed at all.

       owstats -v datafile.owp

	      Show individual delays for each packet with  summary  statistics
	      printed at the end.

       owstats -M datafile.owp

	      Print  out  summary statistics in	a more computer	pars-able for-

       owstats datafile1.owp datafile2.owp datafile3.owp

	      Print out	summary	statistics for multiple	files.

       owampd(8),   owping(1),	 owfetch(1)   and   the	  OWAMP	   web	  site

       This  material  is based	in part	on work	supported by the National Sci-
       ence Foundation (NSF) under Grant No. ANI-0314723. Any opinions,	 find-
       ings  and conclusions or	recommendations	expressed in this material are
       those of	the author(s) and do not necessarily reflect the views of  the

	     $Date: 2009-01-07 14:38:08	-0500 (Wed, 07 Jan 2009) $  owstats(1)


Want to link to this manual page? Use this URL:

home | help