Info
Video versions of this guide are available on the Apica Systems YouTube account here: https://www.youtube.com/playlist?list=PL7P4sd6wT60B5JAxU3l3Rzjhf7v01lqQz

Why Use a Scripted Check?

If you are in a DevOps shop, you can use the DevOps Toolchain that you might already have in place. If you've got the resources to write and edit Java, Python, or JavaScript, you can create a long-term global script for ASM without needing a unique scripting tool or proxy setup. If you know what URLs you want to monitor, this allows you to become less reliant on proprietary scripting solutions and also frees these script languages from being unable to do more than a test application performance from a single QA/developer machine.

Scripted Check Overview

The term “Scripted Check” refers to checks which run scripts which customers create on their own and upload to the ASM Platform for monitoring. Currently, Java, Python, JavaScript, and AWS Lambda scripts are supported within ASM. Scripts may be stored and uploaded to an HTTP server or GitHub repository. When you download a script for execution, you must specify either the HTTP URL or the GitHub Repo URL.

...

Setup GitHub to store the scripts.
Script the check (in Java, Python, or JavaScript)
Upload the Script into GitHub.
Create the ASM Check to any one of Apica's global agents on the Apica Monitoring Platform.
Collect, compare and analyze the ASM Check Results OR send the results to integrated systems that use ASM as a data source.

Document Scope

As an example of a Scripted Check, this documents how you set up a Run Python Scripted Check for the Apica platform.

This document will not cover the AWS Lambda Scripted Check, addressed in a separate Serverless Computing guide. The AWS Lambda superset of scripting languages will be handled in that guide.

When "Scripted Checks" are used alone, they refer to the Java Jar, Python, and JavaScript pre-selected languages.

1. GitHub Setup (Optional; Getting Started with GitHub)

...

title	Github Setup as of January 2022

You will require a GitHub repository/Repo to store the scripts themselves.

...

Step

...

Screenshot

...

Create a GitHub repository

Log into GitHub.

In this demo, we'll be creating a new test repository. Press "New Repository"

Info
Note: You don't have to do this if you already have a repository.

The repository can be public or private. Apica recommends that it be set as private. Private repositories give you more requests on your GitHub token rate limit.

Click "Create repository."

...

Create GitHub Personal Access Token

We've created the repository (keep it in a new tab while creating a Personal Access Token that you'll give to ASM).

Personal Access Tokens are used to run any scripts that you create inside ASM as a check.

...

Getting the Personal Access Token

This Personal Access Token will allow ASM to pull scripts from your repository.

Go to your user Settings.

Scroll down to Developer settings and click "Personal Access Tokens."

...

Generate New Token

Click "Generate new token."

Enter your GitHub password if prompted.

Apica recommends adding a new note. So, we will put “ASM 2021-11-03" into the note field in this example.

For this example, only we'll set no expiration because we don't want this token to expire, but do set a token expiration date as your security policy requires.

Select the permission scope that will be needed for this example: repo [no others are needed].

Finally, click Generate token.

...

GitHub generates your token

Info
Make sure to copy your personal access token now. You won't be able to see it again!

Copy the token into a text file for later re-use.

...

2. Scripting an Example Python Check

Next is a simple example of writing your script and running it in ASM.

We will be coding a straightforward Python check for its use in ASM. This Python check will call a URL that we specify, and it will return the response that we received from this URL.

...

Step

...

Screenshot

...

Import Libraries (as needed)

import requests

import sys

import JSON

import time

After Python is up, import the requests {a library for doing any URL call}, sys, JSON, and time libraries into the virtual environment.

Info
See https://apica-kb.atlassian.net/wiki/spaces/ASMDOCS/pages/2135393547/Scripted+Check#7.-Appendix for instructions on using a custom module within your script.

...

Set the URL Request

Set the URL call to be an argument.

Make a GET request against that URL.

The response will need to set a default URL to call, if we don't have an argument. Set exceptions as 'e'. and The URL will be http://google.com.

Our script returned a 200 status code. Our script will call either http://google.com or a URL that we provide.

...

