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 thepostman-request
package. For information on thepostman-request
package, see postman-request.
To upload the script to Application Performance Monitoring:
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:
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 theendTime
operation.endTime
: Records the duration of time between thestartTime
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 beoraSynCustomMarker
for it to be recognized as a custom command. The values for command parameterstarget
andvalue
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)
ReplacecustomMarker
with the value of the CustomMarker dimension andCustomOperation
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
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.
.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>
- A specific vault:
-
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 usevaultRegion
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 is255
. -
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.
- Create a dynamic group on monitor resource type.
Add the one of the following rules to allow all monitor resources of resource-type
apmsyntheticmonitor
to access Vault secrets:- Option 1:
All {resource.type='apmsyntheticmonitor'}
Use this option if you have a single resource (such as a single monitor).
- Option 2:
ANY {resource.type='apmsyntheticmonitor'}
Use this option if you have a single resource (such as a single monitor) or if you have multiple resources (such as APM Domain and others).
- Option 1:
- Add policy to allow access to Vaults using Resource Principals:
Allow dynamic-group <vault dg> to read to secret-family in compartment <compartment-name>
Optional: For cross tenancy Vault secrets access, do the following:
- Add policies to the APM Domain tenancy:
DEFINE tenancy vault_tenancy as <ocid_of_vault_tenancy> ENDORSE dynamic-group apm_domain_tenancy_dynamic_group to read secret-family in tenancy vault_tenancy
- Add policies to the Vault tenancy:
DEFINE tenancy apm_domain_tenancy as <ocid_of_apm_domain_tenancy> DEFINE dynamic-group apm_domain_tenancy_dynamic_group as <ocid_of_apm_domain_tenancy_dynamic_group> ADMIT dynamic-group apm_domain_tenancy_dynamic_group of tenancy apm_domain_tenancy to read secret-family in compartment <vault_compartment_name>
For information on
DEFINE
,ENDORSE
andADMIT
statements, see Object Storage Documentation. - Add policies to the APM Domain tenancy:
- Add Vault parameters in the script with the
RESOURCE_PRINCIPAL
keywordProvide the appropiate syntax in the
.js
script or.side
script.Along with the Vault secret OCID and region, aRESOURCE_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); });