Systems

Systems

#340420

Description

This resource is used to return information about systems loaded through data collection in Densify. These systems do not have to belong to a control environment or a cloud environment, but must be of a supported entity type. Returned resource element values match those that are displayed in the Densify Analysis Console from the Data Collection > Discovered System Explorer (DSE) > System Summary or Attributes pages.

Resource

/systems

Supported Operations

Table: Systems Supported Operations

Operation

HTTP Method

Input

Output

Description

Get Collection

GET /systems

Query String Parameter Options:

Collection of Response elements

Used to return configuration and attribute information of systems (of supported type) that are being tracked under recent data collection activity.

Example: Getting a Collection of Sorted GCP Systems, Displaying One Page

Example: Getting a Collection of VMware Systems using Attribute Filters

Get Individual Systems

GET /systems/<id>

Path Parameter:

  • id (system ID)

Response elements

Used to return configuration and attribute information for a system specified by id. The system returned are being tracked under recent data collection activity and must be one of the supported system type.

Example: Getting an Individual Host System

Example: Getting an Individual Guest System

Get Report PDF

GET /systems/<id>/analysis-report

Path Parameter:

  • id (system ID)

Used to obtain the Impact Analysis and Recommendation Report (also known as the Application Owner report). This PDF report for the specified instance, is available for download after the reporting database tables have been updated (i.e. after RDB populate has been executed). By default, the reporting database tables are updated once every night.

See Viewing the Impact Analysis and Recommendation Report for details on the content of the report.

Use Accept : application/octet-stream in the request header to download the PDF file.

Example: Downloading an Impact Analysis and Recommendation Report

Modify System Attributes

PUT /systems/<id>/attributes

Path Parameter:

  • id (system ID)

Request Body Parameters:

array of attributes

Response elements with attributes modified

Used to modify the values of a system’s attributes.

If attribute name corresponds to an existing set attribute in the system, then the attribute's value will be updated to value. If attribute name is not set in the system, then the [name,value] tuple will be added to the system's attribute array.

For multi-value attributes (i.e. "Multiple Values" property is enabled for the attribute), a PUT request for that attribute will append the new [name,value] pair to the attribute array, if that attribute [name,value] pair does not exist. To overwrite a multi-value attribute value, you will first need to delete the existing attribute value.

Example: Modifying a System’s Attributes

Delete System Attributes

DELETE /systems/<id>/attributes

Path Parameter:

  • id (system ID)

Request Body Parameters:

array of attributes

or

Response elements with attributes deleted

Used to delete attributes from an individual system given the attribute ID-value [id,value] pair or attribute [id].

If the attribute [id,value] pair is provided, the attribute will be deleted only if the attribute [id] and corresponding [value] matched the one found in the system.

For multi-value attributes (i.e. "Multiple Values" property is enabled for the attribute), a DELETE request with only attribute [id] provided will delete all the values with that attribute ID; a DELETE request with [id,value] pair provided will delete only the attribute ID entry with that specific value.

Example: Deleting a System’s Attributes

Parameters

Path Parameters

Table: Systems Path Parameters

Parameter Name

Type

Description

id

string

The Densify unique referenced ID of the system.

Request Body Parameters

Table: Systems Request Body Parameters (Array of [id, name, value] attributes)

Parameter Name

Type

Description

id

string

The unique ID for the attribute in Densify.

System attributes are properties set by a data collection from a vendor platform or by Densify for control analytics. The system's attributes array contains attribute elements, stored as an [id, name, value] tuple in the system's attributes array.

name

string

The name of the attribute corresponding to the id and value attribute tuple.

value

string

The value of the attribute corresponding to the id and name attribute tuple.

Query String Parameters

The following query string parameter options are available to the /systems resource:

Sorting

You can order the returned collection by name or by memory size using the sort_by option. See Sort By for an overview of the Sort By option.

Supported Sort By elements for the /systems resource are described below:

  • size

  • The size element is a representation of the following properties to sort by, in priority order:

    1. memory
    2. total_physical_cpus
    3. cores_per_cpu

    This implies that if two systems have the same total memory, the total_physical_cpus count is considered next in the sort logic; and if the physical CPU count is the same, the next property to consider for sorting is the cores_per_cpu count. By default, the returned sort_by=size collection is ordered in ascending (asc) order. Specify desc for descending order. For example:

    GET /systems/?sort_by=size,desc

    Systems with any "_Unknown_" values are sorted at the end of the collection independent of the specified sort order.

  • name

  • The returned collection is sorted by the system's name element in ascending alphabetical order. Specify desc for descending alphabetical order.

    If you specify the Paging option, the returned collection will be sorted by name in ascending order automatically. For example, the following two requests will return the same result (i.e. page two of the collection in ascending name order):

    GET /systems/?page=1

    GET /systems/?sort_by=name&page=1

