Agent: throughput - Configuration

This article provides configuration basics for Skylight sensor agent: throughput.

See https://docs.accedian.io/docs/skylight-roadrunner for information on how to use Analytics UI to create a new roadrunner configuration for agents.

Overview

Skylight sensor: agent throughput implements support for the RFC6349 framework for TCP througput measurements.

This includes methods to assess network round-trip-time (RTT), path maximum transmission unit (MTU) discovery and bottleneck bandwidth (BB) detection as well as bulk TCP transfer bandwidth using configurable number of concurrent TCP streams.

The IETF RFC6349 outlines a method divided into two phases:

1. Baseline phase - Initial RTT, MTU and BB discovery. This should be done on an "empty" network, ideally at day 0 of service commissioning, and could be done with a tool separate from the actual TCP throughput measurement.
2. Throughput test phase - Time-boxed TCP transfer in one direction using one or more parallel TCP streams.

A user of RFC6349 testing should thus typically perform 1) only once - to get the "known good" or best possible datapoint for RTT, MTU and BB. Then 2) would be performed at-will, or scheduled, whenever the TCP throughput quality should be assessed.

The report from an RFC6349 TCP test uses the throughput results in conjunction with the baseline test data points to craft three metrics that can be used to compare test runs:

• RTT increase %
• TCP efficiency %
• TCP transfer time ratio

A common situation is that the baseline cannot be assessed properly through testing, simply because the network path is already in use or due to other limiting factors such as lack of resources to properly probe for BB. In these cases the RFC6349 stipulates that the values for RTT, MTU and BB can be provided as pre-set parameters to the throughput test phase.

Accedian RFC6349

The sensor: agent throughput supports both the baseline test phase and the throughput test phase. These are run individually, and it is up to the API user or automation system to trigger the tests. The results from a baseline test (Bottleneck Bandwidth, Maximum Transmit Unit and Round Trip Time) are automatically added to the throughput test session in the orchestration.

Testing Topology

To simplify operation, Accedian's throughput agent is compatible with the common open source tool iperf3. This means that the "far end" of a test path can be configured with just an iperf3 running in server mode.

$ apt-get install -y iperf3
$ iperf3 -p 24000 -s --daemon

Agent Configuration

The query example below shows the GET and response for session configuration of a throughput agent. Three throughput tests are defined in this example.

GET https://{{tenant-server}}/api/orchestrate/v3/agents/sessions/{{agentId}}

RESPONSE
{
    "data": [
        {
            "attributes": {
                "_rev": "7-5467beae8648dc8ff4e8a574894f0025",
                "agentId": "f422344c-1b97-fake-8073-77example9e2",
                "session": {
                    "enable": false,
                    "period": "once",
                    "sessionId": "230d2cbe-234e-4cbb-a9fa-780aefcebcc1",
                    "sessionName": "Jio-demo TCP",
                    "sessionType": "tcp-throughput",
                    "throughput": {
                        "networkBottleneckBandwidthBitsPerSec": 941200000,
                        "networkMaxRateBitsPerSec": 1000000000,
                        "networkMtuBytes": 1500,
                        "networkRttMs": 5.867,
                        "testDurationSecs": 60,
                        "testReverse": false,
                        "testServerAddress": "192.168.0.5",
                        "testServerPort": 12345
                    }
                }
            },
            "id": "f422344c-1b97-fake-8073-77example9e2_230d2cbe-234e-4cbb-a9fa-780aefakecc1",
            "type": "agentSessions"
        },
        {
            "attributes": {
                "_rev": "19-14240d0083d13558347e65e15b4513fd",
                "agentId": "f422344c-1b97-fake-8073-77example9e2",
                "session": {
                    "enable": false,
                    "period": "once",
                    "sessionId": "30e6e65d-6b2b-473d-8ae9-fbf91d81faeb",
                    "sessionName": "towards-aws-se",
                    "sessionType": "tcp-throughput",
                    "throughput": {
                        "networkBottleneckBandwidthBitsPerSec": 250000000,
                        "networkMaxRateBitsPerSec": 250000000,
                        "networkMtuBytes": 1500,
                        "networkRttMs": 2.32,
                        "testDurationSecs": 60,
                        "testReverse": false,
                        "testServerAddress": "16.171.15.75",
                        "testServerPort": 24000,
                        "testTracerouteDestPort": 24000
                    }
                }
            },
            "id": "f422344c-1b97-fake-8073-77example9e2_30e6e65d-6b2b-473d-8ae9-fbf91d81faeb",
            "type": "agentSessions"
        },
        {
            "attributes": {
                "_rev": "39-10e40b4847bd91d617bb19bc19b6274f",
                "agentId": "f422344c-1b97-fake-8073-77example9e2",
                "session": {
                    "enable": false,
                    "period": "once",
                    "sessionId": "a4e717af-ba3b-4c21-aa94-ef9ec8238d0c",
                    "sessionName": "TCP-service-5",
                    "sessionType": "tcp-throughput",
                    "throughput": {
                        "networkBottleneckBandwidthBitsPerSec": 941200000,
                        "networkMaxRateBitsPerSec": 1000000000,
                        "networkMtuBytes": 1500,
                        "networkRttMs": 5.109,
                        "testDurationSecs": 60,
                        "testReverse": false,
                        "testServerAddress": "192.168.0.5",
                        "testServerPort": 12345
                    }
                }
            },
            "id": "f422344c-1b97-fake-8073-77example9e2_a4e717af-ba3b-4c21-aa94-ef9ec8238d0c",
            "type": "agentSessions"
        }
    ]
}

