The Data Engine

Download this manual as a PDF file

This section describes how to use the data engine in PHP code for custom reports in SL1.

Use the following menu options to navigate the SL1 user interface:

  • To view a pop-out list of menu options, click the menu icon ().
  • To view a page containing all the menu options, click the Advanced menu icon ().

This section includes the following topics:

What is the Data Engine?

The data engine is a class that can be used in PHP code for reports and widgets. The data engine provides access to collected performance data from Dynamic Applications, monitoring policies, and internal collections.

To use the data engine class in your report or widget code:

  1. Instantiate a data engine object.
  2. Define the time period for which you want data.
  3. Optionally, configure the data engine object to return normalized data.
  4. For Dynamic Application data, define the indexes for which you want data.
  5. For counter data, configure how the data engine should handle counter rollovers.
  6. Optionally, use other methods that are defined for the data engine class.
  7. Retrieve data.
  8. Use the unset() method on the data engine object. If you are instantiating multiple data engine objects, this is recommended to prevent excessive memory usage.

Instantiating a Data Engine Object

Use the following syntax to instantiate a data engine object:

<object name> = em7_data_engine::obj(<type>, <entity_id>, <args>);

The constructor takes the following parameters:

  • type. The type of data you want to retrieve. The types are:
  • dynapp. Performance Dynamic Application data.

  • vitalmap. Data associated with a collection label. Collection labels are an abstraction layer for Dynamic Application presentation objects. If two presentation objects are associated with the same collection label, e.g. "CPU", "Memory", or "Swap", those objects collect the same type of data. This option is equivalent to instantiating a data engine object for the Dynamic Application presentation object that is associated with the collection label for the specified device. For more information on collection labels, see the section on Collection Labels.
  • avail. Availability data.
  • cv. Data from a Web Content monitoring policy.
  • ports. Data from a port monitoring policy.
  • procs. Data from a System Process monitoring policy.
  • tv. Data from a SOAP/XML Transaction monitoring policy.
  • dns. Data from a Domain Name monitoring policy.
  • email. Data from an Email Round-Trip monitoring policy.
  • services. Data from a Windows Service monitoring policy.
  • storage. Data about File system utilization.
  • if. The following types of interface data: utilization in octets, error rate, discard rate.
  • ifutil. Data about Interface utilization, in percent.
  • vif. Data from a bandwidth billing policy.
  • itsm_har. Health, Availability, and Risk data for an IT service policy.
  • itsm. Performance metric data for an IT service policy.
  • entity_id. The ID of the primary entity with which the data is associated. For the itsm_har and itsm data types, this is the ID of the IT service policy. For all other data types, this is the device ID for the device record associated with the data.
  • args. An array of arguments. The arguments array is different for each type of data. The following sections describe the structure of this array for each type.

Dynamic Application Data

For Dynamic Application data, the args parameter for the constructor is an array that includes the following keys:

  • aid. The ID of the Dynamic Application for which you want data.
  • presentation_id. The ID of the presentation object for which you want data.
  • index. An optional array of indexes for which you want data. If you do not supply this parameter and do not use the set_indexes() method for supplying a list of indexes, the data engine will return data for index 0 only.

Data Associated with Collection Labels

Collection labels are an abstraction layer for Dynamic Application presentation objects. If two presentation objects are associated with the same collection label, e.g. "CPU", "Memory", or "Swap", those objects collect the same type of data. This option is equivalent to instantiating a data engine object for the Dynamic Application presentation object that is associated with the collection label for the specified device. The args parameter for the constructor is an array that includes the following key:

  • map_type. The GUID of the collection label. Collection label GUIDs are stored in the master.system_data_labels database table. For a collection label that is installed via a PowerPack, the GUID for that collection label is the same on both the source and the target system. The following table lists the GUIDs for the default set of collection labels provided by ScienceLogic:

Label Group GUID
CPU Vitals AFF64E74C73D96244F7DB426158A359F
Memory

Vitals

C36F10744B4BCA7C91CD1C405BC568C0
Swap

Vitals

