Specify the Device Pack Elements Information

How to Generate Device Packs › Add the Required Information to the Device Pack Configuration File › Specify the Device Pack Elements Information

Specify the Device Pack Elements Information

After you have specified the values for the input file information in the device pack configuration XML file, specify the values for the device pack element information in the appropriate section of the XML file.

Each device pack contains three element types, which are DevicePackHeader, DevicePackData, and DevicePackKPI:

DevicePackHeader

The device pack uses the information that you specify here to provide the name of the new devices and device components, which are shown in the Inventory tab in CA Performance Center. Part of this information also contributes to the name of the new metric families.

There are six types of DevicePackHeader elements. You are required to provide five of those six types, which are described as follows:

Note: The following sample CSV data from Huawei2000WDM explains each type:

Sample file name: PM_IG500011_15_201109092200Z_01.csv

Sample file content:

[1] DeviceID, DeviceName, ResourceName, CollectionTime, GranularityPeriod

[2] 3145804, ARE_Electrical, Shelf0-52TOM-3(RX1/TX1)-OCH:1, 2013-05-09 10:15, 15

[3] 3145804, ARE_Electrical, Shelf0-52TOM-4(RX2/TX2)-OCH:1, 2013-05-09 10:15, 15

Line [1] is the CSV header. A CSV header line contains the column names separated by a delimiter. These column names are never repeated throughout the file.
Lines [2] and [3] are CSV data. A CSV data line contains some information separated by a delimiter. One-to-one mapping exists between each column name and the information in data. Each data line has only one column name value.
The Resource Name column has a value of Shelf0-52TOM-3(RX1/TX1)-OCH:1 in the first data line. The Resource Name column has a value of Shelf0-52TOM-4(RX2/TX2)-OCH:1 in the second data line.
Notes:
- Anything above the header in the file is a comment. Anything after the header in the file is data.
- A CSV file does not contain line numbers. The line numbers are provided in the previous example to describe the example.
- The application does not support more than one header in a CSV file. For a CSV file that has multiple headers, we recommend that you split the single CSV file to several small CSV files. Create as many CSV files as necessary so that each CSV file contains one header and its data.

Device

Specifies the name or an identifier of the device or Element Management System (EMS) from which the input data file was generated or was received, and monitors using this device pack.

Note: For the CSV format that the application supports, there is only one value for Device per CSV file.

The value is displayed in CA Performance Center as a new device in the Inventory tab.

Example:

ARE_Electrical (value of column “DeviceName”) or 3145804_ ARE_Electrical (value of column “DeviceID” appended with column “DeviceName”)

Note: The default character to append multiple values is an underscore (_).

Branch

Specifies an identifier in the input data file name or file content (or an identifier provided from an external source) that uniquely identifies other data files from the same device.

Note: For the CSV format that the application supports, there is usually only one value for Branch per CSV file.

In CA Performance Center, the new metric family is named using the device pack name and the value of Branch.

Example:

IG500011 (value of a group capturing the regular expression applied on a file name)

Regular expression: ^PM_(IG.*)_\d\d_.*$

BranchDesc

Specifies an identifier in the input data file that with the Device element and the Branch element uniquely identify each line of a file. BranchDesc is a short form of branch description. This value is comprised of either one column or a combination of two or more columns. In case you have Device and Branch identifying each line of a file, we recommend that you provide a meaningful string that can be prefixed or suffixed with Branch to form a BranchDesc.

Note: For the CSV format that the application supports, there is more than one value of BranchDesc per line in the CSV file. In most cases, BranchDesc is the value of one column or a combination of columns.

Example:

Shelf0-52TOM-3(RX1/TX1)-OCH:1 (value of column “ResourceName”)

DeviceIP

Specifies the IP address of the device or EMS.

Note: The IP address cannot be 127.0.0.1.

Default: 255.255.255.255

Delta

Specifies the time interval in seconds at which CSV files are generated by the device or EMS.

Default: 900 seconds

Note: This element value is provided as part of <Path> and is therefore skipped here.

UTC

Specifies the time and the format of time at which each individual data line in the file was generated.

Default: The current time in UTC format.

The application internally converts the time value to UTC.

Example:

2013-05-09 10:15 (value of column “GranularityPeriod” with format as “yyyy-MM-dd HH:mm”)

Note: If you use the application to obtain data from static files or do not know the time format, do not enter a value. The default time is used when the data is processed. If you use the application to obtain data from static files, set the IGNORE_DOWNLOAD_HISTORY parameter value in EMS Integration Profile as True.

DevicePackData

The device pack uses the information that you specify to provide the metrics in the new metric families. These data elements display in the dashboards as metrics. A metric name is comprised of those column names that you want this application to treat as data columns.

The application provides special support for Counter metrics. You provide the list of all Counter metrics (column names).

Default: The metric type is Gauge.

DevicePackKPI (Key Performance Indicator elements)

The device pack uses the information that you specify to create new metrics and new metric families other than what is available in the CSV file. Key Performance Indicator (KPI) is an important measurement in performance monitoring. The application provides support for KPI identification and calculation.

You evaluate the key performance indicators based on a certain value or a combination of multiple values.

Specifying DevicePackKPI is optional.

To specify the device pack element information in the device pack configuration XML file, navigate to each of the following sections. For each section, specify the required values for the device pack that you want to generate.

Follow these steps:

Specify the following values for the DevicePackHeader Device element:
Important! Make sure you provide the correct information so that the application can correctly generate the device pack.
Device
```
<Device fixedValue="">
```
Specifies the name to display as the new device in the Inventory tab in CA Performance Center.

To use a fixed name instead of reading the value from the file name or file content for this device pack, specify this attribute.

If you use this attribute, then you do not need to complete any more information for <Device>. All files are associated with this device name.

If you do not use this attribute, then there are three ways to provide the information for <Device>:
- Using the file name
- Using the Comment in the file
- Using the Header in the file
FileName
```
<FileName prefix="" suffix="">
```
```
<Value fileNamePattern="" isValueRegEx="true"></Value>
```
```
<Value fileNamePattern="" isValueRegEx="true"></Value>
```
```
</FileName>
```
Use <FileName> if the device name is included in the file name.

To capture the value from the string, provide regular expression groups. If no groups are provided, then the value is empty.

If the device name varies across the files, then provide the regular expression specific to a particular file name pattern, using the fileNamePattern attribute.

Make sure that the fileNamePattern attribute is a plain regular expression (without any groups). This expression matches file names and if a match is successful, then the value of <Value> (which is a regular expression with Group) is applied to FileName to get the device name.

If the device name is a fixed value, then you do not need to provide the regular expression. Provide this fixed value instead, and then change the attribute isValueRegEx to “false.”

Matches occur in the sequence you provide and the first match is used as the device.

Optionally provide a prefix or a suffix that you can add or append to the device name.

Example:
```
<FileName prefix="CA" suffix="Texas">
```
```
	<Value fileNamePattern="^.* PEB-U-NTHS_ifstat .*$"
```
```
isValueRegEx="true">^.*-(.*)_.*$</Value>
```
```
</FileName>
```
Filename = Bulk_PEB-U-NTHS_ifstat_24-12141617-58_up_1272018000.sts

Filename matches with fileNamePattern

The attribute isValueRegEx is true so you apply the value “^.*-(.*)_.*$” to Filename to get “PEB-U-NTHS”

Apply the prefix and the suffix to get “CA_PEB-U-NTHS_Texas”

The device name is CA_PEB-U-NTHS_Texas

Example:
```
<FileName prefix="CA" suffix="Texas">
```
```
	<Value fileNamePattern=".*_ifstat_.*"
```
```
isValueRegEx="true">^.*_(.*)_.*$</Value>
```
```
	<Value fileNamePattern=".*system.*" 
```
```
isValueRegEx="false">Localhost</Value>
```
```
</FileName>
```
For all files where the name matches the pattern provided in fileNamePattern, apply this regular expression to get the device.

Filename = Bulk_PEB-U-NTHS_ifstat_24-12141617-58_up_1272018000.sts

The device name is CA_PEB-U-NTHS_Texas

Filename = Bulk_NPE-M-WiFi_ifstat_24-12141617-58_up_1272018000.sts

The device name is CA_ NPE-M - WiFi _Texas

