CSAGENT

NAME

SYNOPSIS

DESCRIPTION

The data gathered by this agent is specific to COMSERV and is both static (unchanging over time) and dynamic. The agent obtains static parameters (SP) from the COMSERV station.ini files for the stations it operates on. The specifics of the SPs are detailed below in the section titled STATION.INI DIRECTIVES. Dynamic parameters (DP) are obtained from the COMSERV shared memory region to which the program attaches (see the COMSERV documentation for details). The DPs collected by this agent are described in the section DYNAMIC PARAMETERS.

csagent requires an initialization file containing parametric information to specify how the agent will operate. Most of the information in this file, known as collection.ini, are operational timeouts, locations of stations, and logging levels. See the COLLECTION.INI section below for specification of the details of this file.  

TriNetWatch COMMUNICATIONS

ARGUMENTS

-ORBconfig orb.config

The orb.config file holds the ORBACUS specific information about the 3 event channels which are used by this agent. The orb.config file for this agent must have services for the following three service names: CaRequestEventService, DynAgentEventService and StatAgentEventService.

collection.ini

The collection.ini file contains all of the running and logging parameters needed by the agent.

COLLECTION.INI

The collection.ini file holds ASCII parameters used by the agent to initialize and run. There are three sections to the file, [TIMEOUTS], [USAGES], and [STATIONS], that each must be specified in the first character of data on a line and be all in upper case enclosed by []s. Within the TIMEOUTS section are listed the timeouts used for transmitting data and failovers. Within the STATIONS section there are directives that describe the stations operated on and the level of logging. The USAGES section provides a UsageLevel to Comserv process mapping. The numbers in the USAGES, should correspond to the number/name/ symbol used in the NSI ruleset.ini file (See the NSI documentation). Each of the sections directives are described below.

[TIMEOUTS]

SPTimeout=N

Specifies N, where N is how many microseconds (usecs) to wait before each Static Parameter Message (SP_MSG) is sent to the NSI. The purpose of this timeout is to be able to slow transmission of messages if the event channel is being flooded at a rate greater than the NSI can handle. A default value is 250 usecs.

DPTimeout=N

Specifies N, where N is how many usecs to wait before each Dynamic Parameter Messsage (DP_MSG) is sent. The purpose of this timeout is to be able to slow transmission of messages if the event channel is being flooded at a rate greater than the NSI can handle. A default value is 250 usecs.

DPFailoverTimeout=N

N is the number of seconds AFTER connection to the event channels when Dynamic Parameters will start being sent. This is a threaded agent and SPs are sent upon request, but DP's are in a separate agent which is started when this timeout expires. The default value for this timeout is 15 seconds.

DPGatherWait=N

N is the number of seconds to wait before gathering Dynamic Parameters from the data aquisition system being observed by this agent (COMSERV). Once the parameters have been gathered, they are sent one at a time (with a short DPTimeout interval between each) to the NSI. This is probably the most important time out of the bunch as it governs how frequently the agent collects information. The default value for this timeout is 60 seconds.

[USAGES]

N=proc1,proc2,....

This section associates a Usage Level number N (as mapped in the NSI ruleset.ini) to a set of comserv processes proc1,proc2,..... The processes listed must use the COMSERV client code (CDWA, DLOG, C2MC, etc...). If the server process is to be specified, it can be listed as "comlink", which implies that either an mserv or comserv process will be running. Failing the use of the comlink keyword, the EXACT server name must be used. The keyword "off" implies that NO comserv server or clients are running. The numbers should start at 1 since 0 represents an UNKNOWN usage level.

[STATIONS]

Stations=sta1,sta2,....

The list of stations this agent operates on is specified by this parameter. The list should be comma separated with NO WHITESPACE between station names. If all stations in the initialization file are desired, then a * may be used. The station names should NOT have network codes here because COMSERV does not use netcodes yet! To specify the network codes, use the NetworkCode parameter.

Init=initialization_file

The init file in most cases for TriNetWatch agents is /etc/stations.ini. However, this provides a mechanism to point to other stations.ini files if necessary.

AgentName=name-of-agent

The name of the agent should be specified here. This is used to write a UNIQUE log file (if DebugMode=2 is used) AND also to uniquely tag messages sent from this agent. This is a required directive.

NetworkCode=NN

The SEED network code for the stations being monitored by this agent should be specified with this directive. This is a required directive.

DebugMode=N

The DebugMode specifies where log messages are sent. 0=turned off, 1=to stderr, 2=to a file. If DebugMode is set to 2, then the file is named after the AgentName appended with a .log.

DebugLevel=N

