nws - Howto use the Network Weather Service API.

nws

This man page briefly explain how to use the Network Weather Service (NWS) API. We will provide few example upon which you can build your own program that interface with NWS. We assume there is already a NWS system in place (nws_nameserver(1), nws_memory(1) and nws_sensor(1)).

To be able to access the NWS API you need to include the nws_api.h header file and compile with -llibnws.a option to include the library.

Currently NWS provides the following header file:

nws_api.h this is the main and only header file to access NWS. If before the include statement NWSAPI_SHORTNAMES is defined, shorted naming of the functions can be used (e.g. NWSAPI_GetMeasurements can be referenced as GetMeasurements). In the EXAMPLES sections there are few examples on how to use the functions here defined.

The NWS API uses few data structures: here there is a list of the most important one;

NWSAPI_HostSpec defines a hostname port pair: we expect to have a NWS component listening on hostname:port.

NWSAPI_SeriesSpec a description of a NWS experiment series. The series is uniquely identified by a source machine, a destination machine (ignored for single machine resource) and a resource name.

NWSAPI_Measurement is a structure containing timeStamp and measurement (both double). It is a single measurement as returned by an experiment.

NWSAPI_Forecast is a structure containing forecast, error, and methodUsed (forecast and error are double). It is a single forecast returned by a forecaster (identified by the index methodUsed ) with an estimate of its precision.

NWSAPI_ForecastCollection is a structure containing a collection of the best forecastes based on MAE (mean absolute error) and MSE (mean square error). It contains measurement (inclued here for convenience) and forecasts an array of 2 NWSAPI_Forecast (first one is MAE forecast and the second is MSE forecast).

NWSAPI_ForecastState this is an opaque structure used to keep the state of the forecaster. You shouln't modify it directly nor read it.

NWSAPI_ObjectSet it is a typedef to char *. NWSAPI_ObjectSet are used when retrieving registration from a nameserver or such: there are specific NWS functions to deal with NWSAPI_ObjectSet.

NWSAPI_Object it is a typedef to char *. NWSAPI_Objest contains NwsAttribute and are contained in NWSAPI_ObjectSet. There are specific NWS functions to deal with NWSAPI_Object.

NWSAPI_ObjectSet it is a typedef to char *. NWSAPI_NwsAttribute is a pair of tag:value and are usually contained in NWSAPI_Object. There are specific NWS functions to deal with NWSAPI_NwsAttribute.

Here we list most of the functions defined in the NWS API with a brief explanation on their functionality. See EXAMPLES for examples on how to use them. Here we use the short names (that is without the NWSAPI_ if we had defined NWSAPI_SHORTNAMES).

const HostSpec * MakeHostSpec (const char *host, Port machinePort) generate a HostSpec given a machine name and a port.

const SeriesSpec * MakeSeriesSpec (const char *sourceMachine, const char *destinationMachine, const char *seriesName); generate a SeriesSpec given a resource name and a source and destination machine.

const char * SeriesName (const SeriesSpec *whichSeries); contructs a series name given a SeriesSpec

const char * ForecasterMethodName (unsigned int methodIndex) returnes the name of the forecasting method corresponding to methodIndex (as found in a Forecast)

ForecatState * NewForecastState (); returns a new forecast state ready to be used by UpdateForecast (for example).

void FreeForecastState (ForecastState **state); free the memory associated with this forecaster state.

void UpdateForecastState (ForecastState *state, const Measurement *measurements, size_t howManyMeasurements, ForecastCollection *forecasts, size_t howManyForecasts); update the state of forecas given the howManyMeasurements ner measurements. If forecasts is not NULL, howManyForecasts are returned.

void UpdateForecast (ForecastState *state, const Measurement *measurements, size_t howManyMeasurements,); similar to UpdateForecastState but doens't return any forecast, just update the forecaster state.

int GetForecasts (const char *seriesName, double sinceWhen, ForecastCollection *whereTo, size_t atMost, size_t *numberReturned); retrieves a time series of forecast collections for measurements of the series named seriesName that have been generated since sinceWhen and returns them in the atMost long array whereTo

