NS1 status

Articles in this section

Creating Pulsar applications and jobs

  • Updated
Follow

Note

NOTE

Note

This article covers the basic process of creating Pulsar applications and jobs. Typically, this is done in the context of setting up private or custom data ingestion. To learn more, refer to the Configuring private data collection for Pulsar article.

A Pulsar application is a collection of Pulsar resources (or assets to which the Pulsar engine measures, such as a single-pixel image embedded across your website to help track latency). Upon each impression when the Pulsar JavaScript tag is run by users, Pulsar references the application ID (appID) to determine which set of jobs should record a measurement.

After creating a Pulsar application, you will create Pulsar jobs and associate them with the application (using the appID if creating the job via API). A job corresponds to a specific resource (CDN, data center, cloud, etc.) being measured. The resource hosts an asset (such as a single-pixel image) used to measure availability and latency when the JavaScript tag is executed upon page load.

Pulsar must be enabled on your account in order to create an application and its associated jobs.

You can create Pulsar applications and jobs in two ways:

Creating Pulsar applications and jobs via the NS1 Portal

  1. Log in to the NS1 Portal.

  2. Click Pulsar in the navigation.

  3. Open the application list by clicking Resources in the Pulsar subnavigation.

    pulsar_resources_nav.png

  4. Create a new application and any associated jobs:

    1. Click the Create Pulsar application button, located above the application list.

    2. In the Create Application dialog that opens, enter an app name.

    3. Click the Create App button.

      pulsar_app_new.png

      The Application summary will confirm and display your new application.

    4. If you want to configure advanced settings for the application, click the Edit pencil icon next to the application name, then configure advanced settings.

      pulsar_app_adv_config.png

      Note

      BEST PRACTICE

      Set the default values for all jobs within the Application Advanced Configuration menu. This prevents most potential issues when a job’s settings override what you have set for the application.

  5. Add new jobs to the application in the Job list:

    • If no jobs are currently associated with the application, complete the Create Job, then click Create Job.

      pulsar_new_job.png

    • Be sure to modify any advanced settings for the job in the Advanced Configuration menu.

      pulsar_new_job_adv_config.png

      If you edit any of these settings, it will override what you have set for the application within which this job resides. If you do not set a different value for a timeout setting, the application default value is used.

      JavaScript (a setting that measures latency) is the default job type, but if you are measuring anything else (such as bandwidth), select the Custom type.

      Note

      IMPORTANT

      Unless you are told by NS1 Support that you should modify the Job Configuration, you should keep the default settings. If you override these settings to clash with the overall application defaults, you may cause issues when the job runs.

    • If resources are already associated with the application, add a new one by clicking the Add a job button, then complete the Create Job form. Click Create Job.

      pulsar_create_new_job_existing.png

  6. If you have selected JavaScript for the Job type, embed your Pulsar tag in the <head> section of one or more HTML documents that reside on your resource:

    1. Click the Copy JS tag to clipboard button, located under the Default job settings portion of the application summary. The Embed Your Pulsar Tag dialog opens.

      pulsar_embed_js_tag.png

    2. Copy the JavaScript snippet, then paste the information on pages on your resource.

Creating Pulsar applications and jobs via the API

To create an application:

Use the PUT request below to create a new Pulsar application, replacing ACME Pulsar Tag with a relevant name for your Pulsar application. This generates an appID in response.

curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"name": "ACME Pulsar Tag", "active": 
true, "default_config": {"http": true, "https": true}}' 
https://api.nsone.net/v1/pulsar/apps

Example response:

{
 "customer": 0,
 "appid": "x4f12h0",
 "name": "ACME Pulsar Tag",
 "active": true,
 "token": 0,
 "browser_wait_millis": 0,
 "jobs_per_transaction": 0,
 "default_config": {
   "http": true,
   "https": true,
   "request_timeout_millis": 0,
   "job_timeout_millis": 0,
   "use_xhr": true,
 },
 "community": true
}

Note and record the appID value (for example, x4f12h0) generated in the response. When creating a Pulsar job, you'll need the appID to specify the application with which the job is associated.

To create a job:

A jobID is applied to an answer within the DNS resource record. Use the PUT request below to create a Puslar job within your app—auto-generating a jobID.

curl -X PUT -H "X-NSONE-Key: $API_KEY" -d '{"name": "$RESOURCE_NAME", "typeid": 
"latency", "active": true, "config": {"host": "https://www.ns1.com", "url_path": 
"/img/ns1-logo.png"}}' https://api.nsone.net/v1/pulsar/apps/$APP_ID/jobs

where:

  • name is the name of the job (typically, the CDN or endpoint to which you are measuring).

  • typeid is the type of Pulsar measurement—either latency or custom. Users collecting Pulsar data via the embedded JavaScript tag must specify “latency” as the type.

  • appID is the unique identifier generated in the response after creating an application (for example, x4f12h0).

Example response:

{
 "customer": 0,
 "appid": "x4f12h0",
 "jobid": "d45ma0",
 "name": "CDN A",
 "typeid": "latency",
 "active": true,
 "community": true,
 "shared": true,
 "config": {
   "host": "string",
   "url_path": "string",
   "http": true,
   "https": true,
   "request_timeout_millis": 0,
   "job_timeout_millis": 0,
   "use_xhr": true,
 }
}

Note the jobID value (for example, d45ma0) in the response. If you plan to apply the associated data source to a DNS answer’s metadata via the API, you will need the jobID. If using the NS1 portal, you will only need the resource name.

Related articles