Content-type: text/html Manpage of ghabitat

ghabitat

Section: Habitat (1)
Updated: 0.99.3
Index Return to Main Contents
 

NAME

ghabitat - Gtk+ Graphical interface to Habitat suite  

SYNTAX

ghabitat [-c <purl>] [-C <cfcmd>] [-e <fmt>] [-dDhsv]  

DESCRIPTION

This is the standard graphical interface for Habitat, including the ability to view repository data provided by Harvest.

When the tool starts, a check is made for the existence of the local collection agent, clockwork. If it is not running, the user is asked if they wish to run it and what starting behaviour they wish in the future.

In appearance, clockwork resembles that of a file manager, with choices on the left and visualisation on the right. If files or other data sources have been opened before, then their re-opening is attempted by ghabitat and will be placed under the my files node in the tree.

See DATA SOURCES section for details of the data that can be viewed, NAVIGATION for how to interpret the data structures and VISUALISATION for how to examine the data once displayed.

This GUI requires Xwindows to run, use other front ends or command line tools if you do not have that facility.  

OPTIONS

-c <purl>
Append user configuration data from the route <purl>, rather than the default file ~/.habrc.
-C <cfcmd>
Append a list of configuration directives from <cfcmd>, separated by semicolons.
-d
Place ghabitat in diagnositc mode, giving an additional level of logging and sending the text to stderr rather than the default or configured destinations. In daemon mode, will send output to the controlling terminal.
-D
Place ghabitat in debug mode. As -d above but generating a great deal more information, designed to be used in conjunction with the source code. Also overrides normal outputs and will send the text to stderr. In daemon mode, will send output to the controlling terminal.
-e <fmt>
Change the logging output to one of eight preset alternative formats, some showing additional information. <fmt> must be 0-7. See LOGGING below.
-h
Print a help message to stdout and exit
-v
Print the version to stdout and exit
-s
Run in safe mode, which prevents ghabitat automatically loading data from files or over the network from peer machines or the repository. Use if ghabitat start up time is excessively long. Once started, all data resourcese can be loaded manually.
 

DATA SOURCES

Currently, data can be obtained from four types of sources:-

Storage file
The standard local data storage file known as a ringstore, which is a structured format using GDBM. Open it with File->Open or ^O and use the file chooser. The file will appear under my files in the choice tree.
Repository
Centralised data automatically appears under the repository node in the choice tree if the configuration directive is set to a valid location. The directive is route.sqlrs.geturl which must contain the URL of a repository output interface. (route.sqlrs.puturl works in the opposite direction for replication.)
Network data
Data for an individual machine can be read from the repository or a peer clockwork instance on another host. Select File->Host or ^H, type in the hostname and pick repository or host as a source. (Currently, host access is not fully implemented.) Your selection will appear under my hosts in the choice tree.
Route specification
Select File->Route or ^R and type the full route specification of the data source. This is the most generic way of addressing in habitat, encompassing all of the styles used above and more.

Files can be removed by selecting their entry from the list brought up with File->Close (^C).  

NAVIGATION

The repository source is special, in that the hierarchical nature of the group organisation is shown. To get to a machine, one needs to know its organisational location and traverse it in the tree. Whilst this aids browsing, one may wish to use the File->Host option to go directly to a machine.

Opening the data source trees will reveal the capabilities of the data source, which include the following:-

perf graphs
Performance data is retrieved in a time series and will display as a chart the visualisation section
perf data
Performance data presented in a textual form, encompassing tabular time-series data, key-data values or simple list. Visualisation is always in a table.
events
Text scanning, pattern matching and threshold breaching functionality is clustered under this node. The configuration tables are presented here along with the events and logs that have been generated.
logs
Logs and errors from running the jobs in clockwork
replication
Logs and state of the data replication to and from the repository
jobs
The job table that clockwork follows to collect and refine data
data
Contains all the data in the storage mechanism with out interpretation.

Under the performance nodes will be the available data collections, also known as rings. The names of these collections are decided when data is inserted into the storage. For example, sending data to the route tab:fred.ts,mydata and mounting it under ghabitat, will cause the data to appear here as mydata.

There are conventions for the names of standard probes, but they will only appear in a data store if their collection is configured in the job table (usually just uncommenting it: see clockwork(1)):-

