Statistics retrieval using registerLogToFile

Overview

You can use the registerLogToFile method to create accounting or performance statistics data files for specific classes. Accounting and performance statistics are collected and stored in the NFM-P database. When the registerLogToFile method is used, the specific statistics are stored in the NFM-P database, and files are exported to the NFM-P main or auxiliary server file system with the requested data for each registered XML API client. Because the two actions occur in parallel, the data is available in files before you can export the data from the database.

An OSS client that retrieves statistics files using the registerLogToFile method requires a RHEL user account on each main or auxiliary server from which statistics are to be collected. Such a user account requires FTP or SFTP access, depending on whether TLS is enabled on the XML API. See Configuring FTP and SFTP access for OSS clients for the specific requirements and best practices for creating OSS client user accounts.

A LogFileAvailableEvent is sent each time a file is ready for retrieval by an OSS client, if the client subscribes to specific JMS topics. See Chapter 4, Event monitoring using JMS for information about JMS events.

By default, the NFM-P performs a regular JMS client inactivity check and deregisters any JMS client that does not subscribe to an event stream within a specified time. For registerLogToFile, a JMS subscription is optional; to avoid client deregistration after inactivity, you can disable the JMS client inactivity check. See Statistics data retrieval with registerLogToFile and find/findToFile for information about disabling the JMS client inactivity check.

The span of control associated with the JMS client is applied to each registerLogToFile request at the NE level. If an NE is not within the client span of control, the NFM-P excludes the requested statistics for the NE in the exported files. See the NSP System Administrator Guide for more information about span of control.

For scheduled accounting statistics collection, you can configure registerLogToFile system preferences that include the following:

Log Retention Time (minutes)—the number of minutes to keep the statistics files on disk before purging the files
JMS Client Registration Grace Intervals—the number of file-creation intervals to wait for a JMS subscriber to reconnect before cancelling the logToFile subscription. The parameter has no effect when the JMS client inactivity check is disabled. An interval is defined as 5 minutes.

For scheduled performance statistics collection, you can configure registerLogToFile system preferences that include the following:

Log Retention Time (minutes)—the number of minutes to keep the statistics files on disk before purging the files
Log Rollover Time (minutes)—the number of minutes during which statistics data is written to a file
JMS Client Registration Grace Intervals—the number of file-creation intervals to wait for a JMS subscriber to reconnect before cancelling the logToFile subscription. The parameter has no effect when the JMS client inactivity check is disabled. An interval is defined as 5 minutes.

You can modify the parameters from the Statistics tab of the System Preferences form in the client GUI. Alternatively, an OSS can use the XML API to modify the retention, rollover, and jmsRetries properties in the log.LogToFileManager class.

See the system preferences configuration procedures in the NSP System Administrator Guide for more information.

registerLogToFile filtering

To reduce the volume of exported statistics data, a client can apply a filter during registerLogToFile registration. The filter criteria determine which records are returned to a client; for example, if multiple API clients are individually responsible for statistics collection in a specific subnet; each client can apply a filter to return only the statistics associated with the NEs in specific subnets.

You can filter on any properties of a statistics log record that are string-based, such as monitoredObjectClass or monitoredObjectSiteId. See the LogRecord class definition in the XML API Reference for a list of the class properties.

For accounting statistics, you can configure an NFM-P system preference to include the accounting policy ID in each accounting statistics record. This enables an OSS client to use registerLogToFile and JMS filters based on the accounting policy ID.

See the system preferences configuration procedures in the NSP System Administrator Guide for more information.

See the registerLogToFile method description in the XML API Reference for a list of the supported filter elements and syntax.

See JMS message filtering for information about creating JMS filters.

registerLogToFile export from main server

The following figure shows the process associated with the event-driven statistics export from the NFM-P main server after an XML API client registers for notifications using the registerLogToFile method.

Figure 14-6: Event-driven registerLogToFile process using NFM-P main server