BAC2484664F897DDBC2FECB0BD798E04
In Use Video Performance D6189453171DBC7296233976D5F51AF4
Max % Packet Loss

Video Performance

1C7F5513FB8ADEED16810A27293D3E34
Max Jitter

Video Performance

E96337379DFBEFAF393684C1800EEE4C
Rx Audio Jitter

Video Performance

777985E7BB0846423653FAE19A230F8C
Rx Audio Pkts Lost

Video Performance

7E86018AD212A94671FB3FADB2F14ED6
Rx Total BW

Video Performance

1ECD99199531EFB695866285A79B46DF
Rx Video Jitter

Video Performance

D57C18E5A4730B0A2C207140427255B0
Rx Video Pkts Lost

Video Performance

96AB8783E2AC72E50424DA081192F19D
Tx Audio Jitter

Video Performance

DAFC53AF195639B311272BF8C7169777
Tx Audio Pkts Lost

Video Performance

06BB4148C9FAD147ECE7E76BCFD84B01
Tx Total BW

Video Performance

C97457AFAE8658BF49B6C9F69E54670D
Tx Video Jitter

Video Performance

C97457AFAE8658BF49B6C9F69E54670D
Tx Video Pkts Lost

Video Performance

C03030DF1BCFC6692A627341C7EBE954
Usage

Video Performance

E8CE7E065677B95C83A5F404A6BA6178

Availability Data

For Availability data, the args parameter for the constructor is an array that includes the following key:

  • datafields. An array that includes the data series for which you want data. You must supply an array that includes one or both of the following values:
    • d_check. The data series for device availability.
    • d_latency. The data series for device latency.

Web Content Monitoring Policy Data

For Web Content Monitoring Policy data, the args parameter for the constructor is an array that includes the following keys:

  • policy_id. The ID of the web content monitoring policy.
  • datafields. An array that includes the data series for which you want data. You must supply an array that includes one, multiple, or all of the following values:
    • d_state. The availability data for the web content monitoring policy.
    • d_conn_time. The connection time data for the web content monitoring policy.
    • d_ns_time. The lookup time data for the web content monitoring policy.
    • d_dl_size. The page size data for the web content monitoring policy.
    • d_dl_speed. The download speed data for the web content monitoring policy.
    • d_trans_time. The transaction time data for the web content monitoring policy.

Port Monitoring Policy Data

For Port Monitoring Policy data, the args parameter for the constructor is an array that includes the following key:

  • policy_id. The ID of the port monitoring policy.

For port monitoring policies, the data engine returns a single data series, labeled 'd_state', representing the availability of the port.

System Process Monitoring Policy Data

For System Process Monitoring Policy data, the args parameter for the constructor is an array that includes the following keys:

  • policy_id. The ID of the system process monitoring policy.
  • datafields. An array that includes the data series for which you want data. You must supply an array that includes one or both of the following values:
    • d_state. The availability data for the system process monitoring policy.
    • d_counter. The number of running processes for the system process monitoring policy.

SOAP/XML Transaction Monitoring Policy Data

For SOAP/XML Transaction Monitoring Policy data, the args parameter for the constructor is an array that includes the following keys:

  • policy_id. The ID of the SOAP/XML transaction monitoring policy.
  • datafields. An array that includes the data series for which you want data. You must supply an array that includes one, multiple, or all of the following values:
    • d_state. The availability data for the SOAP/XML transaction monitoring policy.
    • d_conn_time. The connection time data for the SOAP/XML transaction monitoring policy.
    • d_ns_time. The lookup time data for the SOAP/XML transaction monitoring policy.
    • d_dl_size. The page size data for the SOAP/XML transaction monitoring policy.
    • d_dl_speed. The download speed data for the SOAP/XML transaction monitoring policy.
    • d_trans_time. The transaction time data for the SOAP/XML transaction monitoring policy.

Domain Name Monitoring Policy Data

For Domain Name Monitoring Policy data, the args parameter for the constructor is an array that includes the following keys:

  • policy_id. The ID of the domain name monitoring policy.

  • datafields. An array that includes the data series for which you want data. You must supply an array that includes one or both of the following values:
  • d_state. The availability data for the domain name monitoring policy.
  • d_ns_time. The DNS-lookup time for the domain name monitoring policy.

