Command Line Utilities

Introduction

Other commands exists to complement the GUI and data collector.

clockwork	The collection agent, runs in the background as a daemon
killclock	Stop the clockwork daemon
statclock	Print information about clockwork
habrs	Command line interface to ringstore storage & admin
habget	Get data from a route
habput	Send data to a route
habedit	Edit a route or ringstore (useful for configuring)
habmeth	Run a clockwork method manually
habprobe	Run one of the built-in data gathering probe manually
habrep	Synchronise data with the repository

A number of command line utilities are provided in the standard Habitat distribution. These address getting data in and out of habitat's various storage systems, maintaining ringstore files and being able to get data or run the suite's methods on an ad-hoc basis.

This section describes each tool and their function. Their manual pages are held separately in the appendix.

Common Arguments

Where possible, all the command line utilities share a common set of arguments. They are:-

-c croute	Append user configuration data from croute (route addressing format), rather than the default file ~/.habrc. For example, -c [/cf.dat file:cf.dat] would load configuration from cf.dat.
-C cfcmd	Append a list of configuration directives from cfcmd, separated by semicolons. For example, -C "nmalloc=1;dummy=6" would set the configuration variables nmalloc to 1 and dummy to 6
-d	Place command in diagnostic mode, giving an additional level of logging and sending the text to stderr rather than default or configured destinations. Used for clockwork in daemon mode, will send output to the controlling terminal
-D	Place command 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. Used for clockwork 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 in the range 0-7, with format 3 being concise but useful. The formats are:- 0. everything!! time, severity, path, process ids, file, function, line, origin, code, text 1. upper case severity letter, text 2. severity, text 3. justified severity, text, file, function, line 4. upper case severity letter, short date time, binary name, file, function, line, text 5. time, severity, binary path, pid, file, function, line, code, text 6. long time, epoch time, severity, binary path, pid, tid, file, function, line, origin, code, text 7. justified severity text, justified file, line, function, text
-h	Print a help message to stdout and exit
-v	Print the version to stdout and exit

If a command does not work as expected, the user may be directed to run it with the -d or -D flags to help diagnose the problem.

Data Addressing

Most of the commands use route formats to address their data. The format of a route is similar to URLs and has been extended to cope with the formats of data storage used in habitat. It is fully explained in the concept section at the beginning of this guide.

habget

The utility habget opens a route specified on the command line, and redirects the output to stdout. As an example, the following outputs the data collected by the system probe (the data is collected at a 60 second interval):

$ habget rs:/var/lib/habitat/myhost.rs,sys,60
load1	load5	load15	runque	nprocs	lastproc
1 min load	5 min load	15 min load	num run procs	num procs	last proc run		info
4		4		4		""		""		""			max
abs		abs		abs		abs		abs		abs			sense
nano		nano		nano		u32		u32		u32			type
--
0.00		0.00		0.04		1		142		5895

The data returned has been shortened & edited for brevity. In reality, the info strings are longer and there are many more columns. The six columns in the example have rows info, max, sense and type.

The most recent sample is returned, which in the example above is a single line. To get more data, use the additional route qualifiers t= or s=, which explicitly specify the time or sequence. For example, to return everything in the sys,60 ring, use

rs:/var/lib/habitat/myhost.rs,sys,60,s=0-

Which will return all the records from sequence 0 on to the end. When explicit time and sequence addresses are used, the output will be augmented with a sequence, time and duration column (_seq, _time and _dur). All routes are valid addresses, including http: and sqlrs:.

habput

The utility habput inserts data onto a route for storage in a ringstore or SQLringstore. The following example reads the table headed tom dick harry and stores it in the ring called myring with a 0 second duration contained in the ringstore file myfile.rs.:

$ habput rs:myfile.rs,myring,0 <


A
ring of 0 duration is the convention for data with irregular
frequency. Sending the data to a ringstore causes it to be
scanned for a table structure and if passed, will append the data to
the ring.


If
there is an error in the format of the table or in the address
syntax, then the ring will generate an error and no data will be
stored. Appended data is given an ascending sequence number and will
be data stamped.


Please
note:
rings may be implicitly created with this utility, in which case a
default size and description will be given (which can be overridden
with the -s and -t
switches). The default ring is circular with 1,000 slots; when
sequence 1,001 is appended, the oldest will be lost. To create a
queue rather than a ring buffer, use -s
0.


Rings may be manipulated (size, name, description, etc) using the utility
habrs, which is described in the Administration manual.


Manual and Automatic Starting


The
commands clockwork and killclock are used to start and
stop the collection daemon on each machine. (Unless habitat is
installed as a system service, see /etc/init.d/habitat
below). To start a shared collection service for the system, run
clockwork on its own. It will become a background daemon
process, requiring to be stopped with the program killclock,
also with no argument.


If
a collection process is not running when myhabitat is started,
then a pop-up will ask if you wish to start one (see sections above).
In this case, the data file will be owned by the starting user
although the network service will still be available.


If
a user wishes to run their own data collection in addition to system
collection, they can do so by providing a custom job table to
clockwork, like so:

clockwork -j jobroute



Jobroute
must be a route but typically is a file created for the
specific situation. Job tables are described in the Administration
Manual, and describe the probes to run, their frequency and where
their storage is located. The -j
flag does not daemonise and stays attach to the controlling terminal,
so that it may be controlled and stopped like a normal shell level
process.

/etc/init.d/habitat



When
habitat is fully installed as a system service or daemon, a single
script manages the starting and stopping of clockwork. It is
automatically run on on the machine's start-up.


As
root, one can manually control clockwork collection using the
conventional command syntax:

/etc/init.d/habitat [ start | stop | status ]



If
this is the case in your installation, you do not need to manually
start a personal instance of clockwork unless you wish to run
specific jobs.


This
command is covered in greater depth in the Administration manual.


Other commands


The remaining commands are covered by the Administration Manual:-


  

    
habedit
    

      Edits configuration tables within ringstores
    
  

  

    
habmeth
    

      Runs clockwork methods from the command line
    
  

  

    
habprobe
    

	Runs built-in data collection probes from the command line
    
  

  

    
habrep
    

	Forces a replication cycle to take place
    
  

  

    
habrs
    

      Interactive ringstore utility, allowing administration of the data 
      held in ringstore files