registerLogToFile export from auxiliary server

The following figure shows the process associated with the event-driven statistics export from an NFM-P auxiliary server after an XML API client registers for notifications using the registerLogToFile method.

Figure 14-7: Event-driven registerLogToFile process using NFM-P auxiliary server

Registration request

You can specify multiple accounting or performance statistics classes in a registration request. Table 14-2, registerLogToFile method input parameters describes the input parameters of the registerLogToFile method.

Note: The registerLogToFile file compression option requires additional NFM-P server resources. The additional load may prevent the NFM-P from collecting the maximum number of statistics records in the NSP Planning Guide.

Table 14-2: registerLogToFile method input parameters

Input parameter	Description	Values
fullClassName	Package qualified class name in dot-separated format	A comma-separated list of accounting statistics classes, performance statistics classes, or both
dirName	The relative path of the directory that is to contain the exported files. The path is relative to the accountingStats or performanceStats below the XML output directory that is specified during NFM-P server installation or upgrade. Nokia recommends that you use a separate directory for each application that requires exported statistics. Statistics classes for the same accounting file and jmsClientId cannot be sent to different directories. If statistics classes from the same file have different registrations to different directories, collection will not separate the classes to different directories. The statistics classes cannot be replicated in another registerLogToFile request to a different directory using the same jmsClientId. Each subsequent registerLogToFile request for the same statistics class and jmsClientId will overwrite the previous request.	String
compress	Optional parameter that specifies whether data files are compressed when they are exported If you set this parameter to true, the NFM-P statistics collection performance may be affected.	The options are: true—compresses data files using gzip; each exported file has a gz extension false (default)—does not compress exported files
jmsClientId	The JMS client ID or Kafka Subscription ID to be notified when a new export file is ready for retrieval	String See Chapter 4, Event monitoring using JMS for information about JMS client ID formats.
filter	Optional parameter that uses filter elements to specify the set of NEs for which data records are exported; you can use the parameter to reduce the volume of returned information	<filter>element</filter> See the registerLogToFile method description in the XML API Reference for a list of the supported filter elements and regular-expression syntax.
resultFilter	Optional parameter that specifies the attributes to include in the exported data records; you can use the parameter to reduce the size of the exported files	<attribute>attribute_name</attribute>
continuOnFailure	Optional parameter that specifies whether to continue processing requests in the stream after an exception occurs	The options are: true—processing continues after an exception false (default)—processing stops after an exception

The optional filter input parameter for registerLogToFile allows filtering on the monitoredObjectSiteName attribute of the log record that is written to the statistics file. The following filter tags are supported:

and
equal
in
not
notEqual
notSuperset

or
regex
subset
superset
wildcard

The following figure shows a registerLogToFile filter that allows log records for objects whose siteName begins with toro, vanc, or mont, and is followed by one to eight non-digits, wan, and one or more digits.

Figure 14-8: regex filter example

<filter>

   <regex name="monitoredObjectSiteName" value="^(toro|vanc|mont)[^0-9]{1,8}wan[0-9]+"/>

</filter>

The following figure uses an or tag to group three regular expressions that achieve the same results as in the previous figure. The regular expressions would each be evaluated against the same data set and the intermediate results would be merged together to produce the final result.

Figure 14-9: regex filter example using or expression

<filter>

   <or>

      <regex name="monitoredObjectSiteName" value="^toro[^0-9]{1,8}wan[0-9]+"/>

      <regex name="monitoredObjectSiteName" value="^vanc[^0-9]{1,8}wan[0-9]+"/>

      <regex name="monitoredObjectSiteName" value="^mont[^0-9]{1,8}wan[0-9]+"/>

   </or>

</filter>

Note: Regular expressions are case-sensitive. Case insensitivity flags may be introduced within the regular expression itself. For more information about Java regular expression syntax, refer to the Javadoc description (since Java 1.4) of class java.util.regex.Pattern.

