NerdGraph tutorial: Manage your synthetic monitors

Our NerdGraph API allows you to automate creating, updating, or deleting your synthetic monitors.

Requirements

Requirements include:

General NerdGraph requirements
Relevant user permissions: the same Synthetics permissions that apply for using the synthetics UI apply for using NerdGraph

Understand fields in NerdGraph explorer

You can view field definitions in NerdGraph explorer, but it may help to better understand the LOCATION, PERIOD, TAGS, and other fields.

To identify a private location in your scripts, use the private location's entity GUID. To verify that a script executes successfully, also include the vsePassword attribute. For example:

locations: {
  private: {
    guid: LOCATION_ENTITY_GUID, 
    vsePassword: YOUR_VSE_PASSWORD
  }
}

Public locations use the location identifier without AWS_, for example:

locations: {
  public: ["US_EAST_2", "US_WEST_1"]
}

The PERIOD attribute defines a time interval for your monitors to execute. To define the interval, use these forms:

EVERY_MINUTE for every minute.
EVERY_N_MINUTES, where 'N' is minutes. Supported values include EVERY_5_MINUTES, EVERY_10_MINUTES, EVERY_15_MINUTES, and EVERY_30_MINUTES.
EVERY_HOUR for every hour.
EVERY_N_HOURS, where 'N' is hours. Supported values include EVERY_6_HOURS and EVERY_12_HOURS.
EVERY_DAY for once a day.

Some fields are for more advanced configurations. These are optional.

For ping monitors, these include:

HEADER_NAME: Your custom header names that appear on the request.
HEADER_VALUE: The custom header value on the request.
REDIRECT_IS_FAILURE: Your monitor reports a failure if it's redirected.
VALIDATION_TEXT: If this text is not included in your monitor's response, it returns a failure.
TLS_VALIDATION: Verifies the validity of the SSL certificate chain.

For simple browser monitors:

RUNTIME_TYPE: The runtime type used by your monitor. "CHROME_BROWSER" is the only accepted value.
RUNTIME_TYPE_VERSION: The runtime type version used by your monitor. "100" is the only accepted value.
SCRIPT_LANGUAGE: The language used in your monitor. "JAVASCRIPT" is the only accepted value.

For scripted API monitors:

SCRIPT_CONTENT: The actual contents of the script. This should not be based64 encoded.
RUNTIME_TYPE: The runtime type used by your monitor. "NODE_API" is the only accepted value.
RUNTIME_TYPE_VERSION: The runtime type version used by your monitor. The only accepted value is 16.10.0.
SCRIPT_LANGUAGE: The language used in your monitor. "JAVASCRIPT" is the only accepted value.

For scripted browser monitors:

SCRIPT_CONTENT: The actual contents of the script. This should not be based64 encoded.
RUNTIME_TYPE: The runtime type used by your monitor. "CHROME_BROWSER" is the only accepted value.
RUNTIME_TYPE_VERSION: The runtime type version used by your monitor. "100" is the only accepted value.
SCRIPT_LANGUAGE: The language used in your monitor. "JAVASCRIPT" is the only accepted value.

For certificate check monitors:

DAYS_UNTIL_EXPIRATION: Notifies you when you need to update your certificate. For example, if you wanted a notification 30 days before the certificate expires, you would input 30.

Use queries to retrieve data

Queries make requests to fetch data. To learn additional query capabilities available to your synthetic entities, check out NerdGraph entities API tutorial.

You can query your synthetic monitors to get current status information about your data or details about the monitor configuration. Some query examples include:

{
  actor {
    entitySearch(query: "domain = 'SYNTH' AND type = 'MONITOR'") {
      results {
        entities {
          ... on SyntheticMonitorEntityOutline {
            guid
            name
            accountId
            monitorType
            tags {
              key
              values
            }
          }
        }
      }
    }
  }
}

You're able to query your private locations:

{
  actor {
    entitySearch(query: "domain = 'SYNTH' AND type = 'PRIVATE_LOCATION'") {
      results {
        entities {
          accountId
          guid
          name
          tags {
            key
            values
          }
        }
      }
    }
  }
}

Querying secure credentials lets you retrieve metadata only, but not the credential values themselves:

{
  actor {
    entitySearch(query: "domain = 'SYNTH' AND type = 'SECURE_CRED'") {
      results {
        entities {
          ... on SecureCredentialEntityOutline {
            accountId
            guid
            name
            tags {
              key
              values
            }
            updatedAt
          }
        }
      }
    }
  }
}

Retrieve the script used in a scripted API or scripted browser monitor. Other monitor types will return an error.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      synthetics {
        script(monitorGuid: "ENTITY_GUID") {
          text
        }
      }
    }
  }
}

Retrieve the steps configured for a step monitor. Other monitor types will return an error.

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      synthetics {
        steps(monitorGuid: "ENTITY_GUID") {
          ordinal
          type
          values
        }
      }
    }
  }
}

Create your synthetic monitors

Below are some sample requests to automate the creation of your synthetic monitors.

Tip

Include the runtime object that includes runtimeType, runtimeTypeVersion, and scriptLanguage to use a newer runtime. Do not include the runtime object and these attributes to continue using a legacy runtime.

Ping monitors check that your application is running. Here's an example for creating one in NerdGraph:

mutation {
    syntheticsCreateSimpleMonitor (
      accountId: YOUR_ACCOUNT_ID 
      monitor: {
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          }, 
        name: "YOUR_MONITOR_NAME", 
        period: PERIOD, 
        status: STATUS, 
        uri: "MONITORED_URI", 
        advancedOptions: {
          customHeaders: {
            name: "HEADER_NAME", 
            value: "HEADER_VALUE"
          }, 
          redirectIsFailure: REDIRECT_IS_FAILURE, 
          responseValidationText: "VALIDATION_TEXT", 
          shouldBypassHeadRequest: BYPASS_HEAD_REQUEST, 
          useTlsValidation: TLS_VALIDATION
        }
      }
  ) {
      errors {
        description
        type
      }
    }
  }

Simple browser monitors use Chrome instances to mimic customer visits. Here's an example for creating one in NerdGraph:

mutation {
    syntheticsCreateSimpleBrowserMonitor (
      accountId: YOUR_ACCOUNT_ID, 
      monitor: {
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          }, 
        name: "YOUR_MONITOR_NAME", 
        period: PERIOD, 
        runtime: {
          runtimeType: "RUNTIME_TYPE",
          runtimeTypeVersion: "RUNTIME_TYPE_VERSION",
          scriptLanguage: "SCRIPT_LANGUAGE"
        }
        status: STATUS, 
        uri: "MONITORED_URI", 
        advancedOptions: {
          customHeaders: {
            name: "HEADER_NAME", 
            value: "HEADER_VALUE"
          }, 
          enableScreenshotOnFailureAndScript: ENABLE_SCREENSHOT, 
          responseValidationText: "VALIDATION_TEXT", 
          useTlsValidation: TLS_VALIDATION
        }
      ) {
      errors {
        description
        type
      }
    }
  }

Scripted browser monitors are more complex interactions with your pages and applications. Here's an example for creating one in NerdGraph:

mutation {
    syntheticsCreateScriptBrowserMonitor (
      accountId: YOUR_ACCOUNT_ID, 
      monitor: { 
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          }, 
        name: "MONITOR_NAME", 
        period: PERIOD,
        runtime: {
          runtimeType: "RUNTIME_TYPE",
          runtimeTypeVersion: "RUNTIME_TYPE_VERSION",
          scriptLanguage: "SCRIPT_LANGUAGE"
        }
        script: "SCRIPT_CONTENT", 
        status: STATUS, 
        advancedOptions: {
          enableScreenshotOnFailureAndScript: ENABLE_SCREENSHOT
        }
      }
    ) {
      errors {
        description
        type
      }
    }
  }

Scripted API monitors check your API endpoints. Here's an example for creating one in NerdGraph:

mutation {
    syntheticsCreateScriptApiMonitor (
      accountId: YOUR_ACCOUNT_ID, 
      monitor: {
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          }, 
        name: "YOUR_MONITOR_NAME", 
        period: PERIOD,
        runtime: {
          runtimeType: "RUNTIME_TYPE",
          runtimeTypeVersion: "RUNTIME_TYPE_VERSION",
          scriptLanguage: "SCRIPT_LANGUAGE"
        }
        script: "SCRIPT_CONTENT", 
        status: STATUS
      }
    ) {
      errors {
        description
        type
      }
    }
  }

Step monitors provide codeless multi-step browser based monitors. Here's an example for creating one in NerdGraph:

mutation {
syntheticsCreateStepMonitor (
  accountId: NR_ACCOUNT_ID, 
  monitor: {
    locations: {
      public: ["LOCATION_1", "LOCATION_2"]
      },  
    name: "MONITOR_NAME", 
    period: PERIOD, 
    status: STATUS, 
    steps: [{
      ordinal: 0, 
      type: NAVIGATE, 
      values: ["MONITORED_URI"],["USER_AGENT"]
      },{
      ordinal: STEP_NUMBER,
      type: STEP_TYPE,
      values: ["CONDITIONAL_TYPE","VALUE"]
    }]
    advancedOptions: {
      enableScreenshotOnFailureAndScript: ENABLE_SCREENSHOT
    }
  }
) {
    errors {
      description
      type
    }
}
}

Set up monitors to notify you when your SSL certificates are about to expire. Here's an example for creating one in NerdGraph:

mutation {
    syntheticsCreateCertCheckMonitor (
      accountId: YOUR_ACCOUNT_ID, 
      monitor: {
        domain: "DOMAIN", 
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          },
        name: "YOUR_MONITOR_NAME", 
        numberDaysToFailBeforeCertExpires: DAYS_UNTIL_EXPIRATION, 
        period: PERIOD, 
        status: STATUS
      }
    ) {
      errors {
        description
        type
      }
    }
  }

Broken links monitors check the links on a webpage for failure. Here's an example for creating one in NerdGraph:

mutation {
  syntheticsCreateBrokenLinksMonitor (
    accountId: YOUR_ACCOUNT_ID, 
    monitor: {
      locations: {
        public: ["LOCATION_1", "LOCATION_2"]
        }, 
      name: "YOUR_MONITOR_NAME", 
      period: PERIOD, 
      status: STATUS, 
      uri: "MONITOR_URI", 
      tags: {
        key: "YOUR_TAG_NAME", 
        values: "TAG_VALUE"
        }
      }
    ) {
      errors {
        description
        type
      }
  }
}

Update your synthetic monitors

While you can't change the monitor type after creating it, you can update its settings. Only the guid and the settings that need updated are required as part of the request.

Tip

Include the runtime object that includes runtimeType, runtimeTypeVersion, and scriptLanguage to upgrade a monitor to use a newer runtime. Do not include this object and these attributes to continue using a legacy runtime.

Use this to update your ping monitors:

mutation {
  syntheticsUpdateSimpleMonitor (
    guid: "ENTITY_GUID", 
    monitor: {
      locations: {
        public: ["LOCATION_1", "LOCATION_2"]
      },  
      name: "YOUR_MONITOR_NAME", 
      period: PERIOD, 
      status: STATUS, 
      uri: "MONITORED_URI", 
      advancedOptions: {
        customHeaders: {
          name: "HEADER_NAME", 
          value: "HEADER_VALUE"
        }, 
        redirectIsFailure: REDIRECT_IS_FAILURE, 
        responseValidationText: "VALIDATION_TEXT", 
        shouldBypassHeadRequest: BYPASS_HEAD_REQUEST, 
        useTlsValidation: TLS_VALIDATION
      }
    }
  ) {
    errors {
      description
      type
    }
  }
}

To update a simple browser monitor (including the ability to upgrade the runtime version), use this:

mutation {
    syntheticsUpdateSimpleBrowserMonitor (
      guid: ENTITY_GUID, 
      monitor: {
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          }, 
        name: "YOUR_MONITOR_NAME", 
        period: PERIOD, 
        runtime: {
          runtimeType: "RUNTIME_TYPE",
          runtimeTypeVersion: "RUNTIME_TYPE_VERSION",
          scriptLanguage: "SCRIPT_LANGUAGE"
        }
        status: STATUS, 
        uri: "MONITORED_URI", 
        advancedOptions: {
          customHeaders: {
            name: "HEADER_NAME", 
            value: "HEADER_VALUE"
          }, 
          enableScreenshotOnFailureAndScript: ENABLE_SCREENSHOT, 
          responseValidationText: "VALIDATION_TEXT", 
          useTlsValidation: TLS_VALIDATION
        }
      ) {
      errors {
        description
        type
      }
    }
  }

To update a scripted browser monitor (including the ability to upgrade the runtime version), use this:

mutation {
    syntheticsUpdateScriptBrowserMonitor (
      guid: ENTITY_GUID, 
      monitor: { 
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          }, 
        name: "MONITOR_NAME", 
        period: PERIOD,
        runtime: {
          runtimeType: "RUNTIME_TYPE",
          runtimeTypeVersion: "RUNTIME_TYPE_VERSION",
          scriptLanguage: "SCRIPT_LANGUAGE"
        }
        script: "SCRIPT_CONTENT", 
        status: STATUS, 
        advancedOptions: {
          enableScreenshotOnFailureAndScript: ENABLE_SCREENSHOT
        }
      }
    ) {
      errors {
        description
        type
      }
    }
  }

To update a scripted API monitor (including the ability to upgrade the runtime version), use this:

mutation {
    syntheticsUpdateScriptApiMonitor (
      guid: ENTITY_GUID, 
      monitor: {
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          }, 
        name: "YOUR_MONITOR_NAME", 
        period: PERIOD,
        runtime: {
          runtimeType: "RUNTIME_TYPE",
          runtimeTypeVersion: "RUNTIME_TYPE_VERSION",
          scriptLanguage: "SCRIPT_LANGUAGE"
        }
        script: "SCRIPT_CONTENT", 
        status: STATUS
      }
    ) {
      errors {
        description
        type
      }
    }
  }

Use this to update a step monitor:

mutation {
  syntheticsCreateStepMonitor (
    accountId: NR_ACCOUNT_ID, 
    monitor: {
      locations: {
        public: ["LOCATION_1", "LOCATION_2"]
        },  
      name: "MONITOR_NAME", 
      period: PERIOD, 
      status: STATUS, 
      steps: [{
        ordinal: 0, 
        type: NAVIGATE, 
        values: ["MONITORED_URI"],["USER_AGENT"]
        },{
        ordinal: STEP_NUMBER,
        type: STEP_TYPE,
        values: ["VALUE_1","VALUE_2"]
      }]
      advancedOptions: {
        enableScreenshotOnFailureAndScript: ENABLE_SCREENSHOT
      }
    }
  ) {
      errors {
        description
        type
      }
  }
}

Use this to update a certificate check monitor:

mutation {
    syntheticsUpdateCertCheckMonitor (
      guid: ENTITY_GUID, 
      monitor: {
        domain: "DOMAIN", 
        locations: {
          public: ["LOCATION_1", "LOCATION_2"]
          },
        name: "YOUR_MONITOR_NAME", 
        numberDaysToFailBeforeCertExpires: DAYS_UNTIL_EXPIRATION, 
        period: PERIOD, 
        status: STATUS
      }
    ) {
      errors {
        description
        type
      }
    }
  }

Use this to update a broken links monitor:

mutation {
  syntheticsUpdateBrokenLinksMonitor (
    guid: ENTITY_GUID, 
    monitor: {
      locations: {
        public: ["LOCATION_1", "LOCATION_2"]
        }, 
      name: "YOUR_MONITOR_NAME", 
      period: PERIOD, 
      status: STATUS, 
      uri: "MONITOR_URI", 
      tags: {
        key: "YOUR_TAG_NAME", 
        values: "TAG_VALUE"
        }
      }
    ) {
      errors {
        description
        type
      }
  }
}

You can use the below example to update a simple browser, scripted API, or scripted browser monitor to the new Chrome 100 or Node 16.10 runtimes. The following example upgrades a scripted browser monitor to the new runtime from the legacy runtime.

To update a simple browser monitor using the below example, change the mutation to syntheticsUpdateSimpleBrowserMonitor instead of syntheticsUpdateScriptBrowserMonitor.
To update a scripted API monitor using the below example, change the mutation to syntheticsUpdateScriptApiMonitor instead of syntheticsUpdateScriptBrowserMonitor.

Check out optional-fields for additional details on runtime settings.

mutation {
  syntheticsUpdateScriptBrowserMonitor ( 
    guid: "<ENTITY_GUID>", 
    monitor: {
      runtime: {
        runtimeType: "RUNTIME_TYPE", 
        runtimeTypeVersion: "RUNTIME_TYPE_VERSION", 
        scriptLanguage: "SCRIPT_LANGUAGE"
        }
      }
    ) {
    errors {
      description
      type
    }
  }
}

Delete a synthetic monitor

Use these scripts to delete your monitors:

Manage your private locations

A private location allows you to monitor applications behind your firewall. When you create a private location, you install and configure private minions to execute the monitors assigned to that private location.

mutation{
  syntheticsCreatePrivateLocation (
    accountId: NR_ACCOUNT_ID,
    name: "PrivateLocationName",
    description: "Optional description",
    verifiedScriptExecution: false
  ) {
    guid
    errors {
      description
      type
    }
  }
}

mutation {
  syntheticsUpdatePrivateLocation (
    guid: YOUR_ENTITY_GUID,     
    description: "EnterYourDescription", 
    verifiedScriptExecution: true
  ) {
  description
  verifiedScriptExecution
  errors {
    description
    type
    }
  }
}

Manage your secure credentials

You use secure credentials when storing, protecting, and centrally managing protected information used by your monitors, like passwords, API keys, or encoded certificates. Using NerdGraph allows you to programmatically change the values of your secure credentials if you need to reset any credentials for any reason.

mutation {
  syntheticsCreateSecureCredential (
    accountId: YOUR_ENTITY_GUID, 
    description: "YourOptionalDescription", 
    key: SECURE_CREDENTIAL_NAME, 
    value: SECURE_CREDENTIAL_VALUE 
    ) {
    errors {
      description
    }
  }
}

mutation {
  syntheticsUpdateSecureCredential (
    accountId: YOUR_ACCOUNT_ID, 
    description: "YourOptionalDescription", 
    key: SECURE_CREDENTIAL_NAME, 
    value: SECURE_CREDENTIAL_VALUE) {
    createdAt
    lastUpdate
    errors {
      description
    }
  }
}

NerdGraph tutorial: Manage your synthetic monitors

Requirements

Understand fields in NerdGraph explorer

Define period fields

Define tags fields

Define optional fields

Use queries to retrieve data

Query monitors

Query private locations

Query secure credentials

Query monitor script

Query monitor steps

Create your synthetic monitors

Tip

Create a ping monitor

Create a simple browser monitor

Create a scripted browser

Create a scripted API monitor

Create a step monitor

Create a certificate check monitor

Create a broken links monitor

Update your synthetic monitors

Tip

Update a ping monitor

Update a simple browser monitor

Update a scripted browser monitor

Update an API test monitor

Update a step monitor

Update a certificate check monitor

Update a broken links monitor

Upgrade a monitor's runtime

Delete a synthetic monitor

Delete monitor

Manage your private locations

Create a private location

Update a private location

Delete a private location

Purge a private location job queue

Manage your secure credentials

Create a secure credential

Update a secure credential

Delete a secure credential