Agent: actuate - Configuration

This article provides the configuration basics for Sensor agent: actuate.

Overview

Skylight sensor: agent actuate implements support for these performance monitoring sessions:

• RFC5357 Two-way active measurement protocol.
• RFC862 UDP Echo
• RFC792 ICMP Echo

Monitored metrics include methods to assess network one-way and two-way latency (delay), jitter, delay variation, packet loss and several QoS metrics.

The IETF RFC5357 defines a standard mode, here called TWAMP-control and a simplified mode, here called TWAMP-light. Skylight sensor: agent supports TWAMP-light and TWAMP-control in unauthenticated and unencrypted mode.

For example, if you run a server with IP address 10.11.12.13 and start up an actuate container with docker on this host, the docker may get IP address 172.1.2.3 inside the container. To successfully use TWAMP-control from this agent, set the TWAMP control sender IP address parameter to "10.11.12.13".

A different solution is to launch the actuate container in host networking mode, and declare the host interface with the AGENTSOURCEINTERFACE= environment variable.

Agent Actuate Configuration

This section assumes that an actuate agent has already been defined, deployed and registered in the orchestration system through the APIs. See Agent installation guidelines if this has not yet been done.

Configuration Parameters on Agent Level

Each actuate agent holds a number of configuration parameters that relate to the agent itself, and not the monitoring sessions it performs. These configuration parameters do not normally change during the lifetime of an agent, but are static settings like agent name, its unique agentId, which RoadRunner gateway it uses for metrics streaming, and any other agent-wide configuration parameters.

The set of agent level parameters for actuate are:
agentId
This is a UUID string uniquely identifying this agent.

dataGateway
This is a set of two parameters defining the FQDN or IP address of the roadrunner through which the agent will send result data metrics.
Note that this could be a different roadrunner instance than the one used for management, however normally this should be the same roadrunner IP/FQDN, where management uses port 55777/tcp and data metrics streaming using port 55888/tcp.

identification
Under the identification node, the agentName is set, and in the future more details like location, geo-coordinates, etc. will be supported.

reflector
Under the reflector node, there is a list of enable/disable parameters for the TWAMP and UDP echo reflectors for IPv4 and IPv6.

Below is an example showing the GET and response for configuration of agent with ID 0a805c6e-6266-fake-a8e4-afb94a124cd2

GET https://my.tenant.io/api/orchestrate/v3/agents/configuration/0a805c6e-6266-fake-a8e4-afb94a124cd2

RESPONSE
{
    "data": {
        "attributes": {
            "_rev": "1-44ab571a7f7a5f300f94bf82d1bed065",
            "agentId": "0a805c6e-6266-fake-a8e4-afb94a124cd2",
            "dataGateway": {
                "port": 55888,
                "server": "192.168.0.222"
            },
            "identification": {
                "agentName": "my-cool-twamp-agent"
            },
            "reflector": {
                "reflectors": [
                    {
                        "reflectorType": "twampIpv4",
                        "enable": true
                    }
                ]
            }
        },
        "id": "0a805c6e-6266-fake-a8e4-afb94a124cd2",
        "type": "agentConfigs"
    }
}

As seen above, the agent configuration contains a revision field _rev in the beginning that is used for configuration consistency. To update an agent's 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.

Changing Parameters on Agent Level

The API describes the PUT for changes on an agent's configuration here: API Update agent configuration

Below is an example changing the agent name, and disabling the IPv4 TWAMP reflector on agent with agentId=0a805c6e-6266-fake-a8e4-afb94a124cd2

Remember to first do a GET for the agent configuration to fetch the current _rev revision value and use that in the PUT query to update the configuration.

PUT
{
    "data": {
        "type": "agentConfigs",
        "attributes": {
            "_rev": "1-44ab571a7f7a5f300f94bf82d1bed065",
            "agentId": "0a805c6e-6266-43a4-a8e4-afb94a124cd2",
            "identification": {
                "agentName": "my-even-cooler-agent"
            },
            "reflector": {
                "reflectors": [
                    {
                        "reflectorType": "twampIpv4",
                        "enable": false
                    }
                ]
            }
        }
    }
}

Actuate Agent Session Configuration

Session section in the API

The following parameters are configurable for an actuate session.

Add / delete throughput sessions to an agent

The orchestration can multiple session configurations for each agent, in release 23.12 the recommendation is to not run more than 500 simultaneously to stay within the reference CPU&RAM values. To add and delete sessions, use the POST and DELETE API calls

To add a session -

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

With the configuration in the BODY.

The example below is for TWAMP-light, providing only the minimum required session configuration parameters

{
  "data": {
    "type": "agentSessions",
    "attributes": {
      "agentId": "{{agentId}}",
      "session": {
        "sessionId": "{{sessionId}}",
        "sessionName": "my TWAMP session example 😀",
        "sessionType": "twamp-stateful",
        "enable": true,
        "period": "continuous",
        "twamp": {
            "reflectorAddr": "192.168.12.254",
            "reflectorPort": 50862
        }
      }
    }
  }
}

Related Documentation and References

throughput - test configuration
Agent: trace- Configuration
Agent: transfer - Configuration