- Macros
- ADD
- APPNAME
- APSTATSXMLPOLL
- ASNTONAME
- AVIPOLL
- BITS
- BOTTOMN
- BYTESTOMACADDR
- CHANGENODEIPADDRESSES
- CONTAINS
- COUNT
- CREDSEXIST
- CSVPULLNEXT
- DATEANDTIME
- DCMPOLL
- DELTA
- DELTANEXT
- DEVICECUSTOMNAME
- DEVICEID
- DEVICEIPADDRESS
- DEVICELOCATION
- DEVICENAME
- DEVICESTATE
- DEVICESOFTWAREVERSION
- DEVICESYNCNAME
- DEVICESYSNAME
- DEVICETYPE
- DIRNAMEPOLL
- DOUBLEVALUE
- ENDSWITH
- ENTITYINFO
- EXPONENT
- FILTER
- FILTERCUSTOMINTERVAL
- FLOWPOLL
- FOR
- FOREACH
- FORMATTIME
- GENERICCSVPOLL
- GET
- GETALL
- GETAPSTATSINFO
- GETAVAILABILITYINFO
- GETCEPHCLUSTERNAME
- GETDOMAINBYIPADDRESS
- GETDSCP
- GETECN
- GETIPGROUP
- GETHOSTADDRESS
- GETHOSTNAME
- GMONDPOLL
- GETNETFLOWSTATS
- GETPINGINFO
- GETPREFIX
- GETSERVERBY PORT
- GETSTRING
- GETSYSTEMPROPERTY
- GROUP
- GETWEBQUERIES
- HASGMONDPOLL
- HASCAPABILITY
- HASINTERFACE
- HASMATCHINGENTRIES
- HASSENSOR
- HASVAR
- HEX2STRING
- HOSTANDPLUGINPOLL
- HYPERVISORPOLL
- HYPERVISORPOLLPERSIST
- IF
- IFDESCR
- IFINFO
- IFSPEED
- IFSPEEDRECEIVE
- IFTABLE
- INDEXOF
- INRANGE
- INTERVALDURATION
- INTVALUE
- INVENTORYPERSIST
- IOSVERSION
- IPADDRESS
- IPADDRTOLONG
- ISCOLLECTD
- ISINGROUP
- ISHYPERVISOR
- ISNULL
- ISTABLEEMPTY
- ISTABLENOTEMPTY
- JOIN
- JMXCREDSEXIST
- JMXPOLL
- LEFTJOIN
- LEFTJOINMANY
- LENGTH
- LONGVALUE
- MAP
- MACADDRESS
- MATCHES
- MATCHESGROUP
- NOT
- OPENSTACKPOLL
- OSCREDSEXIST
- PARSESTRING
- POLL
- POLLMT
- POLLNEXT
- POLLPERSIST
- PROCESSORLIST
- PROTOCOLNAME
- RATE
- REMOVE
- RUNCMD
- SETALGORITHMS
- SETCPUINFO
- SETMEMORYPOOLINFO
- SETTIMEVARINFO
- SMIEXIST
- SMIPOLL
- STARTSWITH
- SYSTIME
- TABLEINDICES
- TOCIDSHEALTHSECMONMISSEDPKT
- TOLOWERSTRING
- TOPN
- TOSTRING
- TOUPPERSTRING
- VIEWDESCENDANT
- XMLPOLL
- XMLPOLLNEXT
- XMLPOLLPERSIST
- XMLPOLLTKPERSIST
- XMLPOLLWITHTOKEN
- Y1731XMLPOLLNEXT
Reports Macro Reference
The Prime Performance Manager report interface provides a number of predefined report macros that you can use in your reports. Macros can be called in two different ways:
1.
object.macro ( arg1, arg2, arg3, etc.) or
2. macro ( object, arg1, arg2, arg3, etc.)
In the reference topics in this chapter, syntax for the second method is provided.
If arguments are enclosed in square brackets ([]), this indicates that the argument optional.
When it is stated that a certain argument is of a certain type (i.e, the object is a string type), that argument can also be replaced with:
Macros
- ADD
- APPNAME
- APSTATSXMLPOLL
- ASNTONAME
- AVIPOLL
- BITS
- BOTTOMN
- BYTESTOMACADDR
- CHANGENODEIPADDRESSES
- CONTAINS
- COUNT
- CREDSEXIST
- CSVPULLNEXT
- DATEANDTIME
- DCMPOLL
- DELTA
- DELTANEXT
- DEVICECUSTOMNAME
- DEVICEID
- DEVICEIPADDRESS
- DEVICELOCATION
- DEVICENAME
- DEVICESTATE
- DEVICESOFTWAREVERSION
- DEVICESYNCNAME
- DEVICESYSNAME
- DEVICETYPE
- DIRNAMEPOLL
- DOUBLEVALUE
- ENDSWITH
- ENTITYINFO
- EXPONENT
- FILTER
- FILTERCUSTOMINTERVAL
- FLOWPOLL
- FOR
- FOREACH
- FORMATTIME
- GENERICCSVPOLL
- GET
- GETALL
- GETAPSTATSINFO
- GETAVAILABILITYINFO
- GETCEPHCLUSTERNAME
- GETDOMAINBYIPADDRESS
- GETDSCP
- GETECN
- GETIPGROUP
- GETHOSTADDRESS
- GETHOSTNAME
- GMONDPOLL
- GETNETFLOWSTATS
- GETPINGINFO
- GETPREFIX
- GETSERVERBY PORT
- GETSTRING
- GETSYSTEMPROPERTY
- GROUP
- GETWEBQUERIES
- HASGMONDPOLL
- HASCAPABILITY
- HASINTERFACE
- HASMATCHINGENTRIES
- HASSENSOR
- HASVAR
- HEX2STRING
- HOSTANDPLUGINPOLL
- HYPERVISORPOLL
- HYPERVISORPOLLPERSIST
- IF
- IFDESCR
- IFINFO
- IFSPEED
- IFSPEEDRECEIVE
- IFTABLE
- INDEXOF
- INRANGE
- INTERVALDURATION
- INTVALUE
- INVENTORYPERSIST
- IOSVERSION
- IPADDRESS
- IPADDRTOLONG
- ISCOLLECTD
- ISINGROUP
- ISHYPERVISOR
- ISNULL
- ISTABLEEMPTY
- ISTABLENOTEMPTY
- JOIN
- JMXCREDSEXIST
- JMXPOLL
- LEFTJOIN
- LEFTJOINMANY
- LENGTH
- LONGVALUE
- MAP
- MACADDRESS
- MATCHES
- MATCHESGROUP
- MACADDRESS
- NOT
- OPENSTACKPOLL
- OSCREDSEXIST
- PARSESTRING
- POLL
- POLLMT
- POLLNEXT
- POLLPERSIST
- PROCESSORLIST
- PROTOCOLNAME
- RATE
- REMOVE
- RUNCMD
- SETALGORITHMS
- SETCPUINFO
- SETMEMORYPOOLINFO
- SETTIMEVARINFO
- SMIEXIST
- SMIPOLL
- STARTSWITH
- SYSTIME
- TABLEINDICES
- TOCIDSHEALTHSECMONMISSEDPKT
- TOLOWERSTRING
- TOPN
- TOSTRING
- TOUPPERSTRING
- VIEWDESCENDANT
- XMLPOLL
- XMLPOLLNEXT
- XMLPOLLPERSIST
- XMLPOLLTKPERSIST
- XMLPOLLWITHTOKEN
- Y1731XMLPOLLNEXT
ADD
If object is an instance of a collection, the macro adds the arg1 data to object collection. If the object is an instance of Map, the macro adds the key-value (arg1-arg2) pair to object. Returns null, in case of a failure.
- object is either an object instance or a collection instance.
- arg1 is either a key or a value.
- arg2 is a value.
APPNAME
APSTATSXMLPOLL
APSTATSXMLPOLL (arg1, arg2, arg3)
Collects AP (Access Point) stats from 3GPP XML files.
- arg1: a string type, it's the filename of a properties file in etc/apstats/system/, example for RMS-LUS.properties, arg1 is "RMS-LUS", this properties file defines the parameters for the macro to pull AP stats files from RMS LUS server.
- arg2: a list of counters to be collected by this macro call, separated by comma.
- arg3: a list of key counters, separated by comma.
ASNTONAME
Retrieves AS name (description) given an AS number.
AVIPOLL
AVIPoLL (arg1,arg2,arg3,arg4,arg5,arg6,arg7,arg8,arg9,arg10,arg11,arg12,arg13,arg14)
Used only in the PollDefinition section to retrieve AVI device report data. Parameters:
- param 0—Values that need to be polled
- param 1—REST API input parameters
- param 3—REST AP URL pattern for I
- param 4—The path to get results
- param 5—Static or dynamic configuration
- param 6—Map or list<map>
- param 7—REST API input metrics list
- param 8—REST API input parameters
- param 9—Additional REST API parameters
- param 10—Additional REST API parameters
- param 11—REST API header name
- param 12—REST API header name
- param 13—Cache key
BITS
Returns true if the position in object identified by arg is 1; false, otherwise:
BOTTOMN
Returns the bottom n (arg2) rows from object sorted by a sort key ascending:
- object is a table
- arg1 is what column to sort by
- arg2 is the number of records to get (n)..
- When used in the Filter section in a ProcessDBSummary section, rows is an implicit variable that typically can be used for an object that is set when ProcessDBSummary execution is complete.
BYTESTOMACADDR
Converts given address (in bytes) to MAC address (in String).
CHANGENODEIPADDRESSES
CHANGENODEIPADDRESSES (ipAddrTable, ipAddressTable, cIpAddressTable.)
Used in conjunction with the report poller ipAddress.xml file. This macro updates the node IP addresses using the IP addresses polled from the corresponding report poller ipAddress.xml file where ipAddrTable, ipAddressTable and cIpAddressTable contain the results of polling and joining the interface and address tables from IF-MIB.my, IP-MIB.my, and CISCO-IETF-IP-MIB.my MIBs. Refer to the $SR/etc/pollers/system/ipAddress.xml poller configuration file for further information.
CONTAINS
Checks if arg1 contains arg2. If it is contained, it returns true, else it returns false.
COUNT
Ipdates the rows of the grouped data and the count of these rows. Returns the count.
CREDSEXIST
Checks whether specific credentials exist.
CSVPULLNEXT
Pulls the device CSV, which is regularly updated with new lines. This macro parses the file and pulls new lines (after last pull) from it. The new lines are stored as a CSV file in the drop directory. The directory is monitored and parsed by the generic bulkstats feature. For example, in small cells, the PMG server inserts a new line to its pmg-perf-periodic.csv file every 20 seconds.
DATEANDTIME
Returns the DateAndTime format defined in SNMPv2-TC or a time value in milliseconds defined in the Java Calendar.getTimeInMillis(). Detailed input information:
Note If only local time is known, time zone information (fields 8-10) is not present.
DCMPOLL
Parses the performance file in cache that is pushed from the DCM module in device.
DELTA
Returns the delta between the current and the previous poll value (currentPolling - previousPolling). Each time the poll is performed, the poll value is persisted for use as the 'previous' poll value the next time a poll is performed. The macro also takes care of conditions that can occur such as when the first poll occurs (no previous value) and when the number overflows.
- object parameter is a numeric type If detect wrap is enabled it will check for wraps and adjust before calculating difference.
- Used only in the ProcessPollResult section.
DELTANEXT
Calls the DELTA macro between the next row in the database instead of the previous polling. Continues to calculate the delta until the row's value for arg1 changes.
- Object is a numeric type and arg1 is a string type, which is the name of an index of a previously created variable in the PollDefinition section (needs to be in the same table as object).
DEVICECUSTOMNAME
Returns the custom name of the device.
DEVICEID
Returns the unique ID of the device.
DEVICEIPADDRESS
Returns the IP address for the device in the current context.
The following entry determines if the device's IP addresses contains "102.168":
DEVICELOCATION
Returns the device location attribute.
The following entry determines if the device's location attribute contains "labx":
DEVICENAME
The following entry determines if the device name attribute contains "ppm7000a":
DEVICESTATE
Gets the Device State metrics including alarms and severities at the server level that is at the gateway. The macro may be invoked using any of the following options as parameter.
– “Device” - provides severity counts for each device
– “DeviceType” - provides severity counts for each device type
– “Alarm Severity” - provides counts all alarm severities
– “Highest Severity” - provides counts of only severities.
DEVICESOFTWAREVERSION
Returns the device software version.
The following entry determines if the current device's software version contains 1.7.0:
DEVICESYNCNAME
The following entry determines if the device's sync name contains ppm7000a:
DEVICESYSNAME
Returns the device system name.
The following entry determines if the device's system name contains ppm7000a:
DEVICETYPE
Returns the device type of the node, if found, else returns "unknown".
DIRNAMEPOLL
DIRNAMEPOLL (arg1, arg2, arg3, arg4, arg5, arg6)
This class provides the directory name poll function.
- arg1 - package ID
- arg2 - action name
- arg3 - the name of the base directory
- arg4 - keys for values
- arg5 - static or dynamic config
- arg6 - cache key
DOUBLEVALUE
Converts object into a double and returns it. Returns Null, if there is a failure.
ENDSWITH
Returns true if the string object ends with the string arg1. It is similar to Java's endsWith string function.
ENTITYINFO
Gets the data of ENTITY-MIB. If it is found in cache, the cache data will be returned. If not, the persistency data is checked. If found and the entity is not been changed since the last poll, the persisted data is returned. If still no data is available, the device is polled for the entity data.
EXPONENT
Returns the exponent value. Returns Null, in case of a failure.
FILTER
Returns a subset of objects with items that do not pass the conditions (items that return false) removed.
FILTERCUSTOMINTERVAL
FILTERCUSTOMINTERVAL (Object arg)
Filters data based upon a user specified filter.
FLOWPOLL
FLOWPOLL (arg1, arg2, arg3, arg4)
Used only in the PollDefinition section TO retrieve NetFlow statistics from receive NetFlow streams.
- arg1—A list of non-key fields (comma delimited list of field names in double quotes) to be retrieved from NetFlow streams.
- arg2—A list of key fields (comma delimited list of field names in double quotes) to be retrieved from NetFlow streams. A key field can optionally have a default value separated by a colon delimiter.
- arg3—A list of template IDs fields (comma delimited list of template numbers in double quotes). If key fields are not enough to identify unique flows by themselves, you can provide template IDs to act as additional filters. This argument is optional.
- arg4—A list of valid NetFlow versions (comma delimited list of version numbers in double quotes). If provided the macro returns rows only when the device’s NetFlow version matches with one of the version numbers in this parameter list. This argument is optional.
FOR
The macro uses the arguments: loop initializer, loop control and loop increment, in a Java' for' loop and determines the return value of each processor. If the return value is a break, it breaks the Java for loop.
- arg1 is the loop initializer.
- arg2 is the loop control.
- arg3 is the loop increment.
- arg4 is the value, which indicates the processor.
FOREACH
The macro uses a Java 'for' loop to iterate through each record of the object. Each object along with the arg1 is used to determine the return value. If the return value is a break, it breaks the Java 'for' loop.
FORMATTIME
Converts the object into an HH:MM:SS formatted string and returns the string. If a failure occurs, returns "00:00:00".
GENERICCSVPOLL
GENERICCSVPOLL (arg1, arg2, arg3, arg4)
Used only in the PollDefinition section. Used specifically to retrieve Generic Bulk statistic counter values from the generated CSV files. Helps to retrieve counters that belong to the same type. Note that you need to poll all counters referenced in current and other reports with the same label in the same poll macro. This is to prevent re-parsing of bulk statistics file.
- arg1—Indicates the Generic CSV template filename as defined in /opt/CSCOppm-gw/etc/csvstats/system folder.
- arg2—List of non-key counters (comma delimited list of counter names in double quotes) to get from bulk statistics file. Each counter variable is prefixed with the data type of the counter variable so that Prime Performance Manager knows how to parse this variable.
- arg3—List of key counters (comma delimited list of counter names in double quotes) for that act as key for the counters in arg2. Each key variable is prefixed with the data type of the counter variable so that Prime Performance Manager knows how to parse this variable. If there are no key fields an empty string is used.
- arg4—Where condition clause that can be used to retrieve only selected rows that satisfy the condition expression defined.
GET
Returns the element specified by arg1.
GETALL
Returns all the column values of arg1. Returns Null in case of a failure.
GETAPSTATSINFO
This macro is used to poll the statistics of the APStats collector
GETAVAILABILITYINFO
Gets availability information (i.e. whether the system is up or down) from the node (MWTMCURRTIME, sysUpTime, sysName, and availability). In the report in the Poll section, it needs an extra argument: alwaysExecute="true."
GETCEPHCLUSTERNAME
Retrieves the Ceph cluster name as well as the Ceph cluster FSID (UUID). It returns a map with the ClusterName and FSID keys (or null in the case of failure).
GETDOMAINBYIPADDRESS
GETDOMAINBYIPADDRESS (Value ipaddress)
A macro to map an ip address to a top-level domain.
As a theoretical use case: maybe a customer wants a netflow report that includes a column showing all traffic related to google, youtube, gmail, and google maps simply as 'google'.
This can be achieved by listing the ip addresses (x.y.z.1) or ip address ranges (x.y.*.1-5) in the IPToDomainMap.properties file and associating them with 'google'.
GETDSCP
Used only in the ProcessPollResult section to return a textual representation of the Differentiated Services Code Point (DSCP) for input to the Type Of Service (ToS) field as arg1. The macro uses the higher order six bits of input for the ToS field for name lookup. The macro is generally used for NetFlow reports to display the name of the DSCP instead of numerical values. Table B-1 shows the DSCP name and decimal and ToS values.
|
|
|
|
|---|---|---|
AF111 |
||
CS12 |
||
EF3 |
||
|
|
GETECN
Used only in the ProcessPollResult section to return a textual representation of Error Congestion Notification (ECN) for input Type Of Service (ToS) field as arg1. The macro uses the lower order 2 bits of input ToS field for name lookup. Generally used for NetFlow reports to display the ECN name instead of numerical value in reports. Table B-2 shows the ToS values and ECN names.
|
|
|
|
|---|---|---|
GETIPGROUP
Returns an ip group given an ip address. How an ip group is defined via ip addresses is specified in IPGroupSchema, which is located under $ppm_root_dir/etc/IPGroupSchema by default.
GETHOSTADDRESS
Returns the host address in string form. Returns null in case of a failure.
GETHOSTNAME
Returns the host name in string format. The hostname is resolved using the naming resolution defined in the optional arg parameter. If the arg parameter is not provided, the macro uses the naming resolution defined in RESOLVE_HOST_NAMES in the Reports.properties file. If RESOLVE_HOST_NAMES is not found in Reports.properties, the macro uses the DNS to resolve the IP to a hostname. Regardless of the naming resolution strategy, if the macro cannot resolve the IP address, it returns the IP address itself as the hostname.
- object is an IP address.
- arg is an optional parameter that is used to define the naming resolution. Strategy to use: DNS or PPM. The expected value is one of the following:
The default is dns when nothing is provided, and the RESOLVE_HOST_NAMES setting is not found in the Reports.properties file.
The macro is used only in the ProcessPollResult section.
GMONDPOLL
Polls the remote gmond service through a specific socket port. (The default is 8649.)
- arg0 – metrics names that need to poll
- arg1 - cache key (optional)
- arg2 - true if just get local node metrics (optional, default is false)
GETNETFLOWSTATS
Gathers metrics about NetFlow collection process. Flow counts received by the collector, processed into the PPM database, and missed flows (tracked by UDP sequence) are reported.
GETPINGINFO
This macro uses the Device context to obtain a node object. The node object returns a list(of map) of ping results.
GETPREFIX
Used only in the ProcessPollResult section to return the IP Address prefix using the IP address and subnet mask as inputs.
To get the value in string format you can use the GetHostAddress() macro passing the prefix.
GETSERVERBY PORT
Used only in the ProcessPollResult section to return the service name for the given port number and protocol name. Uses the services file in the etc directory on the gateway and unit for the service name lookup.
Generally used with NetFlow reports to display the service or application name in reports.
GETSTRING
GETSTRING (arg1, arg2, [arg3], [arg4], [arg5])
Gets the substring from a string that matches the regular expression passed in. The macro takes 5 arguments of which 2 are mandatory and 3 are optional. The different parameter combination includes:
- (string, regex) -> in this form, startGrp# is 0, endGrp# is the number of capturing groups in this pattern, return value = matched string/null if no match found.
- (string, regex, startGrp#) -> in this form, the endGrp# is the number of capturing groups in this pattern, return value = matched string/null if no match found
- (string, regex, startGrp#, endGrp#) -> in this form, return value = matched string/null if no match found.
- (string, regex, startGrp#, endGrp#, retval) -> in this form, the return value = string/retVal.
GETSYSTEMPROPERTY
GETSYSTEMPROPERTY (arg1, arg2)
Uses arg1 to fetch the system property in the form of a string. If this fails, arg2 is used as a default return value.
GROUP
This macro has groups of rows in a table. It is useful when used with the count macro. It returns the grouped data.
- object is the row which requires grouping.
- arg1 and arg2 are the column names that need to be grouped for a row.
- Used in cmts.xml report.
GETWEBQUERIES
Fetches Web Query Statistics at the server level. The web query statistics provide information on the number of web queries made on a report at the device and network levels.
HASGMONDPOLL
Checks if data can be retrieved using the gmond service.
- arg0 - metrics names that need to poll (optional)
- arg1 - true if just get local node metrics (optional)
HASCAPABILITY
Checks if the Capability names listed as parameters are applicable for the given Node object.
HASINTERFACE
Enables the setting of capabilities based on the existence of certain interfaces.
- arg1 isa conditional statement used to check if any of the device interfaces match the condition
- Used only in the SystemCapability.xml file.
HASMATCHINGENTRIES
HASMATCHINGENTRIES (arg1,arg2)
Checks if the table has the entries by matching filter.
HASSENSOR
Checks for the strings "transmit', 'receive', 'tx', 'rx.' Because these are common strings in the entity table and are not necessarily optical sensor specific, might also need to inspect the entityphysicalvendortype field.
HASVAR
Checks if the MIB variables in the parameter list exists for the given device.
HEX2STRING
Supports the HEX to string conversion. The delimiter is supported as input parameter to separate the HEX values.
HOSTANDPLUGINPOLL
Polls the host name and the plugins for collected
HYPERVISORPOLL
HYPERVISORPOLL (arg1, arg2, arg3, arg4, arg5)
Support the Hypervisor collector. It returns the results from the Hypervisor Poll.
- arg0 is the function name
- arg1 are the input parameters
- arg2 are the keys for values
- arg3 indicates static or dynamic
- arg4 is the cache key
HYPERVISORPOLLPERSIST
Fetches the hypervisor capability and persists it.
IF
If two arguments are used, returns/executes arg1 if object is True or returns Null if object is False. If three arguments are used, returns/executes arg1 if object is True or returns/executes, arg2 if object is False.
IFDESCR
Returns a description of the interface by looking it up first, to prevent re-polling. It returns the optional argument is the index key for the operation (default is ifIndex).
Used only in the ProcessPollResult section.
IFINFO
Returns a list of rows that contain Iftable and ifXtable SNMP data for the current device.
Maximum interface bandwidth is variable. For example, a user can configure QoS on a gigabit interface, so ifSpeed 1000 MBPS). SNMP polling might determine the interface bandwidth is 300 MBPS, so 300 MBPS is the maximum bandwidth instead of 1000 MBPS.
You can use the devicePolicies.xml file, located in /opt/CSCOppm-gw/etc/policies/users to configure specific maximum bandwidths for interfaces instead of relying on SNMP polling. Each device policy is defined in the following format:
IFSPEED
Returns the configured interface speed.
Used only in the ProcessPollResult section.
The optional argument is the index key for the operation (default is ifIndex).
IFSPEEDRECEIVE
Returns the receive interface speed.
IFTABLE
Returns a list of rows that contain the Iftable SNMP data for the current device.
INDEXOF
Provides the index of a character or substring in a string.
- Object - is the string
- arg1 – is the character or substring whose index in Object needs to be obtained.
INRANGE
Supports the range matching for MPLS OAM reports, in which it needs to check if the IPSLA index is included in the probe list rttMplsVpnMonCtrlProbeList. The following cases are supported by this macro:
(a) Individual ID's with comma separated as 1,5,3.
(b) Range form including hyphens with multiple ranges being separated by comma as 1-10,12-34.
(c) Mix of the above two forms as 1,2,4-10,12,15,19-25.
Returns true if successful and false otherwise.
INTERVALDURATION
Returns the time interval for the given report (in seconds). For reports, this will typically only be 15 min, 1 hour, 1 day, and so on.
INTVALUE
Converts the object into an integer. Returns Null, if there is an error.
INVENTORYPERSIST
Persists the value of last change time on running config and entity for other macro usage.
IOSVERSION
If object is "sysDescr" (which is typical), parses the IOS version from the given string.
IPADDRESS
IPADDRESS (object, [arg1, arg2])
If only one argument is used, returns the object converted into an IP address. If only two arguments are used, returns object (starting at byte "arg1") converted into an IP address. If three arguments are used, returns object (starting at byte "arg1" and ending at byte "arg2") converted into an IP address. Offsets are similar to Java's substring function.
- Object is an octet string address and arg1/arg2 are offsets.
- Used only in the ProcessPollResult section.
IPADDRTOLONG
Transforms the OSPF area ID value with an IP-address-format to a long-value-format. For example, the IP address, 0.0.1.44, corresponds to 300, and 255.255.255.255 corresponds to 4294967295.
Note When used in the WebReport section of xml files, transform the long value to String type by calling ToString() macro, so it can be displayed correctly in the GUI. Otherwise, it might display '4.29G' for '4294967295'.
ISCOLLECTD
Determines whether this is a collectd.
ISINGROUP
Checks whether a certain IP address belongs to a user specified IP group. It is mainly used to filter records and in turn only dump the filtered records into the DB to save space.
ISHYPERVISOR
Determines whether the device is a hypervisor.
ISNULL
If one argument is used, returns True if the object is Null and False otherwise. If two arguments are used, returns the object if it is not Null or returns arg1 if it is Null.
ISTABLEEMPTY
Checks if each MIB table in the parameter list is empty or does not exist for the node. Returns True if the object is empty.
ISTABLENOTEMPTY
Checks if each MIB table in the parameter list is not empty. Returns True if object is not empty.
JOIN
Returns the resulting joined tables of object and arg1. A row from object and a row from arg1 are joined together if the condition (arg2) is true.
- object and arg1 are tables and arg2 specifies a match condition.
- Used only in the PollDefinition section.
JMXCREDSEXIST
Checks if the JMX Credentials exist for a particular device.
JMXPOLL
JMXPOLL (BeanName [Path [ s | c | d ]
Retrieves Java Management Extension (JMX) attributes from a server. The macro can be invoked in one of two ways:
- JMXPoll(BeanName)—Polls only the bean name, without specifying an attribute.
- JMXPoll(BeanName)—Polls only the bean name, specifyies an attribute and the depth of the attribute to poll. Options:
– BeanName—The full name of the bean.
– Path—The name of an attribute and its subattributes, if any. The # delimiter used between levels of an attribute, that is, between an attribute and its subattributes.
– s—Retrieves the simple attributes at the path. Example: String, long, string array, long array.
– c—Retrieves all the children attributes from the path. Example: composite data, tabular data.
– c—Retrieves all the descendants, up to the leaf, from the path. Example: composite data, tabular data. Examples: composite data array,combination of composite and tabular data.
The JVM bean has many data types. Here is a summary with an example of their JMXPoll invocation.
LEFTJOIN
Returns the resulting joined tables of object and arg1. A row from object and a row from arg1 are joined together if the condition (arg2) is True. However, each row in the object continues to be retained in the resulting table even if it does not match any row from the object specified in arg1.
LEFTJOINMANY
LEFTJOINMANY (object, arg1, arg2)
Returns the resulting joined tables of object and arg1. A row from object and a row from arg1 are joined together if the condition (arg2) is True. Each row from object can match with multiple rows in arg1. However, each row in the object continues to be retained in the resulting table even if it does not match any row from the object specified in arg1.
LENGTH
Returns the number of characters in object. It is similar to Java's length string function.
LONGVALUE
Converts object into a long value. Returns Null, if there is an error.
MAP
MACADDRESS
Returns the specified MACAddress format defined in SNMPv2-TC.
MATCHES
Returns True if the regular expression pattern arg1 is found in object.
MATCHESGROUP
MATCHESGROUP(String GroupName, String ProcessingName)
Tests whether the data in this context matches the given group and processing.
NOT
Returns the opposite of object.
OPENSTACKPOLL
OPENSTACKPOLL (arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7)
Polls meters using the OpenStack Ceilometer service.
- arg0 - package ID
- arg1 - action name
- arg2 - input parameters
- arg3 - values needs to be polled
- arg4 - keys for values
- arg5 - service type
- arg6 - static or dynamic config
- arg7 - cache key
OSCREDSEXIST
Checks whether OpenStack credentials are configured.
PARSESTRING
PARSESTRING (arg1, arg2, arg3)
Parses the arg1 into tokens and returns the token identified by arg2
- arg1 is a string constant or variable.
- arg2 is a delimiter character used to separate the arg1 into tokens.
- arg3 is an integer number indicating which token to return.
POLL
Polls only the group of scalar values or table variables that share the same index.
- Used only in the PollDefinition section.
- arg1 is a list of variables (comma delimited list of variables in double quotes) to poll
- arg2 is the label used to allow you to reference it in other polls to prevent re-polling..
Note You must poll all variables referenced in current and other reports with the same label in the same poll macro. This is to prevent missing variables. Once a poll result is associated with the label the device will not be re-polled when the poll macro is called with the same label.
POLLMT
POLLMT (String keys, String, String)
Polls the MediaTrace mib table.
POLLNEXT
POLLNEXT (arg1, arg2, arg3, arg4)
Retrieves the data that you have not already retrieved (retrieves the next available data).
Used only in the PollDefinition section.
- arg1 is the index that uniquely identifies each row (comma delimited list of variables in double quotes)
- arg2 is the list of variables to poll (comma delimited list of variables in double quotes)
- arg3 is list of index variables to poll
- arg4 is a Boolean value that is true if you want to return the last row even if it is the same as the last row of the last poll.
POLLPERSIST
Polls the variables in the list and persists the values (in row map) to make the values available in other algorithms.
Polls the values and puts it into the current context (available for immediate use in other capability checks). Used only in the SystemCapability.xml file
Prints the string version of the object in the console log.
- If no arguments are given, prints a blank line in the console log (for debugging).
- If one argument is used, prints the object in the console log (for debugging).
PROCESSORLIST
Creates Lists of objects to be referenced by internal processing code.
- arg1 is a list of objects specified in Java Array syntax that is [ "object1", "object2", "object3" ]
- Typically used in persisted group definition files for the Usage and Objects directives.
PROTOCOLNAME
Used only in the ProcessPollResult section to return the name of protocol provided in the protocol number as arg1. For example, returns UDP for 17. The macro is used in the netflow-config.xml file in the etc directory on gateways and units for protocol name lookup. The macro is generally used for NetFlow reports to display the name of protocol in reports instead of numbers.
RATE
If one argument is used, returns the rate of change between the previous and the current polling for the object (uses sysUpTime as time delay to perform calculation).
If three arguments are used (there is no two argument option), returns the rate of change between the previous and the current polling for the object. In this case, arg1 is the value used for time and arg2 is a multiplier/conversion factor in order to get the correct metric. that is, seconds or milliseconds.
For example, the variable sysUpTime needs a multiplier of 100 to get into seconds since it is recorded in 1/100 seconds.
REMOVE
Removes an element from a map or collection.
- Object – is the collection from which an element needs to be removed.
- arg – is the element which needs to be removed from the collection.
RUNCMD
RUNCMD (arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7)
Supports script collector. Output format should be csv for now with self-defined delimiter.
- arg0 - script absolute path
- arg1 - cache key
- arg2 - delimeter for csv output
- arg3 - timeout of script processing
- arg4 - true if script will provide current timestamp
- arg5 - metrics name for csv columns
- col name like sysUpTime,MWTMCURTIME is for time setting
- arg6~N - parameters for script(optional)
An example of the RunCmd macro used to write reports is shown below. An addition sample is provided in runCmdSampleScript located in at /opt/CSCOppm-gw/samples/runcmd/.
- "/path/to/the/script.sh" is the path to the script to run
- "thisCache" is the name to casche the results under in case another report wants the same data
- '|' is the delimiter for the CSV data returned by the script
- 5 is the timeout value or length of time to wait for the script to complete after which we will kill the process and continue with null results
- False indicates true or false whether PPM provides time stamps for the data or the script includes it in the csv output
- "cpu_idle, cpu_user, cpu_nice, cpu_system" is the name of the variables returned in the script csv file
- DeviceName() is the first parameter to be passed to the script
- "secondParm" is the second parameter to be passed to the script
- "NthParm" is the Nth parameter to be passed to the script
The script returns data in the following format:
This indicates four data rows are to be parsed and processed by the rest of the Prime Performance Manager framework. The macro would be written as:
If the data includes the current timestamp, it would appear as:
The macro would be written as:
The fourth macro parameter indicates whether the script output should provide timestamp. If set to true, the following rules apply:
- CSV timestamps should be measured in milliseconds between the current time and midnight, January 1, 1970 UTC.
- If a customer wants to define the timestamp, the CSV output should provide the current timestamp. The macro should be labeled as "MWTMCURRTIME" in the sixth parameter, which is reserved name for the current timestamp.
- If CSV output provides the system up time, you can label it as "sysUpTime" in the sixth parameter. This is an optional label. It is not necessary if the output only provides the current timestamp. The sysUpTime unit should be hundredths of a second.
SETALGORITHMS
Defines an algorithm to be run.
- arg1 is the algorithm name.
- arg2 is either a list containing macro statements or a map of key=value pairs, where the key is the name of an object assigned the statement defined by value.
SETCPUINFO
Sets the CPU information (cpuDescr, cpuNum, cpuSlot). To override the CPU index, set object to that value.
SETMEMORYPOOLINFO
Creates a combined memory pool name after poll the CISCO-ENHANCED-MEMORYPOOL-MIB and ENTITY-MIB. The new memory pool name will be "slotNumber-slotName-memoryPoolName". After the data is polled, the data will be persisted for re-use if entity isn't changed and will also be put into cache for other macro use.
SETTIMEVARINFO
SETTIMEVARINFO (object, arg1, arg2)
Sets the time variable information with the given arguments in the context.
- object is the time variable to use
- arg1 is a boolean whether to use the variable next time
- arg2 is the index in which you use until it changes value.
SMIEXIST
Checks if the SMI-S namespace or classname exist for the given device.
SMIPOLL
SMIPoll(arg1, arg2, arg3, arg4, arg5)
Used only in the PollDefinition section to retrieve CLI based report data.
- arg1 is a namespace for SMI-S polling.
- arg2 is a classname for SMI-S polling.
- arg3 is a input parameters for SMI-S polling.
- arg4 keys for table indices values.
- arg5 cache key.
STARTSWITH
Returns true if the string object starts with the string arg1
SYSTIME
Returns the current system time (in milliseconds).
TABLEINDICES
Sets object as the value to use to identify a row in a table (comma delimited list of variables in double quotes).
TOCIDSHEALTHSECMONMISSEDPKT
TOCIDSHEALTHSECMONMISSEDPKT ()
This class converts the display string to the measures
TOLOWERSTRING
Returns object in string form all in lower case
TOPN
Returns the top n (arg2) rows from object sorted by a sort key descending
- Used in the PollDefinition or ProcessDBSummary section.
- object is a table
- arg1 is what column to sort by
- arg2 is the number of records to get (n)..
- When used in the Filter section in a ProcessDBSummary section, rows is an implicit variable that typically can be used for an object that is set when ProcessDBSummary execution is complete.
TOSTRING
Returns object in string form.
TOUPPERSTRING
Returns object in string form all in upper case.
VIEWDESCENDANT
Tests if a node is a descendant of the given view name. It returns true if it is a descendant; otherwise, returns false
- arg1 is the view name in the form of: persistedViewlFileName. persistedViewlFileName.viewname.subviewname
- The persistedViewFileName will vary based on whether user access is enabled or not. When not enabled the first 2 level of the view name are the device where the view was originally created. When enabled it is the id of the user.
- Typically used in group and threshold definitions to limit the scope of devices.
XMLPOLL
XMLPOLL (arg1, arg2, arg3, arg4, arg5, arg6)
Used only in the PollDefinition section to retrieve CLI based report data.
- arg1 package ID for PAL call.
- arg2 action name for PAL call.
- arg3 input parameters for PAL call.
- arg4 values to be polled for PAL call.
- arg5 keys for table indices values.
- arg6 a static or dynamic config; indicates whether results should be cached.
- arg7 cache key
XMLPOLLNEXT
XMLPOLLNEXT (arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8)
Used only in the PollDefinition section to retrieve CLI report data based on sub key.
- arg1 package ID for PAL call.
- arg2 action name for PAL call.
- arg3 input parameters for PAL call.
- arg4 values needs to be polled for PAL call.
- arg5 main keys for table indices values.
- arg6 subkeys for values for table indices.
- arg7 key for start time adjustment.
- arg8 cache key.
XMLPOLLPERSIST
Designed for system capability detection by the CLI poll. It is used only in SystemCapability.xml to detect the CLI poll capability(remove).
XMLPOLLTKPERSIST
This macro is used for checking the xml capability. It extends XmlPollPersist and adds logic to get the token before polling the device.
XMLPOLLWITHTOKEN
XMLPOLLWITHTOKEN (arg1,arg2, arg3, arg4, arg5, arg6, arg7)
Supports the XML collector and is an extension of XmlPoll. It provides a token check before polling device.
- arg1 package ID for PAL call.
- arg2 action name for PAL call.
- arg3 input parameters for PAL call.
- arg4 values to be polled for PAL call.
- arg5 keys for table indices values.
- arg6 a static or dynamic config; indicates whether results should be cached.
- arg7 cache key
Y1731XMLPOLLNEXT
Y1731XMLPOLLNEXT (arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
Y1731XmlPollNext is used to poll the Y1731 data from IOX device.
- arg0 - package ID
- arg1 - action name
- arg2 - input parameters which contains profile ID and measurement name
- arg3 - values needs to be polled
- arg4 - main keys for values
- arg5 - sub keys for values
- arg6 - the name of the start time ticket
- arg7 - cache key
- arg8 - the persist flag
- arg9 - the time when run the macro
Feedback