Pulsar is an active traffic steering engine that routes traffic using performance-based telemetry at the DNS layer. It uses real user monitoring (RUM) data from one of three sources: community, private, or custom data ingestion. Pulsar uses this data to monitor the performance of connected application delivery endpoints—application servers, web servers, CDNs—and dynamically routes traffic based on the best-performing endpoint at the time of each query.
| Data source | Implementation method | Description |
| Community data | This is a turnkey solution in which users work with the NS1 team to select the Community data endpoints they’d like to leverage. | Community data contains RUM measurements aggregated from various NS1 partners—including the top CDNs and cloud services—which are configured as NS1 data feeds used by the Pulsar engine. |
| Private data | Users embed a JavaScript tag on their web property. | Private data implementation via the JS tag allows users to measure to their own application servers, web servers, and CDNs. With each page load, the JS executes asynchronously in the background to collect RUM data directly from your user “eyeballs” or impressions. |
| Custom data | Users beacon their RUM performance data via gRPC or HTTP. | If you are already collecting RUM data, you can beacon it to an API endpoint for use with the NS1 Pulsar engine. This is useful to customers with existing data collection processes, allowing you to “bring your own” data. |
Private data allows NS1 customers to take performance measurements from their end-users to their own service footprint. Generally, the data measured should be performance metrics—such as response time—from the vantage point of your end-users to your CDNs, or other delivery endpoints. This article explains the process of implementing private data ingestion via the JavaScript tag.
Implementation Instructions
Step 1: Prepare your target CDN/endpoint
To prepare your CDN, you must set up an asset on the resource that maps to the delivery method/endpoint/provider you wish to measure. Your use case will determine the size of the asset you should use. For example, if you’re focused on availability and latency, measuring a small asset (eg. 1x1-pixel image) is best. If you have a streaming use case and are interested in the availability and TTLB of a larger-sized asset, NS1 recommends working with our team directly to determine an appropriately-sized object based on throughput.
Specify the following headers when setting up your target:
- Timing-Allow-Origin
- Access-Control-Allow-Origin
The asset should be available via HTTP and HTTPS. Ignore query strings to bypass browser caching. You should also return proper CORS headers.
Step 2: Create a Pulsar application
An application is a collection of Pulsar jobs (resources being measured to) which you will create in the next step. Pulsar references the application ID (appID) that determines which set of jobs should record a measurement upon each impression. This ensures that the Pulsar engine has a good breadth of data points from different locations to different jobs.
Use the PUT request below to create a new Pulsar application, replacing ACME Pulsar Tag with a relevant name for your Pulsar application. This auto-generates an appID in the response.
curl -X PUT -H 'X-NSONE-Key: $API_KEY' -d '{"name": "ACME Pulsar Tag", "active": 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,
"blend_metric_weights": {
"timestamp": 0,
"weights": [
{
"name": "string",
"weight": 0,
"default_value": 0,
"maximize": false
}
]
}
},
"community": true
}
Note and record the appID value (ex. x4f12h0) generated in the response. You will need this later in the implementation process.
Step 3: Create a Pulsar job
A job corresponds to a specific resource (CDN, data center, cloud, etc.) being measured. The resource hosts an asset used to measure availability and latency when the JavaScript tag is run by users. The 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": "{JOB_NAME}", "typeid": "latency", "active": true}' https://api.nsone.net/v1/pulsar/apps/<appId>/jobs
where
- name is the name of the job (typically, the CDN or endpoint).
- typeid is the type of Pulsar job. In this case,
latency. - appID is the unique application ID generated in the previous step (ex. 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,
"blend_metric_weights": {
"timestamp": 0,
"weights": [
{
"name": "string",
"weight": 0,
"default_value": 0,
"maximize": false
}
]
}
}
}
Note the jobID value (ex. d45ma0) in the response. If you plan to apply the jobID to the answer metadata via API, you will need the jobID. If using the NS1 portal, you will only need the job name.
Step 4: Configure private data ingestion
To configure private data ingestion, you must embed a JavaScript tag on your web properties. With each page load, the JavaScript executes asynchronously in the background and does not otherwise impact the page view. Once configured, page loads on these web properties begin collecting performance data.
- In the NS1 portal (https://my.nsone.net/), click Pulsar from the main navigation, and then click Active Resources to retrieve the JavaScript tag.
-
Embed the JavaScript tag on your web properties. Typically, NS1 recommends doing this at the end of the <body> block. Note that your unique appID is automatically encoded.
To better understand the function of the js tag, load the following page with developer tools open underneath the Network tab: http://c.ns1p.net/demo.html. You will notice each asset that is mapped to a single job execute after a few seconds taking both performance and availability measurements. The Pulsar engine normalizes and aggregates the data for use in routing, and beams it to our edges. The tag is designed to be fully asynchronous and unobtrusive.
Next steps
To complete Pulsar data configuration, you must create a Filter Chain using one of the Pulsar filters—applying each job to the respective answer via the answer metadata.