CorvilNet Monitoring Technical Reference

Overview

The CorvilNet integration enables Geneos to connect with the CorvilNet Engine (CNE). This integration makes available the network monitoring data from the CorvilNet Engine to Geneos. This integration is performed through the API plug-in.

When set up, the integration and its associated API plug-in comprise the CorvilNet plug-in (CNPI).

When you set up the CNPI for the first time, it produces three basic dataviews:

cnpiConfig — shows the general information and status of your CNPI.
qosAlerts — shows any outstanding quality-of-service alerts.
systemAlerts — shows any outstanding system alerts

The CorvilNet monitoring statistics views appear when you configure the respective configuration (.cfg) files on the API sampler. These views are the main feature of the CorvilNet monitoring integration, as these show the monitoring statistics coming from the CNE:

getSummary — shows a summary of the CorvilNet monitoring statistics.
getStats — shows historical statistics as monitored by the CNE.
getLiveStats — shows live statistics as monitored by the CNE.

If you are using the Latency Management Centre (LMC) to monitor your CNE, then your integration includes three additional views:

trapFODConfig — shows the configuration details of the trap fan-out daemon (trapFOD), including errors encountered when you run the trapFOD.
fodCNEStatus — shows the status of the trap-forwarding process with respect to each known CNE.
fodCNPIStatus — shows the status of the trap forwarding process with respect to each known CNPI instance.

The CNPI receives monitoring statistics from the CNE through the Corvil API. The CNE also sends system event information through the Simple Network Management Protocol (SNMP).

Default metrics and dataviews

cnpiConfig

Headline field	Description
version	Version number of the CNPI software.
hostName	Network hostname of the Netprobe that the CNPI is connected to.
port	Network port of the Netprobe that the CNPI is connected to.
retryInterval	Delay between attempts to recover from network failures. Unit: seconds (s)
loggingTo	Name of the log file that the CNPI is writing to.
cneHostName	Network hostname of the CNE that the CNPI is connected to.
cneAPIPort	Network port configured on the partner CNE to accommodate API queries from the CNPI.
snmpTrapAlerts	Indicates if the CNPI allows SNMP traps.
cneSNMPPort	Network port configured on the partner CNE to accommodate SNMP queries from the CNPI.
trapHostName	Hostname or IP address of the machine where the CNPI is running. This field is used to receive SNMP traps from either the CNE or the trapFOD.
trapPort	Network port of the machine where the CNPI is running. This field is used to receive SNMP traps from either the CNE or the trapFOD.
detached	Indicates if the CNPI is running as a detached daemon process (`Y`) or if it attached to the initiating terminal (`N`).
workingDirectory	File path or working directory where the CNPI log files are written, and where the PID file associated with the CNPI process is located.
UID	User ID associated with the running CNPI process.
pidFile	Name of the PID file that the CNPI process is associated with.
logLevel	Logging level set for the CNPI.
group	Geneos group in effect for communication with the CNPI.
licenseExpires	Date and time when an evaluation or rental license expires. If you are on a perpetual license, then this field displays `NEVER`.
upTime	Elapsed time since the CNPI started, or was restarted. Unit: seconds (s)

qosAlerts and systemAlerts

The qosAlerts and systemAlerts views have the same metrics. However, they report different events:

qosAlerts — shows any outstanding quality-of-service alerts.
systemAlerts — shows any outstanding system alerts.

Headline field	Description
totalAlerts	Total number of notifications or alerts.
numAlertsSet	Number of notifications or alerts currently set.
numAlertsClear	Number of notifications or alerts currently clear.
numseverityAlertsSet	Number of notifications or alerts currently set at a particular level of severity. For more information, see the `severity`field under the column fields.
numseverityAlertsClear	Number of notifications or alerts currently clear at a particular level of severity. For more information, see the `severity`field under the column fields.

Column field	Description
type	Type of the event generating the notification or alert.
time	Time of the notification or alert, in a human-readable format.
timestamp	Time of the notification or alert, in Unix time.
severity	The severity of the notification or alert. Possible values: informational warning minor major severe
deviceIP	IP address of the CNE that generated the notification or alert.
sourceFQN	Fully-qualified name of the CNE source object that generated the notification or alert.
description	Description of the notification or alert.
reason	Reason for the set or clear notification.
value	Where applicable, this field shows the measured value for the variable monitored by this notification or alert.
typeDiscriminator	CNE descriptor specific to the notification or alert type.
count	Where applicable, this field shows the number of times the event occurred within a measurement period.

CorvilNet API metrics and dataviews

The next three views come from the CNE network monitoring statistics. These are passed onto Geneos through the CNPI.

These views do not appear by default, and require you to configure the API sampler you set up for the CNPI.

Note: The field names in this section are controlled by Corvil. For more information, see the CorvilNet API Reference Guide. The fields listed there are as they appear in Corvil API version 6.1.

getSummary view

Headline field	Description
measurementPoint	Fully qualified name of the measurement point to which data in a particular row relates. This is also the key for Geneos snoozing purposes.
cfgFile	Source configuration file that specifies the content of the view.
updateIntervalSeconds	Time between refreshes of the contents of this view. Unit: seconds (s)
updateInterval	Time between refreshes of the contents of this view, as it appears in the source configuration file.
noDataValues	Indicates how the CNPI displays "no data" values. For more information, see Header elements.

