wiki:GEC9DemoVisualizer

Version 1 (modified by Mark Berman, 9 years ago) (diff)

Initial version

Rough Documentation for Visualizer

Intro

The demo visualizer is a basic visualization tool intended to help present the "under-the-hood" picture of computing and network resources included in a GENI slice.

System Requirements (user)

The visualizer is implemented in Microsoft Silverlight http://www.microsoft.com/silverlight/, which means it runs in your browser, using a plug-in that you'll have to download the first time you use it. You'll also need to run either Windows or MacOSX. (There is a linux-based version of Silverlight, called Moonlight, but it's not capable of running the visualizer.

Contact Mark or Niky for a pointer to your configuration's web page and credentials.

System Requirements (host)

Hosting an instance of the visualizer requires the following:

  • Web server (only tested with Apache, but others might work)
  • mySQL server
  • PHP
  • php-mysql

Configuring

The rest of this page discusses configuring an instance of the visualizer to display information from your slice.

The visualizer reads all of its information from a mySQL database. In general, the database and the web server hosting the visualizer are the same, but they don't have to be.

The following tables must appear in your database to run the visualizer:

  • The nodes table contains information about things in your topology that have point locations. Typically, these are computers, switches, etc.
  • The links table contains information about point-to-point links in your topology.
  • The visuals table is probably the key table for the visualizer. It contains an entry for each item that you wish to have appear in your visualization.
  • The status table is used to alter the appearance of rendered items in your visualization. These changes can help draw the viewer's attention or indicate the status of assets in your system.

In addition, your database may contain:

  • The statistics table stores dynamic instrumentation and measurement results, which are displayed as dynamically updated graphs, text, etc. You may choose to use this table or any other table accessible to the visualizer as the location for your I&M data.

Schema information for these tables is presented and explained below.

Performance note: The status table is expected to experience moderately frequent updates to its status field. The statistics table (or whatever table you use to hold your I&M data) is expected to experience frequent row insertions and modifications. The nodes, links, and visuals tables are periodically re-fetched by the visualizer, however, they are not expected to change frequently. Your visualization performance may suffer from many high-speed updates to these tables.

Nodes

mysql> describe nodes;
+-----------+---------------+------+-----+---------+----------------+
| Field     | Type          | Null | Key | Default | Extra          |
+-----------+---------------+------+-----+---------+----------------+
| id        | int(11)       | NO   | PRI | NULL    | auto_increment | 
| name      | varchar(1000) | NO   |     |         |                | 
| latitude  | double        | YES  |     | NULL    |                | 
| longitude | double        | YES  |     | NULL    |                | 
| type      | varchar(1000) | YES  |     | NULL    |                | 
| icon      | varchar(1000) | YES  |     | NULL    |                | 
+-----------+---------------+------+-----+---------+----------------+
6 rows in set (0.00 sec)

In the nodes table:

  • id is the primary key
  • name is a string that's used to refer to the node. It should be unique.
  • latitude and longitude give the location of the node
  • type is currently unused
  • icon is the URL for an image that may be used to represent the node. It is only used if you create a visual with infoType=icon naming this node and can safely be null otherwise. If you have icons that you would like to use, please provide them to Mark and Niky, and we'll include them in the server-side distro, so you can refer to them with a relative URL like images/myimage.png. An absolute URL should work too.

You need to list in this table any nodes referenced in your visuals.

mysql> describe links;
+------------+--------------+------+-----+---------+----------------+
| Field      | Type         | Null | Key | Default | Extra          |
+------------+--------------+------+-----+---------+----------------+
| id         | int(11)      | NO   | PRI | NULL    | auto_increment | 
| name       | varchar(200) | NO   |     |         |                | 
| sourceNode | varchar(200) | NO   |     |         |                | 
| destNode   | varchar(200) | NO   |     |         |                | 
+------------+--------------+------+-----+---------+----------------+
4 rows in set (0.00 sec)

In the links table:

  • id is the primary key
  • name is a string that's used to refer to the node. It should be unique.
  • sourceNode and destNode give the endpoints of the link. They must match the name field of entries in the nodes table.

The links table is lightly used in the visualizer. You'll really only have to use it at all if you want to position one of your visuals along a link somewhere. A visual with objType=link and objName=<name> is anchored at a position midway between the sourceNode and destNode locations.

Visuals

