Note
NOTENote
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:
Log in to the NS1 Portal.
Click Pulsar in the navigation.
-
Open the application list by clicking Resources in the Pulsar subnavigation.
-
Create a new application and any associated jobs:
Click the Create Pulsar application button, located above the application list.
In the Create Application dialog that opens, enter an app name.
-
Click the Create App button.
The Application summary will confirm and display your new application.
-
If you want to configure advanced settings for the application, click the Edit pencil icon next to the application name, then configure advanced settings.
Note
BEST PRACTICESet 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.
-
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.
-
Be sure to modify any advanced settings for the job in the Advanced Configuration menu.
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
IMPORTANTUnless 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.
-
-
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:-
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.
Copy the JavaScript snippet, then paste the information on pages on your resource.
-
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.
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.