getStats view

Headline field	Description
measurementPoint	Fully-qualified name of the measurement-point to which data in a particular row relates. This is also the key for Geneos snoozing purposes.
cfgFile	Source configuration file that specifies the content of the view.
updateIntervalSeconds	Time between refreshes of the contents of this view. Unit: seconds (s)
updateInterval	Time between refreshes of the contents of this view, as it appears in the source configuration file.
noDataValues	Indicates how the CNPI displays "no data" values. For more information, see Header elements.
historyPeriodSeconds	Duration of the period for which historical statistics are shown. This field only appears if you configure a variable time period. Unit: seconds (s)
historyPeriod	Duration of the period for which historical statistics are shown, as it appears in the source configuration file.
dayStartTime	Start of the configured business day. This field only appears if you configure a `BUSINESS-DAY` period.
dayEndTime	End of the configured business day. This field only appears if you configure a `BUSINESS-DAY` period.
startTimestampMs	Start of the period reported in this view, in Unix time, as reported by the CNE. Unit: milliseconds (ms)
startTime	Start of the period reported in this view in human-readable format.
endTimestampMs	End of the period reported in this view, in Unix time, as reported by the CNE. Unit: milliseconds (ms)
endTime	End of the period reported in this view in human-readable format.
lastUpdatedTimestampMS	Local time when the data displayed in the view was requested from the CNE, in Unix time.
lastUpdatedTime	Local time when the data displayed in the view was requested from the CNE, in human-readable format.

getLiveStats view

Headline field	Description
measurementPoint	Fully-qualified name of the measurement-point to which data in a particular row relates. This is also the key for Geneos snoozing purposes.
cfgFile	Source configuration file that specifies the content of the view.
updateIntervalSeconds	Time between refreshes of the contents of this view. Unit: seconds (s)
updateInterval	Time between refreshes of the contents of this view, as it appears in the source configuration file.
noDataValues	Indicates how the CNPI displays "no data" values. For more information, see Header elements.
timestamp	Timestamp of the most recent response from the CNE, in Unix time.
time	Timestamp of the most recent response from the CNE, in human-readable format.
lagOffsetMs	Delay from the initial measurement update time. Unit: milliseconds (ms)

trapfod metrics and dataviews

The trapFOD views pertain to the status of the trap fan-out daemon (trapFOD), which acts as the single routing point for SNMP traps in integrations where the CNPI connects to the LMC instead of a single CNE.

trapFODConfig view

Headline field	Description
version	Version number of the trapFOD software. This must match the version number of the CNPI that communicates with the trapFOD.
hostName	Network hostname of the Netprobe that the trapFOD is connected to.
port	Network port of the Netprobe that the trapFOD is connected to.
retryInterval	Delay between attempts to recover from network failures. Unit: seconds (s)
loggingTo	Name of the log file that the trapFOD is writing to.
trapRxHostName	Network hostname through which trapFOD expects to receive SNMP traps.
trapRxPort	Network port through which trapFOD expects to receive SNMP traps.
sourceOID	Corvil-specific OID of the element within the trap that is expected to contain that IP address. SNMP traps are decoded upon arrival, and the IP address of the sender of the trap is identified from its contents.
detached	Indicates if the trapFOD is running as a detached daemon process (`Y`) or if it attached to the initiating terminal (`N`).
workingDirectory	File path or working directory where the trapFOD log files are being written, and where the PID file associated with the trapFOD process is located.
UID	User ID associated with the trapFOD process.
pidFile	Name of the PID file that the trapFOD process is associated with.
logLevel	Logging level set for the trapFOD.
group	Geneos group in effect for the CNPI.
licenseExpires	Date and time when an evaluation license expires.
upTime	Elapsed time since the trapFOD started, or was restarted.

Column field Description

row

Column field	Description
row	Numeric key allocated for this row when an error in generated. Once allocated, an error text will always have the same row number and can be used for snoozing purposes. This is reset when you cold-start the trapFOD.
severity	Severity of an error. Possible values: `WARNING` — indicates that the trapFOD may not function as expected. `ERROR` — indicates that the trapFOD is not functioning as expected.
message	Error description.

Numeric key allocated for this row when an error in generated.

Once allocated, an error text will always have the same row number and can be used for snoozing purposes. This is reset when you cold-start the trapFOD.

severity

Severity of an error.

Possible values:

WARNING — indicates that the trapFOD may not function as expected.
ERROR — indicates that the trapFOD is not functioning as expected.

message Error description.

fodCNEStatus view

Note: One row is displayed per known CNE. The LMC discovers CNEs as requested by the CNPI. If a known CNE forwards data to the LMC without an associated request from the CNPI, then the information appears as a blank row and indicates an error condition.

Headline field	Description
numCNEs	Number of CNE known to the system. This is the number of unique CNE IP addresses received in forward-requests or traps. This number matches the number of rows in the view.
numTraps	Number of traps received in total (both forwarded and not forwarded).
numTrapsFwd	Number of traps received that have been forwarded to a subscribing CNPI.
numTrapsDiscarded	Number of traps received that have not been forwarded to a subscribing CNPI because no matching subscriber was known at the time of trap receipt.
numErrors	Number of rows in the view that have a status value of `ERROR`.
numWarnings	Number of rows in the view that have a status value of `WARNING`.
time	Time when the view was most recently updated, in Unix time.
timestamp	Time when the view was most recently updated, in human-readable format.