The Debug Level is an integer which represents the level of logging messages that the end-user wishes to see. There are 4 levels of logging currently available: 0= show only system related error messages, 1= show run level error messages, 2= show init level error messages, and 3 = show everything. The lower the number, the less verbose and vice-versa. It is recommended that the first runs of the agent use level=3 and then tone it down to level = 1 once the agents are tuned.

DebugLogDir=directory_name

The DebugLogDir parameter is used to specify where the log file should be written if DebugMode=2. The filename for the log will be the agent name with .log used as the postfix.

An example collection.ini file is shown below:

* a comment
# another comment
* the timeout section begins here.
[TIMEOUTS]
* the following two timeouts are inter message timeouts in usecs
SPTimeout=1
DPTimeout=1
* the following two timeouts are in seconds
DPFailoverTimeout=30
DPGatherWait=10
##########################################
* an example of just 3 usage levels
[USAGES]
1=off
2=comlink,dlog
3=comlink,dlog,cwda
##########################################
[STATIONS]
Stations=LAQ,LCG,FUL
NetworkCode=CI
AgentName=CA-cs-hotspot-1
Init=/etc/stations.ini
* logging Mode 2 sends data to a file named after the AgentName
DebugMode=2
* level 3 means spill your guts
DebugLevel=3
* this places the log file, if debugmode=2 into a given directory
DebugLogDir=/home/isti/agent_logs

STATION.INI DIRECTIVES

This agent uses a directive in the comserv station.ini file to specify which Static Parameters will be sent to the NSI. This directive is [CAStaticParams] and any data in the station.ini after this directive (until the next bracketed directive) will be sent as static parameters for the station. The format of parameters that will be sent are as ParamName=Value, where the Value can be anything. If the value is a string, it should be enclosed in double quotes. There is one reserved parameter name, getComservParams, which is reserved for a special function and is described below.

getComservParams=csparam1,csparma2,...

This special parameter lists a set of COMSERV parameters for which values should be supplied as static parameters. A second pass is made through the station.ini file looking for any comserv parameters that match an item in the list. The list should be comma separated and have NO WHITESPACE between arguments. If no parameter is found for a given item on the list, its value will appear as unknown on the NSI.

An example station.ini csagent directive section is specified below:

[CAStaticParams]
getComservParams="udpaddr,ipport,dir"
* a comment - static params are provided below:
StringParameter="A string static parameter"
stationOperatorPhoneNumber="415 999-9999"
last_edit_date="15 May 2000"
edit_count=3
usualMassPositionVoltageUNE=5.0
* end of the static params section

DYNAMIC PARAMETERS

This agent provides a list of dynamic parameters gathered from the COMSERV shared memory area for each of the stations it monitors. The list of dynamic parameters that this agent monitors is listed below. The exact spelling of the parameter must be used on the NSI if it is to be used in a ruleset/criteria for establishing performance level:

ComservState

This parameter describes the state of the Comserv process itself. It should be "Good" if everything is healthy.

DatalogState

This parameter describes the state of the Comserv datalog process. It should be "Good" if everything is healthy with the datalog program and it is running.

C2wdaState

The c2wda process state is described by this parameter. It is often set to the value "Not Served by CS" to indicate that it is not requested to be run by netmon.

Cs2mcastState

The cs2mcast process state is described by this parameter. It is often set to the value "Not Served by CS" to indicate that it is not requested to be run by netmon or Unknown if it was never requested.

UsageLevel

The UsageLevel parameter describes which process is running. It is one of the four possible states configured for Trinet (Full, Evaluation, TelemOnly, or Off). These correspond to the running of c2wda, datalog, and comserv respectively. Off refers to all of the above processes not running.

Sequence Errors

This parameter provides the total number of sequence errors that have been seen since the comserv process started.

Time of this CS Poll

The time when the agent polled the comserv (CS) memory area is described by this parameter name.

Secs Since Last CS Poll

This parameter provides the number of seconds expired since the last time this agent polled the comserv memory area.

% Seq Err Since Last Poll

The percentage of sequence errors observed since the last time the CS was polled.

% Seq Err Since Boot

The percentage of sequence errors observed since the time the comlink process was started.

Last Good Packet Time

This is the timestamp for the last good packet received by comserv. This does not necessarily have to be a data packet...it is for ANY PACKET.

Secs Since Last Good Packet

This is the time expired since the last good packet at the time the agent polled the comserv memory area.

Secs in Operation

This parameter is provided by the comserv process and indicates how long the process has been running.

SEE ALSO

AUTHOR

BUGS

Index

NAME

SYNOPSIS

DESCRIPTION

TriNetWatch COMMUNICATIONS

ARGUMENTS

COLLECTION.INI

STATION.INI DIRECTIVES

DYNAMIC PARAMETERS

SEE ALSO

AUTHOR

BUGS