Web Services API Guide, Cisco DCNM for LAN, Release 5.x
CollectorApp Service
Downloads: This chapterpdf (PDF - 131.0KB) The complete bookPDF (PDF - 11.08MB) | Feedback

CollectorApp Service

Table Of Contents

CollectorApp Service

Information About CollectorApp Service

addStatisticalEntry

createCollector

deleteCollectionInfo

deleteCollectionInfoCol

deleteStatisticalDataCol

deleteStatisticalData

deleteStatisticalDataTillDate

fetchCollectedData

getAllCollectionInfo

getAllCollectionInfoByConfigIds

getAllCollectionInfoByStatus

getAllCollectionInfoByUserId

getAllCollectionInfoInDevice

getAllCollectionInfoInDeviceByStatus

getAllStatisticalEntriesForDevice

getCollectedData (Deprecated)

getCollectedStatisticalData

getCollectionInfo

getLatestCollectedStatisticalData

getValidConfigInstanceId

modifyCollectorAction

modifySchedule

removeStatisticalEntry

startCollector

startCollectors

startCollectorBySchedule

stopCollector

stopCollectors


CollectorApp Service


This chapter describes the DCNM web services' API methods for the CollectorApp service. This API is available for Cisco Nexus 7000 Series switches that run Cisco NX-OS Release 5.0(3) or later.

Information About CollectorApp Service

The collector allows you to address performance management of network resources. By analyzing statistical data with the collector, you can perform real-time monitoring of data that includes the traffic throughput, the percentage utilization, error rates, and the response time. As a result, you can efficiently use the network resources and have an in-depth knowledge of the network health.

The collector can read statistical information from the devices and store it in the database. You can use the collector APIs to retrieve the information stored in the database.

To perform a collection of statistical data, follow these steps:

1. Create a CollectionInfo by specifying a collection information name, a list of statistical data, a schedule (simple or cron style), and a collection action (persist).

2. Start scheduling the collection information.

To delete an existing collection of statistical data, follow these steps:

1. Stop the CollectionInfo if it is started.

2. Delete the collection information.

addStatisticalEntry

Associates the given statistical entry to an existing collection info. The given statistical entry should not be duplicated within the collection info.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

If the aStatisticalEntry is null

CollectorException is thrown if any of the following situation occurs:

If the aStatisticalEntry already exist for the given collection info

If the aStatisticalEntry have a configInstanceId which is belongs to a different device than the given collection info

Parameters

opContext—Operational context

collectionInfoId—instance name id of the CollectionInfo to which the given statisticalentry should be associated

aStatisticalEntry—instance of a StatisticalEntry that needs to be added to CollectionInfo StatisticalEntry

Return Value

InstanceNameId the instance name id of the StatisticalEntry

createCollector

Creates a collection info and returns its instance name id.

The given collection info object should have one or more statistical entries, a schedule and collector action. Collector will start polling as per the schedule given. If there is no start time is specified in the schedule, collector will start polling immediately

ValidationException is thrown if any of the following situation occurs:

If aCollectionInfo is null.

CollectorException is thrown if any of the following situation occurs:

If name is not specified in aCollectionInfo.

If collector action is not specified in aCollectionInfo.

If schedule is not specified in aCollectionInfo.

If statistical entries are empty in aCollectionInfo.

If statistical entries are duplicated in aCollectionInfo.

In the given statistical entries,

If statistical class name is null or configInstanceId is null or invalid.

If all the configInstanceIds are not belonging to the same device.

If there is no relation between statistical class and configInstanceId.

In the given schedule,

If the expression is invalid for Cron schedule.

If the specified end time is ending before start time.

If the specified interval is less than 30 seconds.

Parameters

opContext—Operational context

aCollectionInfo—instance of CollectionInfo

Return Value

InstanceNameId the instance name id of the CollectionInfo

deleteCollectionInfo

Deletes an existing collection info and the collected statistical data for the given collectioninfo.

Stops the collector if it is running for the given collection info.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

IntegrityException is thrown if the given collectionInfo does not exist in devices.

Parameters

opContext—Operational context

collectionInfoId—instance id of a CollectionInfo.

Return Value

void

deleteCollectionInfoCol

Deletes collection info and its statistical data for the given collection info id list. This method is available for Cisco Nexus 7000 Series switches that run Cisco NX-OS Release 5.1(1) or later.