Attributes On/Off Mode

By default, all the attributes with set values for each system in the collection are returned (which is the attributes_mode=On option). You can suppress the attributes of the returned collection by using the attributes_mode=Off option. For instance, if you want to return a collection of AWS systems without displaying their attributes, specify the following request: 

GET /systems/?platform=aws&attributes_mode=Off

When you filter by attribute in your request, the attributes_mode=Off is disabled and all the set attributes are returned regardless if you provide the attribute_mode=Off option. For instance, if you provide the following request, the set attributes for the returned collection are displayed:

GET /systems/?attribute_name_value=Department,Finance&attributes_mode=Off

Attribute Display Categories

By default, all the attributes with set values for each system in the collection are returned. You can choose to return only specific attribute categories of the requested collection by using the setdisplay_category option. For instance, if you want to return a collection of AWS systems, but only display Business and Transformation attributes with set values, specify the following request: 

GET /systems/?platform=aws&setdisplay_category=Business,Transformation

Element Filters

The /systems endpoint supports the following elements as filters for returning a subset of the collection:

These filters are also denoted by "F" in the Filter column of the Systems Response schema table. Refer to Filters for a complete description of the Filters feature.

Element filters denoted with * support multiple values input. You can provide a list of values, separated by a comma between values, to logically OR a list of possible values for an element. For example, the following request will return all systems from AWS, Azure, or GCP:

GET /systems/?platform=aws,azure,gcp

Refer to Filters for a description of the Multiple Values filtering.

System attributes filtering extends the standard multiple values filtering support (denoted by **) with multiple attribute name, ID, and value combinations. See Attribute Filters - Multiple Values Support for further details.

Note: When filtering with values which include spaces or "+", use URL encoding . See Filters for details on special character support.

Attribute Filters - Multiple Values Support

Systems attributes supports the following filtering features:

  • A single value for attribute_name_like element filter—A collection of systems is returned with attribute names containing the sub-string provided. You can use the '%' character to match zero or more characters. For example, the request below returns systems with attribute values set for attribute names containing the sub-string "east":

    GET /systems/?attribute_name_like=east

  • Multiple attribute IDs for element filter attribute_id—The list of provided attribute IDs are matched to the system's set attributes and results are logically OR'ed to produce the returned collection. For example, the request below returns systems with set values for attribute IDs attr_5, attr_6, or attr_7:

    GET /systems/?attribute_id=attr_5,attr_6,attr_7

  • Multiple attribute names for element filter attribute_name—The list of provided attribute names are matched to the system's set attributes and results are logically OR'ed to produce the returned collection. For example, the request below returns systems with set values for attribute names Department or Resource Group:

    GET /systems/?attribute_name=Department,Resource+Group

  • Multiple attribute ID-value criteria for the element filter attribute_id_value—Existing systems which match all of the provided attribute ID-value pairs (separated by semicolon) are returned. The format of this attribute ID-value criteria filter request is as follows:

    GET /systems/?attribute_id_value=<attr1_id,attr1_value;attr2_id,attr2_value;attr3_id,attr3_value,...>

    The results of matching attribute ID-value pairs are logically AND'ed to produce the returned collection. For example, the systems returned for the request below have

    • attr_Application = "General" AND

    • CLD.BUSINESS.UNIT = "Support" AND

    • attr_OperationalEnvironment = "Production"

    GET /systems/?attribute_id_value=attr_Application,General;CLD.BUSINESS.UNIT,Support;attr_OperationalEnvironment,Production

  • Multiple attribute name-value criteria for the element filter attribute_name_value—Existing systems which match all of the provided attribute name-value pairs (separated by semicolon) are returned. The format of this attribute name-value criteria filter request is below:

    GET /systems/?attribute_name_value=<attr1_name,attr1_value;attr2_name,attr2_value;attr3_name,attr3_value,...>

    The results of matching attribute name-value pairs are logically AND'ed to produce the returned collection. For example, the systems returned for the request below have "debian-8-jessie" as their License model AND "Disk-AB21" as their disk name:

    GET /systems/?attribute_name_value=License+model,debian-8-jessie;Disk+Name,Disk-AB21

Note: When you use attributes for filtering a collection, the attributes_mode=Off feature is disabled. See Attributes On/Off Mode for details.

Response