As seen above, the agent session configuration object contains a revision field _rev that is used for configuration consistency. To update an agent's session configuration, the _rev string sent in the update query needs to match what the _rev is currently set to. That is, to update an agent's configuration, you should first GET the configuration to find the current _rev string. Then, use that string in the PUT query to apply the changes.

Add / Delete Throughput Sessions to an agent

The orchestration can store thousands of test configurations for each agent, but only one test can be actively running at any point in time. To add and delete test configurations, use the POST and DELETE API calls

To add a TCP throughput session -

POST to {{tenant-server}}/api/orchestrate/v3/agents/session

With the configuration in the BODY

{
  "data": {
    "type": "agentSessions",
    "attributes": {
      "agentId": "{{agentId}}",
      "session": {
        "sessionId": "{{sessionId}}",
        "sessionName": "my TCP throughput session example 😀",
        "sessionType": "tcp-throughput",
        "enable": false,
        "period": "continuous",
        "throughput": {
          "networkMaxRateBitsPerSec": 1000000000,
          "testDurationSecs": 60,
          "testReverse": false,
          "testServerAddress": "192.168.0.5",
          "testServerPort": 12345
          }
        }
      }
    }
}

The configuration above is enough to be able to run the baseline test phase. A successful baseline test will update this sessions configuration with the gathered values for networkBottleneckBandwidthBitsPerSec (BB), networkMtuBytes (MTU) and networkRttMs (RTT)

To remove a TCP throughput session -

DELETE on {{tenant-server}}/api/orchestrate/v3/agents/session/{{sessionId}}

Throughput Agent Test Configuration Fields

Session Section

The parameters available for throughput test configuration are:

• testServerAddress - IP address or FQDN of remote iPerf3 server
• testServerPort - TCP port used for communication with the iPerf3 server
• testReverse - determines direction of test true|false, default false which means test in direction server to agent ("download")
• testDurationSecs - desired length of the test in seconds
• testReportIntervalSecs - reporting interval during test in seconds, default 1
• testParallel - number of parallel TCP streams to use, default 1
• testRepeat - true|false, enables endless test mode
• testDscp - diffserv code point to use for test traffic
• testTracerouteDestPort - port to use for initial RTT test using traceroute UDP, default 33434
• networkMaxRateBitsPerSec - sets max bitrate for throughput test (10000000000 = 10Gbps)

The three parameters below are normally auto-populated by performing a baseline test, but can be provided as static values if a baseline test is failing to detect any of the three parameters due to network restrictions like firewalls.

• networkMtuBytes - define MTU to use for throughput test
• networkBottleneckBandwidthBitsPerSec - defines target bitrate for throughput test (1000000 = 1Mbps)
• networkRttMs - defines expected RTT for RFC6349 delay increase calculation.

Running a Baseline Test

To start a baseline test, POST the "start" command with option "baseline" to the API on:

https://my.tenant.io/api/orchestrate/v3/agents/{agentId}/command

Example content:

{
  "data": {
    "type": "agentCommands",
    "attributes": {
      "command": "start",
      "args": [
      {
        "type": "baseline",
        "sessionId": "f422344c-1b97-fake-8073-77example9e2",
        "populateFields": [
           "networkMtuBytes", "networkBottleneckBandwidthBitsPerSec", "networkRttMs"
           ]
         }
       ]
     }
   }
 }

The populateFields section indicate which parameters should be auto-populated after the baseline test finishes.

Running a Throughput Test

To start a throughput test, POST the "start" command with option "throughput" to the API on:

https://my.tenant.io/api/orchestrate/v3/agents/{agentId}/command

Example content:

{
  "data": {
    "type": "agentCommands",
    "attributes": {
      "command": "start",
      "args": [
        {
          "type": "throughput",
          "sessionId": "f422344c-1b97-fake-8073-77example9e2",
          "overrides": {
            "sessionType": "tcp-throughput",
            "throughput": {
              "testReverse": true,
              "testDurationSecs": 120,
            }
          }
        }
      ]
    }
  }
}

The run command for the throughput phase allows overriding any of the stored throughput test session parameters, in the example above the testReverse and testDurationSecs parameters are temporarily provided new values for this test run. This is useful when crafting an end-user throughput test button in a self-service portal, and the network operator wants to be in control of the main test definition, but want the user to be able to set their own values for test duration or perhaps max bandwidth.

Once started, the test will report throughput, RTT and window size data (by default) every second to Skylight analytics. After the test finishes, a final RFC6349-type report gets calculated and sent to Analytics.

Related Documentation and References

Agent: actuate - Configuration
Agent: transfer - Configuration
Agent: trace- Configuration