DB API

NOTE: currently under development.

API Functions

Main API Functions

 
record_data_sample(hostname varchar,
                   data_group varchar,
                   data_item varchar,
                   time_stamp varchar,
                   data_type_id integer,
                   value_int bigint,
                   value_real double precision,
                   value_str varchar,
                   units varchar)
  • Synopsis: records a data sample corresponding to metric data being collected for a node on the cluster, for example: system environmental data, performance data, power management states, etc.
  • Notes:
    • The following records will be added if they don't already exist: host and data item.
  • Parameters:
    • hostname
    • data_group: the name of the group this sample belongs to. This allows grouping data items and avoiding name conflicts with data being collected by different Sensys components.
    • data_item: the name of the data item that was collected.
    • time_stamp: the time stamp at which the sample was collected.
    • data_type_id: the data type ID (as assigned by the application).
    • value_int: the actual value of the sample when the value is of type integer. Specify NULL if not of this type.
    • value_real: the actual value of the sample when the value is of type real. Specify NULL if not of this type.
    • value_str: the actual value of the sample when the value is of type string. Specify NULL if not of this type.
    • units: the data units for the sample (if applicable).
  • Returns: void.
set_node_feature(hostname varchar,
                 feature varchar,
                 data_type_id integer,
                 value_int bigint,
                 value_real double precision,
                 value_str varchar,
                 units varchar)
  • Synopsis: sets a particular feature for a given node, for example: number of sockets, cache, RAM, etc. This is part of the inventory and it is useful for characterizing nodes (information that may be needed by the resource manager).
  • Notes:
    • The following records will be added if they don't already exist: host and feature.
    • If the specified feature has not already been defined for the given node, it will be defined automatically. Otherwise, it will simply be updated with the new value.
  • Parameters:
    • hostname
    • feature: the name of the feature.
    • data_type_id: the data type ID (as assigned by the application).
    • value_int: the actual value of the feature when the value is of type integer. Specify NULL if not of this type.
    • value_real: the actual value of the feature when the value is of type real. Specify NULL if not of this type.
    • value_str: the actual value of the feature when the value is of type string. Specify NULL if not of this type.
    • units: the data units for the feature value (if applicable).
  • Returns: void.
record_diag_test(hostname varchar,
                 diag_type varchar,
                 diag_subtype varchar,
                 start_time timestamp without time zone,
                 end_time timestamp without time zone,
                 component_index integer,
                 test_result varchar)
  • Synopsis: adds a new instance of a diagnostic test that has been run.
  • Parameters:
    • hostname
    • diag_type: the name of the diagnostic type corresponding to the test.
    • diag_subtype: the name of the diagnostic sub type corresponding to the test.
    • start_time: the test's start time.
    • end_time: the test's end time.
    • component_index: an index to identify a particular instance of the component type that was tested.
    • test_result: the test result.
  • Returns: void.
record_diag_test_config(hostname varchar,
                        diag_type varchar,
                        diag_subtype varchar,
                        start_time timestamp without time zone,
                        test_param varchar,
                        value_int bigint,
                        value_real double precision,
                        value_str varchar,
                        units varchar)
  • Synopsis: adds a test parameter associated to a diagnostic test that has been run.
  • Parameters:
    • hostname
    • diag_type: the name of the diagnostic type corresponding to the test.
    • diag_subtype: the name of the diagnostic sub type corresponding to the test.
    • start_time: the test's start time.
    • test_param: the name of the test parameter being added to the test.
    • value_int: the actual value of the test parameter when the value is of type integer. Specify NULL if not of this type.
    • value_real: the actual value of the test parameter when the value is of type real. Specify NULL if not of this type.
    • value_str: the actual value of the test parameter when the value is of type string. Specify NULL if not of this type.
    • units: the data units for the test parameter (if applicable).
  • Returns: void.
record_node_calibration_data(calibration_id integer,
                             frequency integer,
                             hostname varchar,
                             run_time double precision,
                             idle_power double precision,
                             min_power double precision,
                             avg_power double precision,
                             max_power double precision,
                             peak_power double precision,
                             temperature double precision)
  • Synopsis: adds a node calibration data set for a particular node within a given calibration.
  • Parameters:
    • calibration_id: the calibration ID this node calibration data belongs to.
    • frequency: the frequency used during the iteration this node calibration data belongs to.
    • hostname
    • run_time
    • idle_power
    • min_power
    • avg_power
    • max_power
    • peak_power
    • temperature
  • Returns: void.