Creating an Example Scripted Check

The following guide utilizes Python code, but the workflow can apply to Java checks, JavaScript checks, or any other Scripted check type.

1. Scripting the Check

Next is a simple example of writing your script and running it in ASM.

We will be coding a straightforward Python check for its use in ASM. This Python check will call a URL that we specify, and it will return the response that we received from this URL.

Step

Screenshot

Import Libraries (as needed)

import requests

import sys

import JSON

import time

After Python is up, import the requests {a library for doing any URL call}, sys, JSON, and time libraries into the virtual environment.

Info
See https://apica-kb.atlassian.net/wiki/spaces/ASMDOCS/pages/2135393547/Scripted+Check#7.-Appendix for instructions on using a custom module within your script.

Image Added

Set the URL Request

Set the URL call to be an argument.

Make a GET request against that URL.

The response will need to set a default URL to call, if we don't have an argument. Set exceptions as 'e'. and The URL will be http://google.com.

Our script returned a 200 status code. Our script will call either http://google.com or a URL that we provide.

Code Block

language	py

  try:
        url = sys.argv[1]
except Exception as e:
       url = 'https://google.com'

response = requests.get (url)
print (response.status_code)  url = sys.argv[1)

Add JSON format

What JSON format does Apica’s back-end system expect? Apica’s back-end is based on MongoDB.

MongoDB allows us to have an expandable result format. So that's a result format that you can upload almost anything to, and it will become a part of the result.

We have the start and end times that we need. So the start and end times will be the start and end times of your check in ASM (These will show up in the check Result view in ASM).

Set start_time = time.time().
Set end_time = time.time().

Note: we're doing the start_time before our URL call and the end_time at the end of our URL call. This measures the time it takes to call this URL.

Set a message. So our message is “URL call returned status code”, then adds a string response (the returned status code) the value that you see here, in the JSON format, it will be the value of the results.

So this is the main value that you will see. Usually, it's the duration, but it could be anything. To show this, let's say that it's the status code, because this is what we're saying in the message. So we'll set it to response.status.code.
After running this, we have our JSON output; by itself, a valid result.

Code Block

language	py

  try:
        url = sys.argv[1]
except Exception as e:
       url = 'https://google.com'

start_time = time.time()
response = requests.get (url)
end_time time. time()

json_return = (
 "returncode": 0,
 "start_time": start_time,
  "end_time": end_time,
  "message": "URL call returned status code: " + str(response.status_code),
  "unit": "ms",
  "value": response.status.code,
}
 
print(json.dumps(json_return))

Expanding the Returned values

Let's expand this a little bit; we have an expandable JSON format, so let's give ourselves more content and data.

How many headers do we have here?

What is the length of the returned content?

Add these lines below the "value" (line 16 above) to return the response header count and the size of the content.

"header_count": Len(response. headers),

"content_size": len(response.content)

...

Apica's Scripted Checks are very flexible; if your script requires additional Python libraries, you may simply add those libraries to your Scripted Check Private Agent.

...

Advanced JSON

Some additional points to the previous steps.

...

Later, we will show you how to retrieve this information through the ASM API. So anything that you can get from your code, you can get through the ASM API as your check is run.

4. (0ptional) Putting the Script into GitHub.

...

title	Github Script Upload as of January 2022

...

Step

...

Screenshot

...

Open GitHub

...

Upload your script into your new repository

In the repository we created in our first step, we will upload our script. You can use any way to get your script here. You can use the Git command line.

...

Using the UI

So what we'll do is we will get our script by clicking on "uploading an existing file," which will open up a browse/drag/drop dialog to add your file.

Once the file has been uploaded, commit the changes. GitHub will take a moment to process our files. And you'll see the test script main.py.

...

5. Creating an ASM Check

...

2. Uploading the Check to a Repository

When you have finished writing the check and testing locally, upload the check to a repository which has been linked to ASM. See Manage Repository Profiles for instructions on linking a repository for use within ASM. A repository can be added directly via the check creation wizard, when editing the check via the Edit Check page, or within the “Manage > Repository Profiles” page on the top ASM navigation bar.