The following figure shows a registerLogToFile request for performance statistics.

Figure 14-10: registerLogToFile request example, performance statistics

<registerLogToFile xmlns="xmlapi_1.0">

   <fullClassName>equipment.SystemCpuStats</fullClassName>

   <dirName>ossclient</dirName>

   <compress>false</compress>

   <jmsClientId>JMS_client@n</jmsClientId>

   <resultFilter>

      <attribute>systemCpuUsage</attribute>

      <attribute>monitoredObjectPointer</attribute>

      <attribute>monitoredObjectSiteId</attribute>

      <children/>

   </resultFilter>

</registerLogToFile>

One statistics file is created per statistics class for performance statistics and one statistics file is created per NE per record type, which translates to a statistics class, for accounting statistics. The statistics export files are created on the NFM-P main or auxiliary server that performs the statistics collection. The name of each exported file is unique because it is created using the requesting client ID and the current timestamp.

Statistics file creation frequency

The rollover period for accounting statistics files is equivalent to the NE file policy rollover time. See “To configure a file policy” in the NSP NFM-P Statistics Management Guide for more information about modifying a file policy.

You can use the NFM-P GUI to manage the rollover period for performance statistics files. See the system preferences configuration procedures in the NSP System Administrator Guide for more information.

Note: A statistics file export can generate a large number of files and use considerable disk space. The NFM-P periodically deletes aged files to control disk space usage. You can use the NFM-P GUI to manage the file retention time. See the procedure to configure the statistics data retention period for the main database in the NSP System Administrator Guide for more information.

XML statistics output file

Statistics retrieved from the registerLogToFile method in an XML format contain a set of elements and attributes that define the statistic class.

The following figure shows an extract from the XML output file for the statistic counter in the equipment.SystemCpuStats statistic object from the request in previous figure.

Figure 14-11: registerLogToFile statistics response example

<logToFileResponse xmlns="xmlapi_1.0">

   <equipment.SystemCpuStatsLogRecord>

      <systemCpuUsage>5</systemCpuUsage>

      <monitoredObjectPointer>network:198.51.100.60:shelf-1:systemStatsHolder</monitoredObjectPointer>

      <monitoredObjectSiteId>198.51.100.60</monitoredObjectSiteId>

   </equipment.SystemCpuStatsLogRecord>

</logToFileResponse>

Stopping statistics file export from registerLogToFile

An XML API client can deregister from receiving notifications for accounting and performance statistics and stop the export file creation by sending a deregisterLogToFile request. A deregisterLogToFile request requires only the JMS client ID as a parameter.

The following figure shows a sample deregisterLogToFile request.

Figure 14-12: deregisterLogToFile request example

<deregisterLogToFile xmlns="xmlapi_1.0">

   <!-- fullClassName is optional -->

   <fullClassName> equipment.SystemCpuStats </fullClassName>

   <jmsClientId>JMS_client@n</jmsClientId>

</deregisterLogToFile>

An XML API client is also deregistered when the client JMS session closes. The NFM-P checks JMS client connectivity every 5 minutes; you can use a GUI client to configure the maximum number of intervals before a disconnected client is deregistered. See the system preferences configuration procedures in the NSP System Administrator Guide.

A deregistered JMS client must re-register to receive notifications.

Statistics recovery after OSS connection loss

If an OSS client loses connectivity to an NFM-P main or auxiliary server that is collecting statistics, the OSS needs to retrieve the registerLogToFile export files when it reconnects. The files are still available for retrieval if the log retention time does not elapse before the client reconnects. See the NSP System Administrator Guide for more information about configuring the log retention time.

Statistics recovery after JMS client unsubscribed

If an OSS client JMS subscription becomes unsubscribed, the NFM-P deregisters the registerLogToFile session and stops creating export files after a configured time interval. Contact Nokia technical support for information about configuring the time interval.

Use subject to agreed restrictions on disclosure and use.