Technical Blog Post
ITM Agent Insights: Timestamp attribute type with custom agents
IBM Tivoli Monitoring Agent Builder allows for the creation of custom monitoring agents.
In order to be able to do a time comparison as part of a situation using the DATE function, the custom agent needs to define an attribute as a Timestamp field. There is no function to interpret a string as a date / time and then do a comparison.
DATE: Compare Date and Time
Use the DATE formula function in a situation, query, query-based view filter, or table view threshold formula to compare the time stamp from the data sample with the value specified.
This is the default function for time attributes. It compares the Timestamp value from the data sampling with the value entered here.
After you select the DATE function and click inside the value cell, the Select the Time Comparison dialog opens for selecting the exact date and time to compare. The format is the date as seen in the date columns (mm/dd/yy hh:mm:ss) or as defined for your locale.
A Time stamp attribute is a string attribute with a format that conforms to the CYYMMDDHHMMSSmmm format (where C=1 for the 21st century). All 16 characters must be used for scripts or socket clients. When displayed in the Tivoli® Enterprise Portal, a time stamp attribute type is displayed in the correct format for the locale.
A sixteen character string that conforms to the CYYMMDDHHMMSSmmm format is a "Tivoli" timestamp.
The Agent Builder will allow an attribute to be defined as a "Time stamp" in the Data Source Definition, but does not enforce any size restriction on the field, and does not do any error checking to confirm that the string value conforms to a timestamp specification.
If the data source returns a value that is not a 16 character string that meets ITM criteria of a timestamp, the value displayed in the TEP for "real time" and "short term historical" data will be translated and result in an unexpected value.
Historical data read from the contents of the Tivoli Data Warehouse (TDW), will display the actual string value for the attribute without translation, and will match the actual value returned by the data source.
In the above, the last row of data is showing an unexpected result in the "Value" column, which is the custom attribute that is of type "Time stamp".
The last row of data is a historical sample that has NOT yet been exported to the TDW database based on a 15 minute warehousing interval.
All the other rows are older historical samples, that have already been exported to the TDW database from the short term historical (STH) file.
The "Timestamp" column in the above is the timestamp of the data collection, not to be confused with a user defined "Time stamp" attribute.
In order to verify the data as it exists in the STH file, it is necessary to run the "krarloff" utility against the <attribute_group> file that contains the binary data for the historical samples.
Running "krarloff" against example output to see the raw historical sample that is in the STH file:
/opt/IBM/ITM63FP6/tmaitm6/lx8266/bin/krarloff -d *** -o /krarloff.out -m /opt/IBM/ITM63FP6/lx8266/77/hist/K77APPLIT3.hdr -s /opt/IBM/ITM63FP6/lx8266/77/hist/K77APPLIT3
Current codepage is 1208
Source file is : /opt/IBM/ITM63FP6/lx8266/77/hist/K77APPLIT3
Definition file is : /opt/IBM/ITM63FP6/lx8266/77/hist/K77APPLIT3.hdr
Source file will be renamed to : /opt/IBM/ITM63FP6/lx8266/77/hist/K77APPLIT3.old
Destination file is : /krarloff.out
Delimiter set as : ***
ATTRLIB was not defined.
Using working directory as default
Using ./ATTRLIB/ as ATTRLIB
There were 1 entries for various attribute files
# cat /krarloff.out | more
21600***1161118160700000***nc9053114067:77***1161118160719000*** Last Full Backup Time:*** 2016-10-10 18:0***10***60
21600***1161118160700000***nc9053114067:77***1161118160719000*** Last Backup Time:*** 2016-10-12 21:0***11***60
The "raw" data in the STH file is not what is shown in the TEP for the last row, which confirms it is a display issue when the value is interpreted as a "Time stamp" based on current locale.
Once the data is exported to the TDW, it is able to be displayed and matches what is seen when reading it directly from the binary STH file.
The real-time and STH data is displayed incorrectly because the values are assumed to be a 16 character field conforming to the Tivoli timestamp definition, and the value is translated from an assumed CYYMMDDHHMMSSmmm timestamp into human readable time stamp based on the OS locale.
When the data is coming from the TDW warehouse, it is simply returning the "string" that is stored for the attribute field, no translation is performed.
It is up to the end user to ensure that the data source, in this case a user-defined script, returns data in the expected 16 character format if the attribute definition is a "Time stamp".
Additional ITM Agent Insights series of IBM Tivoli Monitoring Agent blogs are indexed under ITM Agent Insights: Introduction.
Subscribe and follow us for all the latest information directly on your social feeds:
Check out all our other posts and updates: