Custom Test

  • 3 minute(s) read
Prev Next

Catchpoint provides many different types of monitors to cover most common testing use-cases. However, there may be a system that you want to test that is not supported by an existing Catchpoint monitor.

Catchpoint's Custom Monitor lets you run your own code on a Linux-based Enterprise Node. You can run code for virtually any type of application or backend service. Just upload your code and schedule a test.

Catchpoint takes care of everything required to run your code and measure performance.

How it works

KB_EnterpriseNodeDiagram_880px.png

Creating a Simple Custom Monitor

In this tutorial, you will learn the basics of running code on your Enterprise Node. We will walk through how to create a simple function on your Enterprise Node. We will then show you how to monitor this code and review your output metrics.

  1. Log into your Enterprise Node
  2. Navigate to /opt/3genlabs/hawk/syntheticnode/service/shellmonitor/sandbox
  3. Create Your Custom Script
    1. Create a file called simple_ping.sh
      $ vim simple_ping.sh
    2. Add the following code:
      #!/bin/sh
      ping -c 4 www.catchpoint.com

Since the Shell Script monitor allows you to create your function in multiple languages, it is important to tell the file what environment the function should use to execute your code.

The script has #!/bin/sh in the first line, meaning that the script should always be run with bash, rather than another shell. /bin/sh is an executable representing the system shell.

  1. Configure Your Function
    1. To run your function, Catchpoint requires that the function be an executable. To change the file permissions, run:
      $ chmod 500 simple_ping.sh $ chown serveruser simple_ping.sh
    2. To verify if the permissions have changed:
      $ ls
      -ltr-r-x------. 1 serveruser usrnam 14 May 31 00:00 simple_ping.sh

NOTE: please keep the permissions to 500 for the script file and sandbox folder.

  1. Set up your Custom Monitor in Catchpoint
    1. In the Tests module, create a new Test and choose monitor type Custom (Under the Custom test type)
    2. Input a Name for the test
    3. In the Script Filename field, input the script filename (no need to specify full path).
    4. In the Targeting and Scheduling section, select the Enterprise Node(s) you saved your script on.
    5. Save your changes.

Sending values to your Custom Script

Custom Monitor allows you to send values from the monitor to your code. The values you want to send to the script need to be configured in the test details, under the custom fields section. Each entry requires a variable name and a value associated with it.

values.png

The Macro name is how you can access the variable in the script. Catchpoint uses the prefix "CP_UNSAFE_VAR" to remind you that these values are being sent from the monitor configuration, and must be validated by your function to prevent abuse. For example, putting the CP_UNSAFE_VAR_host or CP_UNSAFE_VAR_count directly on a command line in your script would not be recommended without validation of the url, to ensure that unintended commands could not be executed by a carefully crafted url.

Example: the below line in your script would execute the ping command to the hostname value associated with the "CP_UNSAFE_VAR_host" macro.

Ping $CP_UNSAFE_VAR_host

Verify a Custom Monitor with Tracepoints & Indicators

Catchpoint Insight allows you to define additional pieces of data for Catchpoint to collect during testing. When you define Insight items, you are setting up rules that instruct Catchpoint to retrieve additional pieces of information when parsing the response from the Custom Script during testing.

When the Enterprise Node runs the custom script, it shows the output of the script in STDOUT. For Example:

Exit Code : 0
Command Exec Time(ms) : 3033
Exec Command Result Bytes : 559
Exec Command Results (1st-10K) :
PING www.google.com (172.217.10.68) 56(84) bytes of data.
64 bytes from lga34s14-in-f4.1e100.net (172.217.10.68): icmp_seq=1 ttl=56 time=4.34 ms
64 bytes from lga34s14-in-f4.1e100.net (172.217.10.68): icmp_seq=2 ttl=56 time=5.05 ms
64 bytes from lga34s14-in-f4.1e100.net (172.217.10.68): icmp_seq=3 ttl=56 time=4.30 ms
64 bytes from lga34s14-in-f4.1e100.net (172.217.10.68): icmp_seq=4 ttl=56 time=6.34 ms

--- www.google.com ping statistics ---
4 packets transmitted, 4 received, 0% packet loss, time 3003ms
rtt min/avg/max/mdev = 4.306/5.012/6.341/0.825 ms

Let's create an Insight to capture the average rtt time from the above output.

  1. Navigate to Settings > Insight
  2. Scroll down to the Insight Indicator section
  3. Create a new insight called rtt_avg and use a Regex mdev...\d+\.\d+/(\d+\.\d+) to capture the average rtt time.
    simple_ping_insight.png
  4. To use this insight, navigate and select your Custom Script test and scroll down to the insight section.
  5. By default, the test should be inheriting the insight form the parent folder/product; override this setting and choose rtt_avg insight.

Insight items are defined at the client-level, and enabled for collection for Products, Folders or Tests in the Tests module. Once data is collected, you can examine it alongside Catchpoint's standard measurements using Performance and Waterfall charts.

Here is a detailed guide on setting up Insight Settings including Tracepoints and Indicators.