SignalFx Developers Guide

Data Links

Data links associate SignalFx metadata with related content, including the following:

  • Splunk instances

  • External websites

  • SignalFx dashboards

Overview

The SignalFx metadata for a data link is known as the trigger. Depending on how you create the data link, the trigger is associated with a single key and value, a single key and any of its values, any of the keys of a single value, or any value of any key.

To learn more about triggers, see Specifying triggers.

Each trigger can have one or more pointers to related content. These are known as link targets.

For a Splunk instance link target, you specify a URL that points to the Splunk instance. SignalFx encodes metadata on the URL before sending it.

For a custom URL link target, you specify a URL template with optional variable tags that SignalFx fills in with metadata before sending the URL.

Data links for dashboards don’t use URLs.

You can create global link targets that are visible throughout your organization or local link targets that are only visible in a single dashboard.

To learn more about link targets, see Specifying targets.

After you’ve created link targets for triggers, you can see them in the following areas of the web UI:

  • Data tables

  • List charts

  • Alert messages

  • Infrastructure Navigator

Specifying triggers

Triggers can have one of the following forms:

Every key and value

The targets are available for every metadata key in your organization, regardless of its value.

All values of a key

The targets are available for every value of a specific metadata key.

Specific key

The targets are available for the metadata key specified in the trigger, regardless of its value.

Specific key-value pairs

The targets are only available for a specific metadata key and value.

Specifying targets

For each trigger, you can specify one or more of the following target types:

Splunk instance link target

URL for a Splunk instance. SignalFx encodes metadata on the URL before sending it. The metadata includes the following:

  • Trigger key name if specified

  • Trigger value if specified

  • Minimum time window starting and ending timestamps. To learn more, see Minimum time window.

Custom URL link target

URL template for an external web site. The template includes the server path, and you can also use it to specify endpoints and query parameters. The template can also contain one or more of the variable tags that SignalFx defines. Before sending the URL, SignalFx replaces the tags with actual data.

Internal link target

Link to a dashboard in SignalFx. For this type of link target, you specify a SignalFx-assigned dashboard ID and dashboard group ID. When users select the link in the web UI, SignalFx displays the dashboard.

All of the target types can have either global or local scope:

  • A link target with global scope is visible everywhere that SignalFx displays link targets. For example, a global link target for the instanceId metadata key appears anywhere that instanceId appears in data tables, list charts, or alert messages in your organization. The data link also appears in the Infrastructure Navigator.

    If you add a global link target to a trigger in one place, and then add the same trigger in another place, the link immediately appears. For example, if you have a global link target for instanceId in a list chart, and you then add instanceId to a chart in another dashboard, the global data link is immediately visible in the other dashboard.

  • A local data link is only visible in a single dashboard. For example, if you have a dashboard named Database Charts, and you add a local data link for the instanceId metadata key in one of the dashboard’s charts, the link appears for any occurrence of instanceId in Database Charts. It doesn’t appear for occurrences of instanceId in other dashboards or in alert messages.

Use the contextId property to set a link target’s scope, using one of these enumerated strings:

  • "global": Global scope

  • "<dashboard_id>": Scope local to the dashboard identified by "<dashboard_id>"

If your organization has the permissions feature enabled, you can only create a local data link if you have the correct write permissions. The user associated with the API token you use to create the link must have write access to the source dashboard for the link. The user doesn’t need write access to the dashboard being linked to.

To create or remove global data links, the user associated with the API token you use must be a SignalFx administrator. All users can retrieve global data links.

To learn more about data link permissions, see the section About defining data links in the product documentation.

For a Splunk link target, SignalFx adds a search request and query parameters to the URL you specify. The query parameters specify the following:

  • Trigger key

  • Trigger value

  • Minimum time window starting timestamp in Unix time, specified in seconds.

  • Minimum time window ending timestamp in Unix time, specified in seconds.

To learn more about minimum time windows, see Minimum time window.

External system link targets offer these features:

URL templates

For an external link target, you can add as much text as you want to the URL. In particular, you can specify a URL template containing SignalFx-defined variable tags. When users select the link target, SignalFx replaces the tags with actual values and sends the resulting URL.