sys
System data, such as cpu statistics and memory use. Labelled as system in choice tree
io
Disk statistics, such as read/write rates and performance levels. Labelled as storage in the choice tree
net
Network statistics, such as packets per second. Labelled as network in the choice tree
ps
Process table. This can contain a significant amount of data over time, so generally only the most significant or useful processes may be included. This is dependent on the configuration of the ps probe. Labelled as processes in the choice tree
names
A set of name-value pairs relating to the configuration of the operating system. Generally captured at start up only.

The final set of nodes below the ring names are a set of time scales by which to examine the data. These dictate how much data is extracted from the data source and generally the speed at which the data will be visualised. These are preset to useful values, commonly 5 minutes, 1 hour, 4 hours, 1 day, 7 days, 1 month, 3 months, 1 year, 3 years, etc.  

VISUALISATION

The right hand section of the window is used for visualisation. Its major uses are for charting and displaying tables.

When charting, the section is divided into several parts. The greatest is used for the graph itself, with other areas being used for curve selection, zooming and data scaling. If the data is multi-instance, such as with multiple disks, then a further area is added to control the number of instance graphs being displayed.

The standard sets of data, such as sys and io have default curves that are displayed when the graph is first drawn. The list of curves down the right hand side are buttons used to draw or remove data on the graph. When drawn, the button changes colour to that of of the curve displayed.

Whilst the largest amount of data displayed is selected from the choice tree, it is possible to 'zoom-in' to particular times very easily using the graph. There are two methods: either drag the mouse of the area of interest, creating a rectangle and click the left button inside or use the x and y axis zoom buttons from the Zoom & Scale area. The display shows the enlarged view and changes the scale the x & y rulers. The time ruler is changes mode to show the most useful feedback of time at that scale. To move back and forth along time, move the horizontal scrollbar. To zoom out, either click the right mouse button over the graph or use the zoom-out button in the Zoom & Scale area.

It is possible to alter the scale and offset of the curves by clicking on the additional fields button in the Zoom & Scale area. This will create addition scale and offset controls next to each curve button. The values relate to the formula y = mx + c, where the offset is c and the scale is m. Moving the scale changes the magnitude of the curve, whereas the offset changes the point at which the curve originates. Using these tools, simple parity can be gained between two curves that you wish to superimpose on the same chart but do not share the same y scale.  

MENU

The File menu adds and removes file and other data sources to the choice tree. It also contains import and export routines to convert between native datastores and plain text, such as csv and tsv files.

The View menu controls the display and refresh of choice and visualisation. It also give the ability to save or send data being displayed to e-mail, applications or a file.

The Collect menu controls data collection, if you own the collection process.

The Graph menu changes the appearance of the chart and is only displayed when the graph appears.

Finally, the Help menu gives access to spot help, documentation and links to the system garden web site for product information. Most help menu items need a common browser on the users path to show help information.  

LOGGING

Ghabitat generates information and error messages. By default, errors are captured internally and can be displayed in the visualisation area by clicking on the logs node under this client.

Also available in this area are the log routes, which shows the how information of different severity is dealt with and configuration, which shows the values of all the current configuration directives in effect.

See habconf(5) for more information.  

FILES

Locations alter depending on how the application is installed.

For the habitat configuration
~/.habrc
$HAB/etc/habitat.conf or /etc/habitat.conf
For graphical appearence: fonts, colours, styles, etc
$HAB/lib/ghabitat.rc or /usr/lib/habitat/ghabitat.rc
For the help information
$HAB/lib/help/ or /usr/lib/habitat/help/
 

ENVIRONMENT VARIABLES

DISPLAY
The X-Windows display to use
PATH
Used to locate a browser to display help information. Typical browsers looked for are Mozilla, Netscape, Konqueror, Opera, Chimera
HOME
User's home directory
 

AUTHORS

Nigel Stuckey <nigel.stuckey@systemgarden.com>  

SEE ALSO

clockwork(1), killclock(1), habget(1), habput(1), irs(1), habedit(1), habprobe(1), habmeth(1), habconf(5)


 

Index

NAME
SYNTAX
DESCRIPTION
OPTIONS
DATA SOURCES
NAVIGATION
VISUALISATION
MENU
LOGGING
FILES
ENVIRONMENT VARIABLES
AUTHORS
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 23:39:25 GMT, June 03, 2010