Email Round-Trip Monitoring Policy Data

For Email Round-Trip Monitoring Policy data, the args parameter for the constructor is an array that includes the following keys:

  • policy_id. The ID of the Email round-trip monitoring policy.
  • datafields. An array that includes the data series for which you want data. You must supply an array that includes one or both of the following values:
    • d_state. The availability data for the Email round-trip monitoring policy.
    • d_rt_time. The round-trip time data for the Email round-trip monitoring policy.

Windows Service Monitoring Policy Data

For Windows Service Monitoring Policy data, the args parameter for the constructor is an array that includes the following key:

  • policy_id. The ID of the Windows service monitoring policy.

For windows service monitoring policies, the data engine returns a single data series, labeled 'd_state', that represents the availability of the Windows service.

File System Utilization Data

For File System Utilization data, the args parameter for the constructor is an array that includes the following keys:

  • policy_id. The ID of the file system. Note that this is the comp_index value for the file system from the master_dev.device_hardware database table, not the inv_id value.
  • datafields. An array that includes the data series for which you want data. You must supply an array that includes one or both of the following values:
    • d_used. The utilization data for the file system, in KB.
    • d_used_percent. The utilization data for the file system, in percent.

Interface Data - Percentage Utilization

For interface utilization data in percentage values, the args parameter for the constructor is an array that includes the following keys:

  • if_id. The ID of the interface for which you want data.
  • datafields. An array that includes the data series for which you want data. You must supply an array that includes one or both of the following values:
    • d_perc_in. The inbound utilization data for the interface, in percent.
    • d_perc_out. The outbound utilization data for the interface, in percent.

Interface Data - Octets, Errors, and Discards

For interface utilization data in octets, interface error rates, and interface discard rates, the args parameter for the constructor is an array that includes the following keys:

  • if_id. The ID of the interface for which you want data.
  • datafields. An array that includes the data series for which you want data. You must supply an array that includes one, multiple, or all of the following values:
    • d_octets_in. The inbound utilization data for the interface, in octets.
    • d_octets_out. The outbound utilization data for the interface, in octets.
    • d_errors_in. The inbound error rate for the interface, in packets.
    • d_errors_out. The outbound error rate for the interface, in packets.
    • d_discards_in. The inbound discard rate for the interface, in packets.
    • d_discards_out. The outbound discard rate for the interface, in packets.

Bandwidth Billing Policy Data

For Bandwidth Billing Policy data, the args parameter for the constructor is an array that includes the following keys:

The data engine returns the aggregate inbound and/or outbound utilization for the interfaces in the bandwidth billing policy, not the calculated percentile values.

  • policy_id. The ID of the bandwidth billing policy for which you want data.
  • datafields. An array that includes the data series for which you want data. You must supply an array that includes one or both of the following values:
    • d_octets_in. The aggregate inbound utilization data for the interfaces in the bandwidth billing policy, in octets.
    • d_octets_out. The aggregate outbound utilization data for the interfaces in the bandwidth billing policy, in octets.

IT Service Data - Health, Availability, and Risk

For health, availability, and risk data for an IT service policy, the args parameter for the constructor is an array that includes the following key:

  • datafields. An array that includes the data series for which you want data. You must supply an array that includes one, multiple, or all of the following values:
    • d_health. The calculated health metric for the IT service.
    • d_available. The calculated availability metric for the IT service.
    • d_risk. The calculated risk metric for the IT service

IT Service Data - Metrics

For performance metric data associated with an IT service policy, the args parameter for the constructor is an array that includes the following key:

  • presentation_id. The ID of the Dynamic Application presentation object that is used to calculate this IT service metric. Presentation object information, including the ID, is stored in the master.dynamic_app_presentation database table.

Time Range Methods

Before retrieving data from a data engine object, you must use one of the following methods to configure the time range for which data will be returned:

set_date_range(<start_ts_or_now>, <end_ts_or_now>)

