RTT Configuration Details

Use a REST client to issue REST POST requests to create, delete, or update tests.
capm360
Use a REST client to issue REST POST requests to create, delete, or update tests.
 
Endpoints
 
http://DA_host:8581/rest/rttProfiles/
TestType
 
 
The following example shows the basic structure of the POST REST request:
<
RTT_Profile
version="1.0.0">
<Item version="1.0.0">
<Name>...</Name>
</Item>
<AttrGroupList>
<AttrGroup>
<ActionType>...</ActionType>
<TestHost>...</TestHost>
<IPDomainID>...</IPDomainID>
<OptionalAttribute0>...</OptionalAttribute0>
<OptionalAttribute1>...</OptionalAttribute1>
</AttrGroup>
</AttrGroupList>
</
RTT_Profile
>
 
RTT_Profile
 specifies the test type and determines which attributes are required and optional. Use one of the following values:
  • DNSRoundTripTestProfile
  • IcmpEchoRoundTripTestProfile
  • IcmpPathEchoRoundTripTestProfile
  • ICMPJitterRoundTripTestProfile
  • HTTPRoundTripTestProfile
  • TCPRoundTripTestProfile
  • JitterRoundTripTestProfile
Action Types
The following table provides details about the operations that you use to configure the tests:
Logical Operation
REST Operation
Action Type
Endpoint
Description
Create
POST
CREATE
/rest/rttprofiles/
<TestType>
 
Creates a test profile.
Force Create
POST
FORCE_CREATE
 /rest/rttprofiles/
<TestType>
 
Creates a test profile, but does not verify uniqueness.
Delete
POST
DELETE
 /rest/rttprofiles/
<TestType>
 
Deletes a test profile, including all the associated test instances.
Update
POST
UPDATE
/rest/rttprofiles/
<TestType>
 
Deletes a test profile, and creates a new test profile that uses the same underlying MIB object index.
Get all test profiles
GET
GET
 /rest/rttprofiles/
<TestType>
 
Fetches all profiles of the specified test type.
Get specific test profile
GET
GET
 /rest/rttprofiles/
<TestType>
/
<ID>
 
Fetches a profile with the specified type and ID.
 
TestType
 specifies the RTT test type. Use one of the following values:
  • dns
  • icmpecho
  • icmppathecho
  • icmpjitter
  • http
  • tcp
  • jitter
 
CREATE
 
This operation creates an instance of a test profile of the specified type with ActionType equal to CREATE. The created profile conceptually represents a background job to perform an SNMP set to create an RTT test on a device. The test is created permanently.
The create operation succeeds only if:
  • The TestHost is a discovered device.
  • The attributes of the requested test do not match an existing test in 
    CA Performance Management
    .
  • The attributes are semantically correct. The TargetHost does not reject the attributes because values are incorrect or the combination of attributes is invalid.
The result of a CREATE request is reflected in the read-only <Result> attribute of the created test. Perform a GET to view the result.
 
FORCE_CREATE
 
This operation is similar to CREATE, but creates the test even if an existing test has the same attribute values.
 
DELETE
 
This operation deletes a test that is identified by ItemIDs or by supplied attributes.
Deletes all tests that match the supplied attributes or the specific tests that matches the ItemIDs.
ItemIDs supersede attributes.
 
UPDATE
 
This operation re-applies attributes to an existing test. The operation deletes the test, and creates a test with new attributes. UPDATE changes only the supplied attributes. UPDATE runs DELETE, then CREATE. To preserve the relationship between the test configuration and the discovered Response Path Test components, the new test reuses the underlying MIB object index.
Attributes
 Depending on the Cisco IOS, some attributes may not apply to your device.