Variable tags have a format that’s similar to Handlebars. To specify a variable tag, you surround the tag name with {{ and }}.

For example, suppose you want to link the key and value host: server1 to the external site https://www.example.com. In addition, you want to send the trigger values in the URL’s query parameters.

www.example.com expects a URL with the following format:

https://www.example.com?&hostkey=<host_key_name>&hostname=<host_name_value>

To send a URL that has this format, use a URL template that includes the {{key}} and {{value}} variable tags. SignalFx replaces these tags with the trigger key name and trigger value.

The template should look like this:

https://www.example.com?&hostkey={{key}}&hostname={{value}}

When users select the data link, SignalFx sends the following URL:

https://www.example.com?&hostkey=host&hostname=server1

Variable tags

For external URL templates, SignalFx defines the following variable tags:

  • {{key}}: Trigger key name

  • {{value}}: Trigger value

  • {{start_time}}: Starting timestamp of the link target’s time window. SignalFx inserts the timestamp in the format you specify in the timeFormat property. To learn more, see the section Minimum time window.

  • {{end_time}}: End time of the link target’s time window. SignalFx inserts the timestamp in the format you specify in the timeFormat property. To learn more, see the section Minimum time window.

  • {{properties.<property_name>}}: Other metadata from the current context. properties contains a map of the names and current values of metadata that SignalFx is displaying in the current data table, list chart, alert message, or Infrastructure Navigator. To insert a name and value from this map, use {{properties.<property_name>}}.

Property mapping

Property mapping lets you map SignalFx key names and values to the property names and values used by the external system. For example, you can map the SignalFx key host to the property key hostname used by an external system.

Mapping a property name

To map a SignalFx metadata key to an external system key, specify the propertyKepMapping property. For example, if the SignalFx metadata key is host and the external system key is hostname, specify the following:

1
2
3
"propertyKeyMapping": {
    "host": "hostname"
}

Since propertyKeyMapping expects a map of SignalFx to external key names, you can also specify multiple mappings. For example, if the host key maps to the external property key hostname, and the container key maps to docker_container, specify the following:

1
2
3
4
"propertyKeyMapping": {
    "host": "hostname",
    "container": "docker_container"
}

Mapping a property name and value

The propertyKeyMapping property can also map SignalFx key-value pairs to external key-pairs. For example, consider the previous example that maps host to hostname and container to docker_container. Suppose instead that you want to map specific values of these keys to values used by the external system.

For example, you want to map host to hostname and server1 to host-server-1, and you also want to map container to docker_container and container5 to docker_instance_5. To do this, specify propertyKeyMapping as follows:

1
2
3
4
"propertyKeyMapping": {
    "host:hostname":"server1:host-server-1",
    "container:docker_container":"container5:docker_instance_5"
}

propertyKeyMapping isn’t limited to one type of mapping. You can combine key mapping and key-value mapping in the same property. For example:

1
2
3
4
5
"propertyKeyMapping": {
    "region": "cluster_region",
    "host:hostname":"server1:host-server-1",
    "container:docker_container":"container5:docker_instance_5"
}

Minimum time window

A data link’s minimum time window helps refine the search that a Splunk or external site link triggers.

SignalFx assumes that you add data links for external sites in order to trigger searches for SignalFx data in the external site; the same is true for Splunk links. SignalFx encodes the properties and values you specify for the link on the link URL in the form of query parameters and values.

To help focus the search on recent data, SignalFx also encodes a starting and ending timestamp on the URL. The external site can use these timestamps to narrow its search to recent data. SignalFx calculates the timestamps based on a user action time and a minimum time window:

  • User action time:

    • For charts: Time at which the user selected the link

    • For detectors: Time at which the most recent alert occurred

  • Minimum time window:

    • For charts: The larger of minimumTimeWindow specified in the request body for POST https://api.{REALM}.signalfx.com/v2/crosslink, or if you link from a data table, the chart’s resolution

    • For detectors: minimumTimeWindow specified in the request body for POST https://api.{REALM}.signalfx.com/v2/crosslink