This method takes two parameters:

  • start_ts_or_now. The start of the time range. You must pass either a unix timestamp or, to use the current time, the string "now" in this field.
  • end_ts_or_now. The end of the time range.You must pass either a unix timestamp or the string "now" in this field to use the current time.

For example, if you instantiated the variable $data_obj as a data engine object, you can set the time range from midnight UTC on January 1st, 2014 to the current time using the following line of code:

$data_obj->set_date_range(1388534400, 'now');

 

set_date_readable(<start>, <end>)

This method takes two parameters:

  • start. The start of the time range. You must pass a string that is parsable by the strtotime() PHP function.
  • end. The end of the time range. You must pass a string that is parsable by the strtotime() PHP function.

For example, if you instantiated the variable $data_obj as a data engine object, you can set the time range from the first day of the month to the current time using the following line of code:

$data_obj->set_date_readable('first day', 'now');

 

set_date_range_forward(<start_ts>, <duration>, <interval>)

This method takes three parameters:

  • start_ts. The start of the time range. You must pass a unix timestamp value.
  • duration. The duration of the time range. The units for the duration are specified by the interval parameter.
  • interval. The units for the duration parameter. You must pass one of the following strings: 'SECOND', 'MINUTE', 'HOUR', 'DAY', 'MONTH', or 'YEAR'.

For example, if you instantiated the variable $data_obj as a data engine object, you can set the time range from midnight UTC on January 1st, 2014 to 30 days later using the following line of code:

$data_obj->set_date_range_forward(1388534400, 30, 'DAY');

 

set_date_range_reverse(<end_ts>, <duration>, <interval>)

This method takes three parameters:

  • end_ts. The end of the time range. You must pass a unix timestamp value.
  • duration. The duration of the time range. The units for the duration are specified by the interval parameter.
  • interval. The units for the duration parameter. You must pass one of the following strings: 'SECOND', 'MINUTE', 'HOUR', 'DAY', 'MONTH', or 'YEAR'.

For example, if you instantiated the variable $data_obj as a data engine object, you can set the time range to be the 12 hours, ending at midnight UTC on January 1st, 2014 using the following line of code:

$data_obj->set_date_range_reverse(1388534400, 12, 'HOUR');

The following method can be used to retrieve the timestamp of the first collected item in the available data set:

get_first_timestamp()

The following method can be used to retrieve the timestamp of the last collected item in the available data set:

get_last_timestamp()

For example, if you instantiated the variable $data_obj as a data engine object, you can set the time interval to 4 hours up to the last collection time with the following lines of code:

$last_ts = $data_obj->get_last_timestamp();

$data_obj->set_date_range_reverse($last_ts,4,'HOUR');

Normalized Data Methods

By default, the data engine class returns the raw collected values for the selected data type. Additional methods are available that configure a data engine object to return normalized (rolled-up) data. Normalized data includes values for the average, minimum, maximum, sum, and standard deviation for the data in each normalization period. Depending on the frequency at which raw data is collected, up to two different normalization periods are available:

  • Hourly normalized data
  • Daily normalized data

NOTE: Frequent normalization has been deprecated in the SL1. Methods that previously specified frequent normalization will now return hourly normalized data.

Return Normalized Data for a Specified Normalization Period

To configure a data engine object to return normalized data for a specific normalization period, call one of the following methods with the specified parameters:

You cannot reconfigure a data engine object to return normalized data if that object has already been used to return data.

  • Frequent data:
  • set_norm_interval('FREQ','MIN')

  • Hourly data:
  • set_norm_interval(1,'HOUR')

  • Daily data:
  • set_norm_interval(1,'DAY')

Return a Specified Number of Data Points of Normalized Data

To configure a data engine object to return normalized data with an automatically-selected normalization period based on a maximum number of data points, use the following method:

set_norm_interval_auto(<max_points>, <allow_raw>)

This method takes the following parameters:

  • max_points. Pass an integer value. The maximum number of data points that should be returned when one of the data retrieval methods is called. The set_norm_interval_auto method will determine which available normalization period will generate the most data points for the currently specified timeperiod that is less than the max_points value.

  • allow_raw. Pass a boolean value. If you pass TRUE for this parameter, the method will not configure the data engine object to return normalization data if there are fewer raw collected data points in the specified time period than the max_points parameter. If you pass FALSE for this parameter, the method will always configure the data engine object to use normalized data.

