You are on page 1of 6


1. Arguments and returned values

1.1. Quick info
int History_GetData( const string &topic, vector<string> &axes, vector<string> &details); topic - data request axes - column names will be returned details - in each string comma delimited value list returned First string in axes and details represents time, rest strings - columns required in topic. Return value - number of values in every line of details. If topic has syntax error, JetNexception is thrown with corresponding message. If syntax is correct, but data not available, 0 is returned. For usage sample, look at CallGetPutRrd_Test_Hist in htmlext.cpp.

1.2. Examples
To test any request, start webconsole and manually enter address config/albx/Tests/jnMonRepTest4.htm Then, enter text in topic line and press Update. Possible topic values: Channel,server,[ bytes out,max bytes out, Minimum compression,avg connections,pool size],minute,now [ bytes out, compression,avg connections],3/6/11 16:40,hour, channel 1 [ CPUpercent,maximum bytes in compressed],day,now Possible results on first request: axes: time (s) Average Bytes out Maximum Bytes out Minimum Compression % Average Connections Average Pool Size details; 03/06/2011 07:03:57,03/06/2011 07:03:58,03/06/2011 07:03:59,03/06/2011 07:04:00,03/06/2011 07:04:01,03/06/2011 07:04:02, ... ,,123.5,12,0,5678.4323, ... ,,131,12,0,5678.4323, ... ,,0,0,0,13.566, ... ,,0.924756,1,1,1, ... ,,12,13.6,22.33,0, ... If RRD database does not contain data for specified time, we have no data between commas in details. In most cases, all result columns contain empty data in the same places. First result line (time) never has empty data.

1.3. Topic syntax

All requests are case insensitive. topic contains 3-5 comma-separated parts. Part sequence free. Mandatory: columns (in square brackets), end time, period. Optional: channel, server Optional parts determine request type. Allowed combinations: neither channel nor server specified - global request. only channel specified - channel request. both channel and server specified - server request.

1.3.1. Channel
Two ways to specify - IP:Port and ordinal number (numbering from 1). In case of number, channel is detected from jetnexus.conf. For example, if 1st interface contain 2 ports, Channel 3 means 2.1, 1st port at 2nd interface

1.3.2. Server
Two ways to specify - IP:Port and ordinal number (numbering from 1). In case of number, server is detected from jetnexus.conf, number is sequence number at specified channel.

1.3.3. End time

Special value now means that period ends in request moment. A typical specification consists on date and time parts divided by blank. If date omitted, UTC today assumed. If time omitted, 0:00 assumed. Supported date formats: d/m/y d,m - leading zeros allowed, but not required; y - 2 or 4 digits. yyyy--mm-dd Supported time formats: h:m:s h:m h,m,s - leading zeros allowed, but not required Note. In program output (first line of details) always used dd/mm/yyyy hh:mm:ss with leading zeros.

1.3.4. Period
Supported values: minute, hour, day, week, month, year.

1.3.5. Columns
Square brackets contain comma separated list with column names. Allowed names listed below. Name can contain blanks. Each name may be prefixed by one of 3 keywords - Maximum, Average, Minimum or their shortenings max, avg, min. Prefix, if used, separated from column name by blank. If prefix omitted, Average assumed. Column names in global request

CPU % (increment of (utime+stime) from /proc/(pid of jetnexusdaemon)/stat) / (increment of all (up to 10) numbers in /proc/stat) * 100 Connections increment of TotalClientConnections Memory % percent from PerfRec (from jetnexusdaemon) (MemoryUsedK / MemoryTotalK * 100) Disk Free % DiskFreePercent Compression % % (increment OverallOutputBytes)/(increment OverallInputBytes) Bytes in increment OverallInputBytes Bytes out increment OverallOutputBytes Bytes in compressed increment CompressedInputBytes Bytes out compressed increment CompressedOutputBytes Column names in server request

Bytes in increment OverallInputBytes Bytes out increment OverallOutputBytes Compression % 100 - 100 * (increment OverallOutputBytes)/(increment OverallInputBytes) Connections PresentClientConnections (number, not increment) Pool Size PoolUsage TPS increment HitCount Column names in channel request

