Instana U

 View Only

Managing Synthetic tests, Smart alerts, locations and credentials with Synthetic CLI

By Swetha Lohith posted Sun November 26, 2023 11:48 PM

  

Co Author: Rong Zhu Shang

You can manage Synthetic tests, locations, and credentials by using synctl. It is a command line tool for Synthetic monitoring. The tool is based on requests libraries. For more information, see Synthetic CLI Command.  

Installing synctl 

If you have previously installed synctl (version 1.0.x), make sure to remove /usr/local/bin/synctl.

To install synctl, run:

pip3 install synctl

Upgrading synctl

You can use the  synctl install to upgrade synctl as shown in the following examples: 

# upgrade to latest
pip3 install --upgrade synctl

# upgrade synctl to specified version
pip3 install --upgrade synctl==<version>

Configuring the Instana backend 

You can configure  Instana backend by using the  synctl command.  You can configure the Instana backend by using a configuration file, command options, or environment variables. 
Configuring an Instana backend by using a configuration file is shown in the following example:  
 
# set your backend host and token, and give it an alias name, and set it as default 
synctl config set \ 
--host "https://test-instana.pink.instana.rocks" \ 
--token "Your Token" \ 
--name "pink" \ 
--default 
 
You can use the  synctl config to configure, list or remove a configuration as shown in the following examples: 
#list all configurations 
synctl config list 
 
# set pink as default 
synctl config use --name pink –default 
# remove a configuration 
synctl config remove --name pink 
 
Note: To use --host and –-token options, refer to Use command options and Use environment variables. 
 

Query Synthetic tests 

 
To display all the Synthetic tests, run: 
synctl get test 
 
A sample output: 
 
 
Synthetic result shows success rate and latency by default. The default interval is 1 hour. To change the interval, use the option –-window-size with the interval [1, 60]m, or[1,24]h. Setting an interval for Synthetic tests is shown in the following examples: 
synctl get test --window-size 30m 
synctl get test --window-size 6h 
 
You can retrieve Synthetic tests by type.  To retrieve the tests by type, run: 
synctl get test -t <type> 
 
Every test type is represented by a number. In the command, use the number that represents the test type that you want to retrieve:  
  • API Simple : 0  
  • API Script : 1 
  • Browser Script : 2 
  • Webpage Script : 3 
  • Webpage Simple : 4 
Get the list of API simple test: 
 
To show the test details of a Synthetic test, run: 
synctl get test <id> --show-details
Retrieving the tests details is shown in the following example: 
 
If the test type is API script or Browser script, you view the test script in the command output. 
To show the script test, specify the option --show-script: 
 
synctl get test <id> --show-script 
 
The test script is shown in the following example: 
 
 
To save the test script to a local file, run: 
synctl get test <id> --save-script 
 
Use the test label as the file name. 
 
Example: 
 
 
To show test JSON payload, run: 
synctl get test <id> --show-json 
 
The test JSON payload is shown in the following example: 
 
 
 

Creating a Synthetic test 

You can create a Synthetic test by using the synctl create command. The command supports creating the following tests: 
  • API Simple 
  • API Script 
  • Browser Script 
  • Webpage Script 
  • Webpage Simple 
 
Number from 0 to 4 are used to represent Synthetic tests. The following examples show creating Synthetic tests. 

Create API Simple test 

Location ID is required to create a Synthetic test.  
To get a location ID, use the synctl get lo command. The following example shows a sample output. 
 
 
To create a test on a single location, run: 
 
synctl create test -t 0 \ 
--label "simple-ping" \ 
--url "https://httpbin.org/get" \ 
--location "$LOCATION" \ 
--frequency 5 
 
Example: 
 
You can specify multiple location IDs when you create a Synthetic test. 
To create a test on multiple locations, run: 
 
synctl create test -t 0 \ 
--label "simple-ping-multiple-location" \ 
--url "https://httpbin.org/get" \ 
--location "$LOCATION1" "$LOCATION2" "$LOCATION3" ... 
 
Example: 
 

Create API Script test 

 
To create a simple API Script test, run: 
 
synctl create test -t 1 \ 
--label "simple-api-script" \ 
--from-file http-scripts/http-get.js \ 
--location "$LOCATION" \ 
--frequency 5 
 
Example: : 
 
 
      
 To create a bundle test with a zip file, run: 
 