Column field	Description
CNE	IP address of the CNE to which this row relates.
status	Status of this CNE from a trap-forwarding perspective. Possible values: `OK` — the CNE is communicating without problem. `WARNING` — there is a risk that some traps may not appear in Geneos, and may require investigation. `ERROR` — traps generated by the CNE will not appear on Geneos, and require corrective action.
time	Time when this row was most recently updated, in Unix time.
timestamp	Time when this row was most recently updated, in human-readable format.
subscriberManagedEntity	Managed Entity of the CNPI receiving traps from this CNE.
subscriberSampler	Sampler of the CNPI receiving traps from this CNE.
numTraps	Total number of traps received from this CNE.
numTrapsFwd	Number of traps received from this CNE and forwarded to the subscribing CNPI.
numTrapsDiscarded	Number of traps received from this CNE but not forwarded to a subscribing CNPI because no CNPI was known at the time of receipt.
statusDetails	Description of any issue indicated by the `status`value for this row. If the status value is `OK`, then this cell is blank.

fodCNPIStatus view

Headline field	Description
numCNPIs	Number of CNPIs known to the system. This is the number of unique managed entity–sampler combinations received in forward requests. This number matches the number of rows in the view.
numTrapsFwd	Number of traps forwarded to a subscribing CNPIs.
numErrors	Number of rows in the view that have a status value of `ERROR`.
numWarnings	Number of rows in the view that have a status value of `WARNING`.
time	Time when the view was most recently updated, in Unix time.
timestamp	Time when the view was most recently updated, in human-readable format.

Column field	Description
CNPI	Managed entity and sampler names associated with the CNPI in this row. The value is shown in the format `<managedEntityName>:<samplerName>`.
status	Status of this CNPI from a trap-forwarding perspective. Possible values: `OK` — the CNPI is communicating without problem. `WARNING` — there is a risk that the CNPI will not receive traps from its partner CNE, and may require investigation. `ERROR` — the CNPI will not receive traps from its partner CNE, and requires corrective action.
time	Time when this row was most recently updated, in Unix time.
timestamp	Time when this row was most recently updated, in human-readable format.
partnerCNE	IP address of the CNE from which the CNPI requests to receive traps.
trapSocket	Network address through which the CNPI requests to receive traps. This value is shown in the format `<IPaddress:port>`.
numTrapsFwd	Number of traps received from the indicated partner CNE and forwarded to CNPI.
statusDetails	Description of any issue indicated by the `status`value for this row. If the status value is `OK`, then this cell is blank.

Plug-in configuration

Configuration file template

Example templates are available in the CorvilNet integration package available in the ITRS Downloads page. These files can be found in the \examples folder:

get_summary_template.cfg — for getSummary views
get_stats_template.cfg — for getStats views
get_live_stats_template.cfg — for getLiveStats views

Use these templates to guide you in configuring the CNPI views.

Header elements

All configuration files for the API sampler have common header elements:

GENEOS-CNPI
INTERVAL
ALERTS
NODATA

The first non-comment, non-blank line of a configuration file must always contain GENEOS-CNPI.

Configuration option Value options Default value Description

Configuration option	Value options	Default value	Description
`INTERVAL`	`seconds` `minutes` `hours` `days`	`5 minutes`	Sets the time between refreshes of the view data. If no unit is provided, then the default interval is in seconds. There is no limit on the interval duration. However, the CNPI does not track intervals between restarts.
`ALERTS`	`yes` `no`	`no`	If enabled, the view embeds alerts within a measurement point. If no option is provided, then the CNPI follows the behaviour of the default value. Alerts do not follow the `INTERVAL` option, and update when a new status is received via SNMP traps.
`NODATA`	`unchanged` `blank` `previous`	`unchanged`	Sets how the view displays the CNE's "no data" values. The CNE distinguishes a "no data" cell from a zero value. Hence, it returns a value of `-1` for these. In addition, the CNE return a value of `-2` if it cannot accurately calculate data values. The CNPI displays "no data" values according to the following options: `unchanged` — displays "no data" values as `-1`. `blank` — displays "no data" values as empty cells. `previous` — displays the last data received. If no value has been received, then displays an empty cell.

INTERVAL

seconds
minutes
hours
days

5 minutes

Sets the time between refreshes of the view data. If no unit is provided, then the default interval is in seconds.

There is no limit on the interval duration. However, the CNPI does not track intervals between restarts.

ALERTS

yes
no

no

If enabled, the view embeds alerts within a measurement point. If no option is provided, then the CNPI follows the behaviour of the default value.

Alerts do not follow the INTERVAL option, and update when a new status is received via SNMP traps.

NODATA

unchanged
blank
previous

unchanged

Sets how the view displays the CNE's "no data" values. The CNE distinguishes a "no data" cell from a zero value. Hence, it returns a value of -1 for these. In addition, the CNE return a value of -2 if it cannot accurately calculate data values.

The CNPI displays "no data" values according to the following options:

unchanged — displays "no data" values as -1.
blank — displays "no data" values as empty cells.
previous — displays the last data received. If no value has been received, then displays an empty cell.