It stores ths count od retrieved collections in numberedReturned if it is non-NULL. Return 1 if succesfull, else 0.

int GetForecast (const char *seriesName, ForecastCollection *whereTo); similar to GetForecasts, just return 1 forecastCollection.

int GetMeasurements (const char *seriesName, double sinceWhen, Measurement *whereTo, size_t atMost, size_t *numberReturned); retrieves up to atMost measurements for the series named seriesName that have been taken since sinceWhen (the most recent ones are returned).

Returns the measurements in the atMost ling array whereTo with the newest one in the first element. Stores the count of retrieved measurements in numberReturned if non-NULL. Returns 1 on success, 0 else.

int GetMeasurment (const char *seriesName, Measurement *whereTo); similar to GetMeasurements but returns only the last measurement.

int UseMemory (const HostSpec *whichMemory); use whichMemory as NWS memory, that is as the repository for all the measurements. If not set, the interface will attempt to find the best NWS memory available for the required data.

Returns 1 if succesfull, else 0.

int UseNameServer (const HostSpec *whichNS) add whichNS to the NWS nameservers list to use. Needed when looking for registrations and information on the NWS deployment. You need to set at least one NWS nameserver before been able to GetMeasurements and GetForecasts etc...

If whichNS is NULL or the empty string, the list is reset.

Returns 1 if succesfull, else 0.

int GetNameServer (const HostSpec *whoToAsk, HostSpec *nameServer); contact the NWS host whoToAsk and returns the nameserver used by it in nameserver.

Returns 1 if succesfull, else 0.

int GetMemory (const HostSpec *whoToAsk, HostSpec *memory); contact the NWS host whoToAsk and returns the memory used by it in memory.

Returns 1 if succesfull, else 0.

int GetObjects (const char *filter, ObjectSet *whereTo); contact the nameserver (see UseNameServer() ) and retrieves the objects that matches filter.

Returns the restrieved objects in whereTo. After a succesful call, FreeObjectSet needs to be called on whereTo to free the memory. Returns 1 if succesfull, else 0.

void FreeObjectSet (ObjectSet *toBeFreed); free the memory used by toBeFreed.

Objecct NextObject (ObjectSet objects, Object current); returns the next NWS objects contained in objects after current object or the first object if NULL.

Returns NULL if no more objects are presents.

NwsAttribute NextNwsAttribute (Object object, NwsAttribute current); returns the next NWS attribute contained in object after current attribute or the first attribute if NULL.

Returns NULL if no more attribute are presents.

We will assume that a NWS system is already deployed with at least a nameserver (host NS.test.edu in the example), a NWS memory (host MEM.test.edu in the example) and two sensors (hosts ONE.test.edu and TWO.test.edu in the example). In the following examples all error checking is omitted and only the part relevant to NWS have been included to keep the code easy to follow.

The following example retrieves a list of hosts registered with the nameserver:

#define NWSAPI_SHORTNAMES
#include "nws_api.h"

HostSpec *NS; char filter[256]; ObjectSet objs; Object current; NwsAttribute attr; char *tmp, *tmp1;

/* let's instruct the interface to use the right nameserver */ NS = MakeHostSpec("NS.test.edu", 8090); UseNameServer(&NS);

/* create the right filter */ sprintf(filter, "objectclass=nwsHost");

/* query the NS */ GetObjects(filter, &objs)

/* now we can browse though the objects*/ for (current = NextObject(objs, NULL); current != NULL; current = NextObject(objs, current)) { /* now we can browse though the attribute*/ for (attr = NextNwsAttribute(current, NULL); attr != NULL; attr = NextNwsAttribute(current, attr)) { /* do some pretty printing */ tmp = NwsAttributeName_r(attr); tmp1 = NwsAttributeValue_r(attr); printf("%s: %s\n", tmp, tmp1); free(tmp); free(tmp1); } }