The following is a complete list of possible response elements that are returned for the /systems resource. If the response element does not apply to the system returned, then the element is not displayed in the results.

Table: Systems Response Schema

Element

Type

Mod

Filter/Sort

Description

id, name, href

strings

 

F by

  • id
  • name
  • name_like

S by name

See ID, Name and Self Reference (id, name, href).

To filter systems with names that contain a given input string, use ?name_like="<substring>" in your collection request. The '%' character can be used to match zero or more characters.

Example: Getting a Collection of Azure Systems with Name "*test*"

resource_id

strings

 

F

The unique system ID assigned by the cloud provider.

To search for a system with a particular cloud provider ID, use ?resource_id=<cloud_id> in your request.

Example: Getting Public Cloud Attributes for an Individual System

attributes

[id, name, value]

M

F by

  • attribute_name_like
  • attribute_id
  • attribute_name
  • attribute_id_value
  • attribute_name_value

System attributes are properties set by an audit from a vendor platform or by Densify for control analytics.

On a GET request, only those attributes that have values are returned. To hide the set attributes, use the attributes_mode=Off option. See Attributes On/Off Mode for details. To only return set attributes in specific categories, use the setdisplay_category option. See Attribute Display Categories for details.

To filter based on attributes, you must use one of the following element options — in each case, system data will be returned only if the attributes selected have values assigned to them:

  • attribute_name_like
  • attribute_id with a provided list of attribute IDs
  • attribute_name with a provided list of attribute names
  • attribute_id_value with a provided list of attribute ID-value pairs
  • attribute_name_value with a provided list of attribute name-value pairs

Refer to Attribute Filters - Multiple Values Support for a description of how to use these attribute filters.

Note that when you use attributes to filter the collection, the attributes_mode=Off feature is disabled.

Example: Getting a Collection of VMware Systems using Attribute Filters

Example: Getting Public Cloud Attributes for an Individual System

children

string

 

 

The number of other systems that are considered "children" of the current system.

For a host system (i.e. "type": "host"), this is the number of VMs the host system has (e.g. "children": "10"). For AWS ASGs (i.e. "type" : "asg"), this is the number of active EC2 instances that belong to the group. For other type of systems where this element does not apply, children is not returned.

This element is returned for host and ASG systems only when the details=true option is in the request URI. See Collection Details.

control_environment

[id, name, platform_category, href, icon]

 

F by

  • control_environment
  • platform_category

If the system is associated with a Control Environment, the environment details are returned:

  • id
  • name
  • platform_category
  • href
  • icon

To filter based on Control Environment, you must use one of the following elements:

  • control_environment—with a control environment name specified
  • platform_category—with a platform category specified (i.e. "External Cloud" or "Internal Virtual")

Example: Getting a Filtered Collection of Systems.

cores_per_cpu

string

 

Tertiary sort key for sort_by=size

Cores per CPU for computing systems.

cpu_benchmarks

[name, score_type, value]

 

 

The default CPU benchmark for applicable systems.

  • name—Label with possible values:
    • "CINT2000"
    • "CINT2000 Rate"
    • "CINT2006 Rate"
    • "RPE2"
  • score_type—Score type with possible values:
    • "cint2000"
    • "cint2000rate"
    • "cint2006rate"
    • "rpe2"
  • value

cpu_model

string

 

 

The CPU architecture model of the compute system.

cpu_speed

string

 

 

The normalized CPU speed (MHz) of the compute system.

entity_role_name

string

 

 

The entity role name that Densify assigns to the system (e.g. "VMWARE_VM") based on their platform and system role.

entity_type

string

 

 

The entity type that Densify assigns to the system (e.g. "VMware ESX Guest") based on their platform and system type.

hostId

string

 

 

An ID of the system provided from the data collection audit for the purpose of resolving duplication conflicts.

I/O_benchmarks

[name, score_type, value]

 

 

The list of all available I/O benchmarks.

  • name—Label with possible values:
    • "Maximum Disk Throughput (bytes/s)"
    • "Maximum Network Throughput (bytes/s)"
  • score_type—Score type with possible values:
    • "disk"
    • "net"
  • value—A value of -1 means there is no value specified.

infrastructure_group

[id, name, href]

 

F by infrastructure_group

If the system is associated with an Infrastructure Group (cluster), the group details are returned:

  • id
  • name
  • href

When filtering based on Infrastructure Group, you must use the element infrastructure_group with the group name specified.

Example: Getting a Filtered Collection of Systems.

ip_address

string

 

 

Primary IP address of the system.

mac_address

string

 

 

