Over the past couple of years we have seen our customers increasingly use ThousandEyes to monitor their applications and services hosted in IaaS providers. As a part of our continued support for IaaS performance monitoring, and as part of my summer internship here at ThousandEyes, I was assigned a research project to compare the performance of three large IaaS providers: AWS, Google Cloud and Microsoft Azure. This was a cool project for me because as a college student I had access to the full capabilities of a platform that Fortune 500 companies utilize to monitor their networks. Taking advantage of features from our recent multi-cloud launch, I was able to leverage Cloud Agents hosted in multiple regions within each of these public cloud providers to monitor inter-region performance, global connectivity and multi-cloud performance. This meant creating a total of 1485 tests (from 55 vantage points to 27 regions across AWS, Google Cloud and Microsoft Azure) between cloud agent pairs. Manually creating these many tests would have been a time consuming and cumbersome task. But thanks to the ThousandEyes API, I was able to automate this in no time. In today’s blog post I will summarize how to leverage the ThousandEyes API for automating test creation and improving operational efficiency.
Introduction
The ThousandEyes API is a powerful integration framework that our customers heavily rely on to automate processes and management of their ThousandEyes deployment. Like most web APIs, it uses the standardized HTTP protocol and XML/JSON response formats. The API includes multiple endpoints (URLs), each of which performs a different task when it receives an HTTP request. To access the API, a user must provide their credentials (account username (email) and a token) as part of all HTTP requests. Token information is accessible through the account settings page. API permissions can be modified in the roles section of an organization’s settings.
There are multiple ways users interact with the ThousandEyes API, the simplest being a cURL command. However, most programming languages have various libraries and integrations for the HTTP protocol, and there are even applications that let you easily test and visualize the responses of API requests (I used Insomnia). We have customers using a variety of platforms, including Microsoft .NET, PHP, Powershell, and Python to interact with the API.
I chose to receive responses in JSON (Javascript object notation) format because of its readability and compatibility with Java. Responses are in XML by default, but you can select JSON by either appending .json to the url or adding Accept: application/json to the HTTP header.
Creating a Test
I categorized the process of creating tests using the ThousandEyes API into 3 broad steps:
1. Identify Test Parameters: As the first step, decide on the parameters for your test. ThousandEyes offers a variety of test types, with advanced options to modify them. The parameters required to create each type test are detailed on the test metadata section of the developer reference. For example, to create an agent-to-agent test between the AWS eu-west-2 and AWS us-east-1 Cloud Agents, the test parameters would be the test name, monitoring interval, and target and source agents. You can also choose to enable or disable alerts, among other options. I picked the test name to be AWS eu-west-2 -- AWS us-east-1 for easy lookup. And set the monitoring interval to 10 minutes. The target agent is the Cloud Agent located in London, England in AWS eu-west-2 and the source agent is located in Ashburn, VA in AWS us-east-1. Since we are using the API and not the UI dropdown to pick agents, you need the agentId numbers. That brings us to the second step.
2. Obtain AgentId Numbers: Look up the agentId numbers of the required agents. To obtain information on all of the agents (cloud and enterprise) associated with your account, send a GET request to the following endpoint: https://api.thousandeyes.com/v6/agents.json. The response will be in this format:
{
"agents": [
{
"agentId": 56250,
"agentName": "Ashburn, VA (AWS us-east-1)",
"agentType": "Cloud",
"countryId": "US",
"ipAddresses": [
"1.2.3.4",
"1.2.3.4"
],
"location": "Ashburn Area",
"createdDate": "2018-03-24 00:11:10"
},
...
{
"agentId": 56286,
"agentName": "London, England (AWS eu-west-2)",
"agentType": "Cloud",
"countryId": "GB",
"ipAddresses": [
"1.2.3.4",
"1.2.3.4"
],
"location": "England, United Kingdom",
"createdDate": "2018-03-24 01:09:39"
},
...
{
"agentId": 29,
"agentName": "Sample Enterprise Agent",
"location": "United States",
"countryId": "US",
"prefix": "38.0.0.0/8",
"ipAddresses": [
"1.2.3.4"
],
"publicIpAddresses": [
"1.2.3.4"
],
"network": "Cogent Communications (AS 174)",
"agentType": "Enterprise",
"lastSeen": "2015-02-05 23:23:33",
"agentState": "Online"
}
]
}
Depending on which programming language you use, there are various ways to process this response data. Since I wrote my program in Java, I used Jackson, a tool developed by GitHub to work with JSON data. All you need to do is look up the agentId numbers corresponding to the agents selected in step 1.
3. Formulate and send a POST request: To finally create a test send a POST request to this endpoint: https://api.thousandeyes.com/v6/tests/{test-type}/new.json. Since this is a POST request, it contains a payload (the information that you are sending to ThousandEyes servers). To send the payload in JSON format, add Content-Type: application/json to the request header. Then you can specify the conditions of the test in JSON format, like the example below:
$ curl -i https://api.thousandeyes.com/v6/tests/agent-to-agent/new.json \
-d '{ "interval": 600,
"agents": [
{"agentId": 56250}
],
"targetAgentId": 56286
"testName": "AWS eu-west-2 -- AWS us-east-1",
"alertsEnabled": 0
}' \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2
If you receive a 201 HTTP response code, then you have successfully created your test. There are multiple possible error codes, which are documented on the developer reference. For example, if I create a test with a name that is already taken, I will receive a 400 response code and the following as the body:
{
"errorMessage": "There were some errors in your request, please correct them before trying again. A test with this name already exists."
}
Updating Tests
If you would like to check what tests you have created or would like to update any tests, you will need to initiate a GET request to the https://api.thousandeyes.com/v6/tests.json endpoint. This endpoint responds with a list of all tests associated with a user’s account, in a similar format to the /agents endpoint. You can access the testId number for a test, and to update it, send a POST request to https://api.thousandeyes.com/v6/tests/{testType}/{testId}/update.json with the parameters you would like to change in the payload. For example, to change the monitoring interval of an agent-to-agent test to 5 minutes, your request would look like this, where {testId} represents the testId number found from the /tests endpoint:
$ curl -i https://api.thousandeyes.com/v6/tests/agent-to-agent/{testId}/update.json \
-d '{"interval": 300}' \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2
Automation
At first glance, using the API may seem complicated, but when it comes to creating over 1000 tests, it is definitely the way to go and a breeze! This was my first experience using any kind of API, and I was able to master it in no time. In order to create all of the tests I planned, I used Java to write a program that when given a list of agents (supplied from the API agents endpoint), iterates through the list and creates a bidirectional agent-to-agent test between each combination. In the snippet of code below, cloudToCloud() is a function I created that takes two agents and creates an agent-to-agent test between them.
for (int i = 0; i < list.size(); i++) {
for (int j = i + 1; j < list.size(); j++) {
cloudToCloud(list.get(i), list.get(j));
}
}
Conclusion
For companies looking to integrate ThousandEyes test creation, alerts, and reporting into their operational processes the ThousandEyes API is a useful and versatile framework. I have only begun to experiment with the ThousandEyes API, and what you have read is just an introduction to its many functionalities. Users can update tests, agent settings, create alerts, reports and more. Be on the lookout for an upcoming blog post on how to process test and report data. To try out the sandbox version of the API and for complete documentation, visit http://developer.thousandeyes.com/v6/. If you would like to experiment with creating tests, sign up for a free trial of ThousandEyes.