Of course one important feature of NWS is to report measurements and forecasts of specific resources. The following example extracts measurements and generate forecasts for a known nwsSeries (where the series name can be found querying the nws_nameserver -- see the previous example):

#define NWSAPI_SHORTNAMES
#include "nws_api.h"

char *series; SeriesSpec *spec; int howMany; HostSpec NS; /* how many measurement we retrieve */ #define HOW_MANY 20 Measurement meas[HOW_MANY]; ForecastCollection forecasts[HOW_MANY]; ForecastState *state;

/* let's instruct the interface to use the right nameserver */ NS = MakeHostSpec("NS.test.edu", 8090); UseNameServer(&NS);

/* get the series name: the right way is to query the nameserver to find * the right name of the series. For simplicity we build one here, * assuming that there is indeed such a series reigsterd with the * nameserver */ spec = MakeSeriesSpec("a.edu", "b.edu", "bandwidthTcp"); series = SeriesName(spec);

/* initialize the forecast state */ state = NewForecastState();

/* get the measurements */ if (!GetMeasurements(series, NWSAPI_BEGINNING_OF_TIME, meas, HOW_MANY, &howMany)) { printf("failed to retrieve measurements\n"); exit(0); }

/* we have howMany measurements: generate the forecasts now. */ UpdateForecastState(state, meas, howMany, forecasts, howMany);

/* ForecastCollection keeps a copy of the measurements handy : let's * print measurments and forecasts */ for (; howMany >= 0; howMany--) { printf("time %.5f measurement %.2f ", forecasts[howMany].measurement.timeStamp, forecasts[howMany].measurement.measurement) /* we use only the MAE forecasts here */ pritnf("forecast %.5f with error %.5f method used %s\n", forecasts[howMany].forecasts[NWSAPI_MAE_FORECAST].forecast, forecasts[howMany].forecasts[NWSAPI_MAE_FORECAST].error, MethodName(forecasts[howMany].forecasts[NWSAPI_MAE_FORECAST].methodUsed); }

/* free the memory associated with the forecast state */ FreeForecastState(&state);

Starting from version 2.11 of NWS, you can call directly GetForecasts without having the need of a forecaster process running. The previous code can then be written as:

#define NWSAPI_SHORTNAMES
#include "nws_api.h"

char *series; SeriesSpec *spec; int howMany; HostSpec NS; /* how many measurement we retrieve */ #define HOW_MANY 20 ForecastCollection forecasts[HOW_MANY];

/* let's instruct the interface to use the right nameserver */ NS = MakeHostSpec("NS.test.edu", 8090); UseNameServer(&NS);

/* get the series name: the right way is to query the nameserver to find * the right name of the series. For simplicity we build one here, * assuming that there is indeed such a series reigsterd with the * nameserver */ spec = MakeSeriesSpec("a.edu", "b.edu", "bandwidthTcp"); series = SeriesName(spec);

/* get the forecasts */ if (!GetForecasts(series, NWSAPI_BEGINNING_OF_TIME, forecasts, HOW_MANY, &howMany)) { printf("GetForecasts failed\n"); exit(0); }

/* ForecastCollection keeps a copy of the measurements handy : let's * print measurments and forecasts */ for (; howMany >= 0; howMany--) { printf("time %.5f measurement %.2f ", forecasts[howMany].measurement.timeStamp, forecasts[howMany].measurement.measurement) /* we use only the MAE forecasts here */ pritnf("forecast %.5f with error %.5f method used %s\n", forecasts[howMany].forecasts[NWSAPI_MAE_FORECAST].forecast, forecasts[howMany].forecasts[NWSAPI_MAE_FORECAST].error, MethodName(forecasts[howMany].forecasts[NWSAPI_MAE_FORECAST].methodUsed); }

Bugs list is at http://nws.cs.ucsb.edu.

NWS is an original idea of Rich Wolski Rich Wolski (rich@cs.ucsb.edu).

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

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

nws_sensor(1), nws_search(1), nws_nameserver(1), nws_memory(1), nws_extract(1)