Data to write in channel RRD database are obtained by summing corresponding server data for all servers belonging to given channel. Bytes in increment sum(OverallInputBytes) Bytes out increment sum(OverallOutputBytes) Bytes cached increment sum(CacheBytes) Compression % 100 - 100 * (increment sum(OverallOutputBytes))/(increment sum(OverallInputBytes)) Connections sum(PresentClientConnections) TPS increment sum(HitCount) Cache Hits increment sum(Cache n304 Hits + Cache n200 Hits) Cache Hits % % increment sum(Cache n304 Hits + Cache n200 Hits) / increment sum(HitCount)

1.4. Result syntax

axes have first string "time (s)", another strings corresponding to parts in Columns element of topic. details have the same number of strings as axis. First string contain comma-separated time values in format dd/mm/yyyy hh:mm:ss - they can be converted into ptime using StringToPtime from ApiCommon (or in any another way). Next strings contain float values - with decimal point or without, if not needed for current value. If no RRD data for some time, empty value placed between commas.

2. Compiling and deployment

2.1. Prerequisites
On VA, rrdtool package required. Before it, a large number of another RPMs should be installed, I listed them earlier. On development computer, rrdtool-devel needed. On my Centos, I already had all non-RRD packages installed, so two commands were enough: rpm -ivh rrdtool-perl-1.4.4-1.el5.wrl.i386.rpm rrdtool-1.4.4-1.el5.wrl.i386.rpm rpm -i rrdtool-devel-1.4.4-1.el5.wrl.i386.rpm

2.2. Deployment
In lib, two boost libraries should be added: In jetnexus, rrdfiller and should be included.

2.3. Compiling can be compiled also on computers without rrdtool-devel. To compile rrdfiller and, rrdtool-devel should be installed. TopDefs.h should contain #define SHMNEW_USED true. These compilations use make-either in corresponding directories. History_GetData tries to load dynamically. On failure, JetNexception raised.

3. Miscellaneous
3.1. Disabling in jetnexus.conf
rrdfiller starts always, from /etc/inittab. But it can work either in active mode adding data to RRD databases, or in passive mode, doing nothing. If rrdfiller works in passive mode, History_GetData is still available, but for last data empty values will be returned. Mode is determined by rrdfillerActive in section jetnexusdaemon. Possible values: rrdfillerActive=1 active, write in databases rrdfillerActive=0 do nothing Default value (if rrdfillerActive does not exist) is 1. Currently, rrdfillerActive can be changed only manually. If rrdfillerActive change will be added to webconsole, rrdfiller should be restarted after the change.

3.2. Considerations about possible RRD daemon (rrdcached) usage

rrdcached (part of RRD runtime) can be started to decrease disk writes. Currently usage not supported in rrdfiller and History_GetData. If used, update (main command in rrdfiller, executed every second) does not write directly in RRD databases, but keeps data in rrdcached memory and flushes them to disk after some interval (default 300 seconds) or immediately on command flush. fetch (main command in History_GetData) always retrieve data from disk. So, before every fetch RRD requires daemon to flush data for corresponding database. Obviously, usability of rrdcached depends on flushing frequency. If we issue flush every second for every database, obviously, rrdcached does not give any benefit, only extra overhead. Such a mode possible if webconsole draws something from all databases and updates drawings every second.

3.3. Database changes

Currently, if some RRD database format changed, old databases of this format are deleted and new created. It is supported using 3 constants in jnRrdUtil.h #define RRDDB_VERSION_GLOBAL "2011-05-31-1" #define RRDDB_VERSION_CHAN "2011-05-28-1" #define RRDDB_VERSION_SRV "2011-06-03-1" Values of these constants are written in /jetnexus/rrddata/rrddb.ini If rrdfiller at start detects that some constant is changed, it deletes old databases of corresponding type and updates rrddb.ini. In general, RRD allows to export old database to XML and import this XML in a new database. If needed, such import can be written. For this purpose, 3 another constants (currently unused) are placed in jnRrdUtil.h with idea: if current version less than "LAST_COMPATIBLE", old database is simply deleted, otherwise it is imported into the new one.