getSummary configuration

The getSummary configuration file has the following elements after the header:

getSummary
NAME
PERIOD
FILTER

Configuration option	Value options	Default value	Description
`getSummary`	Not applicable.	Not applicable.	Instructs the CNPI to create a summary view and to interpret the lines that follow as the specification for such a view.
`NAME`	Any string.	`getSummaryTemplate`	Sets the name of the view in Geneos.
`PERIOD`	`1-hour 12-hours 24-hours 48-hours 7-days 30-days 60-days`	`1-hour`	Sets the period over which data will be summarised.
`FILTER`	CorvilNet API supported wild-card patterns.	`*`	Selects the measurement points for which summary statistics will be displayed. This is an optional configuration. By default, all measurement points are included in the view. For more information on the supported wild-card patterns, see the CorvilNet XML API Reference Guide.

getStats configuration

The getStats configuration file has the following elements after the header:

getStats
NAME
PERIOD

The declarations for the measurement points and statistics follow these elements.

Configuration option Value options Default value Description

getStats Not applicable. Not applicable. Instructs the CNPI to create a historical statistics view and to interpret the lines that follow as the specification for such a view.

NAME Any string. getStatsTemplate Sets the name of the view in Geneos.

Configuration option	Value options	Default value	Description
`getStats`	Not applicable.	Not applicable.	Instructs the CNPI to create a historical statistics view and to interpret the lines that follow as the specification for such a view.
`NAME`	Any string.	`getStatsTemplate`	Sets the name of the view in Geneos.
`PERIOD`	For fixed periods: `1-hour 12-hours 24-hours 48-hours 7-days 30-days 60-days` For variable periods: `<number> <unit>` where unit can be `second`, `minute`, `hour`, or `day`. For a business day: `BUSINESS-DAY <HH:MM> <HH:MM>` where the `<HH:MM>` denote the start and end of day, in the 24-hour format.	Not applicable.	Sets the period over which data will be summarised. If you use `BUSINESS-DAY`, then the statistics become static at the end of the business day. Note: The plug-in has no business day calendar. Thus, everyday is a business day. We recommend that you set a period not shorter than 5 minutes.

PERIOD

For fixed periods:

1-hour 12-hours 24-hours 48-hours 7-days 30-days 60-days

For variable periods:

<number> <unit>

where unit can be second, minute, hour, or day.

For a business day:

BUSINESS-DAY <HH:MM> <HH:MM>

where the <HH:MM> denote the start and end of day, in the 24-hour format.

Not applicable.

Sets the period over which data will be summarised.

If you use BUSINESS-DAY, then the statistics become static at the end of the business day.

Note: The plug-in has no business day calendar. Thus, everyday is a business day.

We recommend that you set a period not shorter than 5 minutes.

getLiveStats configuration

The getLiveStats view configuration files can produce more than one view per file. However, these views must share the same INTERVAL.

The getLiveStats configuration file has the following elements after the header:

getLiveStats
VIEW

The declarations for the measurement points and statistics follow these elements.

Configuration option	Value options	Default value	Description
`getLiveStats`	Not applicable.	Not applicable.	Instructs the CNPI to create live statistics views and to interpret the lines that follow as the specification for such a view.
`VIEW`	Any string.	Not applicable.	Sets the name of the view in Geneos.

Note: This view does not support measurement points associated with offline channels. If such measurement points are included in your view configuration, then these are removed by the CNPI.

Measurement points

The CNPI uses the CNE's measurement points in displaying the getStats and getLiveStats views.

There are five ways to define measurement points in your view configuration file:

Configuration option	Value options	Default value	Description
MP-`ALL`	Not applicable.	Not applicable.	Includes all measurement points coming from the CNE.
`MP-MECH`	Name of a known mechanism as it appears in the CNE.	`pnqm ".*"`	Includes measurement points falling under a monitoring mechanism, as it appears in the CNE. You can further refine this option by adding any Perl-compatible regular expression enclosed in double quotation marks.
`MP-CFG-STATS`	Names of known configurable statistics.	Not applicable.	Includes measurement points matching the set of named configurable statistics. You can include several configurable statistics, separated by a comma. The last value must not end in a comma for the CNPI to recognise the end of the list. If you include a configurable statistic whose name begins in a special character other than underscores or hyphens, then you must enclose that name in double quotation marks.
`MP-PCRE`	Any Perl-compatible regular expression.	`".*"`	Includes measurement points that match the expression
`MP-LIST`	Names of known measurement points.	Not applicable.	Includes measurement points listed by name. Each measurement point must be specified on a single line and the name must be URL encoded (for example, spaces represented as `%20`).

Be default, measurement points are named by the key to the row view. To name individual measurement points, do any of the folowing:

Enable DISPLAYNAMES in the Other view options.
Use measurement point aliases. These are configurable in the .cfg files.

There are three ways to create aliases:

Configuration option Example configuration Descrpition

MP <key> <alias> MP rt-class/FIX-SERVERS//London_CNE/FIX-CLIENTS/FIX-RTT/class-default "London FIX engine." Lists an individual measurement point alias.

MP-ALIAS <key> <alias> MP-ALIAS rt-class//London-CNE/Amsterdam_CNE/EU-Amsterdam//Voice "London->Amsterdam (Voice)" rt-class//London-CNE/Amsterdam_CNE/EU-Amsterdam//Management "London->Amsterdam (Management)" Lists many measurements points and aliases.

