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 Availability 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)

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:

{
    "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

1. 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>

2. 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>

3. 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.