Monitoring endpoints with Synthetic tests

You can use the Synthetic Monitoring user interface to create and manage Synthetic tests and Smart Alerts for such tests.

Creating a test

To create a Synthetic test, go to Synthetic Monitoring > Tests > ADD > Add Synthetic Test, and then complete the steps to create an API Simple test or an API Script test.
Use the Create Synthetic Test wizard or click Switch to Advanced Mode to view additional options. You can create an API Simple test to perform a REST call or an API Script test for a more complex test by using a script that you enter or upload. The API Simple test type is equivalent to an HTTPAction test type and the API Script test type is equivalent to an HTTPScript test type.

The advantages of the wizard are:

  • Guided steps
  • Quick creation of a basic Synthetic test

The advantages of advanced mode are:

  • Allows you to define many optional settings for your test definition
  • Aligns more closely with defining a test by using the Open API

Creating a test by using the wizard

Step 1: Select type: Choose the type of test that you want to create:

  • API Simple Use this type of test for an HTTP GET method to a URL of your choice. In Instana 250 and earlier versions, it is labeled as HTTPAction.
  • API Script Use this type of test to upload a Javascript file or enter the script into the input box. In Instana 250 and earlier versions, it is labeled as HTTPScript.

Step 2: Request details: Create the actual test.

  • For an API Simple test type, provide the URL. For the test to be run successfully, the URL must have the form 'https://www.YourCompany.com' or 'http://www.YourCompany.com'. The portion 'https://www' or 'http://www' is required. To create a Synthetic test with a different HTTP method, use the Open API. Refer to the Synthetic Monitoring section of the Open API documentation.

  • For an API Script test type, upload a file or enter the script in the box. Basic Javascript validation is run against the script. For both test types, select the locations where the test is run.

Step 3: Scheduling: Select the test run frequency.

Select the frequency by using the slider. You can select any interval from 1 minute to 120 minutes. The interval that you select is applied on each PoP where the test is assigned to run the test repeatedly.

Step 4: Provide details: Identify the test.

Give the test a name (required) and a description (optional). If the test is associated with an application that is also monitored by Instana, you can select the application name from the list, or use the search button to find the correct application name. You need not assign a name for the application. You can create a Synthetic test that is not associated with an application.

Creating a test by using advanced mode

In the Test type section of advanced mode, select the type of test that you want to create, either the API Simple test type or API Script test type.

After you select the test type, the Configuration section displays the required and optional elements of the test configuration.

  • API Simple test: Provide the URL or API endpoint. For the test to run successfully, the URL or API endpoint must begin with the form 'https://www.YourCompany.com' or 'http://www.YourCompany.com'. The portion 'https://www' or 'http://www' is required. To create a Synthetic test with a different HTTP method, use the Open API. Refer to the Synthetic Monitoring section of the Open API documentation.

    Several other optional configurations are provided to define an API Simple test:

    • Header: You can add one or multiple header elements. Each header element is added to the test by the PoPs when the test is run.
    • Body: You can define specific content to include in the body of the request. Only one body element can be added. The body element is added to the test by the PoPs when the test is run.
    • Validation String: You can define a string that should appear in the response when the test has run. Only one validation string element can be added. When the test is run, if the string is missing, the test fails.
    • expectStatus: You can define the expected HTTP return code for the test. If the return code does not match when the test has run, the test fails. Only one expectStatus element can be added. Use the drop-down menu to select the desired expect condition. Use Add Validation to add more than one expect condition. You can add one of each type of expect condition to a test.
    • expectMatch: You can provide a regular expression to check when the test runs. Only one expectMatch element can be added. If the expression is not matched when the test is run, the test fails. Use the drop-down menu to select expectMatch. Use Add Validation to add more than one expect condition. You can add one of each expect condition to a test.
    • expectJson: You can provide a json snippet to check when the test runs. Only one expectJson element can be added. If the json file is not matched when the test is run, the test fails. Use the drop-down menu to select expectJson. Use Add Validation to add more than one expect condition. You can add one of each expect condition to a test.
    • followRedirect: This flag is set to true by default. You can change this behavior to disallow redirection by deselecting the box.
    • allowInsecure: The flag to enable testing of HTTP endpoints. The flag is set to true by default. You can change this behavior and prevent insecure URLs for your test by deselecting this box.

  • API Script test: Select Add Script. An additional view is displayed where you can enter the script in the box, upload a single file, or upload a bundled set of scripts in a zip file. For more information about how to create a bundled set of scripts see Creating a bundled api script test. If you upload a single script file, the contents of the file appear in the text box. Basic JavaScript validation runs for a single uploaded script and a manually entered script. You can correct the script in the text box. If you uploaded the script and changed it in the text box, the script file is treated as if it was manually entered. If you upload a bundled set of scripts, you must enter the name of the main script in the input box. Select Add to accept the script or bundle and return to the Configuration section view.

The remaining sections in advanced mode apply to both types of tests.

In the Locations section, click Select Location. A list of locations that are available to you and that support the test type is displayed. Select the checkboxes for your choice of locations, or use the search box to find a location and select its checkbox. Select Add Locations to add the location and return to the Locations section. To remove a location from the selected locations, use the minus icon at the end of the row.

The Schedule section is the same in advanced mode and wizard mode. Select the frequency by using the slider. You can select any interval from 1 minute to 120 minutes. The interval that you select is applied on every PoP where the test is assigned to run repeatedly.