Configuration option	Example configuration	Descrpition
`MP <key> <alias>`	`MP rt-class/FIX-SERVERS//London_CNE/FIX-CLIENTS/FIX-RTT/class-default "London FIX engine."`	Lists an individual measurement point alias.
`MP-ALIAS <key> <alias>`	`MP-ALIAS rt-class//London-CNE/Amsterdam_CNE/EU-Amsterdam//Voice "London->Amsterdam (Voice)" rt-class//London-CNE/Amsterdam_CNE/EU-Amsterdam//Management "London->Amsterdam (Management)"`	Lists many measurements points and aliases.
`MP-ALIASES-FILE <filename>`	`MP-ALIASES-FILE "/home/geneos/cnpi/amsterdam_mp.aliases"`	Refers to a separate file where measurement point aliases are declared. In an aliases file, the measurement points are listed in the format `<key> <alias>` per line.

MP-ALIASES-FILE <filename>

MP-ALIASES-FILE "/home/geneos/cnpi/amsterdam_mp.aliases"

Refers to a separate file where measurement point aliases are declared.

In an aliases file, the measurement points are listed in the format <key> <alias> per line.

Pre-defined and configurable statistics

For getStats and getLiveSTats views, the column fields are referred to as statistics. These populate the columns in the Geneos dataview.

Note: The full list of statistics and statistics groups are listed in the geneos-cnpi.cgf file.

Any request for a configurable statistic whose name is not found in the CNE will cause the configuration file to be rejected.

Some rules governing the use of pre-defined and configurable statistics:

If you include any pre-defined statistic beginning with top-, then you cannot use configurable statistics in the same view configuration.
If you list both pre-defined and configurable statistics in one view configuration, then the configurable statistics must follow the options for pre-defined statistics.
The CNE does not support requested percentiles for historical statistics views.

Due to the way that the CNE responses to pre-defined statistics beginning with top-, the CNPI has the following limitations:

Exactly one top- statistic must be specified per view. Additional statistics, whether pre-defined or configurable, cannot be supported.
The ROWKEY view option behaves differently. Specifying the ref option simply removes the measurement point column so that screen real estate may still be saved. The addition of custom measurement point names is supported as normal.
The top- statistics do not support the RAW, CNEUNITS, FACTOR, and DECIMALS options.
Pre-defined statistics in the top-*-rate format supply a time-series graph data only and are not supported.

Configuration option	Value options	Example value	Description
`STATS-LIST`	Any statistic listed on `geneos-cnpi.cgf`.	`average bitrate, throughput, summary`	Includes the pre-defined statistic listed by name, separated by a comma. The last value must not end in a comma for the CNPI to recognise the end of the list.
`STATS-GROUP`	Any statistic group listed on `geneos-cnpi.cgf`.	`pnqm`	Includes the pre-defined statistics listed under a group. Statistics groups are a set of statistics whose measurements are similar enough to not delay the transmission of one another.
`CFG-STATS-LIST`	Any known configurable statistic from the CNE.	Not applicable.	Includes known configurable statistics listed by name, separated by a comma. The last value must not end in a comma for the CNPI to recognise the end of the list. If you include a configurable statistic whose name begins in a special character other than underscores or hyphen, then you must enclose that name in double quotation marks.
Percentile list	Any set of your desired percentiles.	`97%, 98%, 99.5%`	Optional list of requested percentiles, separated by a comma, The last value must not end in a comma for the CNPI to recognise the end of the list. If you use this option for configurable statistics, then it works only in the getLiveStats view.

On the same line, you can add the following optional configurations:

Caution: The following configuration options are not required, and cause the CNPI to ignore any statError fields coming from the CNE. We recommend that you run the CNPI in verbose or debug logging when using any of the following options.

Configuration option	Value options	Example value	Description
`RAW`	Not applicable.	Not applicable.	Requests raw statistics from the CNE. This causes the view to ignore any columns pertaining to a statistic's factor or unit. This setting is recommended for experienced users of CNE who wish to lessen the load associated with running the CNPI.
`CNEUNITS`	Not applicable.	Not applicable.	Requests the statistics as they appear on the CNE. This can be followed by the `DECIMALS` option to add decimal places to the statistics.
`FACTOR`	Any number in the power of 10.	`10000`	Requests the raw statistics and divides it by the factor you specify. This can be followed by the `DECIMALS` option to add decimal places to the statistics.
`DECIMALS`	Any number.	`4`	Adds decimal places to reported statistics.

Other view options

The CNPI supports other options when you configure views using the .cfg files.