synctl create test -t 1 --label syn-bundle-zip-test \ 
--bundle synthetic.zip \ 
--script-file index.js \ 
--location "$LOCATION" \ 
--frequency 5 
 
Example: 
        
 
To create a bundle test with a string encoded with BASE64, run: 
 
BASE64_STR=` cat synthetic.zip|base64` 
synctl create test -t 1 --label "syn-bundle-test" \ 
--bundle "${BASE64STR}" \ 
--script-file index.js \ 
--location "$LOCATION" \ 
--frequency 5 
 
Example: 
 
 

Create a Browser Script test 

    
To create a Browser Script test, run: 
synctl create test -t 2 \ 
--label browser-script-test \ 
--from-file browserscripts/api-sample.js \ 
--location "$LOCATION" \ 
--frequency 15 
        
Example:  
 
To create browser bundle test by using a zip file, run: 
 
synctl create test -t 2 \ 
--label browser-script-test-zip \ 
--bundle browserscript-bundle.zip \ 
--script-file mytest.js \ 
--location "$LOCATION" \ 
--frequency 15 
 
Example: 
 
       
To create browser bundle test with the base64 string, run: 
 
BASE64_STR=` cat synthetic.zip|base64` 
synctl create test -t 2 \ 
--label "browser-script-test-bundle" \ 
--location "$LOCATION" \ 
--frequency 15 \ 
--browser firefox \ 
--script-file mytest.js \ 
--bundle "$BASE64_STR" 
Example: 
  
 

Create a Webpage Script test 

 
To create a Webpage Script test, run: 
 
synctl create test -t 3 \ 
--label "webpage-script-test" \ 
--location "$LOCATION" --frequency 15 \ 
--from-file side/webpage-script.side  \ 
--browser chrome 
      
Example: 
 
 

Create a Webpage Action test 

 
To create a Webpage Action test, run: 
synctl create test -t 4 \  
--label "webpage-action-test" \ 
--url "https://httpbin.org/get" \ 
--location "$LOCATION" \ 
--frequency 5 \ 
--record-video true 
--browser chrome 
 
Example: 
 
 
 

Create Synthetic test by using JSON payload 

 
You can specify a JSON payload when you create a Synthetic test. In the JSON file all required properties must be filled in the payload file. For more information on properties, refer to Synthetic Test Properties. 
 
To create a Synthetic test by using JSON payload, run: 
 
synctl create test -t <type> \ 
--from-json payload/api-script.json 
 
For more test options, refer to synctl create test Options. 
 
 

Assigning a test to an Instana application 

 
You can assign a Synthetic test to an application.  
 To assign a test: 
  1. Get application list, run: 
synctl get app 
 
  1. Create a test with an application ID, run: 
synctl create test -t <type> --app-id <application-id> ... 
 
To filter the applications by name, run: 
synctl get app --name-filter <application-name> 
 

Patching a Synthetic test 

 
The command patch is utilized to update specific attributes of a Synthetic test. You can patch only one attribute in an instance.  
Patching a Synthetic test is shown in the following example: 
 
  1. Set label to API Simple run: 
synctl patch test <synthetic-id> --label simple-ping 
     
Sample output:  
 
  1. Set description to "This is a Synthetic test", run: 
 
synctl patch test <synthetic-id> --description "This is a Synthetic test" 
 
Sample output: 
 
 
  1. Set test frequency to 15, run: 
synctl patch test <synthetic-id> --frequency 15 
 
Sample output: 
 
 
  1. Set timeout to 120s: 
 
synctl patch test <synthetic-id> --timeout 120s 
 
Sample output: 
 
 
  1. Edit script file, and update Synthetic test with new script. For API Script test or Browser Script test, you can use the patch command to update the script content as shown in the following example: 
# first get the script file using --save-script option 
synctl get test <id> --save-script 
 
# edit the script file, then update the test script with patch command 
synctl patch test <synthetic-id> --script-file simple-api-script.js 
 
Sample output: 
 
 
  1. Update bundle test with a zip file. Use the option --bundle to update the bundle test content, you can use zip file and BASE64 encoded string: 
 
synctl patch test <synthetic-id> --bundle synthetic.zip 
 
Sample output: 
 
 
BASE64_STR= `cat synthetic.zip|base64` 
synctl patch test <synthetic-id> --bundle "$BASE64_STR" 
 