mysql> describe visuals;
+------------------+--------------+------+-----+---------+----------------+
| Field            | Type         | Null | Key | Default | Extra          |
+------------------+--------------+------+-----+---------+----------------+
| id               | int(11)      | NO   | PRI | NULL    | auto_increment | 
| sliceName        | varchar(200) | NO   |     |         |                | 
| name             | varchar(200) | NO   | UNI |         |                | 
| subSlice         | varchar(200) | YES  |     | NULL    |                | 
| sequence         | int(11)      | YES  |     | NULL    |                | 
| infoType         | varchar(10)  | YES  |     | NULL    |                | 
| objType          | varchar(20)  | YES  |     | NULL    |                | 
| objName          | varchar(200) | YES  |     | NULL    |                | 
| statType         | varchar(20)  | YES  |     | NULL    |                | 
| statHistory      | int(11)      | YES  |     | NULL    |                | 
| minValue         | double       | YES  |     | NULL    |                | 
| maxValue         | double       | YES  |     | NULL    |                | 
| statQuery        | varchar(500) | YES  |     | NULL    |                | 
| statusHandle     | varchar(100) | YES  |     | NULL    |                | 
| renderAttributes | varchar(500) | YES  |     | NULL    |                | 
+------------------+--------------+------+-----+---------+----------------+
15 rows in set (0.00 sec)

Each row in the visuals table (except for a map pseudo-visual) represents a single object displayed in your visualization. The visual type of the object (text label, line graph, icon, etc.) is indicated by the value of the infoType column.

