Platform definition JSON file structure

DEVICEENTITYTYPE

Discovering devices where the parents of the devices are monitored by a PATROL Agent. In this case, DEVICEENTITYTYPE can be used for identification.

AIX host DEVICEENTITYTYPE is set to “IBM.MG_SYS.Host” when
its parent HMC is monitored by a PATROL Agent.

Hence, AIX host can be discovered by searching for
devices whose DEVICEENTITYTYPE is "IBM.MG_SYS.Host"

"src_identification": {

"src_identification_type":  
       "DEVICEENTITYTYPE",

"src_identification_value":
       "IBM.MG_SYS.Host" }

Discovering devices that are related to a device (Device-to-Device discovery):

In this case, any INSTANCE information between a parent and a child device is not shared. Hence, this relationship is used when there is no INSTANCE present between a parent
and a child device to be discovered.

LPAR (Device) to WPAR (Device).

In this case, WPARs for a given LPAR will be discovered using DEVICEENTITYTYPE of children having value
 IBM.WPAR.Virtual_Machine

"src_identification": {

 "src_identification_type":
        "DEVICEENTITYTYPE",

"src_identification_value":
 "IBM.WPAR.Virtual_Machine" }

MONITORTYPE

Discovering instances related to a device (Device-to-Instance discovery)

AIX host (Device) to Pool (Instance) by traversing the instances
of a specific MONITORYTYPE in between AIX host and Pool.

In this case, the pool for AIX host will be discovered by
discovering the instance of monitor type _PATROL__MG_SYS, that has a child  
instance of monitor type _PATROL__LP_CONT with an instance name
“Shared   Processor Pools” that have instances of monitor type
_PATROL__PROCPOOL

"src_identification":   { 

"src_identification_type":
       "MONITORTYPE",

"src_identification_value":
         "_PATROL__MG_SYS/
_PATROL__LP_CONT##
Shared Processor Pools/
_PATROL__PROCPOOL" }

Discovering devices related to specific instances (Instance-to Device-discovery)

To get SPLPARs under Pool.

In this case, SPLPARs under Pool of AIX host will be discovered by discovering instance of type PATROL__LP_CONT that has children instances of monitor type _PATROL__LPAR for a given Pool.

"src_identification":   {

"src_identification_type":
        "MONITORTYPE",

"src_identification_value":
    "_PATROL__LP_CONT/
_PATROL__LPAR" }

Discovering devices under specific instance under specific device (Device-to-Instance-to-Device discovery)

To get dedicated partitions under AIX host.

In this case, dedicated partitions for AIX host will be discovered by discovering instance of type _PATROL__MG_SYS that has a child instance of monitor type _PATROL__LP_CONT with instance name “Dedicated Partitions” that have instances of monitor type _PATROL__LPAR.

"src_identification": { 

"src_identification_type":
    "MONITORTYPE",  

"src_identification_value":
     "_PATROL__MG_SYS/
_PATROL__LP_CONT##
Dedicated  Partitions/
_PATROL__LPAR" }

CONFIGDATA

• Parent of a device does not exist. For example:Bare metal devices, Primary LDOM
• Parent of a device is not monitored by a PATROL Agent. For example, AIX LPARs for whom HMC is not monitored), its DEVICEENTITYTYPE is set to “Default” and cannot be used for identification of a device. In such a case, configuration data that gives the entity type can be used for identification, which means that ENTITYTYPE associated with _PATROL__UNIX_OS/_PATROL__WINDOWS_OS instance of a device is used for identification of a device.

AIX LPARs when HMC is not monitored, its DEVICEENTITYTYPE
is set to "Default" and hence cannot be used for identification, however,
its _PATROL__UNIX_OS instance configuration data for metric
ENTITYTYPE can be used for identification.

In this case, Stand-alone LPARs (LPARs whose parent, AIX host/HMC, is not monitored by a PATROL Agent) will be discovered by using CONFIGDATA from monitor type "_PATROL__UNIX_OS", that has a value "IBM.LPAR.HOST" for metric "ENTITYTYPE".

"src_identification": {

 "src_identification_type":    
    "CONFIGDATA",

 "src_identification_value":
     "IBM.LPAR.HOST"

 "src_monitor_type":
   "_PATROL__UNIX_OS",

 "src_identification_metric":
    "ENTITYTYPE" }

“type”

Defines the type of platform for the JSON

The following attribute-value pair suggests that this JSON file is for “AIX” platform:

"type":   "AIX"

“entities”:{}

Defines the entities to be discovered for the platform. Each entity defines the way it is discovered, its lookup, its children entities, and its key for metric definition
to be used in "metrics" section.

This example shows that the entity type being fetched is “AIX HOST”. Also, the key used to define metrics for this entity in the "metrics" section is "metric_configuration_key".

"entities": {

        "AIX HOST": {

................

"metric_configuration_key":
   "AIX HOST METRICS"

................

       }

}

“metrics”: {

    “basic_metrics”

    “derived_metrics”

 “aggregated_metrics”

}

Defines the metrics to be discovered for each entity with a key as defined in the "entities" attribute. The following categories of metrics are defined:

Basic; Derived; Aggregated

"metrics": {

    "AIX HOST METRICS": {

          "basic_metrics": [

                 {

                 }

             ],

          "derived_metrics": [

                 {

                 }

             ],

                 "aggregated_metrics":[

                 {

                 }

             ]

    }

}

Here, the key "AIX HOST METRICS" defines the basic, derived, and aggregated metrics for AIX host.

“dst_ent_type”

Defines the Destination entity type

"dst_ent_type":   "vh:lp"

ENTITYTYPE in Destination is “vh:lp”, which corresponds to AIX host

"dst_ent_cat"

Defines the Destination entity category

"dst_ent_cat":   "SYS"

Entity category in Destination is SYS

“src_ent_cat”

Defines the Source entity category - DEVICE or INSTANCE

“src_ent_cat”: ”DEVICE”

AIX host is DEVICE. AIX pool is an INSTANCE.

"dst_top_level_entity”

Defines whether the entity being fetched is a top level entity for Destination.

This top-level entity is represented under the root domain in the Destination. The JSON file starts discovery with the top-level entity that is followed by discovering children, grand-children, and so on, and the same hierarchy is represented on the Destination.

Ensure that the JSON file has at least one entity with this flag set as true. If this attribute is not specified, the default value for this attribute is false.

"dst_top_level_entity":   true

"dst_discover_independently”

Defines whether this entity must be discovered independently.

After the top-level entities, its children, and grandchildren are discovered, entities with this flag are discovered. These entities have not been already discovered and will be represented under the root domain.

This attribute is optional. If this attribute is not specified, the default value is false. 

"dst_discover_independently”:   true

The flow of discovering top-level entity for AIX platform is as follows: AIX host with children such as Pool, LPARs that will discover LPARs for whom HMC is monitored.
For LPARs that are not part of the HMC being monitored, this flag is used.

For example. for discovering Standalone LPARs that are not discovered as children of AIX HOST.

"metric_configuration_key"

Defines metrics for the entity under the “metrics” section of the JSON file

"metric_configuration_key":   "AIX HOST METRICS"

Metrics for this entity will be available within the “AIX HOST METRICS” section of the “metrics” section.

"src_identification":   {

 "src_identification_type"

"src_identification_value"

"src_monitor_type"

"src_identification_metric”

            }

Defines the following attributes on the Source:

• "src_identification_type"  – Type of identification used on the Source. Possible values are DEVICEENTITYTYTYPE, MONITORTYPE, CONFIGDATA
• "src_identification_value"  – Value for the specified identification type

Consider the following attributes only when the value of "src_identification_type" is CONFIGDATA:

• "src_monitor_type" – Source monitor type from where the configuration metrics are fetched
• "src_identification_metric"  – Source metric that will be used for identification

“lookup”

Defines the lookup attributes that are used on Destination. For attribute details, see Attributes for "lookup" section.

“lookup": [

{

} ]

“children”

Defines children entities for the entity under consideration. For attribute details, see Attributes for "children" section.

 "children": [

{

} ]

“lookup”: [

{

"type"

"fields": [

                        {

                              "dst_field"

                        }

                ]

"mapping": [

                        {

                            "dst_field" 

                            "src_field"

                        }

                  ]

}

]

• "type" - type of lookup
• “fields” - fields used for lookup
• “dst_field” – Destination lookup field name
• “src_field” – Source lookup field name
• “mapping” includes the mapping of the lookup fields in Destination to those in Source.

This example defines STRONG lookup for an entity in the Destination. The entity under consideration has lookup fields:

• “TOKEN_ID” that maps to “tokenId”
• “HOSTNAME” maps to “dnsname” on Source

When “src_ent_cat” is DEVICE, possible values that can be used for "src_field" are:

• “tokenId”: token identification of the device in Source
• “dnsname”: DNS name of the device in Source

When “src_ent_cat” is INSTANCE, a possible value that can be used for "src_field" is "monInstName”.

"lookup": [

{

“type”: “STRONG”

"fields": [

                        {

                              "dst_field": "TOKEN_ID"

                        },

                        {

                              "dst_field": "HOSTNAME"

                        }

                    ],

"mapping": [

                        {

                            "dst_field":   "TOKEN_ID",

                             "src_field": "tokenId"

                        },

                        {

                              "dst_field": "HOSTNAME",

                              "src_field": "dnsname"

                        }

                    ]

}

]

"children": [

 {

“entity_key”

"dst_relation_type

}

]

• “entity_key” - Key of child entity in this JSON file
• “dst_relation_type” - Relation type in Destination

For the “AIX HOST” entity, AIX POOL and AIX LPAR children are defined:

"children": [

               {

                      "entity_key": "AIX POOL",

                      "dst_relation_type": "RP_CONTAINS_GM",

              },

                {

                      "entity_key": "AIX LPAR",

                      "dst_relation_type": "VH_CONTAINS_GM",               

                }

            ]

“basic_metrics”: [             

 {

 "src_monitor_type"                

"src_monitor_data_type"   

 "dst_subobject_mapping"              

"filter_condition": {

      "filter_type"

      "src_metric_name"

      "src_metric_value"                

   }

    "metrics": [

      {

 "dst_metric"

 "src_metric"

 "formula"

“available_for_other_
metric_computation”

“populate_dst_metric”

       }

    ]

  }

]

• "basic_metrics" - Defines basic metrics that have one-to-one mapping between the Source and Destination metrics with a formula for conversion.
• "src_monitor_type" - Defines the monitor type on the Source for which metrics are to be fetched. The basic metrics to be fetched are grouped by monitor type.
• “src_monitor_data_type” – Defines the monitor data type for which Destination wants to fetch data. The possible values are "config" for fetching configuration data and "perf" for fetching performance data.
• “metrics” – Defines metrics to import along with related mapping and formula, for the monitor type under consideration.
• “dst_metric” - Defines the metric on Destination
• “src_metric” - Defines the metric on Source
• “formula” – Defines the formula for conversion from Source-to-Destination unit of measure. This attribute is required only if conversion is needed for converting metric to a Destination unit of measure. Possible operators are:
  +
  -
  *
  /
• “dst_subobject_mapping” – Defines the subobject mapping that is required only for BY type of metrics wherein subobject name in Destination needs to be mapped to a name in Source.
• “filter_condition” – Defines the condition under which to filter data from Source.
• “filter_type” – Defines whether to include or exclude data, respectively.

• "src_metric_name" - Defines the Source metric name.
• “src_metric_value” –  Defines the Source metric value on which to filter. Multiple values can be specified separated by "|".
• “available_for_other_metric_computation” - Defines the condition true if the basic metric under consideration needs to be used in computation of derived or aggregated metric. If this attribute is not specified (as true), the default value is false.
• “populate_dst_metric” – Defines the condition true if basic metric is not to be populated in Destination, but only to be used for computation for derived or aggregated metric. If this attribute is not specified (as false), the default value is true.

In this example, metrics from CPU and FILESYSTEM monitor types are fetched for LPAR. For FILESYSTEM metrics: the imported metrics are BY metrics, "dst_subobject_mapping" is required and maps to "monInstName", which is the monitor instance name on Source. Also, to exclude some file systems, a filter_condition is specified.

“basic_metrics” :   [           

   {

        "src_monitor_type":
"_PATROL__CPU",                  

         "src_monitor_data_type": “perf”,

         "metrics": [

                     {

                           "dst_metric": "CPU_UTIL",

                           "src_metric": "CPUCPUUTIL",

                           "formula": "CPUCPUUTIL/100"

                     },

                     {

                           "dst_metric": "CPU_ENT_UTIL",

                           "src_metric": "CPUENTLUTIL",

                           "formula": "CPUENTLUTIL/100"

                     }

                 ]

},

{

         "src_monitor_type": 
"_PATROL__FILESYSTEM",                   

         "src_monitor_data_type": “perf”,

          "dst_subobject_mapping":”monInstName”,              

          "filter_condition":   {

             "filter_type":   "exclude",

             "src_metric_name":   "FILESYSTEMTYPE",

             "src_metric_value":   "NFS | NFS2|
NFS3 | SHAREFS | No Data | LOFS | ZFS |
OBJFS | MNTFS |   CTFS | DEVFS | FDFS"

             }

     "metrics": [

                     {

                         "dst_metric":  "BYFS_USED_SPACE_PCT",

                          "src_metric": "FSCAPACITY",

                          "formula": "FSCAPACITY/100"

                     },

                     {

                           "dst_metric": "BYFS_FREE",

                           "src_metric": "FSAVAILABLESPACEMB",

                           "formula":
"FSAVAILABLESPACEMB*1024*1024",

                            "available_for_other_metric_computation": true

                     },

             ]

}

]

"derived_metrics":   [

{

    "dst_metric"

    "formula"                         

   "formula_variables": [

   {

       variable

    },

  ]

}

]

• "derived_metrics" - Specifies metrics that are calculated by using more than one basic metric of the same entity for which derived metric is being calculated.
• "dst_metric" – Specifies a Destination metric to be derived by using more than one Destination basic metric.
• "formula" – Specifies the metrics with formula.
• "formula_variables" – Specifies the individual variables, namely metrics in the formula.

In this example, derived metric for AIX LPAR is defined. The BYFS_SIZE metric is derived by addition of BYFS_USED and BYFS_FREE metrics.

"derived_metrics":   [

                {

                              "dst_metric": "BYFS_SIZE",

                              "formula": "BYFS_USED+BYFS_FREE",

                              "formula_variables": [

                                   {

                                                variable: "BYFS_USED"

                                   },

                                   {

                                               variable: "BYFS_FREE"

                                   }

                    ]

                }

            ]

“aggregated_metrics”: [

 {

          "dst_metric":

          "formula":

          "formula_variables":   [

          {

                "variable":

                "computation":

                 {

               "use_associated_entity"

               "operation”

               "input_metric"

                }                          

            }

         ]

  }

]

• "aggregated_metrics" - Metrics that are calculated at an entity level using metrics of a different entity that can be a child, parent, or subobject entity
• "dst_metric" - Destination metric to be computed              
• "formula" - Formula to be applied on variables
• "formula_variables" - Formula variables as used in formula            
• "variable" - Variable in the formula, which is the result of computation
• "computation" - Computation of variable of formula, that uses “operation” on “input_ metric” of  entities as specified in “use_associated_entity”               
• "use_associated_entity" - Entity to be used for computation. Multiple entities can be specified separated by “|”. Possible values are Destination entity types as specified in "dst_ent_type". If unspecified, it means the operation is on the entity under consideration.
• "process_subobjects" - Flag that indicates true if the "input_metric" is a BY metric that holds subobjects. If unspecified, the default value is false.
• "operation" - Operation to be used for computation on the associated entity. Supported values are as follows:
  • SUM – Performs summation of metric values across entities
  • MAX - Considers maximum of metric values across entities
  • COUNT – Considers count of number of entities for the entity specified in "use_associated_entity"
  • COPY_ONE_ENTITY – Copies value of input_metric only for one of the associated entity
  • COPY_ALL_ENTITIES - Copies value of input_metric for all of the associated entities
• "input_metric" - Input metric to be used for computation
• “dst_subobject_mapping” – Attribute that is required when dst_metric is a BY type of metric wherein subobject name in Destination needs to be mapped to a name in Source              

Example 1:

In this example, two aggregated metrics for AIX LPAR/SPLPAR are defined.

• For SUM operation: The total file system utilization of an LPAR is computed using “subobject”, which is file system.
• For MAX operation: The peak disk utilization of LPAR is computed using “subobject”, which is disk.

For both these examples, "use_associated_entity" is unspecified because the computation for metric is for LPAR entity using LPAR entity, which means the operation is performed on itself. The "input_metric" under consideration has subobjects and hence, "process_subobjects" is specified as true.

    "aggregated_metrics": [

                 {

                              "dst_metric": "TOTAL_FS_UTIL",

                              "formula": "sum_of_lpar_byfs_used/ sum_of_lpar_byfs_size",

                              "formula_variables": [

                                {

                                      "variable": "sum_of_lpar_byfs_used",

                                      "computation": {

                                         "process_subobjects":   true,

                                          "operation": "SUM",

                                          "input_metric": "BYFS_USED"

                                           }

                                },

                                {

                                      "variable": "sum_of_lpar_byfs_size",

                                      "computation": {

                                          "process_subobjects":   true,

                                           "operation":   "SUM",

                                          "input_metric": "BYFS_SIZE"

                                            }

                                }

                            ]

             },

             {                                                

                    "dst_metric":   "DISK_UTIL_PEAK",                       

                    "formula":   "max_of_lpar_bydisk_util",               

                     "formula_variables": [                                              

                        {                                                     

                              "variable":"max_of_lpar_bydisk_util",                                                               

                              "computation": {                                                 

                                   "process_subobjects":   true,

                                   "operation": "MAX",    

                                   "input_metric": "BYDISK_UTIL"                

                                    }                                                 

                        }

                   ]

               }

]

Example 2:

In this example. three aggregated metrics for AIX HOST are defined.

• For COUNT operation: COUNT of all LPARs/SPLPARs under AIX host is computed.
• For COPY_ONE_ENTITY operation: CPU_MODEL value of one of the associated entities (LPAR/SPLPAR) is copied to its host.
• For COPY_ALL_ENTITIES operation: CPU_UTIL of all associated entities (LPARs/SPLPARs in this case) are copied under AIX host, to AIX host as a BY metric with subobject as LPAR/SPLPAR name.

"aggregated_metrics": [

              {

                    "dst_metric":   "GM_NUM",

                    "formula":   "lpar_gm_num_count",

                    "formula_variables": [

                        {

                              "variable": "lpar_gm_num_count",

                              "computation": {

                                  "use_associated_entity": "gm:lp|gm:splp",

                                  "operation": "COUNT"

                                   }

                        }

                    ]

             },

             {

                    "dst_metric":   "CPU_MODEL",

                    "formula":   "lpar_cpu_model",

                      "formula_variables": [

                        {

                              "variable": "lpar_cpu_model",

                              "computation": {

                                  "use_associated_entity": "gm:lp|gm:splp",

                                  "operation": "COPY_ONE_ENTITY",

                                  "input_metric":   "CPU_MODEL"

                                 }

                         }

                    ]

             },

            {

                    "dst_metric":   "BYLP_CPU_UTIL",

                    "formula":   "lpar_cpu_util",

                     "formula_variables": [

                        {

                              "variable": "lpar_cpu_util",

                              "computation": {

                                  "use_associated_entity": "gm:lp|gm:splp",

                                  "operation": "COPY_ALL_ENTITIES",

                                  "input_metric": "CPU_UTIL",

                                  "dst_subobject_mapping": "dnsname"

                                  }

                       }

                    ]

            }

]