Sample output: 
 
 
  1. Set test URL to https://www.ibm.com: 
 
synctl patch test <synthetic-id> --url https://www.ibm.com 
 
Sample output: 
 
 
  1. Disable Synthetic test:  
synctl patch test <synthetic-id> --active false
After the Synthetic test is disabled, the PoP (Point of Presence) does not conduct any playback until the test is enabled again. No test results are displayed on the UI. 
 
Sample output: 
 
 
Note: For more patch options, see synctl patch Options. 
 

Deleting Synthetic tests 

 
To delete a Synthetic test, run: 
 synctl delete test <synthetic-id> 
 
To delete multiple Synthetic tests, run: 
 synctl delete test <synthetic-id-1> n<synthetic-id-2> <synthetic-id-3> ... 
 
To delete all tests which match the label regex "^ping-test-*", run: 
synctl delete test --match-regex "^ping-test-*" 
For more information on regex, refer to https://docs.python.org/3/library/re.html.
            
       
To delete all tests, run: 
synctl delete test --match-regex ".*" 
 
Delete all tests with location <location-id>, you can delete test with a single location, or multiple locations in a single command. For those tests with more than one location, delete command with a single location ID will not delete tests that have multiple location IDs. For example, synctl delete test --match-location A will not delete test with location [A, B]. 
 
synctl delete test --match-location <location-id> 
      
Example: 
 
 
Delete all tests which has no locations, use the option --no-locations to match those tests whose location id are empty.  
 
synctl delete test --no-locations 
 

Querying Smart Alerts 

 
To display all Smart Alerts, run: 
 
synctl get alert 
 
Sample output: 
 
To show details of a Smart Alert, run: 
 
 synctl get alert <id> --show-details 
 
Retrieving the alert details is shown in the following example: 
 
 
 
To show alert JSON payload, run: 
 
synctl get alert <id> --show-json 
 
Sample output: 
 
 
Creating a Smart Alert 
 
You can create a Smart Alert by using the synctl create command. 
To create a Smart Alert, you need a Synthetic test ID and alerting channel.  
 
To get a synthetic test ID, run synctl get test.    
To get alerting channel, run synctl get alert-channel.  
 
 
 
 
 
synctl create alert --name "synthetic test failed" \ 
--test "$TEST_ID" \ 
--alert-channel  "$ALERT_CHANNEL_ID" \ 
--severity warning 
 
Example: 
 
 
To create a Smart Alert for multiple tests, specify the test IDs when you create a Smart Alert. 
 
synctl create alert \ 
–-name "multiple tests failed " \ 
--test "$TEST_ID_1" "$TEST_ID_2" \ 
--alert-channel "$ALERT_CHANNEL_ID" \ 
--severity warning 
 
Example: 
 
 

Updating a Smart alert 

 
You can update the entire Smart Alert configuration with the update command. 
To update an alert, first preserve the existing alert configuration by saving it to a file. Then update the file and apply the changes to the alert. 
 
synctl get alert <alert-id> --show-json > alert.json 
synctl update alert <alert-id> --file/-f alert.json 
 
Example: 
 
 

Deleting Smart Alerts 

 
To delete a Smart Alert, run: 
synctl delete alert <id>  
 
 
 
To delete Smart Alerts, run: 
synctl delete alert <id-1>  <id-2> ... 
 
Example: 
 
 

Managing Synthetic test locations

 
To display the Synthetic locations, run: 
 
synctl get location 
 
     Example: 
 
 
To display details of a Synthetic location, run: 
 
synctl get location <location-id> --show-details 
       
 Example:    
 

Deleting Synthetic test locations 

 
To delete a Synthetic test location, run: 
 
synctl delete location <location-id> 
 
 
To delete Synthetic locations, run: 
 
synctl delete location <location-id-1> <location-id-2> <location-id-3> ... 
Example: 
          
 

Managing test credentials 

To display all the test credentials, run: 
 
synctl get cred 
 
Example: 
 
 
To create a test credential, run: 
 
synctl create cred --key <key-name> --value <value> 
 
Example: 
 
 
  1. Delete a credential 
 
synctl delete <credential_name> 
 
Example: 
 
 

Summary 

With the synctl tool, you can seamlessly manage Synthetic tests, Smart alerts, locations and credentials. 
 
 
 

Permalink