IBM Instana and IBM NS1 Connect integration guide

How Instana drives the up field

The NS1 channel applies the following logic to the up custom payload field automatically:

Step 1: Create the NS1 Connect alert channel

1. In Instana, go to Settings > Global settings > Events & alerts > Alert channels > Add alert channel.
2. Select IBM NS1 Connect.
3. Fill in the fields:
   • Name: A descriptive name, for example NS1 — prod-origin-1 failover.
   • Feed label (optional): If your NS1 data source contains multiple feeds, enter the exact name of the target feed. The payload is wrapped as {"<feed-label>": {"up": "0"}}. Leave blank to send the payload unwrapped.
   • Webhook URL(s): The NS1 webhook URL for the data feed, for example https://api.nsone.net/v1/data/feeds/<feed-id>.
   • Custom HTTP Headers: Add X-NSONE-Key: <your-api-key> for authentication.
4. Click Create.

For full field descriptions, see IBM NS1 Connect alert channel.

Step 2: Create the alert configuration

1. Go to Settings > Global settings > Events & alerts > Alerts > New alert.
2. Configure the alert to match your health condition (for example, a built-in host availability issue or a custom threshold rule).
3. In the Custom Payloads section, add the following entry:
   • Key: custom:up
   • Value type: Static
   • Value: 0

   The value 0 signals that the origin is down. The channel automatically overrides this to 1 on manual close.

4. In Alert Channels, select the NS1 Connect channel that you created.
5. Click Create.

Step 3: Verify the end-to-end flow

1. Trigger a test condition on the monitored host (for example, stop the agent or simulate a threshold breach).
2. Confirm that Instana opens the alert.
3. Check the NS1 data feed, the up value should now be 0.
4. Verify that DNS responses for the protected record no longer include the failing origin.
5. Resolve the underlying issue on the host.
6. Wait for Instana to detect recovery, the alert may close automatically, but NS1 is not notified on automatic close. The origin remains marked down.
7. Once you have confirmed that the host is stable, manually close the alert in Instana.
8. Confirm that NS1 receives up: 1 and the origin is restored in DNS responses.

Failover payload examples

{"up": "0"}

{"prod-origin-1": {"up": "0"}}

{"prod-origin-1": {"up": "1"}}

How metric-based custom payloads work

When you configure a custom payload field with a Dynamic > Metric value in an alert configuration, Instana fetches the live metric value at both alert open and alert close time and includes it in the payload sent to NS1. This means NS1 receives a fresh metric snapshot when the condition clears, not just when it fires. The metric is queried over the time window you specify, using the aggregation you select (for example, SUM for call counts, or P95 for latency).

Step 1: Create one NS1 alert channel per origin or feed

Each NS1 data feed receives its own payload. Create a separate alert channel for each origin you want to steer traffic for, using the Feed label field to target the correct feed within a shared data source.

Example: Three-origin setup:

All three channels point to the same data source webhook URL. The feed label routes each payload to the correct feed within that source.

Step 2: Create alerts with metric payloads

Create one alert configuration per origin, scoped to the application, service, or endpoint for that origin. In the Custom Payloads section, add Dynamic > Metric entries for the values NS1 needs to make routing decisions. Use custom:<feed_field> as the key, where <feed_field> is the exact field name from your NS1 feed schema. For example, if your NS1 feed defines fields named latency and calls:

Set the time window to match your smart alert's granularity so the metric value covers the full violating interval. Select the NS1 channel for that origin.

Step 3: Configure NS1 to act on the metric values

In NS1 Connect, configure the DNS record to use a filter chain that reads the metric values from the data feeds. For example:

• Use a weighted shuffle filter where weights are derived from calls feed values to proportionally distribute traffic based on current throughput.
• Use a shed load filter where an origin is removed from responses when its latency_p95 value exceeds a configured threshold.

Refer to the IBM NS1 Connect documentation for details on filter chain configuration.

Load balancing payload examples

Instana sends a fresh metric snapshot both when the smart alert opens and when it closes, so NS1 always has current data. The field names in the payload (calls, latency) are illustrative — use the exact field names defined in your NS1 feed schema.

{
  "region-us": {
    "calls": "14823",
    "latency": "42.17"
  }
}

{
  "region-eu": {
    "calls": "3201",
    "latency": "318.44"
  }
}

NS1 receives these values for each feed update and adjusts routing accordingly, for example, shedding traffic from region-eu while its latency is elevated.

Multi-region traffic steering with feed labels

Instana smart alert fires for region-us application
  → NS1 channel "region-us" (feed label: region-us)
      → Payload: {"region-us": {"up": "0", "calls": "14823", "latency": "318.44"}}
      → NS1 data source receives update for feed "region-us"
      → DNS removes region-us from rotation

Operator manually closes alert after confirming recovery
  → NS1 channel "region-us" (feed label: region-us)
      → Payload: {"region-us": {"up": "1", "calls": "9823", "latency": "51.02"}}
      → NS1 restores region-us to rotation

Limitations

Related information