Return a Specified Type of Normalized Data (Average, Minimum, Maximum, Standard Deviation, Sum)

When you configure a data engine object to return normalized data, you can specify which calculated values will be returned for each normalization period by calling the following method:

NOTE: If you do not call this method, a default list of values will be used. The default list includes average, minimum, maximum, standard deviation high value, and standard deviation low value.

set_norm_fields(<fields>)

This method takes a single parameter: an array of data labels that correspond to the different calculated values that are available for normalized data. Valid array values are:

  • avg. Returns the average of the collected values from each normalization period. This value is included in the default list.
  • min. Returns the smallest collected value from each normalization period. This value is included in the default list.
  • max. Returns the largest collected value from each normalization period. This value is included in the default list.
  • std. Returns the standard deviation for the collected values from each normalization period.
  • sum. Returns the sum of the collected values from each normalization period.
  • std_high. Returns either the average value plus half the standard deviation value or the largest collected value from each normalization period, whichever is higher. This value is included in the default list.
  • std_low. Returns either the average value minus half the standard deviation value or the smallest collected value from each normalization period, whichever is lower. This value is included in the default list.

Dynamic Application Methods

The following methods can be used to get information about Dynamic Applications, Presentation Objects, and Indexes.

Return Information about a Dynamic Application

The following method can be used to get information about the Dynamic Application for which the data engine object is configured:

get_app_info(<field>)

The field parameter is optional. If no parameter is specified, the method returns an array that contains the following key/value pairs:

  • app_type. The type of Dynamic Application. Possible values are:
    • 0. SNMP Performance.
    • 4. XML Performance.
    • 8. Database Performance.
    • 10. SOAP Performance.
    • 14. Snippet Performance.
    • 16. XSLT Performance.
    • 18. WMI Performance.
    • 22. PowerShell Performance.
  • poll. The poll frequency of the Dynamic Application, in minutes.
  • name. The name of the Dynamic Application.
  • db. The database that contains the data returned by this object.
  • table. The name of the database and database table that contains the data returned by this object. This value is in the format "<database>.<database_table>".

You can optionally pass one of the listed array keys in the field parameter. If you pass a parameter, the method will return the value associated with that key instead of returning an array.

Return Information about a Presentation Object

The following method can be used to get information about the presentation object for which the data engine object is configured:

get_presentation_info(<field>)

The field parameter is optional. If no parameter is specified, the method returns an array that contains the following key/value pairs:

  • presentation_id. The ID of the presentation object.

  • presentation_guid The PowerPack GUID of the presentation object.
  • app_id. The ID of the Dynamic Application with which the presentation object is associated.
  • app_guid. The PowerPack GUID of the Dynamic Application with which the presentation object is associated.
  • name. The name of the presentation object.
  • formula. The formula used to calculate each data point for the presentation object.
  • hourly. This field is deprecated.
  • daily. This field is deprecated.
  • monthly. This field is deprecated.
  • monthly_tot. This field is deprecated.
  • 3month. This field is deprecated.
  • yearly. This field is deprecated.
  • suffix. The suffix that represents the units for the presentation object, e.g. "%", "MB", etc.
  • graph_type. This field is deprecated.
  • guage. Whether the presentation object represents a percentage value. Possible values are 0 (zero) for no or 1 (one) for yes. This key name is not spelled "gauge".
  • descr. The description of the presentation object.
  • overview. This field is deprecated.
  • state. Whether the presentation object is enabled. Possible values are 0 (zero) for disabled or 1 (one) for enabled.
  • edit_user. The ID of the user account that last edited this presentation object.
  • edit_date. The date and time that the presentation object was last edited, in YYYY-MM-DD HH-MM-SS format.
  • comp_mapping. Whether the presentation is "vitals linked" to represent the CPU, Memory, or Swap utilization for subscriber devices. Possible values are:
    • 0. The presentation object is not vitals linked.
    • 1. The presentation object represents the CPU utilization for subscriber devices.
    • 4. The presentation object represents the Memory utilization for subscriber devices.
    • 5. The presentation object represents the Swap utilization for subscriber devices.
  • units. The data unit for the presentation object, e.g. "Percent", "Megabytes", etc.
  • formula_req_oids. An array that contains the IDs for the collection objects that are required to calculate a value for the presentation object.
  • formula_oids. An array that contains the IDs for all collection objects that are used to calculate a value for the presentation object.
  • oid_classes. An array that contains the numeric class type for all collection objects that are used to calculate a value for the presentation object. The array keys are the ID for each collection object.

