NVIDIA UFM Enterprise REST API Guide v6.15.0
NVIDIA UFM Enterprise REST API Guide v6.15.0

UFM Dynamic Telemetry Instances REST API

The management of dynamic telemetry instances involves the facilitation of user requests for the creation of multiple telemetry instances. As part of this process, the UFM enables users to establish new UFM Telemetry instances according to their preferred counters and configurations. These instances are not initiated by the UFM but rather are monitored for their operational status through the use of the UFM Telemetry bring-up tool.

  • Description: Instantiates a new telemetry instance per the requested configuration in the request parameters

  • URL: POST https://10.209.36.126/ufmRestV2/app/telemetry/instances/cset_name

  • Request Data:

    Parameter

    Description

    requested_guids

    An array of objects, where each object specifies the node GUID and ports of the requested GUID

    guid

    A string specifying the unique identifier (node GUID) of the requested metrics

    ports

    An array of integers specifying the ports of the requested GUID.

    counters

    An array of strings specifying the names of the metrics counters to be retrieved – only supported counters can be sent (can be retrieved via the supported counters API).

    configuration

    An optional object specifying additional configuration parameters.

    sample_rate

    An integer specifying the rate at which the metrics are sampled.

    base_config

    An optional string specifying the base configuration to be used.

    ttl

    An optional string specifying the time-to-live (TTL) for the metrics data.

    is_registered_discovery

    An optional boolean value indicating whether the metrics are registered with the discovery service.

    is_async

    An optional boolean value. If this parameter is sent, the creation will become asynchronous, and a job_id will be returned. To get the status of this job, please refer to the Jobs API. We recommend using this parameter.

  • Response: Port number to communicate with the instantiated new instance.

  • Request Example:

    Copy
    Copied!
                

    Content-Type: application/json { "requested_guids": [     {       "guid": "xyz123",       "ports": [8080, 8081, 8082]     },     {       "guid": "abc456",       "ports": [9090]     }  ],  "counters": ["cpu", "memory"],  "configuration": {     "setting1": "value1",     "setting2": "value2"  },  "sample_rate": 5"base_config": "config1""ttl": "24h""is_registered_discovery": true  } The API will return a port that will be exposed by the UFM Telemetry. Get All Instances GET https://10.209.36.126/ufmRestV2/app/telemetry/instances Return list of all instances + configuration + ports {    "<cset_name>": {         "name": " <cset_name> ",         "requested_guids": [             {                 "guid": "248a0703008dae46",                 "ports": [                     1                 ]             }         ],         "counters": [             "PortXmitDataExtended",             "PortRcvDataExtended"         ],         "sample_rate": 20,         "ttl": "1h",         "base_config": "",         "endpoint_port": 9007,         "status": "",         "is_registered_discovery": true,         "root_dir": "/opt/ufm/files/dynamic_telemetry/ <cset_name> ",         "configuration": {             "num_iterations": "20000",             "plugin_env_CLX_EXPORT_API_SHOW_STATISTICS": 1,             "plugin_env_UFM_TELEMETRY_MANAGED_MODE": 1         },         "conf_file": "",         "hca": "mlx5_0",         "pid": 7837     }  }

Get Specific Instance Configuration

  • Description: Gets a specific instance configuration.

  • URL: GET https://10.209.36.126/ufmRestV2/app/telemetry/instances/cset_name

  • Request Data: N/A

  • Response Example:

    Copy
    Copied!
                

    { "pdr_dynamic": { "name": "pdr_dynamic", "requested_guids": [ { "guid": "248a0703008fa280", "ports": [ 1, 1, 1, 1 ] }, { "guid": "ec0d9a0300bf551c", "ports": [ 1 ] }, { "guid": "e8ebd3030064b7c6", "ports": [ 1, 1 ] }, { "guid": "043f720300b818a0", "ports": [ 39 ] }, { "guid": "7cfe900300d5ba54", "ports": [ 1, 1, 1 ] }, { "guid": "98039b03009fce76", "ports": [ 1 ] } ], "counters": [ "phy_raw_errors_lane0", "phy_raw_errors_lane1", "phy_raw_errors_lane2", "phy_raw_errors_lane3", "phy_effective_errors", "phy_symbol_errors", ], "sample_rate": 300, "ttl": "10000d", "base_config": "", "endpoint_port": 9007, "status": { "managed_mode": true, "start_time": 1683039674.951503, "num_ports": 29, "status": "running", "iteration_time_sec": 0.274126, "export_time_sec": 0.000279, "port_counters_time_sec": 0.010115, "ports_per_sec": 2867.029164607019, "timestamp": 1683093341.727322 }, "is_registered_discovery": true, "root_dir": "/opt/ufm/files/dynamic_telemetry/pdr_dynamic", "configuration": { "plugin_env_UFM_TELEMETRY_MANAGED_MODE": 1, "plugin_env_CLX_EXPORT_API_SHOW_STATISTICS": 1 }, "conf_file": "", "hca": "mlx5_0", "pid": 3662593 } }

  • Description: Modifies the run configuration of an active telemetry instance. Specifically, the user is permitted to alter a specific set of GUIDs and the sample rate in their request.

  • URL: PUT https://10.209.36.126/ufmRestV2/app/telemetry/instances/cset_name

  • Request Data:

    Copy
    Copied!
                

    Content-Type: application/json  { "requested_guids": [     {       "guid": "1234",       "ports": [5, 1]     },     {       "guid": "5678",       "ports": [8]     }  ],  "sample_rate": 5  }

  • Description: Returns the running status and statistics of the started instances

  • URL: GET https://10.209.36.126/ufmRestV2/app/telemetry/instances/status

  • Request Data: N/A

  • Response Example:

    Copy
    Copied!
                

    {     "dror": {         "managed_mode": true,         "start_time": 1681422289.418903,         "num_ports": 1,         "status": "running",         "iteration_time_sec": 0.026844,         "export_time_sec": 9.4e-5,         "port_counters_time_sec": 0.00068,         "ports_per_sec": 1470.5882352941176,         "timestamp": 1681422417.825401     }  }

Copy
Copied!
            

"requested_guids": [     {       "guid": "1234",       "ports": [5, 1]     },     {       "guid": "5678",       "ports": [8]     }  ],  "sample_rate": 5"ttl": “300d”, }

  • Request Data: N/A

  • Response Example: N/A

© Copyright 2023, NVIDIA. Last updated on Nov 15, 2023.