SignalFx uses the following equations to set the timestamps:

  • start_timestamp=(user_action_time - (default_duration)/2)

  • end_timestamp=(user_action_time + (default_duration)/2)

SignalFx encodes starting and ending timestamps as follows:

Splunk link target

SignalFx automatically encodes the timestamps on the URL.

External link target

You need to specify the starting and ending timestamps using variable tags in the link’s URL template. Set timeFormat to the timestamp format expected by the external system. In the URL template for the external data link, use the following variable tags to specify the starting and ending times:

  • Starting time of the window: {{start_time}}

  • Ending time of the window: {{end_time}}

Timestamp formats

To ensure compatibility with external systems, you can specify the timestamp format that SignalFx uses to encode the starting and ending timestamps on external link URLs.

Use the timeFormat property to select from one of three options:

  • "Epoch": Unix epoch time. When you use this value, SignalFx encodes the start and end times in Unix time in milliseconds.

  • "EpochSeconds": When you use this value, SignalFx encodes the start and end times in Unix time in seconds. Splunk expects this format for timestamps.

  • "ISO8601": ISO8601 time/date format. When you use this value, SignalFx encodes the start and end times as ISO 8601-format strings.

For example, SignalFx converts the start time "February 25, 2020 10:06:35 PM GMT+0" as follows:

  • "Epoch"1582668395000

  • "EpochSeconds"1582668395

  • "ISO8601""20200225T220635Z"

Always specify minimumTimeWindow in milliseconds, regardless of the time format you specify. For example, suppose you want to create a Splunk data link with a minimum time window of 300 seconds (5 minutes). Specify the following:

  • `"timeFormat": "EpochSeconds"

  • `"minimumTimeWindow": 300000

See the section Request body for a more detailed example.

Examples

This example demonstrates how to create global dashboard, Splunk, and external site link targets for a metadata key and value.

Scenario

  • You want to create global link targets for the metadata with the key host and the value server1.

  • For this trigger, you want the following targets:

    • Splunk instance https://example.splunk.com

      • Minimum time window of 5 minutes

    • External site https://www.example.com. For this target, you want to send a search query with the following parameters encoded on the URL:

      • Key (host)

      • Value (server1)

      • Minimum time window of 5 minutes

      • Region key-value pair from the current context. www.example.com uses area to refer to the SignalFx region property.

    • SignalFx dashboard Example Dashboard, id "XYZZY"

      • The dashboard group name is Example Dashboard Group, id "ABCCB"

You want to name this data link "Example data link".

The default link target is the Splunk link.

Request body

To create this data link, send a POST request to https://api.{REALM}.signalfx.com/v2/crosslink with the following JSON for a request body:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
    "id": "Example data link",
    "propertyName": "host",
    "propertyValue": "server1",
    "contextId": "global",
    "targets": [
        {
            "type": "INTERNAL_LINK"
            "isDefault": false,
            "name": "Dashboard data link 1",
            "dashboardGroupId": "ABCCB",
            "dashboardId": "XYZZY",
        },
        {
            "type": "SPLUNK_LINK"
            "isDefault": true,
            "name": "Splunk data link 1",
            "url": "\https://example.splunk.com"
            "timeFormat": "EpochSeconds"
            "timeWindow": 300000
        },
        {
            "type": "EXTERNAL_LINK",
            "isDefault": false,
            "name": "External link 1",
            "minimumTimeWindow": "300000",
            "timeFormat": "ISO8601",
            "url": "\https://www.example.com?hostkey={{key}}&host={{value}}&start={{start_time}}&end={{end_time}}&region={{properties.region}}",
            "propertyKeyMapping": { "region": "area" }
        }
    ]
}

The API provides the following operations:

Create data links

creates one or more link targets for the metadata you specify.

Retrieve data links

Retrieves existing data link information:

Update data links

updates data link object properties and link target properties for a single data link definition specified by its ID. The update operation uses overwrite semantics, so you need to send existing values back to the API, even if you haven’t changed them.

Delete data links

deletes a single data link definition specified by its ID.

© Copyright 2020 Splunk, Inc.

Third-party license information