Creating a data sink

Create data sinks to export DNS Insights metrics to a supported time series database (TSDB). DNS Insights supports Prometheus remote write and OpenTelemetry (OTLP) HTTP telemetry protocols for metric forwarding.

Data sinks use the endpoint details and authentication credentials exposed by the target TSDB to authenticate and forward metrics to the configured telemetry endpoint. After a data sink is configured, IBM support links the data sink to the required DNS Insights data sets to enable metric forwarding.

Note: If you encounter issues while configuring a data sink, contact IBM support for assistance.

Creating a data sink by using the web-based interface

Before you begin

  • Ensure that IBM support has enabled DNS Insights for your account.
  • Gather the required endpoint details and authentication credentials for your TSDB.

    For Prometheus, you require:

    • A remote host URL
    • A username/ instance ID and the password or API key

    For OTLP, you require:

    • An endpoint URL
    • Either:
      • A username and password for basic authentication
      • An API token for token-based authentication

Procedure

  1. From the top navigation menu, click Observability > DNS Insights.
  2. Click Add data sink.
  3. Enter a name for the data sink in the Name field.
  4. From the options for Sink type, select the preferred telemetry protocol.
  5. Depending on the selected telemetry protocol, complete the following steps:
    To create a Prometheus data sink
    1. In the Remote host field, enter the URL of the Prometheus endpoint that receives DNS Insights metrics.
    2. In the Username/Instance ID field, enter the username or instance ID for the Prometheus instance.
    3. In the Password/API key field, enter the corresponding password or API key.
    To create an OpenTelemetry (OTLP) data sink
    1. In the Remote write endpoint field, enter the endpoint URL that receives DNS Insights metrics.
    2. From the Authentication type list, select the authentication method.
      • If you selected Basic Auth, enter the username and password.
      • If you selected API Token, enter the API token.
  6. Click Add Sink.

Result

The data sink is created.

After you configure a data sink, contact IBM support. IBM support links the data sink to the required DNS Insights data sets and validates metric forwarding to the supported TSDB.

Creating a data sink by using the API

Before you begin

  • Ensure that IBM support has enabled DNS Insights for your account.
  • Gather the required endpoint details and authentication credentials for your TSDB.
  • Ensure that you have a valid NS1 Connect API key.

Procedure

Run the PUT request for the telemetry protocol that you want to use. You must include a valid NS1 Connect API key in the request header and the following parameters in the request body as seen in the examples:

Name Type Description
name string (Required) Name of the data sink for internal reference.
description string Description of the data sink for internal reference.
tags object Optional key-value pairs for categorizing and filtering data sinks.
backend string (enum)

(Required) Telemetry protocol used by DNS Insights to send metrics to the configured telemetry endpoint.

  • If you are using OTLP, the value is otlphttp.
  • If you are using Prometheus, the value is prometheus.
config object

(Required) Object containing details and credentials for your TSDB. This object contains two nested objects:

  • exporter (required object): Contains details about the host or endpoint of your TSDB.

    If using prometheus:

    Include the remote_host parameter with the URL to the Prometheus host.

    If using otlphttp:

    Include the endpoint parameter with the base URL of the TSDB that supports the OpenTelemetry Protocol (OTLP). Do not include the /v1/metrics path in the URL. For example, use https://example.com/test instead of https://example.com/test/v1/metrics.

  • authentication (required object): Contains the required authentication parameters based on the type of protocol.

    If using prometheus: Set the type value to basicauth and provide a valid username and password.

    If using otlphttp you can use basic authentication or token-based authentication:

    Basic authentication: Set the type value to basicauth and provide a valid username and password.

    Token-based authentication: Set the type value to bearertokenauth, provide the relevant scheme for the token (refer to the HTTP authentication scheme registry), and provide a valid token.

Examples

Creating a data sink using the Prometheus protocol

curl -X PUT -H "X-NSONE-Key: $NSONE_API_KEY" -d '
{
  "name": "string",
  "backend": "prometheus",
  "config": {
    "exporter": {
      "remote_host": "https://example.com"
    },
    "authentication": {
      "type": "basicauth",
      "username": "string",
      "password": "string"
    }
  }
}
' https://api.nsone.net/v1/insights/sinks

Creating a data sink using the OTLP protocol

curl -X PUT -H "X-NSONE-Key: $NSONE_API_KEY" -d '
{
  "name": "string",
  "backend": "otlphttp",
  "config": {
    "exporter": {
      "endpoint": "https://examplesink.com"
    },
    "authentication": {
      "type": "bearertokenauth",
      "scheme": "...",
      "token": "..."
    }
  }
}
' https://api.nsone.net/v1/insights/sinks

Result

The data sink is created.

After you configure a data sink, contact IBM support. IBM support links the data sink to the required DNS Insights data sets and validates metric forwarding to the supported TSDB.