Configuration option	Value options	Default value	Description
`DISPLAYNAMES`	`yes no`	`no`	Toggles a `displayName` for measurement points in the getStats and getLiveStats views.
`ROWKEY`	`url ref`	`url`	Toggles between the full measurement-point URL (measurementPoint column) or a much shorter automatically-generated reference (mpRef column) for the view row-keys. This is useful for reducing the amount of screen real estate required to display statistics views and should be used in conjunction with the `DISPLAYNAMES` feature. Note: The CNPI does not support this option when `ALERTS` are enabled in a view.
`WITH-VALUE`	`yes no`	`yes`	Toggles between including or excluding the word "value" appended to the column names for pre-defined statistics (for example, "e2eLatencyValue" vesus "e2eLatency").
`CFG-WITH-VALUE`	`yes no`	`no`	Toggles between including or excluding the word "value" appended to the column names for configurable statistics (for example, "Partial Fills" versus "Partial Fills Value").
`CFG-WITH-SPACE`	`yes no`	`no`	Toggles between including or excluding spaces between components when constructing configurable statistics' column names. If your configurable statistics include spaces, then views are generally more aesthetically pleasing if this value is set to `yes`(for example, "Partial Fills Unit" versus "Partial FillsUnit").

API sampler parameters

Parameter	Default value	Description
`CFGFILEnn`	None; this parameter is not configured by default.	Specifies the full path to a view configuration file to load. The parameters can start from `CFGFILE01`, `CFGFILE02`, and so on. The parameters do not have to be configured in order and there can be numerical gaps. For example, `CFGFILE02`, `CFGFILE05`, and `CFGFILE07` may be successfully configured. The default value limit for `nn` is 10. If more configuration files are required, you can update the upper value limit using the `max-cfg-files=`command. For more information, see CNPI commands.
`FOD_HOSTNAME`	`localhost`	For integrations with the LMC, this is the hostname where a trapFOD is listening for trap-forwarding requests. This parameter appears with its default value when you configure the `FOD_PORT` parameter. If neither `FOD_HOSTNAME` nor `FOD_PORT` is configured, then your sampler will not interact with a trapFOD. The configuration of the trapFOD instance must match this value.
`FOD_PORT`	`11011`	For integrations with the LMC, this is the port where a trapFOD is listening for trap-forwarding requests. This parameter appears with its default value when you configure the `FOD_HOSTNAME` parameter. If neither `FOD_HOSTNAME` nor `FOD_PORT` is configured, then your sampler will not interact with a trapFOD. The configuration of the trapFOD instance must match this value.
`FOD_INTERVAL`	`900`	For integrations with the LMC, this is the time between retransmissions of this sampler's trap-forwarding request to the configured trapFOD. A random back-off is used to prevent regular bursts of network traffic between all CorvilNet samplers and the trapFOD. Unit: seconds (s)
`GROUP`	The name of the sampler.	Specifies the Geneos group to use with this sampler. Note: A current limitation of Geneos API-based applications is that the group generated by the CNPI and the group expected by Geneos must be separately configured as the same value. To facilitate this, at invocation and every restart, the CNPI attempts to read the `GROUP` parameter and, if found, replaces the default sampler-name group with the name specified as the value of this parameter. This value should match the group specified in the sampler configuration and in the list of expected views, if configured. If the group names do not match, then the dataviews may become corrupted. To remove this corruption, remove the sampler from the configuration of the managed entity, save the configuration, correct the mismatch, and then add the sampler to the managed-entity. By default, the CNPI places all views within a group that matches the name of the sampler.
`HEARTBEAT`	`10`	For integrations with the LMC, this is the time between updates to the trapfod metrics and dataviews.

Start-up script commands

When you create the start-up script for either the CNPI or the trapFOD for the first time, these are the commands available to the script file.

CNPI commands

