Skylight sensor: agents API Deprecation History

Deprecations

Continuous improvement to the Skylight sensor:agent product will involve occasional new API commands, changes and depreciation of certain APIs. Please refer to this article for a list of depreciations and some corresponding previous release information for further details and comparison.

Please utilize V3 APIs when available.

Skylight sensor: agents API changes 22.04 compared to 21.12:

GET /api/orchestrate/v3/agents/configuration/$AGENTID

Added:
session status reporting
api/orchestrate/v3/agents/sessionstatus/{sessionId}
Field added to report session status as human-readable string, example:

"statusMessage": "Unable to connect."

Skylight sensor: agents API changes 21.12 compared to 21.06:

GET /api/orchestrate/v3/agents/configuration/$AGENTID

Deprecated:
throughput: the agent configuration is stripped of throughput configuration. Throughput is now configured seperately as a session, like all agent tests in 21.12.

Changed:
reflectors (actuate) behaviour: reflectors are no longer enabled per default. In 21.12 they can be enabled in the agent config.

Skylight agent configuration API 21.06 for comparison:

{
  "data": {
    "type": "agentConfigs",
    "attributes": {
      "agentId": "b80fc6e1-43d5-fake-a1de-0b8049da0474",
      "dataGateway": {
        "port": 55888,
        "server": "10.1.2.3"
      },
      "identification": {
        "agentName": "se-tcp-agent"
      },
      "throughput": {
        "networkBottleneckBandwidthBitsPerSec": 1000000000,
        "networkMtuBytes": 1500,
        "networkRttMs": 0.3,
        "testParallel": 1,
        "testRepeat": false,
        "testReverse": false,
        "testServerAddress": "10.1.1.20",
        "testServerPort": 26000,
        "testTracerouteDestPort": 26000
      }
    }
  }
}

Skylight agent configuration API 21.12:

{
  "data": {
    "type": "agentConfigs"
    "attributes": {
      "agentId": "8a682d28-1f96-fake-a78c-1f2c56798b75",
      "dataGateway": {
        "port": 55888,
        "server": "10.1.2.3"
      },
      "identification": {
        "agentName": "se-actuate-agent"
      },
      "metadata": {
        "LOCATION": "Sthlm"
      },
      "reflector": {
        "reflectors": [
          {
            "enable": true,
            "reflectorType": "twampIpv4"
          }
        ]
      }
    }
  }
}

Agent Status:

GET /api/orchestrate/v3/agents/{{AGENTID}}

New:

agentConfigRevision: a revision is auto-incremented when any configuration related to the agent is changed. It is also incremented if an agent session is altered or if the agentConfig is updated.

agentConfigRevisionAck: the revision that is ack'ed by connected agent.

Clarification:

state: indicates if an agent is connected or unconnected to orchestrator via the roadrunner connector.
status: configured or unconfigured: indicates if there is an existing configuration for the agent. An agent may be connected before it is configured.

Agent status:

{
    "data": {
        "attributes": {
            "_rev": "4369-5566dbdbe03eea853d408b5250e46607",
            "agentConfigRevision": "8c89293e-248e-4d55-9889-8974d9297925",
            "agentConfigRevisionAck": "8c89293e-248e-4d55-9889-8974d9297925",
            "agentName": "labAgentName",
            "metadata": {
                "DESC": "test actuate agent",
                "LOCATION": "Sthlm"
            },
            "state": "connected",
            "status": "configured",
            "type": "actuate",
            "version": "dev_skylight-agent-actuate-amd64_66.66.66_3"
        },
        "id": "8a682d28-1f96-fake-a78c-1f2c56798b75",
        "type": "agents"
    }
}

New: session configuration

New:

All agent tests are now sessions and configured in a session structure that has some attributes that are common to all session types and a section that is specific for the sessionType.

Agent actuate

Session common attributes:

sessionName: unique name
sessionId: uuid that is generated if not provided in POST
sessionType: supported session types tcp-throughput, twamp-stateful, twamp-stateless, echo-udp, echo-icmp, path-trace
enable: true if session is to run on agent, false if just provisioned in the orchestration
period: once runs a finite duration test, continuous runs the test continuously (e.g. TWAMP) and repeat repeats the finite duration test indefinitely.