You can optionally pass one of the listed array keys in the field parameter. If you pass a parameter, the method will return the value associated with that key instead of returning an array.

Return Information about Indexes

The following method can be used to get the label for a specific index:

NOTE: For details on indexing in Dynamic Applications, see the section on indexing.

get_series_name(<index>)

This method takes a single parameter, the index for which you want the label. If the label value is not available for the specified index, the index is returned.

The following method, which takes no parameters, can be used to get a list of all available indexes:

get_indexes()

This method returns an array:

  • The array keys are the available indexes.
  • The array values are the label for each index, if available. If label values are not available, the array values are the same as the array keys.

The following method can be used to specify the indexes for which the data engine object will return data:

set_indexes(<indexes>)

This method takes one parameter: an array of indexes for which you want data. If you did not pass indexes to the constructor and do not call this method, the data engine will return data for index 0 only.

The get_indexes() method returns the available indexes as array keys and the set_indexes() method expects indexes to be array values. To configure a data engine object to return data for all available indexes, use the PHP array_keys() function on the output of get_indexes() before passing it to set_indexes().

Counter Processing Methods

For counter objects:

  • SL1 stores the raw collected value.

  • For each collected value, the data engine returns the difference between the collected value and the previously collected value. That is, counter math is already applied to all data returned by the data engine.

There are multiple circumstances under which a collected value for a counter is lower than the previously collected value. SL1 includes logic that determines which of the following circumstances occurred:

  • The maximum value has been exceeded and counter was reset to zero.
  • Data was collected out-of-order, that is, due to a slowdown somewhere in the network, two counter values were stored out of sequence.
  • The counter was manually reset to zero on the external device.

Two thresholds control this behavior:

  • The Rollover Percent threshold is used to determine when a 32-bit counter has reached its maximum value and restarted counting. When SL1 encounters a counter value from a 32-bit counter that is lower than the previously collected value, SL1:
    • Calculates the difference between the two counter values (the delta) using the following formula:
    • maximum value (232) - Last Collected Value + Current Collected Value

    • Examines the value of the Rollover Percent threshold. If the delta is less than the specified percentage of the maximum possible value (232), SL1 concludes that the 32-bit counter rolled over. When SL1determines a 32-bit counter has rolled over, SL1 uses the delta value when displaying the data point for this poll period.

    For 64-bit counters, when the counter values go from a higher value to a lower value, SL1 assumes that the counter has been manually reset or that the two values were collected out of order. The Rollover Percent threshold does not apply to 64-bit counters.

  • The Out-of-order Percent threshold is used to determine when data has been collected out of order. When SL1 encounters a counter value that is lower than the previously collected value and SL1 has determined that the value is not a rollover, SL1:
    • Compares the current value to the last collected value:
    • current value / last collected value

    • If the ratio of current value / last collected value is greater than the percent specified in the Out-of-order Percent field, SL1 concludes that the data was collected out of order.

    • When SL1 determines a data point has been collected out of order, SL1 uses the following value as the current value of the data point:
    • last collected value - current collected value

If a collected value does not meet the rollover or out-of-order criteria, SL1 assumes a manual reset occurred and the current collected value is used for the data point.

By default, the data engine uses the default values for both thresholds:

  • Rollover Percent. 20%
  • Out-of-order Percent. 50%

The following method, which takes no parameters, configures a the data engine object to use the Rollover Percent and Out-of-order Percent thresholds that have been specified for the device with which the data is associated:

load_counter_thresholds()

The following method can be used to specify custom Rollover Percent and Out-of-order Percent thresholds:

set_counter_thresholds(<rollover>,<outoforder>)

This method takes the following parameters:

  • rollover. The Rollover Percent threshold to apply to the data returned by the object.
  • outoforder. The Out-of-order Percent threshold to apply to the data returned by the object.

Report Builder Methods

The report_builder_table class and its methods let you add grouping (separated by) in custom reports.

Methods from the report_builder_table class:

  • set_data($data). This function takes raw data as a parameter and sets data to be displayed in report output tables. For example: $table->set_data($data);

  • set_dynamic_columns($column_arr). This function sets the dynamic columns to be used by the bindcell directive in the report.

  • add_total_column ($column, $function). This function sets the column that will be used to show aggregated for total rows.

  • populate(). This function builds the final output table and initiate the .ods report building.

  • add_separation_level(). This function defines the grouping and separation levels.

You can use additional methods in the report_builder_table class as needed.

Other Methods

The following method, which takes no parameters, returns the name of the database that contains the data returned by this object.

get_db()

The following method returns the name of the database and database table that contains the data returned by this object. The returned value is in the format "<database>.<database_table>":

get_table(<norm>)

This method takes one boolean parameter. If FALSE is passed, the method returns the table that contains the raw data. If TRUE is passed and the object has been configured to return normalized data, the method returns the table that contains the normalized data returned by this object.

The following method, which takes no parameters, returns an array that includes the currently defined start and end times for the time period in unix timestamp format. The start and end times are at array indices 0 and 1, respectively:

get_date_range()

Data Retrieval Methods

To retrieve data from a data engine object, call the following method:

get_datasets()

This method returns an array. The structure of the returned array is different for raw and normalized data. For both raw and normalized data, the array includes data series objects, which have methods for retrieving arrays of data.

Raw Data

For raw data, the get_datasets() method returns an array of data series objects. The array of data series objects has the following keys:

  • For Dynamic Application data (including CPU, Memory, and Swap data), the key values are the indexes that were specified in the index parameter in the constructor or the set_indexes() method.
  • For port and Windows service monitoring policy data, a single key: "d_state".
  • For IT service metric data, a single key: "1".
  • For all other data types, the key values are the data series labels that were specified in the datafields array that was passed to the constructor.

Normalized Data

For normalized data, the get_datasets() method returns an array with the same key values listed for raw data. Each key points to an array that includes keys for each value that was passed to the set_norm_fields() method. If you did not call this method, a default list of array keys is used. Possible array keys are:

  • avg. Returns the average of the collected values from each normalization period. This value is included in the default list.
  • min. Returns the smallest collected value from each normalization period. This value is included in the default list.
  • max. Returns the largest collected value from each normalization period. This value is included in the default list.
  • std. Returns the standard deviation for the collected values from each normalization period.
  • sum. Returns the sum of the collected values from each normalization period.
  • std_high. Returns either the average value plus half the standard deviation value or the largest collected value from each normalization period, whichever is higher. This value is included in the default list.
  • std_low. Returns either the average value minus half the standard deviation value or the smallest collected value from each normalization period, whichever is lower. This value is included in the default list.

Each key in each array of normalized data labels points to a data series object.

Data Series Object Retrieval Methods

The following method can be used to retrieve the array of values from a data series object:

get_array(<addpadding>)

This method returns an array of values for the data series. The array keys are the collection times in unix timestamp format.

This method takes one boolean parameter: addpadding. If TRUE is passed, the array of values includes NULL values for collection times where collection is expected, but no value exists (i.e. a missed poll). If FALSE is passed, missed polls are not included in the output array.

The following method can be used to retrieve the number of missed polls (NULL values) that occurred during the time span of the data series:

get_missed()

This method returns an integer value equal to the number of missed polls.

The following method can be used to retrieve a bi-directional weighted average for each collection time:

get_smoothed()

This method returns an array of smoothed values for the data series. Smoothed values are a bi-directional weighted average for each raw data point. The array keys are the collection times in unix timestamp format.