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 severityfield under the column fields.

numseverityAlertsClear

Number of notifications or alerts currently clear at a particular level of severity.

For more information, see the severityfield 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

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 statusvalue 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 statusvalue 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 . 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
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.
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.
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 .

Further reading

If you are interested in applying the CorvilNet monitoring views on a Gateway, 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"