MAC address of the system provided by the data collection audit.

manufacturer

string

 

 

For host type systems, the manufacturer of the host is returned (e.g. "Dell", "IBM"). For cloud systems, the vendor platform is returned (e.g. "GCP") or "CONTAINERS" is returned for container type systems.

This element is returned only when the details=true option is in the request URI. See Collection Details.

memory

string

 

S by size

The normalized total memory (MB) for the system.

os

string

 

 

Operating System name of the host or VM instance.

This element is returned only when the details=true option is in the request URI. See Collection Details

os_patch_level

string

 

 

Operating System patch level of the host or VM instance.

os_version

string

 

 

Operating System version of the host or VM instance.

parent

string

 

 

Logical parent of the current system.

For a host system (i.e. "type": "HOST"), this does not apply (i.e. "parent": "N/A"). For a VM, this is the name of the parent host system (e.g. "parent": "esx-host-221").

platform

string

 

F

The platform of the system. Use this element to filter systems from the various supported platforms:

  • VMWARE—For systems in VMware
  • HMC—For systems in IBM Power
  • AWS—For systems in AWS
  • GCP—For systems in GCP
  • AZURE—For systems in Azure
  • CONTAINERS—For containers

For example, use platform=azure to return a collection of Azure cloud systems. See Example: Getting a Collection of Azure Systems with Name "*test*".

platform_model

string

 

 

For host systems, the host system model is returned. For cloud instance systems, the instance type is returned.

serial_number

string

 

 

The serial number of the system from the vendor.

size

hidden element

 

S by size

This element is used to sort a collection by size. See Sorting for details.

total_logical_cpus

string

 

 

The total number of logical CPUs for the system.

total_physical_cpus

string

 

Secondary sort key for sort_by=size

The total number of physical CPUs for the system.

threads_per_core

string

 

 

The threads per core for the system.

type

string

 

F

The type of system.

The supported types of systems for the /systems resource include:

  • host—For host systems in VMware, IBM PowerVM (via data collection for HMC 8 method), and AWS platforms.
  • guest—For guest systems in VMware platform.
  • vm—For instances in VMware, IBM PowerVM(via data collection for HMC 8 method), GCP (Compute Engine), and AWS (EC2, ECS) platforms.
  • arm_vm—For instances in the Azure platform.
  • classic_vm—For classic instances in the Azure platform.
  • rds—For RDS instances in the AWS platform.
  • asg—For Auto Scaling groups in the AWS platform.
  • Containers realized through data collection are supported by the /systems endpoint, but does not have the type element populated. You can filter Container systems via the platform=containers element filter.

Note: IBM Power systems returned by the /systems endpoint are the ones created in Densify from the HMC 8 data collection method. Refer to Data Collection for IBM PowerVM Systems for HMC 8 (Help Topic ID 220170) for details.

Examples

Example: Getting a Collection of Azure Systems with Name "*test*"

The following example shows you how to retrieve a collection of systems from the Azure cloud platform with a name containing "test".

Example: Getting a Collection of Sorted GCP Systems, Displaying One Page

This example shows you how to retrieve a collection of GCP systems, sorted by memory size in ascending order and only displaying the second page (note that page=0 is the first page).

Example: Getting a Filtered Collection of Systems

This example shows you how to retrieve a collection of systems filtered by platform and cluster.

Example: Getting a Collection of VMware Systems using Attribute Filters

This example shows you how to retrieve a collection of systems with platform "VMware" using attribute name-value pairs as filters.

Example: Getting an Individual Host System

This example shows you how to retrieve an individual host system by ID.

Example: Getting an Individual Guest System

This example shows you how to retrieve an individual guest system by name.

Example: Downloading an Impact Analysis and Recommendation Report

The following example shows you how to download a PDF version of the Impact Analysis and Recommendation Report for your public cloud (AWS, Azure, GCP) or private cloud (VMware, IBM PowerVM) instances. The report is available after the Densify analysis generates the right-sizing recommendations and rdb-populate has run to completion.

Note: HTTPS needs to be enabled to download the Impact Analysis and Recommendation Report PDF.

You need to save the file (Save Response) and then open it in a PDF reader.

Example: Modifying a System’s Attributes

The following example shows you how to modify system attributes.

Example: Deleting a System’s Attributes

The following example shows you how to delete a system's attr_3 attribute if it has value "0.3", and it removes attr_10 and attr_11 set values.

Example: Getting Public Cloud Attributes for an Individual System

The following example shows you how request information for a system based on the cloud provider's system ID (resource_id) and only show Public Cloud category attributes with set values.