Filename = Bulk_system_24-12141617-58_up_1272018000.sts

The device name is CA_ Localhost_Texas

Filename = Bulk_data_24-12141617-58.csv

The device name is null (empty).
Comment
```
<Comment prefix="" suffix="">
```
```
	<LineNumber></LineNumber>
```
```
	<RegEx></RegEx>
```
```
</Comment>
```
Use this attribute if the device name is in the comment section of the files.

The comment section must be the first entry in the CSV file, followed by the header and the data.

<LineNumber> specifies to select a device name from the string at this line number.

<RegEx> specifies to use the group capturing regular expression (RegEx) on the given line.

If no regular expression is provided, then the entire line is considered the device.

If no line number is provided, then the regular expression matched first is considered the device.

Optionally provide a prefix or a suffix that you can add or append to the device name.
Headers
```
<Headers>
```
```
<Header prefix="" suffix="">
```
```
		<ColumnName></ColumnName>
```
```
		<RegEx></RegEx>
```
```
	</Header>
```
```
</Headers>
```
Use this attribute if the device name is in the header section of the files.

Select the device name from the column whose name matches the value of <ColumnName>. In CSV files, a header consists of column names. A delimiter separates each column name. A delimiter also separates all data lines in CSV and maps to only one Column name.

<RegEx> specifies a group capturing regular expression to use on the value of a given column name.

If no regular expression is provided, then the complete value of the column is considered the device.

If no <ColumnName> is provided, then <RegEx> is applied to the complete data line to get the value.

Optionally provide a prefix or a suffix that you can add or append to the device name.

If the value is in multiple columns, then provide the same number of <Header> attributes. Values are appended in the order they appear from each such occurrence of <Header> to form the final value.

Note: If there are multiple headers, the values are concatenated with "_".
Sequence
```
<Sequence prefix="" suffix="">
```
```
	<SeqElement></SeqElement>
```
```
	<SeqElement></SeqElement>
```
```
</Sequence>
```
<Sequence> is optional.

Use <Sequence> when you want to combine multiple values to one value.

Example:
```
<Sequence prefix="" suffix="">
```
```
	<SeqElement>FileName</SeqElement>
```
```
	<SeqElement>Comment</SeqElement>
```
```
</Sequence>
```
Combine the value selected from <FileName> and <Comment> to get the final value.

Accepted values: FileName, Comment, or Header

Optionally provide a prefix or a suffix that you can add or append to the device name.

Note: If there are multiple sequences, the values are concatenated with "_".
Specify the values for the DevicePackHeader Branch element.
The Branch value is combined with the device pack name value to form new metric families.

Note: The options for the Branch DevicePackHeader element are the same as the Device DevicePackHeader element.
Specify the values for the DevicePackHeader BranchDesc element.
The BranchDesc value is combined with the Branch value to form new device components. These device components display in the Inventory tab in CA Performance Center.

Note: The options for the BranchDesc DevicePackHeader element are the same as the Device DevicePackHeader element
Specify the values for the DevicePackHeader DeviceIP element.
Note: The options for the DeviceIP DevicePackHeader element are the same as the Device DevicePackHeader element
Specify the value for the DevicePackHeader UTC element.
Note: The options for the UTC DevicePackHeader element are the same as the Device, Branch, and BranchDesc DevicePackHeader elements except for an additional attribute that describes what timeFormat pattern is used by this file.

The following information shows how the new attribute is part of the <UTC> tag:
```
<UTC fixedValue="" timeFormat="">
```
Note: If you use the application to obtain data from static files, do not provide values for File Name, Comment, and Headers.

The following table describes the accepted timeFormat patterns that you can use:

Letter	Date or Time Component	Presentation	Example
G	Era designator	Text	AD
y	Year	Year	1996; 96
M	Month in the year	Month	July; Jul; 07
w	Week in the year	Number	27
W	Week in the month	Number	2
D	Day in the year	Number	189
d	Day in the month	Number	10
F	Day of week in the month	Number	2
E	Day in the week	Text	Tuesday; Tue
a	AM or PM marker	Text	PM
H	Hour in the day (0-23)	Number	0
k	Hour in the day (1-24)	Number	24
K	Hour in AM or PM (0-11)	Number	0
h	Hour in AM or PM (1-12)	Number	12
m	Minute in the hour	Number	30
s	Second in the minute	Number	55
S	Millisecond	Number	978
z	Time zone	General time zone	Pacific Standard Time; PST; GMT-08:00
Z	Time zone	RFC 822 time zone	-0800

