Changes between Initial Version and Version 1 of GEC9DemoVisualizer


Ignore:
Timestamp:
10/18/10 22:32:27 (9 years ago)
Author:
Mark Berman
Comment:

Initial version

Legend:

Unmodified
Added
Removed
Modified
  • GEC9DemoVisualizer

    v1 v1  
     1= Rough Documentation for Visualizer =
     2
     3== Intro ==
     4
     5The 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.
     6
     7== System Requirements (user) ==
     8
     9The 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.
     10
     11Contact Mark or Niky for a pointer to your configuration's web page and credentials.
     12
     13== System Requirements (host) ==
     14
     15Hosting an instance of the visualizer requires the following:
     16
     17 * Web server (only tested with Apache, but others might work)
     18 * mySQL server
     19 * PHP
     20 * php-mysql
     21
     22== Configuring ==
     23
     24The rest of this page discusses configuring an instance of the visualizer to display information from your slice.
     25
     26The 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.
     27
     28The following tables must appear in your database to run the visualizer:
     29
     30 * The '''nodes''' table contains information about things in your topology that have point locations.  Typically, these are computers, switches, etc.
     31
     32 * The '''links''' table contains information about point-to-point links in your topology.
     33
     34 * 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.
     35
     36 * 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.
     37
     38In addition, your database may contain:
     39
     40 * 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.
     41
     42Schema information for these tables is presented and explained below.
     43
     44Performance 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.
     45
     46=== Nodes ===
     47{{{
     48mysql> describe nodes;
     49+-----------+---------------+------+-----+---------+----------------+
     50| Field     | Type          | Null | Key | Default | Extra          |
     51+-----------+---------------+------+-----+---------+----------------+
     52| id        | int(11)       | NO   | PRI | NULL    | auto_increment |
     53| name      | varchar(1000) | NO   |     |         |                |
     54| latitude  | double        | YES  |     | NULL    |                |
     55| longitude | double        | YES  |     | NULL    |                |
     56| type      | varchar(1000) | YES  |     | NULL    |                |
     57| icon      | varchar(1000) | YES  |     | NULL    |                |
     58+-----------+---------------+------+-----+---------+----------------+
     596 rows in set (0.00 sec)
     60}}}
     61
     62In the '''nodes''' table:
     63 * '''id''' is the primary key
     64 * '''name''' is a string that's used to refer to the node.  It should be unique.
     65 * '''latitude''' and '''longitude''' give the location of the node
     66 * '''type''' is currently unused
     67 * '''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.
     68
     69You need to list in this table any nodes referenced in your visuals.
     70
     71=== Links ===
     72{{{
     73mysql> describe links;
     74+------------+--------------+------+-----+---------+----------------+
     75| Field      | Type         | Null | Key | Default | Extra          |
     76+------------+--------------+------+-----+---------+----------------+
     77| id         | int(11)      | NO   | PRI | NULL    | auto_increment |
     78| name       | varchar(200) | NO   |     |         |                |
     79| sourceNode | varchar(200) | NO   |     |         |                |
     80| destNode   | varchar(200) | NO   |     |         |                |
     81+------------+--------------+------+-----+---------+----------------+
     824 rows in set (0.00 sec)
     83}}}
     84
     85In the '''links''' table:
     86 * '''id''' is the primary key
     87 * '''name''' is a string that's used to refer to the node.  It should be unique.
     88 * '''sourceNode''' and '''destNode''' give the endpoints of the link.  They must match the '''name''' field of entries in the '''nodes''' table.
     89
     90The '''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.
     91
     92=== Visuals ===
     93{{{
     94mysql> describe visuals;
     95+------------------+--------------+------+-----+---------+----------------+
     96| Field            | Type         | Null | Key | Default | Extra          |
     97+------------------+--------------+------+-----+---------+----------------+
     98| id               | int(11)      | NO   | PRI | NULL    | auto_increment |
     99| sliceName        | varchar(200) | NO   |     |         |                |
     100| name             | varchar(200) | NO   | UNI |         |                |
     101| subSlice         | varchar(200) | YES  |     | NULL    |                |
     102| sequence         | int(11)      | YES  |     | NULL    |                |
     103| infoType         | varchar(10)  | YES  |     | NULL    |                |
     104| objType          | varchar(20)  | YES  |     | NULL    |                |
     105| objName          | varchar(200) | YES  |     | NULL    |                |
     106| statType         | varchar(20)  | YES  |     | NULL    |                |
     107| statHistory      | int(11)      | YES  |     | NULL    |                |
     108| minValue         | double       | YES  |     | NULL    |                |
     109| maxValue         | double       | YES  |     | NULL    |                |
     110| statQuery        | varchar(500) | YES  |     | NULL    |                |
     111| statusHandle     | varchar(100) | YES  |     | NULL    |                |
     112| renderAttributes | varchar(500) | YES  |     | NULL    |                |
     113+------------------+--------------+------+-----+---------+----------------+
     11415 rows in set (0.00 sec)
     115}}}
     116
     117Each 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.
     118
     119In the '''visuals''' table:
     120
     121 * '''id''' is the primary key
     122 * '''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'''.
     123 * '''name''' is a unique string naming this visual.
     124 * '''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.
     125 * '''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.
     126 * '''infoType''' indicates the type of object to be displayed.  Recognized values are listed below.  For additional information, see [#infoType below].
     127  * Static visuals
     128   * ''map'' is a pseudo-object that establishes the parameters of the overall map display
     129   * ''label'' places a text label at a point on the map
     130   * ''icon'' places an icon at a point on the map
     131   * ''zoomButton'' places a button at a point on the map.  Clicking the button creates a popup window with an inset map.
     132   * ''point'' places a star-shaped marker at a point on the map.
     133   * ''arc'' draws a dashed path connecting multiple points on the map.  Arcs support animation to indicate data flow.
     134  * Dynamic data visuals
     135   * ''scalar'' presents a real-valued statistic as a horizontal bar
     136   * ''scalarText'' presents a real-valued statistic as text
     137   * ''usageGrid'' presents an integer-valued statistic as a color-coded grid, useful for showing "m of n" assets in use.
     138   * ''lineGraph'' presents real-values time series data as a line graph.
     139 * '''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.
     140 * '''statType''' is used to label data in dynamic data visuals.
     141 * '''statHistory''' indicates the number of past data point plotted in a lineGraph visual.
     142 * '''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.)
     143 * '''statQuery''' is an SQL query that is periodically executed to generate the data plotted in a dynamic data visual.
     144 * '''statusHandle''' is a string that names an entry in the '''status''' table.
     145 * '''renderAttributes''' is a string containing a comma-separated list of attribute value pairs affecting the display of the visual.  For additional information see [#RenderAttributes below].
     146
     147The columns you need to populate depend on the infoType of the visual, as shown in this table.
     148
     149|| '''infoType''' || '''Visual''' || '''Required settings''' || '''Optional settings''' ||
     150|| map || No object displayed. Map settings established || None || '''renderAttributes''' ||
     151|| label || Text label || '''objType''', '''objName''' || '''statusHandle''', '''renderAttributes''' ||
     152|| icon || Icon || '''objType''', '''objName''' ||  '''statusHandle''', '''renderAttributes''' ||
     153|| zoomButton || Button to create inset map ||   '''objType''', '''objName''', '''zoomTarget''' attribute in '''renderAttributes''' ||  '''statusHandle''', '''renderAttributes''' ||
     154|| point || Star || '''objType''', '''objName''' ||  '''statusHandle''', '''renderAttributes''' ||
     155|| arc || Dashed line ||  '''objType''', '''objName''', '''datapath''' attribute in '''renderAttributes''' || '''statusHandle''', '''renderAttributes''' ||
     156|| scalar || Dynamic measurement as horizontal bar || '''objType''', '''objName''', '''minValue''', '''maxValue''', '''statType''' (label for bar), '''statQuery''' (see below) || '''statusHandle''', '''renderAttributes''' ||
     157|| scalarText || Dynamic measurement as text || '''objType''', '''objName''', '''statType''' (label for text), '''statQuery''' (see below) || '''statusHandle''', '''renderAttributes''' ||
     158|| usageGrid || Dynamic measurement as colored grid || '''objType''', '''objName''', '''statType''' (label for grid), '''statQuery''' (see below), '''maxValue''' || '''statusHandle''', '''renderAttributes''' ||
     159|| lineGraph || Time series line graph || '''objType''', '''objName''', '''statType''' (label for legend), '''statQuery''' (see below) || '''statusHandle''', '''renderAttributes''' ||
     160
     161
     162=== Status ===
     163{{{
     164mysql> describe status;
     165+-----------+--------------+------+-----+---------+----------------+
     166| Field     | Type         | Null | Key | Default | Extra          |
     167+-----------+--------------+------+-----+---------+----------------+
     168| id        | int(11)      | NO   | PRI | NULL    | auto_increment |
     169| sliceName | varchar(200) | YES  |     | NULL    |                |
     170| handle    | varchar(100) | YES  |     | NULL    |                |
     171| status    | varchar(20)  | YES  |     | NULL    |                |
     172+-----------+--------------+------+-----+---------+----------------+
     1734 rows in set (0.00 sec)
     174}}}
     175
     176The 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.
     177
     178In the '''status''' table:
     179
     180 * '''id''' is the primary key
     181 * '''sliceName''' is a string naming your experiment or slice, as in the '''visuals''' table.
     182 * '''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.
     183 * '''status''' names the current status of the visual(s) identified by '''handle'''.  Recognized values include, but are not limited to, the following:
     184  * ''normal'' - visual is displayed normally
     185  * ''hidden'' - visual is not visible
     186  * ''alert'' - visual background flashes red (compatible with all visuals except '''arc''')
     187  * ''throb'' - visual flashes on and off
     188  * ''rainbow'' - visual background displays different colors (not recommended - looks too much like ''alert'' for my taste)
     189  * ''forward'' ('''arc''' only) - dashed line crawls in the forward direction (from first item in '''datapath''' attribute toward last)
     190  * ''backward'' ('''arc''' only) - dashed line crawls in the backward direction
     191  * ''balls-forward'' ('''arc''' only) - animated balls traverse the path in the forward direction
     192  * ''balls-backward'' ('''arc''' only) - animated balls traverse the path in the backward direction
     193  * ''balls-both'' ('''arc''' only) - animated balls traverse the path in both the forward  and backward directions
     194
     195=== Statistics ===
     196{{{
     197mysql> describe statistics;
     198+-------+--------------+------+-----+---------+----------------+
     199| Field | Type         | Null | Key | Default | Extra          |
     200+-------+--------------+------+-----+---------+----------------+
     201| id    | int(11)      | NO   | PRI | NULL    | auto_increment |
     202| stat  | varchar(100) | YES  |     | NULL    |                |
     203| time  | datetime     | YES  |     | NULL    |                |
     204| value | float        | YES  |     | NULL    |                |
     205+-------+--------------+------+-----+---------+----------------+
     2064 rows in set (0.00 sec)
     207}}}
     208
     209The '''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:
     210
     211 * '''id''' is the primary key
     212 * '''stat''' is a string naming a data series
     213 * '''time''' is the time at which the measurement is made
     214 * '''value''' is the real-valued measurement datum
     215
     216So, 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:
     217
     218 * '''id''' = whatever
     219 * '''sliceName''' = sample
     220 * '''name''' = A-B-utilization-graph
     221 * '''subSlice''' = NULL (or subslice name)
     222 * '''sequence''' = whatever
     223 * '''infoType''' = lineGraph
     224 * '''objType''' = link
     225 * '''objName''' = nodeA-nodeB (must match '''name''' column in '''links''' table)
     226 * '''statType''' = Mbps (will appear as label in graph legend)
     227 * '''statHistory''' = 40
     228 * '''minValue''' = NULL
     229 * '''maxValue''' = NULL
     230 * '''statQuery''' = SELECT time, value FROM statistics WHERE stat='nodeA-nodeB' ORDER BY time DESC LIMIT 40
     231 * '''statusHandle''' = A-B-utilization-graph (or NULL, if you don't want to animate this graph)
     232 * '''renderAttributes''' = NULL
     233
     234You 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.
     235
     236{{{
     237select 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
     238}}}
     239
     240
     241== RenderAttributes ==
     242
     243The '''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:
     244
     245{{{
     246attribute1=value1,attribute2=value2
     247}}}
     248
     249The attribute names are case-insensitive.  Values are case-sensitive.
     250
     251The effect of attributes are explained in this table.
     252
     253|| '''Attribute''' || '''Visual Type''' || '''Values''' || '''Effect''' ||
     254|| width || All but point and arc || Number || Specify width of visual ||
     255|| height || All but point and arc || Number || Specify height of visual ||
     256|| alignment || All but arc || "center" (default), "top", "bottom", "left", "right", "topleft", "topright", "bottomleft", "bottomright" || Specify where visual is anchored on map ||
     257|| xoffset || All || Number || Specify horizontal offset (4th quadrant pixels) from map location to visual anchor point ||
     258|| yoffset || All || Number || Specify vertical offset (4th quadrant pixels) from map location to visual anchor point ||
     259|| 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) ||
     260|| text || Label || String || Text to display for label (default is object name) ||
     261|| thickness || arc || Number (default 5) || Thickness of arc ||
     262|| background || All but arc || Color name || Background color of visual ('''not working''' - planned improvement, but don't count on it) ||