The following attributes apply to all test types:
  •  
    ActionType 
    The action type of RTT test.
  •  
    TestHost
    The address of the device on which the test runs.
  •  
    ItemID
    Specifies the ID of the target test for DELETE and UPDATE actions. To get the ItemID, see Get the ItemID for a Test 
  •  
    IPDomainID 
    Specifies the IP Domain of the test. IP Domain is required for all actions that do not include ItemID.
    • CREATE always requires IPDomainID.
    • DELETE requires IPDomainID to delete a test without specifying the ItemID.
    • UPDATE never requires IPDominID.
  • (Optional) 
    Owner
    Specifies the test owner.
  • (Optional) 
    Tag
    A short string that identifies the test in logging and notification.
  • (Optional) 
    Threshold
    Specifies that the test generates a threshold event if test takes longer than specified milliseconds.
  • (Optional) 
    Frequency
    Duration in seconds between initiating each RTT test.
  • (Optional) 
    Timeout
    Duration in milliseconds to wait for an RTT operation completion.
  • (Optional) 
    VrfName
    Specifies the VPN name where the RTT operation is used . The agent uses this field to identify the VPN routing table for the operation.
  • (Optional) 
    Persist
    Indicates whether this test configuration should be saved when persisting agent configuration to non-volatile storage. If left unspecified, the default is true.
    Cisco recommends persisting the tests. If the configuration is lost on the device, 
    CA Performance Management
     does not re-provision the test.
This table summarizes  the attributes that are associated with each IPSLA test. R indicates Required, and O indicates Optional:
Parameter
Description
ICMP Echo (Ping)
ICMP Path Echo
ICMP Jitter
UDP Jitter
UDP Jitter (VoIP)
DNS
TCP
HTTP
SourceAddress
The address of the device on which the test runs.
O
O
O
O
O
O
O
O
SourcePort
Specifies the source address port number. If the port is unspecified, the system selects a port.
N/A
N/A
N/A
O
O
O
O
O
TargetAddress
The destination IP addresses of the RTT test.
R
R
R
R
R
N/A
R
N/A
TargetPort
The destination port to which test probes are sent.
N/A
N/A
N/A
R
R
N/A
R
N/A
RequestSize
The request probe payload size.
(28)
(28)
N/A
(32)
(32)
N/A
N/A
N/A
ResponseSize
The response probe payload size.
N/A
O
N/A
O
O
N/A
N/A
N/A
TypeOfService
The type of service octet in an IP header.
O
O
O
O
O
N/A
O
O
Interval
The inter-packet delay in milliseconds between packets.
N/A
N/A
N/A
O
O
N/A
N/A
N/A
NumPackets
Number of packets to transmit.
N/A
N/A
N/A
O
O
N/A
N/A
N/A
CodecType
The codec type to use with jitter probe.
N/A
N/A
N/A
N/A
O
N/A
N/A
N/A
CodecInterval
The inter-packet delay in milliseconds between packets. Valid only for jitter probe which uses CodecType.
N/A
N/A
N/A
N/A
O
N/A
N/A
N/A
CodecPayload
Number of octets to place into the Data portion of the message. Valid only for jitter probe which uses CodecType.
N/A
N/A
N/A
N/A
O
N/A
N/A
N/A
CodecNumPackets
Number of packets to transmit . Valid only for jitter probe which uses CodecType.
N/A
N/A
N/A
N/A
O
N/A
N/A
N/A
ICPIFAdvFactor
Used while calculating jitter ICPIF values.
N/A
N/A
N/A
N/A
O
N/A
N/A
N/A
TargetAddressString
Specifies the address of the target. This string can be an IP address or a hostname.
N/A
N/A
N/A
N/A
N/A
R
N/A
N/A
NameServer
Specifies the IP address of the name-server.
N/A
N/A
N/A
N/A
N/A
R
N/A
N/A
Url
Specifies the URL that the HTTP probe targets.
N/A
N/A
N/A
N/A
N/A
N/A
N/A
R
Operation
Specifies the HTTP operation that represents the specific type of RTT operation.
N/A
N/A
N/A
N/A
N/A
N/A
N/A
R
HTTPVersion
Specifies the version number of the HTTP server.
N/A
N/A
N/A
N/A
N/A
N/A
N/A
O
String1
Stores the content of a raw HTTP request. If the request cannot fit into String1, use more String attributes.
*Required only if 
Operation
 is set to
 httpRaw (2)
.
N/A
N/A
N/A
N/A
N/A
N/A
N/A
R*
String2
Continues the raw HTTP request from 
String1
.
N/A
N/A
N/A
N/A
N/A
N/A
N/A
O
String3
Continues the raw HTTP request from 
String2
.
N/A
N/A
N/A
N/A
N/A
N/A
N/A
O
String4
Continues the raw HTTP request from 
String3
.
N/A
N/A
N/A
N/A
N/A
N/A
N/A
O
String5
Continues the raw HTTP request from 
String4
.
N/A
N/A
N/A
N/A
N/A
N/A
N/A
O
 When you specify an attribute value that has an associated enumerated name as defined by the MIB, only the numeric value is recognized.
 