In the visuals table:

  • id is the primary key
  • sliceName is a string naming your experiment or slice. If you are managing multiple visualization configurations out of a single database, you can use this field to distinguish between them. If you have only one configuration in your database (the default for GEC9 demos), all your visuals can have the same sliceName.
  • name is a unique string naming this visual.
  • subSlice is a string identifying a subset of the visuals in your slice. It is only used by popup windows generated by a user clicking on a zoomButton object.
  • sequence is an integer indicating the vertical stacking order of multiple visuals anchored to the same object on the map. Visuals are stacked from top to bottom in ascending order by sequence number.
  • infoType indicates the type of object to be displayed. Recognized values are listed below. For additional information, see below.
    • Static visuals
      • map is a pseudo-object that establishes the parameters of the overall map display
      • label places a text label at a point on the map
      • icon places an icon at a point on the map
      • zoomButton places a button at a point on the map. Clicking the button creates a popup window with an inset map.
      • point places a star-shaped marker at a point on the map.
      • arc draws a dashed path connecting multiple points on the map. Arcs support animation to indicate data flow.
    • Dynamic data visuals
      • scalar presents a real-valued statistic as a horizontal bar
      • scalarText presents a real-valued statistic as text
      • usageGrid presents an integer-valued statistic as a color-coded grid, useful for showing "m of n" assets in use.
      • lineGraph presents real-values time series data as a line graph.
  • objType and objName specify a node or link from the nodes or links table. The location of this object is used to anchor the visual on the map. The pair objType and objName must name an object, unless the visual is of infoType map.
  • statType is used to label data in dynamic data visuals.
  • statHistory indicates the number of past data point plotted in a lineGraph visual.
  • minValue and maxValue indicate the range of values corresponding to 'full' and 'empty' in a scalar visual. (They should also name the limits of the Y axis in a lineGraph object, but they don't.)
  • statQuery is an SQL query that is periodically executed to generate the data plotted in a dynamic data visual.
  • statusHandle is a string that names an entry in the status table.
  • renderAttributes is a string containing a comma-separated list of attribute value pairs affecting the display of the visual. For additional information see below.

The columns you need to populate depend on the infoType of the visual, as shown in this table.

infoType Visual Required settings Optional settings
map No object displayed. Map settings established None renderAttributes
label Text label objType, objName statusHandle, renderAttributes
icon Icon objType, objName statusHandle, renderAttributes
zoomButton Button to create inset map objType, objName, zoomTarget attribute in renderAttributes statusHandle, renderAttributes
point Star objType, objName statusHandle, renderAttributes
arc Dashed line objType, objName, datapath attribute in renderAttributes statusHandle, renderAttributes
scalar Dynamic measurement as horizontal bar objType, objName, minValue, maxValue, statType (label for bar), statQuery (see below) statusHandle, renderAttributes
scalarText Dynamic measurement as text objType, objName, statType (label for text), statQuery (see below) statusHandle, renderAttributes
usageGrid Dynamic measurement as colored grid objType, objName, statType (label for grid), statQuery (see below), maxValue statusHandle, renderAttributes
lineGraph Time series line graph objType, objName, statType (label for legend), statQuery (see below) statusHandle, renderAttributes

Status

mysql> describe status;
+-----------+--------------+------+-----+---------+----------------+
| Field     | Type         | Null | Key | Default | Extra          |
+-----------+--------------+------+-----+---------+----------------+
| id        | int(11)      | NO   | PRI | NULL    | auto_increment | 
| sliceName | varchar(200) | YES  |     | NULL    |                | 
| handle    | varchar(100) | YES  |     | NULL    |                | 
| status    | varchar(20)  | YES  |     | NULL    |                | 
+-----------+--------------+------+-----+---------+----------------+
4 rows in set (0.00 sec)

The intent of the status table is to change the appearance of parts of your visualization under application program control. Typically, changing the status of an item will trigger an animation affecting its appearance on the display.

In the status table:

  • id is the primary key
  • sliceName is a string naming your experiment or slice, as in the visuals table.
  • handle is a string indicating which visuals will be affected by changes to the status column. Any visuals whose statusHandle column matches handle are affected.
  • status names the current status of the visual(s) identified by handle. Recognized values include, but are not limited to, the following:
    • normal - visual is displayed normally
    • hidden - visual is not visible
    • alert - visual background flashes red (compatible with all visuals except arc)
    • throb - visual flashes on and off
    • rainbow - visual background displays different colors (not recommended - looks too much like alert for my taste)
    • forward (arc only) - dashed line crawls in the forward direction (from first item in datapath attribute toward last)
    • backward (arc only) - dashed line crawls in the backward direction
    • balls-forward (arc only) - animated balls traverse the path in the forward direction
    • balls-backward (arc only) - animated balls traverse the path in the backward direction
    • balls-both (arc only) - animated balls traverse the path in both the forward and backward directions

Statistics

mysql> describe statistics;
+-------+--------------+------+-----+---------+----------------+
| Field | Type         | Null | Key | Default | Extra          |
+-------+--------------+------+-----+---------+----------------+
| id    | int(11)      | NO   | PRI | NULL    | auto_increment | 
| stat  | varchar(100) | YES  |     | NULL    |                | 
| time  | datetime     | YES  |     | NULL    |                | 
| value | float        | YES  |     | NULL    |                | 
+-------+--------------+------+-----+---------+----------------+
4 rows in set (0.00 sec)

The statistics table is optional, but it is provided to facilitate composing queries that will conveniently feed data to your dynamic data visuals, when used in this way, each row names a single measurement value, as follows:

  • id is the primary key
  • stat is a string naming a data series
  • time is the time at which the measurement is made
  • value is the real-valued measurement datum

So, as an example, if you wish to collect network utilization along the link from nodeA to nodeB and display the data as a line graph, you might create a lineGraph visual like this:

  • id = whatever
  • sliceName = sample
  • name = A-B-utilization-graph
  • subSlice = NULL (or subslice name)
  • sequence = whatever
  • infoType = lineGraph
  • objType = link
  • objName = nodeA-nodeB (must match name column in links table)
  • statType = Mbps (will appear as label in graph legend)
  • statHistory = 40
  • minValue = NULL
  • maxValue = NULL
  • statQuery = SELECT time, value FROM statistics WHERE stat='nodeA-nodeB' ORDER BY time DESC LIMIT 40
  • statusHandle = A-B-utilization-graph (or NULL, if you don't want to animate this graph)
  • renderAttributes = NULL

You may also be using the GEC9_demos database for your visualization. That's where we're gathering selected switch statistics for several demos. A query referencing that database might look like this.

select timestamp as time, data_value as value from GEC9_demos.GeniMeasurementDataItem where data_type = 1 and data_source = 7 order by time desc limit 40

RenderAttributes

The renderAttributes column provides control of the appearance and layout of your visualization. Recall that renderAttributes is a comma-separated list of attribute-value pairs like this:

attribute1=value1,attribute2=value2

The attribute names are case-insensitive. Values are case-sensitive.

The effect of attributes are explained in this table.

Attribute Visual Type Values Effect
width All but point and arc Number Specify width of visual
height All but point and arc Number Specify height of visual
alignment All but arc "center" (default), "top", "bottom", "left", "right", "topleft", "topright", "bottomleft", "bottomright" Specify where visual is anchored on map
xoffset All Number Specify horizontal offset (4th quadrant pixels) from map location to visual anchor point
yoffset All Number Specify vertical offset (4th quadrant pixels) from map location to visual anchor point
datapath arc colon separated list of names of visuals Specify path followed by arc (e.g. 'datapath=vis1:vis2:vis3' indicates a path beginning at the anchor point of vis1, passing through vis2, and terminating at vis3)
text Label String Text to display for label (default is object name)
thickness arc Number (default 5) Thickness of arc
background All but arc Color name Background color of visual (not working - planned improvement, but don't count on it)