Stops the collector if it is running for the given collection info ID list.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

AppException is thrown if any of the collectionInfo (given in the list) does not exist.

Parameters

opContext—Operational context

collectionInfoId—instance id of a CollectionInfo.

Return Value

void

deleteStatisticalDataCol

Deletes collected statistical data for the given collection info id list. This method is available for Cisco Nexus 7000 Series switches that run Cisco NX-OS Release 5.1(1) or later.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

AppException is thrown if any of the collectionInfo (given in the list) does not exist.

Parameters

opContext—Operational context

collectionInfoId—instance id of a CollectionInfo.

Return Value

void

deleteStatisticalData

Deletes the collected statistical data for the given collectioninfo.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

IntegrityException is thrown if the given collectionInfo does not exist in devices.

Parameters

opContext—Operational context

collectionInfoId—instance id of a CollectionInfo.

Return Value

void

deleteStatisticalDataTillDate

Deletes the collected statistical data for the given collectioninfo.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

IntegrityException is thrown if the given collectionInfo does not exist in devices.

Parameters

opContext—Operational context

collectionInfoId—instance id of a CollectionInfo.

Return Value

void

fetchCollectedData

Returns the last polled statistical data of an existing collection info with some additional information like next polling time.

ValidationException is thrown if any of the following situations occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

Parameters

OpContext—operational Context.

collectionInfoId—the instance ID of the CollectionInfo.

Returns

Return an instance of ExtendedCollectedData which is the statistical data that is polled at the last. This is usefull for realtime monitoring.

getAllCollectionInfo

Returns all existing collection info which matches with given statisticalclassname, configInstanceId and interval. If none of them are specified, returns all the CollectionInfos.

Parameters

opContext—Operational context

statisticalClassName—statistics class name

configInstanceId—InstanceNameId of the configuration instance

interval—polling interval

Return Value

All the CollectionInfo which matches with the given parameters

getAllCollectionInfoByConfigIds

Returns the active collection info which exactly matches with given statisticalclassname, configInstanceIds and interval. If none of them are specified, returns null.

Parameters

opContext—Operational context

statisticalClassName—statistics class name

configInstanceIds—List of InstanceNameId of the configuration instances

interval—polling interval

Return Value

Only one CollectionInfo which matches with the given parameters

getAllCollectionInfoByStatus

Returns all existing collection info with a specific collection status.

ValidationException is thrown if any of the following situation occurs:

If aCollectionStatus is null.

Parameters

opContext—Operational context

aCollectionStatus—status of the CollectionInfo

Return Value

All existing CollectionInfo having the specified CollectionStatus.

getAllCollectionInfoByUserId

Returns all existing collection info created by a user.

ValidationException is thrown if any of the following situation occurs:

If userId is null.

Parameters

opContext—Operational context

username—name of the user who created the CollectionInfo.

Return Value

All the CollectionInfo created by the specified username.

getAllCollectionInfoInDevice

Returns all existing collection info bound to a network element.

ValidationException is thrown if any of the following situation occurs:

If neInstanceNameId is null.

If neInstanceNameId is not a valid network element InstanceNameId.

Parameters

opContext—Operational context

networkElementId—instance id of the network element.

Return Value

All the CollectionInfo having the specified CollectionStatus.

getAllCollectionInfoInDeviceByStatus

Returns all existing collection info bound to a network element and having a specific collection status.

ValidationException is thrown if any of the following situation occurs:

If neInstanceNameId is null.

If neInstanceNameId is not a valid network element InstanceNameId.

If aCollectionStatus is null.

Parameters

opContext—Operational context

aCollectionStatus—status of the CollectionInfo

deviceId—instance id of the CollectionInfo

Return Value

All the CollectionInfo having the specified CollectionStatus.

getAllStatisticalEntriesForDevice

Returns all the statistical entries bound to a network element.

ValidationException is thrown if any of the following situation occurs:

If neInstanceNameId is null.

If neInstanceNameId is not a valid network element InstanceNameId.

Parameters

opContext—Operational context

networkElementId—instance id of the CollectionInfo

Return Value

All the statistical entries that were polled for the specified deviceId.

getCollectedData (Deprecated)

Returns the last polled statistical data of an existing collection info with some additional information like next polling time.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

Parameters

