To set up the Synthetic Monitoring feature, you must create a monitor to monitor the availability and performance of your application across geographical locations and send metrics to Oracle Cloud Infrastructure.

1. Navigate to the Synthetic Monitoring page.
2. On the left pane, ensure that Monitors is selected.
3. On the left pane, select the compartment and the APM domain in which you want to create the monitor.
4. Click Create Monitor.
   The Create Monitor wizard is displayed.
5. On the Monitor Definition page:
   1. Name: Enter a unique name for the monitor.

      The name can have a maximum of 255 alphanumeric characters. A hyphen and an underscore are the only two special characters allowed. For example, you can add a hyphen between two characters and an underscore at the beginning or the end of the name or between characters. Blank spaces are not allowed.

   2. Type: Select one of the following monitor types:
      • Browser: Tests the performance of a single URL loaded by a browser.
      • Scripted Browser: Tests the performance of a complete user transaction workflow recorded in a .side script file.
      • REST: Tests the performance of a single URL loaded by a REST call.
      • Scripted REST: Tests the performance of a complete user transaction workflow recorded in a .js script file.
      • Network:Tests the availability and performance of any network server or host which gets accomplished by pinging the host.
      • DNS: Validates and tests the availability of the DNS.
      • SQL: Measures the performance of a SQL query allowing the user to spot any availability or load time issues.
      • FTP: Measures the performance of FTP operations allowing the user to spot any availability or latency issues. It takes target FTP server details as input and runs the requested operation to generate various timing metrics.
   3. Update the fields displayed based on the monitor type selected in the previous step:
      • For the Browser monitor type:
        1. Base URL: Specify the base URL on which to run the monitor.
        2. Response Validations: Optionally, select the following check box:
           • Response Code: Specify valid HTTP status codes separated by commas. For example: 200,401. It also accepts the following format: 2xx, 3xx, 4xx.
           • Verify Response Content: Add a string or REGEX to verify expected response in response headers and body.
        3. Verify Response Content Optional: Optionally, add a string to verify expected response content. For details, see Verify Response Content (Optional).
        4. Options: Optionally, select the following check boxes:
           • Verify SSL: Select this option to verify the validity of the SSL certificate.
           • Enable Snapshot: Select this option to enable or disable the monitor to collect screenshots during the execution. By default, it's enabled.
           • Override DNS: Select this option to specify the IP address to which the target's domain name will resolve, instead of using the standard DNS resolution.
      • For the Scripted Browser monitor type:
        1. Script: Select a script file from the drop-down list, which is populated with the names of the .side scripts you've created.
        2. Base URL Optional: Based on the selected .side script file, this field is populated with the base URL on which the monitor is to be run. Optionally, you can also specify the base URL in this field.
        3. Script Parameters: If script parameters are defined in the contents of the script file, then they are displayed in the Script Parameter fields and you can choose to replace the parameter values. Note that the parameter value is not displayed if the Value is secret option is used when creating or uploading the script.
        4. Options: Optionally, select the following check boxes:
           • Verify SSL: Select this option to verify the validity of the SSL certificate.
           • Enable Snapshot: Select this option to enable or disable the monitor to collect screenshots during the execution. By default, it's enabled.
           • Override DNS: Select this option to specify the IP address to which the target's domain name will resolve, instead of using the standard DNS resolution.
      • For the REST monitor type:
        1. Base URL: Specify the base URL on which to run the monitor.
        2. Request Configuration Method: Select a request configuration method: GET or POST. For the POST method, you can optionally enter the request payload information in the Request Body field.
        3. Authentication Type: Select a type of authentication:
           • None: Select this option if no authentication is required.
           • Basic Auth: Select this option if basic authentication is required and specify the User Name and Password.
           • Bearer Token: Select this option if bearer authentication is required and specify the Token.
           • OAuth: Select this option if open authentication is required and specify the Authentication Scheme and information in the fields that are displayed based on the authentication scheme.
           • Resource Principal: Select this option to grant access and monitor OCI resources, such as object storage or vault, without specifying credentials. It uses a dynamic group and policies which provides fine-grained control.
             Note
             
             To use resource principal authentication, you need to create a dynamic group and add polices to it to access the resources in the tenancy and grant APM Synthetic monitors access to OCI resources in their tenancy. For details, see Perform Oracle Cloud Infrastructure Prerequisites.
        4. Query Parameters Optional: Optionally, specify the request configuration query parameters.
        5. Header Parameters Optional: Optionally, specify the request configuration header parameters.
        6. Client Certificate Optional: Optionally, specify the certificate information for client authentication.
           • Private Key: Upload the private key file.
           • Certificate: Upload the client certificate file.
             Note
             
             PEM format is supported for the private key and client certificate.
        7. Response Validations: Optionally, select the following check box:
           • Response Code: Specify valid HTTP status codes separated by commas. For example: 200,401. It also accepts the following format: 2xx, 3xx, 4xx.
           • Verify Response Content: Add a string or REGEX to verify expected response in response headers and body.
        8. Options: Optionally, select the following check boxes:
           • Verify SSL: Select this option to verify the validity of the SSL certificate.
           • Follow Redirects: Select this option to follow redirects.
           • Override DNS: Select this option to specify the IP address to which the target's domain name will resolve, instead of using the standard DNS resolution.
      • For the Scripted REST monitor type:
        1. Script: Select a script file from the drop-down list, which is populated with the names of the .js scripts you've created.
        2. Base URL Optional: Based on the selected .js script file, this field is populated with the base URL on which the monitor is to be run. Optionally, you can also specify the base URL in this field.
        3. Script Parameters: If script parameters are defined in the contents of the script file, then they are displayed in the Script Parameter fields and you can choose to replace the parameter values. Note that the parameter value is not displayed if the Value is secret option is used when creating or uploading the script.
        4. Authentication: Optionally, select the following check box:
           • Resource Principal: Select this option to grant access and monitor OCI resources, such as object storage or vault, without specifying credentials.
             Prerequisites: To use Resource Principal authentication, perform the following prerequisites:

             • Policies: Create a dynamic group and add polices to it to access the resources in the tenancy and grant APM Synthetic monitors access to OCI resources in their tenancy. For details, see Perform Oracle Cloud Infrastructure Prerequisites.
             • Java Script file changes: Make the following changes in the script:
               • Include oci-common module

                 const common = require('oci-common');

               • Create signer

                 const provider = common.ResourcePrincipalAuthenticationDetailsProvider.builder();const signer = new common.DefaultRequestSigner(provider)

               • Sign Request

                 signer.signHttpRequest(options)

               • Copy headers

                 var headers = {};

                 options.headers.forEach(function(i,v){

                 headers[v] = i;

                 });

        5. Response Validations: Optionally, select the following check box:
           • Response Code: Specify valid HTTP status codes separated by commas. For example: 200,401. It also accepts the following format: 2xx, 3xx, 4xx.
        6. Options: Optionally, select the following check box:
           • Override DNS: Select this option to specify the IP address to which the target's domain name will resolve, instead of using the standard DNS resolution.
      • For Network monitor type:
        1. Base URL: Specify the server on which to run the monitor.
           The IP address or the fully qualified domain name (FQDN) of the server are accepted values. For example:

           • 192.168.1.1
           • example.com
           Note
           
           If using TCP protocol, you need to also provide the port number. For example:

           • 192.168.1.1:8080
           • example.com:80
        2. Protocol: Specify the network protocol to be used by the monitor. It can be TCP or ICMP.

           If TCP is selected, the port number is mandatory for the Base URL parameter.

           If ICMP is selected, the port number is not required.

        3. Probe Mode: Specify the probe mode for the TCP network protocol. It can be: SACK or SYN. Note Probe Mode is only available for the TCP network protocol.
        4. Enable IPV6: If checked, provide a Target which can be either a domain name or in the following format: [IPv6]:port. For example: format: [2001:db8:3333:4444:5555:6666:7777:8888]:90 or oracle.com:90.
      • For DNS monitor type:
        1. Configuration type: Select a configuration type for the DNS monitor:
           • DNS Server: It runs queries against target server. It measures resolution time and availability for the target along with network metrics if enabled.
           • DNS Trace: It validates the DNS requests that are correctly delegated to the authoritative servers in child zone from parent zone.
           • DNSSEC: It validates the authenticity of DNS records according to Domain Name System Security Extensions. It provides view for DNSSec Trust Tree and Data Chain.
        2. Domain: Specify the domain name or IP address to be used by the monitor.
        3. Record Type: Specify the DNS record type to be used by the monitor using the dropdown list available.
        4. Send recursive queries: Check the checkbox if you want to send DNS queries in recursive mode. This option is only available if the DNS Server monitor configuration type is selected.
        5. Transport Protocol: Specify the network protocol using the dropdown list. It can be: TCP or UDP.

           This option is available if the DNS Server or DNS Trace monitor configuration types are selected.

        6. DNS Server: Specify the domain name or the IP address of DNS name server that will be queried for the domain name in the domain field.

           This option is only available if the DNS Server monitor configuration type is selected.

        7. Enable IPV6: If checked, provide an IPv6 address or a domain name for DNS Server. If Record Type is PTR, then the Domain should be using the following format: 0.f.e.d.c.b.a.9.8.7.6.5.4.3.2.1.0.f.e.d.c.b.a.9.8.7.6.5.4.3.2.1.ip6.arpa. IPv6 PTR records are stored under the .ip6.arpa domain.
      • For SQL monitor type:
        1. Database type: Select the database type. Currently supported Oracle and MySQL.
        2. Username: Specify the username for database authentication. (Required).
        3. Password Type: Specify the type for database authentication. The following are the two supported formats:
           • Secret OCID: OCI vault secret ocid. For details, see Using Vault Secrets with Resource Principals.
           • Text: Password in plain text format.
        4. Password: The password/secret ocid for database authentication. (Required). For details, see Using Vault Secrets with Resource Principals.
        5. Database role: Specify the database role. (Optional).

           For Oracle database and SYS database user, you must provide the database role SYSDBA or SYSOPER.

           It's recommended to create monitor with a database user that has minimum privileges.

        6. Database connection type: Specify the connection type for database. The following two types are supported:
           • Custom JDBC: For this type, the Custom JDBC URL is required.
           • Cloud Wallet: This option is only available when selecting Oracle database.
             1. Database wallet: Specify the database cloud wallet configuration zip file. (Required).
             2. Service name: Specify the database Service name to be used in establishing connection. (Required).
        7. SQL Query: Specify the SQL query to fetch data from database. Only select statement is allowed. (Required).
      • For FTP monitor type:
        1. Protocol type: The protocol supported by target FTP server (Required).

           The following types are supported: FTP, FTPS and SFTP.

        2. Request type: The request to get performed by FTP. (Required).

           The following types are supported: Download, Upload and List.

        3. Path: The absolute path to the file or directory.

           Mandatory only if Download request type is selected.

           Optional if Upload and List request types are selected. If no path is specified for Upload and List, the home directory of the FTP user which was specified in the authentication, is used as default path.

        4. File size: The upper limit of the file size for Download and Upload request types.

           Mandatory only for upload request type.

        5. Verify Content: Only available in List request type. (Optional).

           User can specify regex to list specific files.

        6. Active Mode: Only supported for FTP and FTPS protocols. (Optional).

           It controls the mode of data transfer and is handled internally by the FTP client library. If enabled, the client establishes the command channel and the server establishes the data channel.

        7. Authentication:: (Required)
           • Username: The username for ftp authentication.
           • Password type: The type for the authentication. (Optional).

             The following types are supported:

             1. Secret OCID: OCI vault secret ocid. For details, see Using Vault Secrets with Resource Principals.
             2. Text: Password in plain text format.
           • Password: The password or secret ocid for authentication. For details, see Using Vault Secrets with Resource Principals.

   Click Next.