Changed:
Twamp was the only test configured as a session in 21.06. This has been changed to the common session configuration model.

21.06 Deprecated twamp session configuration:

{
  "data": {
    "type": "agentSessions",
    "attributes": {
      "agentId": "string",
      "twamp": {
        "sessionId": "f422344c-1b97-fake-8073-773fc592e9e2",
        "sessionName": "myTwampSession",
        "senderAddr": "8.8.8.8",
        "senderPort": 15000,
        "senderPlsize": 82,
        "senderRate": 10,
        "senderDscp": 32,
        "senderTtl": 255,
        "senderVprio": 0,
        "reflectorAddr": "8.8.8.8",
        "reflectorPort": 862,
        "reflectorMode": "stateful",
        "reportInterval": 30,
        "controlAddr": "8.8.8.8",
        "controlPort": 862,
        "controlDscp": 0,
        "controlVprio": 0,
        "controlLegacy": false
      }
    }
  }
}

21.12 twamp configuration new common session configuration model

The specific “twamp” structure has the following changes:

Moved to common level:
sessionName, sessionId.

Deprecated:
reflectorMode This now instead given by the sessionType: twamp-stateless or twamp-stateful.

Renamed:
senderPlsize renamed to senderPayloadSize.

21.12 Full actuate session configuration with optional attributes included:

{
  "data": {
    "type": "agentSessions",
    "attributes": {
      "agentId": "string",
      "session": {
        "sessionName": "myTwampSession",
        "sessionId": "f422344c-1b97-fake-8073-773fc592e9e2",
        "sessionType": "twamp-stateful",
        "enable": true,
        "period": "continuous",
        "twamp": {
          "senderAddr": "8.8.8.8",
          "senderPort": 15000,
          "senderPayloadSize": 82,
          "senderRate": 10,
          "senderDscp": 32,
          "senderTtl": 255,
          "senderVprio": 0,
          "reflectorAddr": "8.8.8.8",
          "reflectorPort": 862,
          "reportInterval": 30,
          "controlAddr": "8.8.8.8",
          "controlPort": 862,
          "controlDscp": 0,
          "controlVprio": 0,
          "controlLegacy": false
        }
      }
    }
  }
}

21.12 Minimum actuate session configuration with only mandatory attributes included:

{
  "data": {
    "type": "agentSessions",
    "attributes": {
      "agentId": "string",
      "session": {
        "sessionName": "myTwampSession",
        "sessionId": "f422344c-1b97-fake-8073-773fc592e9e2",
        "sessionType": "twamp-stateful",
        "enable": true,
        "period": "continuous",
        "twamp": {
          "reflectorAddr": "8.8.8.8",
          "reflectorPort": 862,
        }
      }
    }
  }
}

21.12 new: echo session

Optional attributes omitted:

{
  "data": {
    "type": "agentSessions",
    "attributes": {
      "agentId": "8a682d28-1f96-11ec-a78c-1f2c56798b75",
      "session": {
        "sessionName": "myEcho",
        "sessionType": "echo-udp",
        "period": "continuous",
        "enable": true,
        "echo": {
          "reflectorAddr": "139.59.13.191",
          "reflectorPort": 862
        }
      }
    }
  }
}

21.12 new: trace session

Optional attributes omitted:

{
  "data": {
    "type": "agentSessions",
    "attributes": {
      "agentId": "8a682d28-1f96-11ec-a78c-1f2c56798b75",
      "session": {
        "sessionName": "trace-10",
        "sessionType": "path-trace",
        "enable": false,
        "period": "once",
        "trace": {
          "destination": "10.1.1.12",
          "algorithm": "paris-traceroute",
          "type": "udp"
        }
      }
    }
  }
}

Agent throughput

21.06 Deprecated throughput configuration in agent config:

