= 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. === Links === {{{ 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= 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 [#infoType 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 [#RenderAttributes 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 and 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 || || stringformat || scalarText || String || Value is used in c# string.format to format a double value. Examples available at [http://www.csharp-examples.net/string-format-double/]. For example, stringFormat={0:0.00} formats a number with two decimal places. ('''in beta''' coming soon) || || background || All but arc || Color name || Background color of visual ('''not working''' - planned improvement, but don't count on it) ||