Create a Script

To use the Synthetic Monitoring feature for the Scripted Browser and Scripted REST monitor types, you must first create and upload a script, which is a recorded user path that is used to simulate user transactions on the application.

The script must be recorded in the following file types based on the monitor type you want to create using the script:

.side file for the Scripted Browser monitor type. The .side is created using the Selenium Integrated Development Environment (IDE) recorder. For information on Selenium commands and how to export a .side file, see Selenium Documentation. Note that you can only upload a single script to Application Performance Monitoring, uploading a suite of tests is not supported.
.js file for the Scripted REST monitor type. The .js file can be created using the postman-request package. For information on the postman-request package, see postman-request.

To upload the script to Application Performance Monitoring:

Sign in to the Oracle Cloud Infrastructure console.
Open the navigation menu, click Observability & Management. Under Application Performance Monitoring, click Synthetic Monitoring.
On the left pane, click Scripts.
On the left pane, select the compartment and the APM domain in which you want to create the script.
Click Create Script.
The Create Script wizard is displayed.
On the Script Definition page, drop or select the script file.
After the script file is uploaded, details of the script such as when it was modified, size, and type are displayed along with the following fields:
- Script: Name of the script file.
- Content: Contents of the script file.
  If specified in the script file, the script parameters are displayed too and you can choose to retain the default values or replace them. You can also choose to use the Value is secret option against the parameter to make the value secret, which will then not be displayed when the script is used to create a scripted monitor or when the script is edited. This is especially useful in ensuring that confidential information such as passwords are not visible when editing the script.
  
  The following icons displayed above the contents of the script file enable you to edit the script:
  - : Click to add custom marker commands and values to the script. This enables you to pass a custom dimension, for example, "DURATION: Check Elements" and operation, for example, setValue/startTime/endTime from the script to Metrics Explorer in the Oracle Cloud Infrastructure Monitoring service.
  - : Click to add a custom screenshot command to a .side script. This enables you to capture custom (on-demand) screenshots at a particular instance in the script. Similar to the functionality available for standard screenshots, you can view and download custom screenshots in the History section of the <name of the monitor> page.
  For information on the commands to add custom variables, markers, and screenshots, see Advanced Options to Update Scripts.
Verify the details and click Next.
On the Tags (Optional) page, you can choose to use the Tagging metadata system to organize and track the scripts, and click Next.
If tags are added to the script, then you can filter and view scripts on the Scripts page using Tag Filters on the left pane.
For information on Tagging, see Tagging Overview.
On the Summary page, review the summary of the script, and click Create.

The <name of the script> page is displayed. This page includes two tabs: Script Information with information such as the name of the script file, when it was created, modified, and uploaded, the OCID assigned to it, the type of script, and parameters, if specified in the script. The Tags tab has information about the tags added to the script, if any.

You can also use the options available on the top of the page to perform the following actions on the script:

Edit: Click to edit the script. Note that if a monitor is using this script, then editing the script may result in incompatible parameters and you'll have to make the corresponding modifications to the monitor too.
View: Click to view the script.
Download: Click to download the script (.side or .js) file.
Add Tags: Click to add tags to the script.
Delete: Click to delete the script. Note that if a monitor is using this script, then you cannot delete the script.

At the bottom of the page, you can view the list of monitors using the script or click Create Monitor to create a scripted monitor. For information, see Create a Monitor.

Advanced Options to Update Scripts

The scripts in Synthetic Monitoring enable you to record user paths and simulate user transactions in an application.

You can update the script with custom commands to perform certain tasks, and the following sections detail some of the commands you can add to the script:

Note

It's recommended that you always use an original script and upload and validate it in a scripted monitor run in Application Performance Monitoring, before you edit it and make changes. Updating the script with custom content such as variables may interfere with running the script again from your local Selenium IDE deployment.

Add Custom Variables

You can add custom variables to the contents of the .side and .js scripts, which can be used to define dynamic parameters. This enables you to control these parameters from the script or monitor in Application Performance Monitoring. For example, if you expect a user name or element selection name to change or if you want to make such a value a secret so others who have access to the monitor cannot see the value, then you can use custom variables.

Here's the format:

<ORAP><ON>param name</ON><OV>param value</OV><OS>isParamValueSecret(true/false)</OS></ORAP>

When adding custom variables to the contents of the script, the param name is mandatory, but the param value and isParamValueSecret are optional. The default value for isParamValueSecret is false.

Add Custom Markers

You can add custom marker commands to the contents of the .side and .js scripts, which can be used to pass a custom message and duration from the script to Metrics Explorer in the Monitoring service. This enables you to pass a CustomMarker dimension, for example, "DURATION: Check Elements" and operation, for example, setValue to the Monitoring service. The CustomMarker dimension is available with the CustomMetric metric and using this dimension, you can add the following operations to the script as duration markers for transaction steps, such as the duration of time between log in and full page load:

setValue: Records the duration between the script start time to the time this operation is called.
startTime: Records the duration of time between this operation and the endTime operation.
endTime: Records the duration of time between the startTime operation and this operation.

Note that the startTime and endTime operations work in conjunction with each other. For a CustomMarker containing the startTime and endTime operations, the metric value is <endTime - startTime>.

Here are the commands and examples of the CustomMarker dimension and operations:

.side script: Add command blocks with the operation you want to perform. The command value should be oraSynCustomMarker for it to be recognized as a custom command. The values for command parameters target and value should be the value of the CustomMarker dimension and the operation respectively.

Here's the command used to capture a custom marker in a .side script:

{      
    “id”: “36d45a35-5c07-4d86-8144-90ee7b52260b”,      
    “comment”: “”,      
    “command”: “oraSynCustomMarker”,      
    “target”: “Add Marker Name”,      
    “targets”: [],      
    “value”: “setValue”
}

Here's an example:

{      
    “id”: “36d45a35-5c07-4d86-8144-90ee7b52260b”,      
    “comment”: “For calling synthetic monitoring custom metrics”,      
    “command”: “oraSynCustomMarker”,      
    “target”: “DURATION: Check Elements”,      
    “targets”: [],      
    “value”: “setValue”
}

.js script: Add the following command:
```
oraSynCustomMarker(customMarker, customOperation)
```
Replace customMarker with the value of the CustomMarker dimension and CustomOperation with the operation to be performed on the dimension. Here's an example:
```
oraSynCustomMarker("DURATION: Check Elements", "setValue")
```

You can also create Alarms in the Monitoring service using CustomMetric and the CustomMarker dimension to be notified when the metric meets alarm-specified triggers. For information on the Alarms feature and how to create them, see Managing Alarms.

Add Custom Screenshots

You can add a command to .side scripts to capture custom screenshots. This functionality enables you to take screenshots at any point during the execution of the script to diagnose issues. You can take a maximum of ten custom screenshots in addition to the standard screenshots.

Here's the command used to capture a custom screenshot:

{
    "id": "e227f32f-47f6-432b-976a-6b5db5b53e94",
    "comment": "",
    "command": "oraSynCustomScreenshot",
    "target": "AddScreenshotName",
    "targets": [],
    "value": "true"
}

Use Multi-Factor Authentication (MFA)

Synthetic Transactions supports Multi-Factor Authentication (MFA) that generates a Time-Based One-Time Password (TOTP) token that is given the authentication secret. For the generation of this TOTP you need to provide the secret key during the creation of the monitor.

To use MFA, in the script, you need to include the command oraSynTimeBasedOTP , and then enter the variable ${oraSynTimeBasedOTP} where the TOTP value should be used:

{
    "id": "123abc12-12ab-1a12-1a2a-1234ab123abc",
    "comment": "",
    "command": "oraSynTimeBasedOTP",
    "target": "1ABCDE1A1XTXVOIDQRZP1ZXTZAUDLIBJZ",
    "targets": [],
    "value": ""
}
// After providing the command, user needs to provide the variable.
{
    "id": "123abc12-12ab-1a12-1a2a-1234ab123abc",
    "comment": "",
    "command": "type",
    "target": "id=mfa_token",
    "targets": [
        ["id=mfa_token", "id"],
        ["name=mfa_token", "name"],
        ["css=#mfa_token", "css:finder"],
        ["xpath=//input[@id='mfa_token']", "xpath:attributes"],
        ["xpath=//div[@id='root']/div[3]/div/div[2]/form/div/div/input", "xpath:idRelative"],
        ["xpath=//div/input", "xpath:position"]
    ],
    "value": "${oraSynTimeBasedOTP}"
 }

The command to generate the TOTP is oraSynTimeBasedOTP. This command accepts the secret key that is required to generate the TOTP. The secret key should be passed as a target. It can be passed as a normal variable or a sensitive variable:

Normal parameter:

{    
    "id": "123abc12-12ab-1a12-1a2a-1234ab123abc",        
    "comment": "",    
    "command": "oraSynTimeBasedOTP",        
    "target": "1ABCDE1A1XTXVOIDQRZP1ZXTZAUDLIBJZ",    
    "targets": [],    
    "value": ""
}

Sensitive or like password parameter:

{   
        "id": "123abc12-12ab-1a12-1a2a-1234ab123abc",       
        "comment": "",       
        "command": "oraSynTimeBasedOTP",       
        "target":
        "<ORAP><ON>MFA_Secret</ON><OV>1ABCDE1A1XTXVOIDQRZP1ZXTZAUDLIBJZ</OV><OS>true</OS></ORAP>",       
        "targets": [],       
        "value": "" 
}

{    
        "id": "123abc12-12ab-1a12-1a2a-1234ab123abc",
        "comment": "",    
        "command": "type",
        "target": "id=mfa_token",
        "targets": [        
            ["id=mfa_token", "id"],
            ["name=mfa_token", "name"],
            ["css=#mfa_token", "css:finder"],        
            ["xpath=//input[@id='mfa_token']", "xpath:attributes"],
            ["xpath=//div[@id='root']/div[3]/div/div[2]/form/div/div/input", "xpath:idRelative"],
            ["xpath=//div/input", "xpath:position"]
        ],
        "value": "${oraSynTimeBasedOTP}"
}

You need to mention where the TOTP (which is generated ) should be used. Generally, TOTP will be entered as a value in the respective TOTP text input field. TOTP would be stored in variable name ${oraSynTimeBasedOTP}. You need to provide the variable name as ${oraSynTimeBasedOTP} where the TOTP value will be entered:

Using Vault Secrets

Note

Currently, Vault secrets authentication in public vantage points and dedicated vantage points are done using S2S and Instance Principals respectively. S2S and Instance Principal cannot be used in On-Premise Vantage Points.

For On-Premise Vantage Points, you need to use Resource Principal. Once the keyword RESOURCE_PRINCIPAL is added to the script, the resource principal will be used for authenticating Vault Secrets. This works in all kinds of vantage points. For information, see Using Vault Secrets with Resource Principals.

You are able to specify Vault secrets in .side/.js scripts which will get resolved at runtime. This allows you to update variables such as usernames and passwords dynamically, without updating the scripts or restarting the monitors. Simply create secrets in the vault and use them in scripts which will be resolved during monitor execution by setting the following policies in your tenant:

Public Vantage Points Policy

You can set policies for the APM service to access secrets in a specific vault or compartment:

A specific vault:

Allow service applicationperformancemonitoring to read secret-family in compartment <compartment-name> where all 
{target.vault.id=‘ocid1.vault.oc1.<vault-ocid>’ , any 
{target.vaultsecret.id=‘ocid1.vaultsecret.oc1.phx.<secret-ocid1>, target.vaultsecret.id=‘ocid1.vaultsecret.oc1.phx.<secret-ocid2>}}

A specific compartment, using the name of the compartment:

Allow service applicationperformancemonitoring to read secret-family in compartment <compartment-name>

A specific compartment, using the id of the compartment:

Allow service applicationperformancemonitoring to read secret-family in compartment id <compartment-ocid>

Dedicated Vantage Points Policy

You can set policies for the APM service to access secrets in a compartment using the name or the id of the compartment:
- A specific compartment, using the name of the compartment:
```
Allow dynamic-group  <dvp dynamic group eg stack-11-aug-apmSyntheticDVP-dg> read secret-family in compartment <compartment-name>
```
- A specific compartment, using the id of the compartment:
```
Allow dynamic-group  <dvp dynamic group eg stack-11-aug-apmSyntheticDVP-dg> read secret-family in compartment id <compartment-ocid>
```
Depending on the type of script, use the following syntax:
- Use the following syntax in the .side script:
```
<ORAS>secretOcid</ORAS><ORASREG>vaultRegion</ORASREG>
```
  For example:
```
<ORAS>ocid1.vaultsecret.oc1.phx.abcdefghijklmnopqrstuvwxyz123456789</ORAS><ORASREG>us-phoenix-1</ORASREG>
```
- Use the following syntax in the .js script:
```
method: 'GET',
url:'<ORAS>secretOcid</ORAS><ORASREG>vaultRegion</ORASREG>'
```
  For example:
```
method: 'GET',
url:'<ORAS>ocid1.vaultsecret.oc1.phx.abcdefghijklmnopqrstuvwxyz123456789</ORAS><ORASREG>us-phoenix-1</ORASREG>'
```
This secretOcid will be resolved during execution to fetch current secret values.

<ORASREG> syntax is optional. It can be used when your vault service is in a different region as the monitors. You can use vaultRegion to specify in which region your vault is and secrets will be resolved from there. It enables the same script to be used across regions. Please note that only one <ORASREG>region</ORASREG> should be present in the script.

Note

Maximum length for secret value is 255.

Using Vault Secrets with Resource Principals

You can update the script to use Vault secrets with Resource Principals.

Resource Principal-based support is added to access Vault secrets. Resource Principal-based policies can be added to allow Rest and Siderunner monitors to access the Vault secrets.

To use Vault secrets with Resource Principal, do the following:

Create a dynamic group.
Create a dynamic group on monitor resource type.
Add the below rule to allow all monitor resources of resource-type apmsyntheticmonitor to access Vault secrets.
```
All {resource.type='apmsyntheticmonitor'}
```

Add a policy.

Add the below policy to allow access to Vaults using resource principals:

Allow dynamic-group <vault dg> read to secret-family in compartment <compartment-name>

Add Vault parameters in the script with the RESOURCE_PRINCIPAL keyword

Provide the appropiate syntax in the .js script or .side script.

Along with the Vault secret OCID and region, a RESOURCE_PRINCIPAL keyword needs to be passed.

Note

It needs to be added only in one of the Vault params.

For example, the command line from the script might look similar to the following:

 "command": "<ORAS>ocid1.vaultsecret.oc1.phx.amaaaaaatttttuuuuaa</ORAS><ORASREG>us-phoenix-1</ORASREG><ORASAUTH>RESOURCE_PRINCIPAL</ORASAUTH>",

For more information, see Using Vault Secrets.

JS file changes

For SCRIPTED_REST monitor, use the RESOURCE_PRINCIPAL keyword in the script.

For example, see the following .js script:

var request = require('postman-request');
var options = {
 method: '<ORAS>ocid1.vaultsecret.oc1.phx.amaaaaaafpqv5yya7p2uv63scv37yz64u75x47ajuibwoynro3ygbu2rrtxa</ORAS>',
 url: '<ORAS>ocid1.vaultsecret.oc1.phx.amaaaaaafpqv5yyagfnrwsjmoabretgffs4nkfocrfokvnldtt7nee7htsya</ORAS><ORASREG>us-phoenix-1</ORASREG><ORASAUTH>RESOURCE_PRINCIPAL</ORASAUTH>'
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(response.statusCode);
});

Oracle Cloud Infrastructure Documentation

Advanced Options to Update Scripts

Using Vault Secrets with Resource Principals