Note
NS1 supports two integrations with Datadog: inbound (from Datadog to NS1; for monitoring) and outbound (from NS1 to Datadog; for reporting). This article describes the outbound integration: Datadog pulls information from the NS1 platform, so most configuration and resource management takes place within Datadog. Alternatively, you can configure Datadog as an inbound data source in which NS1 pulls information from the Datadog platform.
Datadog offers a single, unified, SaaS-based data analytics platform that helps cloud applications monitor networks, servers, databases, tools, and services. Datadog’s integration aggregates metrics and logs from separate units of infrastructure for analysis in a unified system.
Currently, NS1 provides two separate integrations with Datadog. The “inbound” integration pushes Datadog monitoring data into NS1 as a data feed so you can direct traffic appropriately and automate real-time traffic management. The “outbound” integration allows you to pull queries-per-second (QPS) and usage statistics from NS1 to report and visualize that data in Datadog.
The configuration instructions below cover the outbound integration, where data flows from NS1 into Datadog. Located in Datadog’s integrations-extras repository, this integration displays statistics from NS1 in an out-of-the-box dashboard in Datadog so you can monitor and report on NS1 services via the Datadog Agent.
-
You must have an NS1 account.
-
You must have a Datadog account with the Datadog Agent installed.
Note
The minimum Datadog Agent version required for supporting integrations is 7.21.0. NS1 recommends using the latest version of the Datadog Agent. Also, you should have only one Agent running when using this integration.
-
You must create an NS1 API key with the following permissions enabled:
-
Ensure "Manage Invoices" permission is enabled in order to use the billing/QPS statistics feature.
-
Under DNS Permissions, ensure “Manage Zones,” “View Zones,” and “Allow by Default” are enabled.
-
Under DHCP, ensure “View DHCP” is enabled (for NS1 Cloud-Managed DDI customers only).
-
Note
You must have a Datadog account with the Datadog Agent installed. The minimum Datadog Agent version required for supporting integrations is 7.21.0. NS1 recommends using the latest version of the Datadog Agent. Also, you should have only one Agent running when using this integration.
-
Log in to Datadog and select Integrations>Integrations in the left-side navigation bar.
-
Search for the NS1 integration via the search bar and select the NS1 tile when it displays by clicking the “Available” button.
-
Navigate to the Configuration tab and click the “Install Integration” button.
Installation may take a few minutes, after which the Configuration tab will display the following:
-
Verify your dashboard connection by navigating to Dashboards>Dashboard List via the left-side navigation bar. The preset dashboard, “NS1 Screenboard,” will appear in the list.
Note
If you navigate to the Infrastructure tab via the left navigation after this process, your machine will display in the host list here, provided that you also have the Agent installed and configured.
-
Navigate back to Integrations>Integrations via the left-side navigation bar and click on the NS1 tile.
-
Follow the instructions from Datadog’s Community integration installation article to install the NS1 integration with the Datadog Agent. When running the installation process, use the following variables which are specific to the NS1 integration:
-
<INTEGRATION_NAME>: NS1
-
<INTEGRATION_VERSION>: 0.0.4
-
In the configuration file, you must edit the parameters to specify what data Datadog should collect from NS1. After implementation, you will be able to view this data in the Datadog portal.
Note
The YAML configuration file is saved automatically upon downloading the integration.
-
Navigate to the YAML file. The file is saved to “/etc/datadog-agent/conf.d/ns1.d”.
-
Rename the default “conf.yaml.example” file to “conf.yaml” and edit the file to indicate the desired NS1 metrics to gather.
-
Once complete, save the configuration file and restart the Agent.
Warning
The YAML file has strict formatting rules. Use of tabs to indent is not allowed. Each indent must be exactly two spaces. Elements arranged in a list must be preceded with '-', which must be indented exactly two spaces.
Below is an example configuration file followed by parameters tables for reference when editing the config file. Each parameter corresponds to one or more NS1 API endpoints. For more information, refer to the NS1 API documentation.
The file below represents the default configuration file. Highlighted sections require editing for your specific use case.
## All options defined here are available to all instances. # init_config: ## @param service - string - optional ## Attach the tag `service: <SERVICE>` to every metric, event, and service check emitted by this integration. ## ## Additionally, this sets the default `service` for every log source. # # service: <SERVICE> ## Every instance is scheduled independent of the others. # instances: ## @param api_endpoint - string - required ## The URL to check. # - api_endpoint: https://example.org ## @param api_key - string - required ## The api authentication key. # api_key: test_key_123 ## @param networks - list - optional ## If present, usage stats are queried and reported by the network. ## Each network’s stats are tagged with network name. ## If omitted, usage stats are reported only account wide. ## If a list of network IDs is supplied, only those networks are queried. ## If the parameter is present without a list of network IDs, ## all available networks are queried. # # networks: # - 0 # - 5 # - 80 ## @param metrics - dictionary - required ## List of metrics to report to Datadog ## Each individual entry within the metric dictionary is optional, ## however at least one has to be present ## i.e. you must specify at least one of the following: ## qps, usage, account, ddi, pulsar, pulsar_by_app, pulsar_by_record # metrics: ## @param pulsar - boolean - optional ## if parameter is present, the following is reported account-wide: ## number of decisions, number of undetermined decisions, route map hits and misses # # pulsar: ## @param pulsar_by_record - list - optional ## if parameter is present, the following is reported on per record basis: ## number of decisions, route map hits and misses ## enter list of dns records in form: ## - <record name>: <record type> # # pulsar_by_record: # - www.test.com: A # - www.test1.com: A ## @param pulsar_by_app - list - optional ## if parameter is present, aggregate performance data ## and pulsar availability data is reported. ## Enter a list of pulsar application IDs and job IDs in form: ## - <app_id>: <job_id> # # pulsar_by_app: # - 1xy4sn3: 1b1o94j # - 1xy4sn3: 1uy3acz ## @param ddi - list - optional ## if parameter is present, lease statistics will be reported account-wide ## you can specify array of scope groups ID's to additionally ## report leases for each scope # # ddi: # - 1 # - 2 ## @param qps - list - optional ## (Queries per second) ## if parameter is present, QPS statistics will be reported account-wide ## you can specify an array of domain names to additionally ## report qps for each domain separately ## if sub-array of records within domain is specified, ## qps will be reported for each record separately # # qps: # - test.com: # - www.test.com: A ## @param usage - list - optional ## (Number of queries) ## if parameter is present, usage statistics will be reported account-wide ## you can specify array of domain names to additionally ## report usage for each domain separately ## if sub-array of records within domain is specified, ## usage will be reported for each record separately # # usage: # - test.com: # - www.test.com: A ## @param account - list - optional ## (billing and ttl) ## if 'billing' element is present, account query limit and current number of queries ## will be reported. ## If ttl element is present, TTL will be reported for each of the domains ## specified in sub-array # # account: # - billing: # - ttl: # - test.com # - test1.com ## @param query_parameters - dictionary - optional ## Pulsar API endpoints can have query string parameters ## For pulsar, period should be at least 1 hour # # query_params: # pulsar_period: 1h # pulsar_geo: "*" # pulsar_asn: "*" # pulsar_agg: avg ## @param min_collection_interval - integer - optional - default: 15 ## This changes the collection interval of the check. For more information, see: ## https://docs.datadoghq.com/developers/write_agent_check/#collection-interval # # min_collection_interval: 60 ## @param empty_default_hostname - boolean - optional - default: false ## This forces the check to send metrics with no hostname. ## ## This is useful for cluster-level checks. # # empty_default_hostname: false
Configure the following parameters to determine which metrics will be collected for the Agent instance:
Parameter |
Type |
Description |
api_endpoint* |
string |
The host URL for NS1 API. If you use Managed DNS, this will be https://api.nsone.net. |
api_key* |
string |
A valid NS1 API key. |
metrics* |
dictionary |
A list of metrics to report to Datadog. At least one metric must be present (i.e., you must specify at least one of the following: qps, usage, account, ddi, pulsar, pulsar_by_app, pulsar_by_record). Refer to the parameter options below for details. |
*Indicates a required parameter.
Edit the “metrics” section of the configuration file to specify key details within each parameter.
Note
You must select at least one of the elements in this section. Refer to the NS1 API documentation to learn more about the API endpoints associated with these metrics.
Parameter |
Type |
Description |
account |
list |
If this parameter is present, you must specify ‘billing', ‘ttl’, or both. If the ‘billing’ element is present, the account query limit and current number of queries will be reported. If the TTL element is present, the time-to-live value will be reported for each of the domains specified in a sub-array. For example: # account: # - billing: # - ttl: # - test.com # - test1.com |
ddi |
list |
If this parameter is present, DDI lease statistics will be reported account-wide. Additionally, you can specify an array of scope groups IDs to report leases and lps for each scope. |
pulsar |
boolean |
If set to “true,” this parameter reports the following account-wide:
|
pulsar_by_app |
list |
If this parameter is present, aggregate performance data and Pulsar availability data will be reported. Specify a list of Pulsar application IDs and job IDs in the following format: <app_id>: <job_id> |
pulsar_by_record |
list |
Enter a list of DNS records in the form <record name>: <record type>. If present, the following will be reported on a per-record basis:
|
qps |
list |
This reports QPS statistics account-wide. Additionally, you can specify an array of domain names to report QPS for each zone separately. If a sub-array of records within a domain is specified, QPS will be reported for each record separately. For example, the following configuration will collect qps for the entire account, the test.com zone, and the www.test.com A record. qps: - test.com: - www: A |
query_parameters |
dictionary |
This is a dictionary of key-value parameters (all have string value) applicable to usage and Pulsar API endpoints. See the table below for details. |
usage |
list |
This reports usage statistics account-wide. It uses the same format as the QPS parameter, so you can specify an array of domain names to additionally report usage for each domain separately as well as a sub-array of records within the domain to get statistics for each record. |
For reference, NS1 supports the following query_parameters:
Parameter |
Function |
pulsar_asn |
Specifies an Autonomous System Number (ASN) by which to filter |
pulsar_geo |
Specifies a location such as ‘US’, ‘FR’, ‘GR’, ‘JP’, ‘US_NY’, etc. |
pulsar_period |
Specifies a period for querying Pulsar endpoints (default 1 hour), applicable only to pulsar_by_app |
usage_networks |
Supports networks parameter and allows you to filter results for a specific network |
Run the Agent's status subcommand and look for NS1 under the Checks section.
Once the integration is installed, you can view the preconfigured Datadog dashboard, called "NS1 Screenboard." The various charts display the data specified in the configuration file. Note the metrics are prefixed with “ns1.” in the portal, whereas this prefix does not appear in the configuration file.