{
  "data": {
    "type": "agentConfigs",
    "attributes": {
      "agentId": "string",
      "throughput": {
        "testServerAddress": "13.0.0.9",
        "testServerPort": 5201,
        "testReverse": false,
        "testDurationSecs": 60,
        "testReportIntervalSecs": 1.5,
        "testParallel": 1,
        "testRepeat": false,
        "testDscp": 0,
        "testTracerouteDestPort": 33434,
        "networkMaxRateBitsPerSec": 180,
        "networkMtuBytes": 1500,
        "networkBottleneckBandwidthBitsPerSec": 161,
        "networkRttMs": 0.44
      }
    }
  }
}  

21.12 throughput configuration new common session configuration model

Changed
The specific throughput structure has changed.

deprecated:
testRepeat Replaced by period in the common part.

Full throughput configuration with all optional attributes included:

{
  "data": {
    "type": "agentSessions",
    "id": "string",
    "attributes": {
      "agentId": "string",
      "session": {
        "sessionName": "myThroughput",
        "sessionId": "f422344c-1b97-fake-8073-773fc592e9e2",
        "sessionType": "tcp-throughput",
        "enable": true,
        "period": "once",
        "throughput": {
          "testServerAddress": "13.0.0.9",
          "testServerPort": 5201,
          "testReverse": false,
          "testDurationSecs": 60,
          "testReportIntervalSecs": 1.5,
          "testParallel": 1,
          "testDscp": 0,
          "testTracerouteDestPort": 33434,
          "networkMaxRateBitsPerSec": 280000000,
          "networkMtuBytes": 1500,
          "networkBottleneckBandwidthBitsPerSec": 250000000,
          "networkRttMs": 0.44
        }
      }
    }
  }
}

Minimum throughput configuration with only mandatory attributes included:

{
  "data": {
    "type": "agentSessions",
    "id": "string",
    "attributes": {
      "agentId": "string",
      "session": {
        "sessionName": "myThroughput",
        "sessionId": "f422344c-1b97-fake-8073-773fc592e9e2",
        "sessionType": "tcp-throughput",
        "enable": true,
        "period": "once",
        "throughput": {
          "testServerAddress": "13.0.0.9",
          "testServerPort": 5201
        }
      }
    }
  }
}

21.12 Test start command

POST /api/orchestrate/v3/agents/$AGENTID/command

Deprecated:

run Only commands start and stop remain in 21.12.
requestId Not used.
id Not used, attribute previously required to be the AGENTID.

New:
overrides
populateFields required for tcp-throughput baseline start command. The results from the baseline will be populated to the session configuration. In 21.06 the baseline results where not stored.

21.12 baseline start command

{
  "data": {
    "type": "agentCommands",
    "attributes": {
      "command": "start",
      "args": [
        {
          "sessionId": "b46fa5d1-6c06-fake-8020-fcc810118ae8",
          "type": "baseline",
          "populateFields": [
            "networkBottleneckBandwidthBitsPerSec",
            "networkRttMs",
            "networkMtuBytes"
          ]
        }
      ]
    }
  }
}

new: overrides are supported for tcp-throughput test enabling users to optionally override configured or baselined attributes when starting a throughput test.

21.12 throughput test start

{
  "data": {
    "type": "agentCommands",
    "attributes": {
      "command": "start",
      "args": [
        {
          "sessionId": "b46fa5d1-6c06-fake-8020-fcc810118ae8",
          "type": "throughput",
          "overrides": {
            "sessionType": "tcp-throughput",
            "throughput": {
              "networkBottleneckBandwidthBitsPerSec": 55555,
              "networkMtuBytes": 9000,
              "networkRttMs": 0.555
            }
          }
        }
      ]
    }
  }
}

Session status:

GET /api/orchestrate/v3/agents/sessionstatus/$SESSIONID

New:
captureTime time when status generated.
statusMessage status description specific to the session type.

TWAMP session status:

{
    "data": {
        "attributes": {
            "captureTime": "2021-11-24T00:05:28Z",
            "sessionId": "62fe0f79-3021-fake-9d69-607efb0a156a",
            "status": "running",
            "statusMessage": "TxPkts 595, RxPkts 594, UlinkLost 0, DlinkLost 0"
        },
        "type": "sessionStatuses"
    }
}

API Documentation Portal

For the latest available Skylight sensor: agent API documentation, please visit: Sensor agents: API documentation

All API functions are documented in the AgentServiceV3 section of the Sensor Orchestrator API.