Specify the following values for the DevicePackData element. These values display in the CA Performance Center dashboards as metrics.
```
<DevicePackData  endOfData=””>
```
```
	<Range fileNamePattern="">
```
```
		<Column>
```
```
			<Start></Start>
```
```
			<End></End>
```
```
		</Column>
```
```
		<Column>
```
```
			<Start></Start>
```
```
			<End></End>
```
```
		</Column>
```
```
	</Range>
```
```
</DevicePackData>
```
DevicePackData

Specifies where in the CSV file to retrieve actual data.

endOfData
Specifies how the application identifies that end of data is reached in the file. Provide a regular expression to match with each line. The first line that matches with this regular expression is considered end of data for this file. Once the application detects end of data, it moves to the next file. endOfData is optional; if endOfData is left empty then the application reads until the last line.

Example:
```
endOfData=”##EOF##”
```
The previous example shows that the application reads all lines of the file until it gets to a line that matches with “##EOF##”. Once the match is found, the file processing stops and the next file is processed.

You can provide multiple <Range> attributes.

Each <Range> attribute that you use expresses:
```
fileNamePattern 
```
Use fileNamePattern if the given <Range> is applicable for specific files. If fileNamePattern is left empty, then the given <Range> is applied to all files.

Specifies the column number (not the name) with which to start, and the column number (not the name) with which to end. Use this attribute if you do not want to consider all columns as data.

Default: All columns are considered data.

Example:
```
<Range fileNamePattern="PM_IG.*" >
```
```
	<Column>
```
```
		<Start>4</Start>
```
```
		<End>7</End>
```
```
	</Column>
```
```
	<Column>
```
```
		<Start>8</Start>
```
```
		<End>11</End>
```
```
	</Column>
```
```
</Range>
```
The previous example shows the following information:
- Range is applicable to only those files whose name starts with “PM_IG”.
- The application considers only the following columns as having data (metrics that show in reports):
Column number 4, column number 5, column number 6, and column number 7; column number 8, column number 9, column number 10, and column number 11.
(Optional) Specify the following values for the DevicePackKPI element:
```
<DevicePackKPI>
```
```
<Range fileNamePattern=""    addAsNewBranch="false">
```
```
	<MetricsAsCounter></MetricsAsCounter>
```
```
	<Expression name=""></Expression>
```
```
	<Expression name=""></Expression>
```
```
</Range>
```
```
<Range fileNamePattern=""   addAsNewBranch ="true">
```
```
	<Expression name=""></Expression>
```
```
	<Expression name=""></Expression>
```
```
</Range>
```
To specify if the <Range> containing KPI information is specific for certain files or not, use the fileNamePattern attribute. If this attribute is empty, then it is used on all files. We recommend that you provide a value for the fileNamePattern attribute so that the application can correctly evaluate KPI information for each CSV file.

To specify whether to add the KPI information as a separate branch or include it in existing branches, use the addAsNewBranch attribute. The addAsNewBranch attribute uses the following values:

true

Specifies to add as a new branch and be considered as a separate or new metric family for this device pack.

The new metric family is named: <DevicePackName>KPI<BranchName>.

false

Specifies to include in existing branches and be a part of the existing metric family of this device pack.

The new metric is added, but does not result in a new metric family.

Any string other than true or false

Specifies to add as a new branch and use this string as the name of this new branch.

A new metric family is named: <DevicePackName> <String>.

MetricsAsCounter

Specifies those metrics (column names) to treat as a counter while KPI calculation is performed.

A counter represents a set of variables whose values are an unsigned integer that grows over time. This number never gets smaller, it is always incrementing.

You can specify more than one metric as a comma-separated list.

Example:

<MetricsAsCounter>Column Name1, Column Name2</MetricsAsCounter>

Each <Expression> specifies the column names to evaluate KPI and how the evaluation is performed. Once the evaluation is done and a value is obtained, the value is added as a new metric using the value of name as the name of the metric.

