Agent: trace- Configuration

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

Overview and testing topology

Skylight sensor: agent trace implements a path trace (traceroute) client for testing reachability and layer-3-path from the test agent towards a service or destination.

Each agent supports up to 100 test destinations (referred to as sessions) defined, where each session is executed in a sequence once the agent is told to run. This means that there is no built-in scheduler for repeating the trace tests, this has to be triggered from an external system through the agent control API.

Below is a picture showing a sample trace test from an agent towards a URI (service.example.com)

In the example above, the path from the test agent towards the target traverse six hops before reaching the service.example.com destination. A trace test is unidirectional as indicated by the arrows, the path in the reverse direction may be a completely different one, to probe the path in both directions require performing the trace test from both ends.

Agent Configuration

The query example below shows the GET and response for session configuration of a trace agent. Two trace sessions are defined in this example, one using udp packets and one using icmp packets to probe the path.

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

{
            "attributes": {
                "_rev": "8-24764f562b312346c00c55bbf35a650",
                "agentId": "2522b9ee-0035-fake-bdd4-exampleba31f",
                "session": {
                    "enable": false,
                    "sessionId": "4af15733-0018-fake-8f67-examplec458",
                    "sessionName": "trace-accedian.com",
                    "sessionType": "path-trace",
                    "trace": {
                        "algorithm": "paris-traceroute",
                        "destination": "accedian.com",
                        "destinationPort": 33434,
                        "ipVersion": "IPv4",
                        "probesPerHop": 1,
                        "probingRate": 10,
                        "senderDscp": 0,
                        "senderTtlMax": 30,
                        "senderTtlMin": 1,
                        "type": "udp"
                    }
                }
            },
            "id": "2522b9ee-0035-fake-bdd4-exampleba31f_4af15733-0018-fake-8f67-examplec458",
            "type": "agentSessions"
        }
        {
            "attributes": {
                "_rev": "8-24764f562b312346c00c55b555a650",
                "agentId": "2522b9ee-0035-fake-bdd5-exampleba31f",
                "session": {
                    "enable": false,
                    "sessionId": "4af15733-0015-fake-8f67-examplec458",
                    "sessionName": "trace-service.example.com",
                    "sessionType": "path-trace",
                    "trace": {
                        "algorithm": "paris-traceroute",
                        "destination": "service.example.com",
                        "destinationPort": 33434,
                        "ipVersion": "IPv4",
                        "probesPerHop": 1,
                        "probingRate": 10,
                        "senderDscp": 0,
                        "senderTtlMax": 30,
                        "senderTtlMin": 1,
                        "type": "icmp"
                    }
                }
            },
            "id": "2522b9ee-0035-fake-bdd5-exampleba31f_4af15733-0015-fake-8f67-examplec458",
            "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 trace sessions to an agent

The orchestration can store up to 100 test sessions for each agent, where each will be executed in sequence. To add and delete test configurations, use the POST and DELETE API calls

To add a trace 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 new trace session to www.google.com 😀",
        "sessionType": "path-trace",
        "enable": true,
        "trace": {
            "algorithm": "paris-traceroute",
            "destination": "service.example.com",
            "destinationPort": 33434,
            "ipVersion": "IPv4",
            "probesPerHop": 1,
            "probingRate": 10,
            "senderDscp": 0,
            "senderTtlMax": 30,
            "senderTtlMin": 1,
            "type": "icmp"
        }
      }
    }
}

To remove a trace session -

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

Start trace sessions

To tell the trace agent to perform a trace, use the command node on the agent to POST the start command

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

With the command in the BODY

{
"data":
  {
    "type":"agentCommands",
    "attributes":
      {
        "command":"start",
        "args":
          [
            {
              "sessionId":"4af15733-0018-fake-8f67-examplec458"
            }
          ]
        }
      }
    }

The "args" section can contain a list of several trace sessionIds that will be scheduled to execute sequentially

Trace Agent Test Configuration Fields

Session Section

The parameters available for transfer session configuration are:

destination
required, tells the agent where to send its probes towards. Accepted values include; IPv4 address, IPv6 address or FQDN

destinationPort
optional integer [ 1 .. 65535 ], default is 33457. Note that for icmp probes this field is not used.

senderPort
optional integer [ 1 .. 65535 ], default is 33456. Note that for icmp probes this field is not used.

ipVersion
optional string. Accepted values are "IPv4" or "IPv6". This is useful if the DNS server provides both an IPv4 and IPv6 address when looking up the destination FQDN, and you want to explicly test the IPv4 or IPv6 path

algorithm
optional string for future use. Accepted value is "paris-traceroute" which is the only algorithm currently supported.

type
optional string. Default value "udp". Accepted values are "udp", "icmp" or "tcp". Determines what type of packets the agent shall use to probe the path.

probingRate
optional integer [ 1 .. 99 ] . Default value 10. Sets the probing rate in packets per second.

senderTtlMin
optional integer [ 1 .. 255 ]. Default value 1. Determines the starting TTL, raising this to 5 causes result to skip detecting the first 5 hops.

senderTtlMax
optional integer [ 1 .. 255 ]. Default value 30. Sets the max number of probed hops.

senderDscp
optional integer [ 0 .. 63 ]. Default value 0. DSCP value used for outgoing probes.

probesPerHop
optional integer [ 1 .. 255 ]. Default value 3. Number of times each hop is tested.

maxUndiscovered
optional integer [ 1 .. 255 ]. Default value 3. Terminates the test if this number of unresponsie hops have been detected.

waitSec
optional integer [ 1 .. 60 ]. Default value 5. Timeout, in seconds, to wait for responses for each hop.

testDurationSec
optional integer [ 1 .. 900 ]. Default value 180. Timeout limit for complete test execution.

Related Documentation and References

Agent: actuate - Configuration
Agent: throughput - Configuration
Agent: transfer - Configuration

Agent API documentation: https://api.analytics.accedian.io/agent-orchestration.html