3. Uploading and Running the Check in ASM

When the script is complete and uploaded to your repository profile, you are ready to create a Scripted check in ASM in order to utilize the script.

Note
You MUST select either “+1 Stockholm, Sweden, [amazon] or a private agent with the correct software installed when selecting an agent location. See “Run Python Step 2” for more information.

Step

Screenshot

Open ASM

Navigate to New Check+

Add Script via Run Python.

The Run Python Scripted Check type icon should be displayed. If you don't have this, you may need to get it unlocked. Please ask your sales team for access because this is a more advanced check, not available for customers by default.

Creating a Run Python Check, Step 1

Enter "New Test Check." Add any description and relevant tags, and then click Next.

Run Python Step 2

Configure this check

Resource URL/Github URL
Resource Auth Type
Resource Auth
Resource Path
Secondary Resource
Script Runner
Script Arguments
Location

Info
Note that the agent will delete any local files you create after running your script. Any sensitive data written to local files during script execution is deleted at the end of execution.

Resource URL/Github URL: This answers the question, "Where do we find your script?" This could be an HTTP download link, or it can be to your GitHub repository. For this example, go to your repository and copy+paste the URL here, ending with the branch (master/main). Ours is main.

Enter the URL that this script resides at. In this example, it resides in a GitHub Repo at https://github.com/[username]/NewTestRepository/main

Resource Auth Type: This type of resource authorization will be needed, GitHub or HTTP. This example uses GitHub. But if you have your file on an HTTP server, you could use HTTP as the type.

Resource Auth: Resource authorization is required. The authorization header allows you to download resources.

It's a basic authorization header when your resource authorization type is HTTP.
- If you have an HTTP server with no protection, you may do it that way, but Apica does not recommend it because it's not secure.
If your auth type is GitHub, this form <USERNAME>:<TOKEN>.
- Remember, the token is the Personal Access Token that we created back in the first step [it can also be empty if your repository is public].
- Example if your username is foobar: foobar:ghp_JlvGv7PGTrAzI2LWVIQZDhRthYBBQI1TGl0J

Expand

title	Resource Auth Best Practice

To set the Resource Auth, remember that it is a hidden field, so you won't be able to see anything you type here. Apica recommends taking your username as your username without the email domain and then assembling it with the colon and Personal Access Token so you can see it in another location.

For example: if your GitHub username is foobar@gmail.com, your username will be 'foobar,' without @gmail.com.

Then append the colon ':.'

Finally, add the Personal Access Token, and your resource authorization looks like this and is ready to copy into that field:

foobar:ghp_JlvGv7PGTrAzI2LWVIQZDhRthYBBQI1TGl0J

Resource Path: This is the path inside your repository to the scripts you want to run. Our example scripts are just in the base level repository, so enter main.py

Secondary Resource: If your script requires any sort of additional files, you can use this secondary resource to download another file. However, you can also start your script off by downloading the file directly: That way, you can use any sort of security you want to protect it. For example, you could have a secondary resource, like a certificate protected by OAuth: Your script could go through the whole OAuth process and then use the local file.

In this example, the secondary resource will be blank because it is unnecessary.

It is possible to reference subfolders from a base directory using the “Secondary Resource” field. For instance, if your use case requires a “/python/main.py” file and main.py depends on a module defined in /python/modules, you can specify /python, and the check runner will recognize the module because it is able to “search” the /python folder for secondary resources.

For example, if “local_module_sample.py” depends on a subfolder in /python, you can specify the project like so:

Script Runner: Python is pre-selected (as the only choice).

Script Arguments: These will be provided if we enter them on the command lines. Enter http://example.com So, we will pass this argument to our script.Location: So now let's look at all of our private locations to use this. This example uses the Sweden Stockholm Amazon location. Click Next,

Note

Location: you must use either the “+1 Sweden, Stockholm, [amazon]” location OR a private agent with the necessary software installed to run the check! Not all check locations have the necessary software required to run the check.

Consult Apica Support or your TAM if you would like more information on running Scripted Checks on a private agent.

