Statistics retrieval using findToFile

Overview

You can use the findToFile method to transfer accounting and performance statistics log records from the NFM-P to an OSS client. The method can save statistics from multiple NEs in one file. The NFM-P sends a FileAvailableEvent message each time a statistics file becomes available.

An OSS client that retrieves statistics files using the findToFile method requires a RHEL user account on each main server. 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.

The following figure shows the process associated with the statistics retrieval using the findToFile method.

Figure 14-13: findToFile statistics retrieval process

Note: In addition to the illustrated scenario, step 4 of Figure 14-13, findToFile statistics retrieval process can result in the following.

If a file name is specified, a write file is created.
If an FTP address is specified, the NFM-P server sends the file to a URL without creating an intermediate file.
If the file location is on a remote disk that is read directly by the client application, the application may read or copy the file.

Note: The OSS application is responsible for managing files and disk space associated with the requests.

Note: The NFM-P maps the object FDNs to a corresponding database index. It is recommended to use FDN properties in queries to maximize the query processing speed. The XML API queries should also use concrete classes, rather than an abstract class, to optimize performance.

Statistics retrieval examples using the findToFile method

Figure 14-14, findToFile request example, performance statistics shows a sample request to perform the following tasks using the findToFile method:

interface statistics collection
storage of the collected statistics in XML format

Figure 14-14: findToFile request example, performance statistics

<SOAP:Body>

   <findToFile xmlns="xmlapi_1.0">

      <fullClassName>equipment.InterfaceAdditionalStats</fullClassName>

      <filter>

         <or>

            <equal name="monitoredObjectSiteId" value="10.1.202.95"/>

            <equal name="monitoredObjectSiteId" value="10.1.202.94"/>

         </or>

      </filter>

      <resultFilter>

         <attribute>receivedTotalOctetsPeriodic</attribute>

         <attribute>transmittedTotalOctetsPeriodic</attribute>

      </resultFilter>

      <fileName>Equipment.InterfaceAdditionalStatsLogRecord.xml</fileName>

   </findToFile>

</SOAP:Body>

The following table describes the input parameters of the findToFile method.

Table 14-3: findToFile 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
fileName	The relative file in which to store the results. The format is: [s]ftp://[user:password@]host[:port]/directory/file	The following format rules apply. For a remote client, the directory is relative to the default client FTP directory. The / and ; characters are reserved, so must be encoded. For example, to specify a file in the /tmp directory on the client, the path is ftp://name@password/%2Ftmp/filename.xml. The path ftp://name@password/tmp/filename.xml specifies a file in a /tmp directory under the client FTP directory. See RFC 1738 Uniform Resource Locators (URL), Section 3.2.2 for more information about the FTP URL path requirements.
timeStamp	Include the timestamp in the name of the result file.	The options are: true false (default)
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
timeout	The time, in ms, after which the operation times out. The request is aborted and an exception is returned in the FileAvailableEvent notification. The result file may be incomplete.	The default is 0, which means no timeout.
filter	Optional but strongly recommended parameter that uses filter elements based on properties of the class specified by the fullClassName parameter	<filter>element</filter> See the findToFile method description in the XML API Reference for a list of the supported filter elements and regular-expression syntax. It is recommended to filter only the relevant attributes and to use the timeCaptured attribute to limit the scale of logRecords for efficiency.
resultFilter	Optional but strongly recommended parameter that filters to restrict the information returned per object	<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
synchronous	Optional parameter that specifies that the method runs synchronously; the result is returned only after the method completes.	The options are: true—processing continues after an exception false (default)—processing stops after an exception

To return the data in a streamed XML result, you can use the <find> method with a similar set of filters. This method of statistics retrieval is recommended for testing, not for periodic retrieval. See Chapter 13, Inventory management for more information.

When you create export files using the findToFile method:

the export files are placed in a directory that is specified during the NFM-P server installation
an FTP server is not installed during the NFM-P database installation. To export files from the specified directory, an FTP server can be installed on the same machine as the database, if required. If the files are on a remote disk, an FTP server may not be required to access files.

An exception-free response indicates that the request was received and validated.

Sample request to retrieve historical statistics from an NE

The following figure shows a sample request to retrieve historical statistics from an NE using the findToFile method. The sample uses the timeCaptured attribute to limit the number of logRecords to be retrieved on a specific port only.