Secondary API Functions (Helper Functions)

 
add_calibration(start_time timestamp,
                workload_name varchar)
  • Synopsis: adds a new calibration record which can later be used to record node calibration data.
  • Parameters:
    • start_time: the start time for this calibration.
    • workload_name: the name of the workload used for the calibration.
  • Returns: integer: the ID of the newly added calibration.
add_calibration_iteration(calibration_id integer,
                          frequency integer)
  • Synopsis: adds a new calibration iteration to a calibration.
  • Parameters:
    • calibration_id: the calibration ID this iteration belongs to.
    • frequency: the frequency used during this iteration.
  • Returns: integer: the iteration number.
add_data_item(data_item varchar,
              data_type integer)
  • Synopsis: adds a new data item that can be used when recording data samples.
  • Parameters:
    • data_item: the name of the data item.
    • data_type: the data item type: 1 for numeric and 2 for string.
  • Returns: integer: the ID of the newly added data item.
add_data_sample(node_id integer,
                data_item_id integer,
                time_stamp timestamp,
                value_int bigint,
                value_real double precision,
                value_str varchar,
                units varchar)
  • Synopsis: adds a new data sample representing metric data corresponding to a node in the cluster.
  • Parameters:
    • node_id: the node's ID as assigned to it in the database.
    • data_item_id: the data item's ID as assigned to it in the database.
    • time_stamp: the time stamp at which the sample was collected.
    • value_int: the actual value of the sample when the value is of type integer. Specify NULL if not of this type.
    • value_real: the actual value of the sample when the value is of type real. Specify NULL if not of this type.
    • value_str: the actual value of the sample when the value is of type string. Specify NULL if not of this type.
    • units: the data units for the sample (if applicable).
  • Returns: void.
add_data_type(data_type_id integer,
              name varchar)
  • Synopsis: adds a new data type that can be associated to data samples, node features, diagnostic test parameters, etc.
  • Parameters:
    • data_type_id: the ID as assigned to it by the application (which it can use later for casting when retrieving data from the database).
    • name: the name of the data type.
  • Returns: void.
add_diag(diag_type_id integer,
         diag_subtype_id integer)
  • Synopsis: adds a new diagnostic test definition, composed of a diagnostic type and a sub type.
  • Parameters:
    • diag_type_id: the diagnostic type ID as assigned to it in the database.
    • diag_subtype_id: the diagnostic subtype ID as assigned to it in the database.
  • Returns: void.
add_diag_subtype(name varchar)
  • Synopsis: adds a new diagnostic test sub type.
  • Parameters:
    • name: the name of the diagnostic sub type.
  • Returns: integer: the ID of the newly added diagnostic sub type.
add_diag_test(node_id integer,
              diag_type_id integer,
              diag_subtype_id integer,
              start_time timestamp without time zone,
              end_time timestamp without time zone,
              component_index integer,
              test_result_id integer)
  • Synopsis: adds a new instance of a diagnostic test that has been run.
  • Parameters:
    • node_id: the ID of the node (as assigned to it in the database) where the test was run.
    • diag_type_id: the ID of the diagnostic type (as assigned to it in the database) corresponding to the test.
    • diag_subtype_id: the ID of the diagnostic sub type (as assigned to it in the database) corresponding to the test.
    • start_time: the test's start time.
    • end_time: the test's end time.
    • component_index: an index to identify a particular instance of the component type that was tested.
    • test_result_id: the ID corresponding to the test result (as assigned to it in the database).
  • Returns: void.