In the Identify section, you have one required parameter, Name, and several optional parameters:

  • Description: The description of the test.
  • Application: If the API or endpoint that is being tested is associated with an application that is also being monitored with Instana, you can associate the test with the application. Use the list and extend it by selecting Load more or use the search box to find the application name and select it. Only a single application name can be selected.

In the Custom Property section, you can specify one or more key-value pairs as custom properties. These become part of the test definition and the test results. They can be useful to locate, sort or filter tests and test results after the test has run. Select Add Property to add additional custom properties. the number of properties that can be added to a test has no limit. If you add a property and want to remove it before creating the test, select the trash icon at the end of the row for that property.

Viewing the summary for a test

To view the summary for a test, select a test on the Tests tab of the Synthetic Monitoring main page.

The Summary tab displays aggregated information about a single Synthetic test for the selected time period. The page also has a tab that lists the test results, a tab that displays Smart Alert configurations, and a tab to view or change the test configuration.

The Summary tab displays KPIs for the test such as the success rate during the time period across locations, the number of locations where the test runs, the average response time of the test runs, and the average response size.

Graphs of Failures, Response Times, and Response Sizes are displayed with data from each location. If more location labels appear on the charts than appear in the "Locations" KPI, then it means that the test was not running at all assigned locations during the selected time period.

The Results widget lists the top 5 results based on the selected filter. You can view the slowest results (those with the longest response time), the most recent results or the failed results. Each row in this widget is a link that will take you to the detailed view of that particular test run.

If the selected test is an API Simple test, you can see two additional charts on the Summary tab: a graph of network timings that show the breakdown of the network communication and a chart of the HTTP return codes that are received.

Viewing the list of results for a test

To view the list of results for a test, select the test on the Tests tab of the Synthetic Monitoring main page, and then click the Results tab.

The Results tab displays a list of results from your selected test. You can sort the list on any column. You can filter the list by using the Status and Location filters. The search box lets you search for all results from a "Location". The test results are listed by the time the test was run. Successful test results appear in the list in the form 'nn minutes ago' with a green indicator. Failed test results appear in the list in the form 'yyyy-mm-dd, hh:mm:ss' representing the time of the failure. They appear with a red indicator.

Viewing Smart Alerts for a test

To view the Smart Alerts for a test, select the test on the Tests tab of the Synthetic Monitoring main page, and then click the Smart Alerts tab.

The Smart Alerts tab displays the configured Smart Alerts for your selected test.

To view details of a Smart Alert, select the Smart Alert entry. You can also edit, duplicate, or delete the Smart Alert by using the ellipses menu.

For more information about working with Smart Alerts, see Smart Alerts for Synthetics.

Viewing the configuration for a test

To view the Configuration for a test, select the test on the Tests tab of the Synthetic Monitoring main page, and then click the Configuration tab.

In the Configuration tab, you can view the test's configuration, locations, schedule, and identification.

If you want to edit the test definition, select the pencil icon. The complete test definition is then displayed. You cannot change the type of the test, but you can modify the rest of the configuration. For an API Simple test, you can change the URL or API endpoint and modify any of the optional elements. For an API Script test, you can edit the single script or upload a new file or bundle. For both test types, you can modify the locations where the test needs to run, the scheduled interval between test runs, the associated applications, and the custom properties.

Viewing test result details

To view the test result details page for a single test run, either select an entry from the Results tab in the Summary page or select an entry from the Results widget in the Summary page. Different displays appear for a test run that succeeds versus a test run that fails.

The test result details for each type and status of Synthetic test are slightly different. All results have the KPIs that show the time of this result, the status, the response time, the number of requests that are made by the test, and the response size. If the test has run partially or to completion, the Timings will be displayed. The timings of each request can be expanded to view more details. If the test has not gotten far enough to make a request, no timings are available.

Failed tests includes a Failures widget with a stack trace that can be collapsed. Failed tests also have a Logs widget. Click the text of the first log message to expand or collapse the log messages. These are the logs that are captured by the PoP during the execution of the Synthetic test.

An API Simple test result detail is as follows:

Note: The Failed Run (Exception) section is shown only for a failed test.

An API Script test result detail is as follows:

If an API Script test failed, the Failed Run (Exception) section is shown with the error messages and stack traces:

To display detailed log messages, click the Logs section:

Instana integration

  • Applications: When you create a Synthetic test and associate it with an application that is already monitored by Instana, you can link between the Synthetic Monitoring page and the Applications page for the applications in the Instana UI. If an application has Synthetic tests associated with it, a new tab Synthetic monitoring appears in the display of a selected application. This tab lists the associated Synthetic tests and lets you use links in the page to go to the Synthetic test UI. On the Tests tab of the Synthetic Monitoring main page, you can use the application name in the row to link to the selected application in the Applications page.

  • Events: If you create an alert for a Synthetic test and that alert fires, you can see it in the Events view. If you select an alert, you can see a graph of failures and a link to the failing Synthetic test results. Similarly, from the Summary tab of a Synthetic test, you can use the alert indicators to link to the details of the alert in the Events view.

    Click a Synthetic Smart Alert event entry:

    Click View Alerting Configuration:

    You can edit, duplicate, or delete an alert from the Alert Configuration page. To create an alert, click ADD SYNTHETIC SMART ALERT.

Monitoring Kubernetes: The PoP is deployed as a set of Kubernetes pods. If an Instana agent is deployed in the same Kubernetes environment but no PoP sensor is deployed, you can link from the Locations tab of the Synthetics Monitoring UI to the Kubernetes pages for the namespace where the PoP is running.