6. On the Run Settings page:
   1. Vantage Points: Select the vantage points on which you want the monitor to run. If you've set up a Dedicated Vantage Point, then it is also listed in the drop-down list and can be selected. For information on Dedicated Vantage Points, see Use Dedicated Vantage Points.
   2. Select one of the following radio buttons to determine the frequency of monitor runs:
      • Interval: Select this radio button to determine the interval of time between each monitor run.
      • Run Once: Select this radio button if you want the monitor to run only once. If the Run Once radio button is selected, the Scheduling Policy drop-down list and the Interval Between Runs (minutes) field are disabled.
   3. Scheduling Policy: Select one of the following options to stagger the monitor runs on the selected vantage points:
      • All: Select this option to run the monitor simultaneously on all selected vantage points.
      • Round Robin: Select this option to schedule the monitor run sequentially on each vantage point. This functionality works in tandem with the value specified in the Interval Between Runs (minutes) field. For example, if 10 minutes is specified in the Interval Between Runs (minutes) field and the monitor is to run on five vantage points, then the monitor will run on the vantage points sequentially with an interval of ten minutes between each run. The total duration of the monitor runs on all vantage points will then be 50 minutes, after which the sequential monitor run will begin again.
      • Batched Round Robin: Select this option to schedule the monitor run sequentially on batches of vantage points. This functionality works in tandem with the values specified in the Interval Between Runs (minutes) and Sub-interval Between Runs (minutes) fields. In this scenario, monitors are scheduled to run on batches of vantage points and the interval between each run is specified in the Sub-interval Between Runs (minutes) field. The value in the Interval Between Runs (minutes) field denotes the total time taken for the monitor run on all batches.

        The number of vantage points in each batch is automatically calculated based on the number of selected vantage points and the values specified in the Interval Between Runs (minutes) and Sub-interval Between Runs (minutes) fields. For example, if there are 7 vantage points, Interval Between Runs (minutes) = 10 minutes, and Sub-interval Between Runs (minutes) = 5 minutes, then two batches are created. The first batch of vantage points will have four vantage points and the second batch will have three.

        
        
        
        
        
   4. Interval Between Runs (minutes): Specify the number of minutes between monitor runs. The default interval duration is 10 minutes. For the REST monitor type, you can specify one minute as the minimum duration of the interval between monitor runs, and for the other monitor types, you can specify five minutes as the minimum duration.

      Note that if the Batched Round Robin option is selected in the Scheduling Policy drop-down list, then the value selected in the Interval Between Runs (minutes) field denotes the total time taken for the monitor run on all batches.

   5. Sub-interval Between Runs (minutes): Specify the number of minutes between monitor runs on batches of vantage points. Note that this field is only displayed if the Batched Round Robin option is selected in the Scheduling Policy drop-down list.
   6. Timeout (minutes): Specify the timeout value. This denotes the maximum runtime allowed and if the monitor runtime does not complete within this time, it will be stopped and marked as a failure. Note that the Interval Between Runs value must be about three times more than the Timeout (minutes) value, however, if the Enable Retry check box is not selected, then the Timeout (minutes) value can be set to 50% of the Interval Between Runs value.
   7. Enable Retry: Select this check box to retry execution in case of failure. Note that this check box is selected by default.
   8. Enable Network Collection: Select this check box to enable data collection from the network and monitor network performance. Note that for a Scripted REST monitor, this check box is only displayed if the Base URL is specified on the Monitor Definition page:

      On selecting the Enable Network Collection check box, the following options are displayed:

      • Protocol: Select a network protocol.
      • Probe Mode: Select a probe mode for the TCP network protocol. Note that the Probe Mode option is only available for the TCP network protocol.
      • Probe Per Hop: Specify the number of probe packets sent per hop.

   Click Next.

