Integrating with Datadog (outbound)
The outbound integration allows you to pull queries and usage statistics from NS1 Connect to report and visualize the data in Datadog.
- The inbound integration pulls data from Datadog as a third-party data source used for monitoring purposes.
- The outbound integration pushes data from NS1 Connect to Datadog for reporting purposes.
Located in the Datadog integrations-extras repository, this integration allows you to view NS1 Connect data in Datadog dashboards.
Before you begin
- You must have a Datadog account with the Datadog agent installed.
Note: The minimum agent version supported is v7.21.0. However, it is recommended that you use the latest version of the Datadog agent and only have one agent running when using this integration.
- You must have a valid NS1 Connect API key with the Manage invoices and Manage zones, View zones, and Allow by default permissions enabled.
Step 1: Install the NS1 Connect integration on the Datadog platform
- Log in to Datadog and select .
- Search and select the NS1 integration tile.
- Click Configuration.
- Click Install Integration.
- When complete, verify the dashboard connection by clicking . The preset dashboard NS1 Screenboard opens in the list.
Note: Validate the integration by going to the Infrastructure page. Your machine should appear in the host list if the agent is installed and configured.
- Click .
- Click the NS1 integration tile.
- Follow the instructions from Datadog Community integration installation documentation to install the integrations with NS1 Connect on the Datadog agent. When running the installation, use the following variables which are specific to this integration.
<INTEGRATION_NAME>:NS1<INTEGRATION_VERSION>:0.0.4
Step 2: Edit the YAML configuration file
In the configuration file, edit the parameters to specify what data Datadog should collect from NS1 Connect. After implementation, you can view this data in the Datadog UI.
- Navigate to the YAML file (/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 metrics to gather.
- Save the configuration file.
- Restart the agent.
-, which must be indented exactly two spaces.The following example file and parameters can be used for reference when editing the configuration file. Refer to the API documentation to learn more about the supported endpoints, requests, and parameters.
## 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:
## 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 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
Instances parameters
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 the NS1 Connect API: https://api.nsone.net |
| api_key | string | A valid NS1 Connect API key |
| metrics | dictionary | A list of metrics to report to Datadog. At least one metric must be present: account, pulsar, pulsar_by_app, pulsar_by_record. |
| Parameter | Type | Description |
|---|---|---|
| account | list | If set, specify billing, ttl, or both. If billing is set, the account query limit and current number of queries will be supported. If ttl is set, the time-to-live value will be reported for each of the domains specified in a sub-array. For example:
|
| pulsar | boolean | If true, this parameter reports the total number of decisions, number of undetermined decisions, route map fits, and route map misses. |
| pulsar_by_app | list | If set, aggregate performance data and RUM-based availability data will be reported. Specify a list of application IDs and job IDs in the following format: <app_id>: <job_id> If set, this parameter reports the number of decisions, route map hits/misses per application. |
| pulsar_by_record | list | Lisa of DNS records in the format <recordName>:<recordType>. If set, this parameter reports the number of decisions, route map hits/misses per record. |
| query_parameters | dictionary | List of key-value pairs (strings) applicable to usage and RUM-based API endpoints. |
| usage | list | If set, returns usage statistics account wide. You can specify an array of domain names to report usage for each, individually. You can also specify a sub array of records in that domain to view record-level statistics.
|
| Parameter | Type | Description |
|---|---|---|
| pulsar_asn | string (enum) | Specifies an Autonomous System Number (ASN) by which to filter |
| pulsar_geo | string (enum) | Specifies a location such as US, FR, GR, JP, US_NY, and so on |
| pulsar_period | string (enum) | Specifies a period for querying Pulsar endpoints (default 1 hour), applicable only to pulsar_by_app |
| usage_networks | string (enum) | Supports networks parameter and allows you to filter results for a specific network |
Step 3: Validate the integration
Run the agent's status subcommand and look for NS1 under the Checks header.
Step 4: View data on the Datadog dashboard
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 UI, whereas this prefix does not appear in the configuration file.
The following table aligns the metrics shown in the dashboard with the relevant NS1 Connect API endpoint.
| Datadog metric name | Dashboard charts | API endpoint |
|---|---|---|
ns1.usage |
|
/v1/stats/usage |
ns1.usage.zone |
|
/v1/stats/usage/<domain> |
ns1.usage.record |
|
/v1/stats/usage/<domain>/<recordType> |
| Datadog metric name | Dashboard charts | API endpoint |
|---|---|---|
ns1.ttl |
|
/v1/zones/<domain> |
ns1.billing |
|
/v1/account/billataglance |
| Datadog metric name | Dashboard charts | API endpoint |
|---|---|---|
ns1.pulsar.decisions |
|
/v1/pulsar/query/decisions |
ns1.pulsar.decisions.insufficient |
/v1/pulsar/query/decision/customer/undetermineds |
|
ns1.pulsar.routemap.hit |
/v1/pulsar/query/routemap/hit/<customerID> |
|
ns1.pulsar.routemap.miss |
/v1/pulsar/query/routemap/miss/<customerID> |
| Datadog metric name | Dashboard charts | API endpoint |
|---|---|---|
ns1.pulsar.performance |
|
/v1/pulsar/apps/<app_id>/jobs/<job_id>/data |
ns1.pulsar.availability |
|
/v1/pulsar/apps/<app_id>/jobs/<job_id>/availability |
| Datadog metric name | Dashboard charts | API endpoint |
|---|---|---|
ns1.pulsar.decisions.record |
|
/v1/pulsar/query/decision/record/<recordName>/<recordType> |
ns1.pulsar.routemap.hit.record |
|
/v1/pulsar/query/routemap/hit/record/<recordName>/<recordType> |
ns1.pulsar.routemap.miss.record |
|
/v1/pulsar/query/routemap/miss/record/<recordName>/<recordType> |