add_diag_test_config(node_id integer,
                     diag_type_id integer,
                     diag_subtype_id integer,
                     start_time timestamp without time zone,
                     test_param_id integer,
                     value_int bigint,
                     value_real double precision,
                     value_str varchar,
                     units varchar)
  • Synopsis: adds a test parameter associated to a diagnostic test that has been run.
  • Parameters:
    • node_id: the ID of the node (as assigned to it in the database) where the test was run.
    • diag_type_id: the ID of the diagnostic type (as assigned to it in the database) corresponding to the test.
    • diag_subtype_id: the ID of the diagnostic sub type (as assigned to it in the database) corresponding to the test.
    • start_time: the test's start time.
    • test_param_id: the ID of the test parameter (as assigned to it in the database) being added to the test.
    • value_int: the actual value of the test parameter when the value is of type integer. Specify NULL if not of this type.
    • value_real: the actual value of the test parameter when the value is of type real. Specify NULL if not of this type.
    • value_str: the actual value of the test parameter when the value is of type string. Specify NULL if not of this type.
    • units: the data units for the test parameter (if applicable).
  • Returns: void.
add_diag_type(name varchar)
  • Synopsis: adds a new diagnostic test type.
  • Parameters:
    • name: the name of the diagnostic type.
  • Returns: integer: the ID of the newly added diagnostic type.
add_feature(feature varchar,
            data_type_id integer)
  • Synopsis: adds a new feature that can later be used to set features for nodes.
  • Parameters:
    • feature: the name of the feature.
    • data_type_id: the ID of the data type (as defined by the application) for this feature.
  • Returns: integer: the ID of the newly added feature.
add_node(hostname varchar)
  • Synopsis: adds a new node.
  • Parameters:
    • hostname
  • Returns: integer: the ID of the newly added node.
add_node_calibration_data(calibration_id integer,
                          iteration integer,
                          node_id integer,
                          run_time double precision,
                          idle_power double precision,
                          min_power double precision,
                          avg_power double precision,
                          max_power double precision,
                          peak_power double precision,
                          temperature double precision)
  • Synopsis: adds a node calibration data set for a particular node within a given calibration.
  • Parameters:
    • calibration_id: the calibration ID this node calibration data belongs to.
    • iteration: the iteration number within the calibration.
    • node_id: the node ID (as assigned to it in the database).
    • run_time
    • idle_power
    • min_power
    • avg_power
    • max_power
    • peak_power
    • temperature
  • Returns: void.
add_node_feature(node_id integer,
                 feature_id integer,
                 value_int bigint,
                 value_real double precision,
                 value_str varchar,
                 units varchar)
  • Synopsis: adds a new feature for a given node.
  • Parameters:
    • node_id: the node's ID as assigned to it in the database.
    • feature_id: the feature's ID as assigned to it in the database.
    • value_int: the actual value of the node feature when the value is of type integer. Specify NULL if not of this type.
    • value_real: the actual value of the node feature when the value is of type real. Specify NULL if not of this type.
    • value_str: the actual value of the node feature when the value is of type string. Specify NULL if not of this type.
    • units: the data units for the node feature value (if applicable).
  • Returns: void.
add_test_param(test_param varchar,
               data_type_id integer)
  • Synopsis: adds a new test parameter that can later be used to specify parameters for diagnostics tests.
  • Parameters:
    • test_param: the name of the test parameter.
    • data_type_id: the ID of the data type (as defined by the application) for this test parameter.
  • Returns: integer: the ID of the newly added test parameter.
add_test_result(test_result varchar)
  • Synopsis: adds a new test result that can later be used to specify results for diagnostics tests.
  • Parameters:
    • test_result: the name or description of the test result.
  • Returns: integer: the ID of the newly added test result.
data_type_exists(data_type_id varchar)
  • Synopsis: checks whether a specified data type exists or not.
  • Parameters:
    • data_type_id: the ID of the data type (as defined by the application).
  • Returns: boolean: true if the data type already exists and false otherwise.
diag_exists(diag_type varchar,
            diag_subtype varchar)
  • Synopsis: checks whether a specified diagnostic type-sub-type combination exists or not.
  • Parameters:
    • diag_type: the name of the diagnostic type.
    • diag_subtype: the name of the diagnostic sub type.
  • Returns: boolean: true if the diagnostic type-sub-type combination already exists and false otherwise.
diag_exists(diag_type_id integer,
            diag_subtype_id integer)
  • Synopsis: checks whether a specified diagnostic type-sub-type combination exists or not.
  • Parameters:
    • diag_type_id: the ID of the diagnostic type (as assigned to it in the database).
    • diag_subtype_id: the ID of the diagnostic sub type (as assigned to it in the database).
  • Returns: boolean: true if the diagnostic type-sub-type combination already exists and false otherwise.