The value of <Expression> must be a valid mathematical expression. Four operators are currently supported: +, -, *, / for addition, subtraction, multiplication, and division respectively. You can use parenthesis ( and ) in <Expression>.

Each such <Expression> must contain at least one column name. The column name used in <Expression> must exactly match the column name in the CSV file.

You can construct <Expression> in multiple ways as shown in the following sample CSV file.

Sample CSV file content:

Citrix,Type_of_service,Location,Bytes Sent,Bytes Received, Response time,SystemUpTime

citrix_1,USAC,Spain,31464,49232,1461,1000

citrix_2,USAC,Colombia, 32732,44824,1004,1900

citrix_3,USAC,London, 10732,24824,300,3000
```
<MetricsAsCounter>SystemUpTime<MetricsAsCounter>
```
```
<Expression name=”UpTimeInMinutes”>SystemUpTime/60<Expression>
```
In this example, for each data line a new metric named UpTimeInMinutes is created with a value of 0 for the first data line. (1900-1000)/60 = 15.00 for the second data line and (3000-1900)/60 = 18.33 for the third data line.
```
<Expression name="ByteOutPercentage">(Bytes Sent / 100)</Expression>
```
In this example, for each data line a new metric named ByteOutPercentage is created with a value as 31464/100 = 314.64 for the first data line shown and similarly for the other two data lines.

Note: Lines that occur after the CSV Header and before endOfData are considered as data lines.
```
<Expression name="ByteOutPercentage">(Bytes Sent,>,20000) / 100</Expression>
```
For each data line that has a value greater than 20000 in the Bytes Sent column, a new metric named ByteOutPercentage is created. In the example, the third data line does not satisfy this condition.

The following information describes supported conditional operators:

<

Less than

(A,<, B) is true only if A is less than B.

>

Greater than

(A,>,B) is true only if A is greater than B.

=

Equal

(A,=,B) is true only if A is equal to B.

>=

Greater than or equal

(A,>=,B) is true only if A is greater than or equal to B.

<=

Less than or equal

(A,<=,B) is true only if A is less than or equal to B.

!=

Not equal

(A,!=,B) is true only if A is not equal to B.
- The syntax for using conditional operators is as follows: (ColumnName, operator, Number)
- Surround the syntax with parentheses.
- The number can be an integer or a decimal (real numbers).
Verify that ColumnName is identical to how it appears in the CSV file, otherwise the application reports an error that it cannot find the column.

Note: The data line that does not satisfy this condition is ignored for the KPI calculation only if addAsNewBranch is true. If addAsNewBranch is false, then a default value of 0 is used as the value of this expression. Using this default value helps make sure that each existing metric family has the same number of metrics.
```
<Expression name="TotalByteTransaction">Bytes Sent + Bytes Received</Expression>
```
For each data line, a new metric named TotalByteTransaction is created with a value as 31464 + 49232 = 80696 for first data line and similarly for the other data lines.
```
<Expression name="AverageResponseTime">sum(Response Time) / CSV_TOTAL_DATA_LINE </Expression>
```
For each file, a new branch is created. This branch has a new metric named AverageResponseTime. The value for AverageResponseTime is (1461+1004+300)/3 = 921.6.

CSV_TOTAL_DATA_LINE is a keyword for the application that describes the total number of data lines for a given file.

Note: For the KPI that you have to evaluate on a file basis, a new branch is created. Therefore, you specify using addAsNewBranch=”true” or addAsNewBranch=”some_name”. The default behavior is to add the file as a new branch.

The application supports the following accumulative operators, which you can use to specify KPI on a file basis:

sum(columnName)

Adds the values of columnName and returns the total value for all of the data lines.

sum(columnName,<,100)

Adds the values of columnName and returns the total value for all of the data lines that have a value of columnName greater than 100.

count(columnName,!=,100)

Returns the total number of lines in this CSV file for which the value of columnName is not equal to 100.

Note: Any invalid expression is reported as an error by the application while it processes a CSV file. Based on the value of <OnFailure>, it skips the current file or exits the process.

The values for the DevicePackKPI element are specified.

The device pack element information is specified in the configuration XML file.