Step 3 Interval, Thresholds & Monitor Groups

In this example, we will be creating a manual check.

Select an interval, if needed, and check the groups you want this check to be a part of.

Click Next.

Confirm

your

Your Check

A Confirmation Page will be displayed for you to either go Back to edit it or Create to continue.

If you are satisfied, you click Create to create the check.

Check Created

Uncheck Enable Failover (which is checked by default) because we don't want to have that enabled right now, as this is just for demo purposes.
Set the max attempts to 1 because we want the check to fail quickly for the test.
Click Save.

Apica generally recommends these settings for testing because what can happen is too long with the default behaviors. If Max Attempts remains at three and the Attempt Pause for each attempt is 30 seconds, this means that your test check could wait up to 90 seconds if it's failing. And so these settings don't help when trying just to debug something; it's better to have the information that your check failed from the beginning.

Click the Check Details button in the upper right as we're ready to run our check.

Check Details Page

The Check Details page has a section called "Status Last 24 Hours," and beneath that will be a "Run Check" icon. Click to run manually.

Check Results

In this example, we set the “Last Value” to the status code by assigning it to the variable “value” in the script.

Drill down

Drilling into these results, we see the Result value (ms) is 200 because, even though the typical value for a result is the number of milliseconds it took to respond, we specified in our JSON that the value would be the response status code, so the 200 is displayed in its place. The number of Attempts is shown as 1, and beneath the result, code is the JSON that we specified:

Code Block

language	py

json_return = {
    "returncode": 0,
    "start_time": start_time,
    "end_time": end_time,
    "message": "URL call returned status code: " + str(response.status_code),
    "unit": "ms",
    "value": response.status_code,
    "headed count": len(response.headers),
    "content_size": len(response.content),
    "headers": dict(response.headers)
}

Messaging via JSON

From Returned Value Table View, note the message it says URL call return status code 200. But this is the message that we sent inside of our JSON. So message when you set it will be placed here.

So you can record any data you like, and it will show up here.

...

In the next section, we will review how to retrieve your check information through the API.

...

3.

...

Interpreting the Check Results in ASM

After creating our new check, using a Python script that we uploaded into GitHub, we know that the script presents the HTTP status code of the URL called as the value of the result in ASM. Next, we will use the ASM API to get information about this check.

...

We've scripted our check (in this example, Python).
We've uploaded a script to GitHub.
We’ve created our ASM check using a script in a GitHub repository.
We've run our check in ASM and viewed the results.
We've pulled the results for the API, including the custom JSON.

...

Appendix

Adding a Custom Python or NodeJS Module to ApicaNet for use with Scripted Checks

...

Version	Old Version 11	New Version 12
Changes made by	Caleb Miller	Caleb Miller
Saved on	Oct 18, 2023	Oct 18, 2023

Page Comparison

Versions Compared

Key

Why Use a Scripted Check?

Scripted Check Overview

Document Scope

1. GitHub Setup (Optional; Getting Started with GitHub)

Create a GitHub repository

Log into GitHub.

Create GitHub Personal Access Token

Getting the Personal Access Token

Generate New Token

GitHub generates your token

2. Scripting an Example Python Check

Import Libraries (as needed)

Set the URL Request

Creating an Example Scripted Check

1. Scripting the Check

Import Libraries (as needed)

Set the URL Request

Add JSON format

Expanding the Returned values

Advanced JSON

4. (0ptional) Putting the Script into GitHub.

Open GitHub

Upload your script into your new repository

Using the UI

5. Creating an ASM Check

2. Uploading the Check to a Repository

3. Uploading and Running the Check in ASM

Open ASM

Add Script via Run Python.

Creating a Run Python Check, Step 1

Run Python Step 2

Step 3 Interval, Thresholds & Monitor Groups

Confirm

Your Check

Check Created

Check Details Page

Check Results

Drill down

Messaging via JSON

3.

Interpreting the Check Results in ASM

Appendix

Adding a Custom Python or NodeJS Module to ApicaNet for use with Scripted Checks