Command	Default value	Description
`version`	Not applicable.	Displays version information, then stops the plug-in.
`help`	Not applicable.	Displays the command synopsis, then stops the plug-in.
`license`=	`geneos-cnpi.lic`	Specifies the file to load as the license file for the plug-in.
`hostname=`	`localhost`	Specifies the hostname or IP address of the machine where the partner Netprobe is running.
`port=`	`7036`	Specifies the port number for communication with the partner Netprobe.
`sampler=`	`CNE`	Specifies the name of the sampler from which the views from the CNPI originates.
`retry=`	`15`	Specifies the number of seconds to wait before retrying network connections between the Netprobe or the CNE.
`nodetach`	Not applicable.	Instructs the CNPI to not run as a detached process from the initiating terminal. Included in `start_cnpi` by default.
`detach=`	Not applicable.	Instructs the CNPI to detach from the initiating terminal as a daemon, and specifies a different working directory. If you invoke this command, then the CNPI follows any other specified `--set-user` , `--pid-file` , and `--log-file`. This is not included in `start_cnpi` by default.
`set-user=`	Invoking user.	Specifies the username of the user under whose privileges the CNPI should run. This is not included in `start_cnpi` by default.
`pid-file=`	`geneos-cnpi.pid`	Specifies the filename to write the PID of the CNPI daemon.
`[no]lock-pid-file`	Not applicable.	If you invoke `--nolock-pid-file`, this allows certain file systems that do not support the `flock()` function locking to be used for PID file storage. By default, PID files are locked to prevent two identical copies of CNPI being started.
`log-file=`	`geneos-cnpi.log`	Specifies the file to which log entries are written, once parameter and option processing are complete.
`cne-api-port=`	`5101`	Specifies the port number for communication with the Web Services Interface of the partner CNE.
`cne-username=`	`monitor`	Specifies the username for accessing the Web Services Interface of the partner CNE.
`cne-password=`	Not applicable.	Specifies the password for accessing the Web Services Interface of the partner CNE in plain text. Note: This command is deprecated, and is provided for backward compatibility only. We recommend that you use the `cne-encrypted-password=` command instead.
`cne-encrypted-password=`	`monitor`	Specifies the password for accessing the Web Services Interface of the partner CNE encrypted using the supplied cnpi-crypt utility.
`cne-timeout=`	`15`	Specifies the number of seconds to wait for a response from the Web Services Interface of the partner CNE before reporting an error.
`nosnmp`	Not applicable.	Disables all SNMP functionality. No walks of the CNE alert table will be performed and traps from the CNE will be ignored. This is not included in `start_cnpi` by default.
`snmp`	Not applicable.	Enables all SNMP functionality. Traps received at the configured hostname and port or discovered during walks of the CNE trap table will be displayed in the alert views and the alert columns of suitably configured data views. Included in the start-up script `start_cnpi` by default.
`cne-snmp-port=`	`161`	Specifies the port number for communication with the SNMP interface of the partner CNE.
`cne-community=`	`public`	Specifies the community string for accessing the SNMP interface of the partner CNE.
`trap-hostname=`	`localhost`	Specifies the hostname or IP address of the interface through which the CNPI should attempt to receive SNMP traps from the partner CNE. Note: A value of `localhost` may default to `127.0.0.1`, instead of your intended hostname. We recommend that you specify the actual hostname or IP address through which traps are intended to be received.
`trap-port=`	`162`	Specifies the number of the port through which the CNPI should attempt to receive SNMP traps from the partner CNE.
`trap-version=`	`8.2`	Specifies the version of SNMP traps to support. Possible values: `8.1` or `8.2`
`max-cfg-files=`	`10`	Sets the maximum number of view configuration files to expect from the API sampler.
`api-config=`	`geneos-cnpi.cfg`	Specifies the source file for CNE statistics types and groups that the CNPI supports.
`brief`	Not applicable.	Instructs the CNPI to generate log entries only in the event of errors. Included in `start_cnpi` by default.
`verbose`	Not applicable.	Instructs the CNPI to generate log entries for warnings and major events. This is not included in `start_cnpi` by default.
`debug`	Not applicable.	Instructs the CNPI to generate voluminous log entries under the control of plug-in specific environment variable values. Use of this option is not recommended for live operation and should only be used when under instruction as part of the enquiry for a support request. This is not included in `start_cnpi` by default.

trapFOD commands

Command	Default value associated	Description
`version`	Not applicable.	Displays version information, then stops the plug-in.
`help`	Not applicable.	Displays the command synopsis, then stops the plug-in.
`hostname=`	`localhost`	Specifies the hostname or IP address of the machine where the partner Netprobe is running.
`port=`	`7036`	Specifies the port number for communication with the partner Netprobe.
`sampler=`	`cneTrapFOD`	Specifies the name of the sampler from which the views from the CNPI originates.
`retry=`	`15`	Specifies the number of seconds to wait before retrying network connections between the Netprobe or the CNE.
`nodetach`	Not applicable.	Instructs the trapFOD to not run as a detached process from the initiating terminal. Included in `start_fod` by default.
`detach=`	Not applicable.	Instructs the trapFOD to detach from the initiating terminal as a daemon, and specifies a different working directory. If you invoke this command, then the trapFOD follows any other specified `--set-user` , `--pid-file` , and `--log-file`. This is not included in `start_fod` by default.
`set-user=`	Invoking user.	Specifies the username of the user under whose privileges the CNPI should run. This is not included in `start_fod` by default.
`pid-file=`	`geneos-cnpi.pid`	Specifies the filename to write the PID of the trapFOD.
`[no]lock-pid-file`	Not applicable.	If you invoke `--nolock-pid-file`, this allows certain file systems that do not support the `flock()` function locking to be used for PID file storage. By default, PID files are locked to prevent two identical copies of the trapFOD from being started.
`log-file=`	`geneos-cnpi.log`	Specifies the file to which log entries will be written, once parameter and option processing are complete.
`trap-hostname=`	`localhost`	Specifies the hostname or IP address of the interface through which the trapFOD should attempt to receive SNMP traps from the partner CNE. Caution: A value of `localhost` may default to `127.0.0.1`, instead of your intended hostname. We recommend that you specify the actual hostname or IP address through which traps are intended to be received.
`trap-port=`	`162`	Specifies the number of the port through which the trapFOD should attempt to receive SNMP traps from the partner CNE.
`source-OID=`	`1.3.6.1.4.1.11829.2.2.1.2.1.1.5`	Specifies the OID identifying the variable binding within incoming traps that contains the IP address of the source CNE.
`brief`	Not applicable.	Instructs the CNPI to generate log entries only in the event of errors. Included in `start_cnpi` by default.
`verbose`	Not applicable.	Instructs the CNPI to generate log entries for warnings and major events. This is not included in `start_cnpi` by default.
`debug`	Not applicable.	Instructs the CNPI to generate voluminous log entries under the control of plug-in specific environment variable values. Use of this option is not recommended for live operation and should only be used when under instruction as part of the enquiry for a support request. This is not included in `start_cnpi` by default.

For more information on how to run the start-up script, see the CorvilNet Monitoring User Guide .

Appendix — Example view configuration snippets

getSummary example

# Hourly summary statistics for all measurement-points updated every five minutes