opContext—Operational context

collectionInfoId—instance id of the CollectionInfo

Return Value

Return an instance of ExtendedCollectedData which is the statistical data that is polled at the last. This is useful for real-time monitoring.

getCollectedStatisticalData

Deprecated.

Returns all the collected statistical data of an existing collection info.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

Parameters

opContext—Operational context

collectionInfoId—instance id of the CollectionInfo

Return Value

Return a collection of CollectedData which is all the statistical data that is polled for the specified collectionInfoId.

getCollectionInfo

Returns the instance of collection info specified by collection info name id.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

Parameters

opContext—Operational context

collectionInfoId—instance name id of the CollectionInfo

Return Value

CollectionInfo CollectionInfo

getLatestCollectedStatisticalData

Returns the last polled statistical data of an existing collection info.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

Parameters

opContext—Operational context

collectionInfoId—instance id of the CollectionInfo

Return Value

Return an instance of CollectedData which is the statistical data that is polled at the last. This is useful for real-time monitoring.

getValidConfigInstanceId

Returns valid configuration instance name ids for the given configuration instance name ids

Instancename ids will differ by the following cases, 1. Rediscovery 2. Type change ex. port mode change in interfaces 3. Data removed from the device 4. Identity is changed by APIs, ex: ACEs are recreated when ACL is getting updated through APIs. Valid instance name ids are returned by reloading from database for the given old instance name ids. ValidationException is thrown if any of the following situation occurs:

If configInstanceIdCol collection contains an element that is null or the collection is empty or it is not type InstanceNameId

if the argument passed is null or it is not a valid InstanceNameId.

Parameters

opContext—Operational context

configInstanceIdCol—InstanceNameId of the one or more configuration entities.

Return Value

The returned list will contain valid InstanceNameIds.

modifyCollectorAction

Modifies the collector action of an existing collection info.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

If aCollectorAction is null.

Parameters

opContext—Operational context

collectionInfoId—instance id of the CollectionInfo.

Return Value

void

modifySchedule

Modifies the schedule of an existing collection info.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If aSchedule is null.

If collectionInfoId is not a valid collection info InstanceNameId.

In the given schedule,

If the expression is invalid for Cron schedule.

If the specified end time is ending before start time.

If the specified interval is less than 30 seconds.

Parameters

opContext—Operational context

collectionInfoId—instance id of the CollectionInfo

aSchedule—new job schedule

Return Value

void

removeStatisticalEntry

Removes a StatisticalEntry from an existing collection info.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

If the statisticalEntryId is null

If statisticalEntryId is not a valid statistical entry InstanceNameId.

CollectorException is thrown if any of the following situation occurs:

If statisticalEntryId is not exist within the given collection info

If the given collection info is having only one statistical entry.

Parameters

opContext—Operational context

collectionInfoId—instance name id of the CollectionInfo

statisticalEntryId—instance name if of a StatisticalEntry that needs to be added to CollectionInfo StatisticalEntry

Return Value

void

startCollector

Starts polling for an existing collection info with its schedule.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

If aCollectorAction is null.

Parameters

collectionInfoId—instance id of the collection info

Return Value

void

startCollectors

Starts polling for an existing collection info with its schedule. This method is available for Cisco Nexus 7000 Series switches that run Cisco NX-OS Release 5.1(1) or later.

AppException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

If aCollectorAction is null.

Parameters

collectionInfoId—instance id of the collection info

Return Value

void

startCollectorBySchedule

Starts polling for an existing collection info as per the given schedule.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

If schedule is null.

In the given schedule,

If the expression is invalid for Cron schedule.

If the specified end time is ending before start time.

If the specified interval is less than 30 seconds.

Parameters

collectionInfoId—instance id of the collection info

Return Value

void

stopCollector

Stops polling for an existing collection info.

ValidationException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

If schedule is null.

Parameters

collectionInfoId—instance id of the collection info

Return Value

void

stopCollectors

Stops polling for an existing collection info. This method is available for Cisco Nexus 7000 Series switches that run Cisco NX-OS Release 5.1(1) or later.

AppException is thrown if any of the following situation occurs:

If collectionInfoId is null.

If collectionInfoId is not a valid collection info InstanceNameId.

If schedule is null.

Parameters

collectionInfoId—instance id of the collection info

Return Value

void