7. On the Availability Configuration (Optional) page, you can select the Enable Availability Configuration check box to configure the criteria to calculate the availability of the monitor and view the corresponding details in the Availability widget in the Oracle-defined Monitors dashboard.

   On selecting the Enable Availability Configuration check box, the following options are displayed:

   • Maximum failures allowed per interval: Specify the maximum number of failed monitor runs allowed in an interval. An interval with more than the specified number of failed monitor runs will be classified as UNAVAILABLE.
   • Minimum runs allowed per interval: Specify the minimum number of monitor runs allowed in an interval. An interval with less than the specified number of monitor runs will be classified as UNKNOWN and excluded from the availability calculations.

   Click Next.

   For information on viewing the availability of the monitor in the Monitors dashboard, see View Monitor Availability.

8. On the Tags (Optional) page, you can choose to use the Tagging metadata system to organize and track the monitors, and click Next.
   In the Tag namespace drop-down list, you can select a namespace that is prefixed with apm-synthetics and add a maximum of five Tag keys and Tag values. These key – value pairs will then be added as dimensions and can be used as additional qualifiers for Synthetic Monitoring metrics (oracle_apm_synthetics namespace). This enables you to monitor other aspects of the monitor and organize and track monitors using an APM-specific tag.

   Note
   
   The Tag key name cannot be the same as an existing dimension. You can create any tag namespace but only namespaces that have the apm-synthetics prefix will be picked up and published to the Oracle Cloud Infrastructure Monitoring service as a dimension.

   For information on:

   • Synthetic Monitoring dimensions and metrics, see Available Metrics: oracle_apm_synthetics.
   • Tagging, see Tagging Overview.
9. On the Summary page, review the summary of the monitor.
   If the monitor type is REST, you can click View JS to view the Javascript based on the input provided on the previous steps.

   A window is displayed with the generated Javascript based on the input provided on the previous steps. At the top right corner, you have the following options available: Copy, Download or Create Script.

   If Create Script is selected, the Create Script page is displayed to create a Javascript script. The created script can be used to create SCRIPTED REST monitors later.

   Under the Create Script page, enter the script name, follow the steps and once completed, click Create to create the Javascript script. For details about creating scripts, see Create a Script.

10. Click Create to create the monitor.