GENEOS-CNPI
INTERVAL 5 minutes
ALERTS yes
NODATA unchanged


getSummary
NAME summary1HourAll
PERIOD 1-hour
FILTER *

# Daily summary statistics for London updated hourly

GENEOS-CNPI
INTERVAL 1 hour
ALERTS no
NODATA unchanged

getSummary
NAME summary24HoursChannels
PERIOD 24-hours
FILTER channel*

getStats example

# 15-minute latency statistics (all), every five minutes

GENEOS-CNPI
INTERVAL 1 minute
ALERTS no
NODATA blank

getStats
NAME latency15Minutes
PERIOD 15 minutes
MP-MECH pnqm
STATS-GROUP pnqm

# Top conversations only

GENEOS-CNPI
INTERVAL 1 minute
ALERTS no
NODATA blank

getStats
NAME topConversations
PERIOD 15 minutes
MP-ALL
STATS-LIST top-conversations

getLiveStats example

# Live latency statistics (all), updated once per minute, display-names included


GENEOS-CNPI
INTERVAL 1 minute
ALERTS yes
NODATA blank

getLiveStats
VIEW
   NAME latencyNow
   DISPLAYNAMES yes
   MP-ALL
   STATS-GROUP pnqm

# Venue latency statistics, jitter plus variable RP, updated once per minute

GENEOS-CNPI
INTERVAL 1 minute
ALERTS yes
NODATA blank

getLiveStats
VIEW
   NAME lseNow
   MP-PCRE "rt-class.*LSE-Infolect.*"
   STATS-LIST e2e-latency, e2e-loss
   STATS-LIST 99.99% e2e-jitter
VIEW
   NAME chicagoNow
   MP-PCRE "rt-class.*Chicago.*"
   STATS-LIST e2e-latency, e2e-loss
   STATS-LIST 99.8% e2e-jitter
VIEW
   NAME frankfurtNow
   MP-PCRE "rt-class.*Frankfurt.*"
   STATS-LIST e2e-latency, e2e-loss
   STATS-LIST 98% e2e-jitter
VIEW
   NAME newJerseyNow
   MP-PCRE "rt-class.*NewJersey.*"
   STATS-LIST e2e-latency, e2e-loss
   STATS-LIST 99.8% e2e-jitter
VIEW
   NAME eurexNow
   MP-PCRE "rt-class.*Eurex.*"
   STATS-LIST e2e-latency, e2e-loss
   STATS-LIST 99.8% e2e-jitter
VIEW
   NAME euronextNow
   MP-PCRE "rt-class.*Euronext.*"
   STATS-LIST e2e-latency, e2e-loss
   STATS-LIST 99.8% e2e-jitter

Statistics configuration

# e2e-latency statistic only, 97%, 98%, and 99%

STATS-LIST 97%,98%,99% e2e-latency

# Alternative 
STATS-LIST
  97%,98%,99%
  e2e-latency

# pnqm and tcp stats groups, 99% and 99.5%

STATS-GROUP 95% pnqm CNEUNITS DECIMALS 3

#e2e-latency and e2e-jitter statistics, 98%, both statistic's values divided by
 1000000 (milliseconds), latency statistics presented to 4 decimal places,
 jitter with no decimal places, no Unit, Factor, or Error columns displayed

STATS-LIST 98%
   e2e-latency FACTOR 1000000 DECIMALS 4,
   e2e-jitter FACTOR 1000000

# configurable statistics using the CNE's units, no percentiles

CFG-STATS-LIST
   "Cancels/Orders" CNEUNITS,
   PartialFills CNEUNITS,
   "Filled Vol" CNEUNITS,
   "Fill Rate" CNEUNITS

Example aliases file

Example aliases file named amsterdam_mp.aliases:

# Aliases London->Amsterdam

rt-class//London-CNE/Amsterdam_CNE/EU-Amsterdam//Voice "London->Amsterdam (Voice)"
rt-class//London-CNE/Amsterdam_CNE/EU-Amsterdam//Management "London->Amsterdam (Management)"
rt-class//London-CNE/Amsterdam_CNE/EU-Amsterdam//Citrix "London->Amsterdam (Citrix)"
rt-class//London-CNE/Amsterdam_CNE/EU-Amsterdam//Applications "London->Amsterdam (Applications)"
rt-class//London-CNE/Amsterdam_CNE/EU-Amsterdam//Low-priority "London->Amsterdam (Low-priority)"
rt-class//London-CNE/Amsterdam_CNE/EU-Amsterdam//class-default "London->Amsterdam"

# Aliases Amsterdam->London
rt-class/EU-Amsterdam/Amsterdam_CNE/London-CNE///Voice "Amsterdam->London (Voice)"
rt-class/EU-Amsterdam/Amsterdam_CNE/London-CNE///Management "Amsterdam->London (Management)"
rt-class/EU-Amsterdam/Amsterdam_CNE/London-CNE///Citrix "Amsterdam->London (Citrix)"
rt-class/EU-Amsterdam/Amsterdam_CNE/London-CNE///Applications "Amsterdam->London (Applications)"
rt-class/EU-Amsterdam/Amsterdam_CNE/London-CNE///Low-priority "Amsterdam->London (Low-priority)"
rt-class/EU-Amsterdam/Amsterdam_CNE/London-CNE///class-default "Amsterdam->London"