To use the Availability 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 applicable only to 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.
.ts file applicable only to Scripted Browser
monitor type. You can use .ts TypeScript when working with
Playwright. For information about Playwright, see https://playwright.dev/docs/intro.
.js file applicable only to 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 Availability 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.
If the script type is
side or playwright, the
Script builder and Inline
editor tabs are available.
Script builder: Provides
a table view of all the commands in an user friendly format.
Use Script builder
to add, update or delete side commands in the script
content in an easier way than using the
Inline editor.
Click
Add command to add commands using
the Script builder.
A window is displayed in the right side
where you can add the
Command,
Target and
Value.
If the Command
selected to add is open or
click, then a radio button is
displayed with options: Page
Title or Comment.
Page Title: If
selected, a custom page title can be used. For
example, if the user wants to pass Login
page as a custom page title, then
Page Title needs to get selected
and enter the value: Login page
under Comment.
Comment: If
selected, enter the comment value under
Comment.
Under Reference,
you can see information about the command.
When finished, click Add
Above or Add
Below.
Click Actions to
Edit,
Clone,
Disable,
Reset or
Delete commands.
Use Edit to update an existing
command.
Use Clone to clone a new command
from an existing one.
Use Disable to disable a
command.
Use Reset to reset the script
content to its initial version (when the user
uploaded the script).
Use Delete to delete commands.
Click a
Command row from within the
table to View command
details.
Click the action
menu to View command details,
Add command,
Edit,
Clone or
Delete.
Use
Enable/Disable Command to
enable or stop the execution of any command at row
level.
Inline editor: Provides
easy navigation to edit the script contents with the
following features:
Use of line numbers with expand and
collapse option to view the code easily.
A map is available at the right side
for faster navigation and location of script
sections.
Search and replace functionality within
the editor.
Script validation feature.
Click the Help
link located at the right side to see the following
options:
Custom
marker: Copy the commands and values
to the script and add them in the editor.
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.
Custom
screenshot: Copy the commands and add
them in the editor 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.
Time based
OTP: Copy the commands and add them in
the editor to generate time-based OTP during test
executions. You can add your secret key when using
this option.
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, .playwright 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 Availability 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.
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. See the below
formats:
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:
Replace customMarker with the value of the
CustomMarker dimension and CustomOperation with the
operation to be performed on the dimension. Here's an
example:
console.log("oraSynCustomMarker:setValue:SetMarker"); // capturing the marker from the starting of the script
console.log("oraSynCustomMarker:startTime:PageDuration"); // setting the starting marker
console.log("oraSynCustomMarker:endTime:PageDuration"); // setting the end marker of the respective starting marker
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 and .ts
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:
Availability Monitoring 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:
Side script:
{
"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:
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.
Playwright script:
The command to generate the TOTP is
oraSynTimeBasedOTP. This command accepts the secret
key that is required to generate the TOTP.
console.log("oraSynTimeBasedOTP:<value>")
Example:
var oraSynTimeBasedOTP = ''; // Mandatory to define. This variable holds the TOTP value.
console.log('oraSynTimeBasedOTP:1ABCDE1A1XTXVOIDQRZP1ZXTZAUDLIBJZ'); // This is normal parameter format to provide the MFA secret.
await page.getByRole('textbox', { name: 'Enter One Time Passcode'}).fill(oraSynTimeBasedOTP); // Here the TOTP value will be utilized to fill in the TOTP text input field.
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,
.ts or .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:
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, Siderunner and
Playwright monitors to access the Vault secrets.
To use Vault secrets with Resource Principal, do the following:
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).
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>
Add Vault parameters in the script with the RESOURCE_PRINCIPAL
keyword
Provide the appropiate syntax in the js
, side or playwright 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.
Side
example:
For side, the script looks like the
following
example::