The tables below map the various metrics to charts viewable in the dashboard. The first column shows the name of the NS1 metric in the Datadog platform, the second column indicates which chart shows metric data, and the third column is the NS1 API endpoint from which this data is sourced.
Datadog metric name |
Chart(s) in dashboard |
NS1 API endpoint source |
ns1.qps |
|
/v1/stats/qps |
ns1.qps.zone |
|
/v1/stats/qps/{domain} |
ns1.qps.record |
|
/v1/stats/qps{domain}/{record}/{recordtype} |
Datadog metric name |
Chart(s) in dashboard |
NS1 API endpoint source |
ns1.usage |
|
/v1/stats/usage |
ns1.usage.zone |
|
/v1/stats/usage/{domain} |
ns1.usage.record |
|
/v1/stats/usage/{domain}/{rectype} |
Datadog metric name |
Chart(s) in dashboard |
NS1 API endpoint source |
ns1.ttl |
|
/v1/zones/{domain} |
ns1.billing |
|
/v1/account/billataglance |
The following parameters are applicable only to users with active NS1 DDI deployments.
Datadog metric name |
Chart(s) in dashboard |
NS1 API endpoint source |
ns1.leases |
|
/v1/stats/leases |
ns1.peak_lps |
|
/v1/stats/lps |
The following parameters are applicable only to users with NS1’s Pulsar active traffic steering solution.
Datadog metric name |
Chart(s) in dashboard |
NS1 API endpoint source |
ns1.pulsar.decisions |
|
/v1/pulsar/query/decisions |
ns1.pulsar.decisions.insufficient |
|
/v1/pulsar/query/decision/ customer/undetermined |
ns1.pulsar.routemap.hit |
|
/v1/pulsar/query/routemap/ hit/{customerID} |
ns1.pulsar.routemap.miss |
|
/v1/pulsar/query/routemap/ miss/{customerID} |
The following parameters are applicable only to users with NS1’s Pulsar active traffic steering solution.
Datadog metric name |
Chart(s) in dashboard |
NS1 API endpoint source |
ns1.pulsar.performance |
|
/v1/pulsar/apps/ {app_id}/jobs/{job_id}/data |
ns1.pulsar.availability |
|
/v1/pulsar/apps/ {app_id}/jobs/{job_id}/availability |
The following parameters are applicable only to users with NS1’s Pulsar active traffic steering solution.
Datadog metric name |
Chart(s) in dashboard |
NS1 API endpoint source |
ns1.pulsar.decisions.record |
|
/v1/pulsar/query/decision/ record/{rec_name}/{rec_type} |
ns1.pulsar.routemap.hit.record |
|
/v1/pulsar/query/routemap/ hit/record/{rec_name}/{rec_type} |
ns1.pulsar.routemap.miss.record |
|
/v1/pulsar/query/routemap/ miss/record/{rec_name}/{rec_type} |