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:
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 willreturna port that will be exposed by the UFM Telemetry. Get All Instances GET https://10.209.36.126/ufmRestV2/app/telemetry/instancesReturn 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:
{
"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:
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:
{
"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} }
Description: Pauses a running instance (with an option to rerun it with the same configuration).
URL: PUT https://10.209.36.126/ufmRestV2/app/telemetry/instances/pause/cset_name
Request Data: N/A
Response Example: N/A
Description: Continues running a stopped instance
URL: PUT https://10.209.36.126/ufmRestV2/app/telemetry/instances/continue/cset_name
{
"requested_guids": [
{
"guid": "1234",
"ports": [5, 1]
},
{
"guid": "5678",
"ports": [8]
}
],
"sample_rate": 5,
"ttl": “300d”,
}
Request Data: N/A
Response Example: N/A
Description: Returns a list of all the supported counters.
URL: GET https://10.209.36.126/ufmRestV2/app/telemetry/instances/counters
Request Data: N/A
Response Example:
[
"ob_amp_lane3","link_width_active", ...,"alev_plus_bfm2_lane0","pre_tap_lane0"]
Description: Deletes a running telemetry instance and returns a job_id to track the deletion process.
URL: DELETE https://10.209.36.126/ufmRestV2/app/telemetry/instances/cset_name
Request Data: N/A
Response Example:
job_id to track the deletion process