.\"Created by graziano obertelli <graziano@cs.ucsb.edu>
.\"
.TH nws_extract 1 "September 27, 2002" "nws_extract"

.SH NAME
nws_extract \- extracts measurements and forecast from the  Network Weather Service

.SH SYNOPSIS
.B nws_extract
[-aS][-f fieldList][-h n][-M host][-n n][-N host][-t n][-w] resource [filter] host [host ...]

.SH DESCRIPTION
This manual page explains the 
.B nws_extract
program. You can use 
.B nws_extract 
to access the NWS measurements and forecasts (see 
.B EXAMPLES
for few examples).

This program extracts measurement data that had been generated by a 
.B nws_sensor(1)
instance and then stored by a
.B nws_memory(1)
istance. We suggest that to take full advantage of NWS, you should start a
.B nws_nameserver(1)
and multiple sensors.

.B
.SH OPTIONS
.B -a
.RS
Treat all listed machines as experiment sources. By default, the program
treats the first machine as the experiment source and the others as
experiment destinations. Use this switch to get information about all
pairs of machines.
.RE

.BI -f\  fieldlist
.RS
Specifies which information you would like displayed. fieldList is a
comma-delimited list of forecast field names that you would like to see.
The recognized names are 

.B destination
.RS
the destination host (meaningful only for multi-host measurements as
latency and bandwidth)
.RE

.B source
.RS
the source host
.RE

.B resource
.RS
the name of the resource measured
.RE

.B measurement
.RS
the values measured by the 
.B nws_sensor(1)
.RE

.B time
.RS
the time at which the measurement is taken (as measured by the
.B nws_sensor(1)
.RE

.B mae_error, mae_forecast, mse_error, mse_forecast, mse_method
.RS
these are the various forecasts, the computed errors and the method used
in the computation (where mae is mean absolute error and mse is mean squared
error).
.RE
.RE

.BI -N\  host
.RS
use
.I host
as the NWS nameserver to contact to discover if and where the data are
available.
.RE

.BI -M\  host
.RS
use
.I host
as the NWS memory to contact to retrieve the NWS measurements. When this
options is set, no NWS nameserver is contacted (that is -N is discarded
if specified).
.RE

.BI -w
.RS
continuosly display informations. The new informations are displaied as
soon as the sensors register them. You need to ctrl-C to stop the
program.
.RE

.BI -h\ n
.RS
Specifies the frequency of the header.
.RE

.BI -n\ howmany
.RS
display 
.I howmany
lines of output (by default 20 lines).
.RE

.BI -t\ time
.RS
display data starting from
.I time
instead of from the most recent going back how many line you asked for
(by default 20 lines).
.RE

.BI -S
.RS
there is no resource/filter/host(s) but only series name. The series are
not checked against a nameserver (-N options isn't used) but a memory
needs to be specified (-M required). 
.RE

.BI resource
.RS
specifies which kind of measurements you want. 
.I resource
is typically (but may depends on compile options) bandwidthTcp,
latencyTcp, availableCPU, currentCPU (to get the list of available
resources for a specific host you can use
.B nws_search(1)
with a filter like '&(objectclass=nwsActivity)(name=host*)' where 
.I host
is the host you are interested in.
.RE

.BI filter
.RS
this is to be used in conjunction with the -N options. It specifies a
filter (as defined in 
.B nws_search(1)
) to be added in the search of the right series: usefull if you have
multiple series amongs the hosts. 
.I filter
has to be between (). Hint you may need to quote the filter to prevent
shell expansion.
.RE 

.BI host\  [host...]
.RS
these are the lists of hosts for which you are interested in getting the
measurements. For some resource (say latencyTcp) you need at least 2
hosts.
.I host
can be of the form hostname:port in case the sensors are running on non
standard ports.
.RE

.SH EXAMPLES
Let's assume there is 
.B nws_nameserver(1)
running on machine A and that there are 2 
.B nws_sensor(1)
running on machine A and B.

.RS
nws_extract -N A avail B
.RE

will extract data for availableCPU for machine B and

.RS
nws_extract -N A avail -f time,measurement B
.RE

will do the same but prints out only the timestamps and the measurements
(no forecasts).

If you have multiple cliques running between A and B, say with different
experiment size (one with the default 64 the other wiht 512) you can
query for all the bandwidth experiments

.RS
nws_extract -N A band A B
.RE

or for only the 512 data

.RS
nws_extract -N A band "(size=512)" A B
.RE


.SH BUGS
.P
Bugs list is at 
.UR http://nws.cs.ucsb.edu
http://nws.cs.ucsb.edu.
.UE

.SH AUTHOR
NWS is an original idea of Rich Wolski Rich Wolski (rich@cs.ucsb.edu) who
came up with the original
.B nws_memory.

.P 
Neil Spring, Jim Hayes (jhayes@cs.ucsd.edu) and Martin Swany maintained
and enhanced it. 

.P 
Graziano Obertelli (graziano@cs.ucsb.edu) currently maintains NWS and
wrote this man page.

.SH SEE ALSO
.BR nws_sensor(1),
.BR nws_search(1),
.BR nws_nameserver(1),
.BR nws_extract(1)
.BR halt_activity(1)
.BR start_activity(1)