Figure 14-15: findToFile request example, historical NE statistics

<SOAP:Body>

   <findToFile xmlns="xmlapi_1.0">

      <fullClassName>equipment.InterfaceAdditionalStatsLogRecord</fullClassName>

      <filter>

         <and>

            <equal name="monitoredObjectPointer" value="network:10.1.202.93:shelf-1:cardSlot-1:card:daughterCardSlot-1:daughterCard:port-3"/>

            <between name="timeCaptured" first="1127142900000" second="1127143800000"/>

         </and>

      </filter>

      <fileName>Equipment.InterfaceAdditionalStatsLogRecord.xml</fileName>

   </findToFile>

</SOAP:Body>

XML statistics output file

Statistics retrieved from the NFM-P database 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.InterfaceAdditionalStatsLogRecord statistic object from the request in the previous figure.

Figure 14-16: Statistics XML output file example

<findToFileResponse xmlns="xmlapi_1.0">

   <equipment.InterfaceAdditionalStatsLogRecord>

      <monitoredObjectClass>equipment.PhysicalPort</monitoredObjectClass>

      <monitoredObjectPointer>network:10.1.202.93:shelf-1:cardSlot-1:card:daughterCardSlot-1:daughterCard:port-3</monitoredObjectPointer>

      <displayedName>Port 1/1/3</displayedName>

      <monitoredObjectSiteId>10.1.202.93</monitoredObjectSiteId>

      <monitoredObjectSiteName>sim202_93</monitoredObjectSiteName>

      <timeCaptured>1127878285113</timeCaptured>

      <periodicTime>938610</periodicTime>

      <suspect>false</suspect>

      <objectFullName>equipment.InterfaceAdditionalStatsLogRecord.equipment.InterfaceAdditionalStats30-346</objectFullName>

      <name>equipment.InterfaceAdditionalStats30-346</name>

      <createdOnPollType>ScheduledFullNodeResync</createdOnPollType>

      <updatedOnPollType>ScheduledFullNodeResync</updatedOnPollType>

      <recordId>346</recordId>

      <bucketId>30</bucketId>

      <deploymentState>0</deploymentState>

      <receivedTotalOctets>0</receivedTotalOctets>

      <receivedTotalOctetsPeriodic>0</receivedTotalOctetsPeriodic>

      <receivedUnicastPackets>0</receivedUnicastPackets>

      <receivedUnicastPacketsPeriodic>0</receivedUnicastPacketsPeriodic>

      <receivedMulticastPackets>0</receivedMulticastPackets>

      <receivedMulticastPacketsPeriodic>0</receivedMulticastPacketsPeriodic>

      <receivedBroadcastPackets>0</receivedBroadcastPackets>

      <receivedBroadcastPacketsPeriodic>0</receivedBroadcastPacketsPeriodic>

      <transmittedTotalOctets>0</transmittedTotalOctets>

      <transmittedTotalOctetsPeriodic>0</transmittedTotalOctetsPeriodic>

      <transmittedUnicastPackets>0</transmittedUnicastPackets>

      <transmittedUnicastPacketsPeriodic>0</transmittedUnicastPacketsPeriodic>

      <transmittedMulticastPackets>0</transmittedMulticastPackets>

      <transmittedMulticastPacketsPeriodic>0</transmittedMulticastPacketsPeriodic>

      <transmittedBroadcastPackets>0</transmittedBroadcastPackets>

      <transmittedBroadcastPacketsPeriodic>0</transmittedBroadcastPacketsPeriodic>

      <children-Set/>

   </equipment.InterfaceAdditionalStatsLogRecord>

</findToFileResponse>

Statistics recovery after OSS connection loss

If an OSS loses connectivity to the NFM-P server and statistics records are not being retrieved, the OSS client needs to record the time of the most recent statistics retrieval. When the connectivity is restored, the OSS client must send specific findToFile requests for the missed statistics data. The OSS must be aware of the different Statistics Policy retention times so that it does not request older log records that have been deleted from the NFM-P database.

Missing performance statistics

It is possible that in between NFM-P performance statistics collection intervals, there are no statistics detected by the OSS. This means that performance statistics log records are missing from the NFM-P database. If these statistics records are missing, the NFM-P server does not attempt to retry collection from the NEs. Therefore, an OSS client does not need to attempt to retrieve the missing statistics log records for the collection interval, and can continue to process statistics for the next collection interval.