Result
 
The result attribute is a read-only attribute that indicates the outcome of the request:
Meaning
<Result> value
The operation is in progress.
PENDING
The operation succeeded.
SUCCESS
The TestHost is not discovered.
FAILURE: Unable to identify device at 192.168.96.1
The requested test is already configured.
ALREADY_EXISTS: Existing Count = 1
TestHost is unreachable.
FAILURE: {http://im.ca.com/normalizer}NormalizedJitterInfo.RttType: NO_RESPONSE - {http://im.ca.com/certifications/snmp}CiscoIPSLAJitterMib.rttMonCtrlAdminRttType: SNMP timeout
{http://im.ca.com/normalizer}NormalizedJitterInfo.TargetAddress: NO_RESPONSE -{http://im.ca.com/certifications/snmp}CiscoIPSLAJitterMib.rttMonEchoAdminTargetAddress: SNMP timeout
{http://im.ca.com/normalizer}NormalizedJitterInfo.Interval: NO_RESPONSE -{http://im.ca.com/certifications/snmp}CiscoIPSLAJitterMib.rttMonEchoAdminInterval: SNMP timeout
{http://im.ca.com/normalizer}NormalizedJitterInfo.CodecInterval: NO_RESPONSE - {http://im.ca.com/certifications/snmp}CiscoIPSLAJitterMib.rttMonEchoAdminCodecInterval: SNMP timeout
Invalid credentials, such as SNMP SET profile.
{http://im.ca.com/normalizer}NormalizedICMPInfo.RttType: OPERATION_NOT_ALLOWED - {http://im.ca.com/certifications/snmp}CiscoRttMonStatsMib.rttMonCtrlAdminRttType: SNMP error 6: No access{http://im.ca.com/normalizer}NormalizedICMPInfo.TargetAddress: ATTRIBUTE_NOT_SET{http://im.ca.com/normalizer}NormalizedICMPInfo.Owner: ATTRIBUTE_NOT_SET{http://im.ca.com/normalizer}NormalizedICMPInfo.Tag: ATTRIBUTE_NOT_SET
The Data Collector associated with the TestHost is down.
  • SOURCE_NOT_AVAILABLE
  • SHUTDOWN
The test was not present on the TestHost because another SNMP client deleted the test.
FAILURE: 1.3.6.1.4.1.9.9.42.1.2.1.1.9.546811228: Commit failed. Error Index: 1
Get the ItemID for a Test
The UPDATE and DELETE operations use ItemID to identify tests. To get the ItemID, use a filtered REST endpoint:
  •  
    http://
    DA_HOST
    :8581/rest/responsepathtest/filtered
    Searches all test types. 
  •  
    http://
    DA_HOST
    :8581/rest/responsepathicmp/filtered
    Searches ICMP Echo tests.
  •  
    http://
    DA_HOST
    :8581/rest/responsepathecho/filtered
    Searches ICMP Path Echo tests.
  •  
    http://
    DA_HOST
    :8581/rest/responsepathjitter/filtered
    Searches UDP Jitter tests.
  • http:// 
    DA_HOST:8581
    /rest/responsepathicmpjitter/filtered
    Searches ICMP Jitter tests.
  • http://
    DA_HOST
    :8581/rest/responsepathhttp/filtered
    Searches HTTP tests.
  • http://
    DA_HOST
    :8581/rest/responsepathtcp/filtered
    Searches TCP Connect tests.
  •  
    http://
    DA_HOST
    :8581/rest/responsepathdns/filtered
    Searches DNS tests.
 
Example Request
 
This example shows a filtered request for tests with the specified target:
<FilterSelect xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:noNamespaceSchemaLocation='filter.xsd'>
<Filter>
<ResponsePathTest.Target type='EQUAL'>10.42.94.250</ResponsePathTest.Target>
</Filter>
<Select use="exclude"/>
</FilterSelect>
 To exclude all attributes except ItemID, the following statement:
Select use="exclude"
 
Example Response
 
This example shows the response to a filtered request:
<ResponsePathIcmpList>
<ResponsePathIcmp version="1.0.0">
<ID>955</ID>
</ResponsePathIcmp>
<ResponsePathIcmp version="1.0.0">
<ID>956</ID>
</ResponsePathIcmp>
</ResponsePathIcmpList>