get_data_item_id(data_item varchar)
  • Synopsis: gets the ID for a given data item as assigned to it in the database.
  • Parameters:
    • data_item: the name of the data item.
  • Returns: integer: the ID of the given data item. If the specified data item is not found, 0 is returned.
get_diag_subtype_id(diag_subtype varchar)
  • Synopsis: gets the ID for a given diagnostic sub type as assigned to it in the database.
  • Parameters:
    • diag_subtype: the name of the diagnostic sub type.
  • Returns: integer: the ID of the given diagnostic sub type. If not found, 0 is returned.
get_diag_type_id(diag_type varchar)
  • Synopsis: gets the ID for a given diagnostic type as assigned to it in the database.
  • Parameters:
    • diag_type: the name of the diagnostic type.
  • Returns: integer: the ID of the given diagnostic type. If not found, 0 is returned.
get_feature_id(feature varchar)
  • Synopsis: gets the ID for a given feature as assigned to it in the database.
  • Parameters:
    • feature: the name of the feature.
  • Returns: integer: the ID of the given feature. If the specified data item is not found, 0 is returned.
get_node_id(hostname varchar)
  • Synopsis: gets the ID for a given node as assigned to it in the database.
  • Parameters:
    • hostname
  • Returns: integer: the ID of the given node. If the specified node is not found, 0 is returned.
get_test_param_id(test_param varchar)
  • Synopsis: gets the ID for a given test parameter as assigned to it in the database.
  • Parameters:
    • test_param: the name of the test parameter.
  • Returns: integer: the ID of the given test parameter. If not found, 0 is returned.
get_test_result_id(test_result varchar)
  • Synopsis: gets the ID for a given test result type as assigned to it in the database.
  • Parameters:
    • test_result: the name of the test result type.
  • Returns: integer: the ID of the given test result type. If not found, 0 is returned.
node_feature_exists(node_id integer,
                    feature_id integer)
  • Synopsis: check if a given feature has been defined for a particular node.
  • Parameters:
    • node_id: the node ID as assigned to it in the database.
    • feature_id: the feature ID as assigned to it in the database.
  • Returns: boolean: true if the given feature has been defined for the given node and false otherwise.
update_node_feature(node_id integer,
                    feature_id integer,
                    value_int bigint,
                    value_real double precision,
                    value_str varchar,
                    units varchar)
  • Synopsis: apply changes to a given node feature.
  • Parameters:
    • node_id: the node's ID as assigned to it in the database.
    • feature_id: the feature ID as assigned to it in the database.
    • value_int: the actual value of the feature when the value is of type integer. Specify NULL if not of this type.
    • value_real: the actual value of the feature when the value is of type real. Specify NULL if not of this type.
    • value_str: the actual value of the feature when the value is of type string. Specify NULL if not of this type.
    • units: the data units for the feature value (if applicable).
  • Returns: void.

DB Views

 
data_samples_view
  • Synopsis: provides a view to all the data samples that have been collected.
  • Columns:
    • node_id: the ID of the node as assigned to it in the database.
    • hostname
    • data_item_id: the ID of the data item as assigned to it in the database.
    • data_item: the name of the data item.
    • data_type: the data item type: 1 for numeric and 2 for string.
    • time_stamp: the time stamp at which the sample was collected.
    • value_int: the actual value of the sample (if integer, NULL otherwise).
    • value_real: the actual value of the sample (if real, NULL otherwise).
    • value_str: the actual value of the sample (if string, NULL otherwise).
    • units: the sample units (if applicable).
node_features_view
  • Synopsis: provides a view to all the node features that have been set for all nodes. Further filtering is necessary to retrieve the features of a particular node.
  • Columns:
    • node_id: the node ID as assigned to it in the database.
    • hostname
    • feature_id: the feature ID as assigned to it in the database.
    • feature: the feature name.
    • value_int: the actual value of the feature (if integer, NULL otherwise).
    • value_real: the actual value of the feature (if real, NULL otherwise).
    • value_str: the actual value of the feature (if string, NULL otherwise).
    • units: the value units (if applicable).