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

  • Time window start and end time. 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

  • Time window start time

  • Time window end time

The time window is pre-defined to be 1 minute, centered on the trigger’s time context. For example, if the trigger is visible for a chart whose right margin is the current time, the time window starts at 1 minute before the current time.

To learn more about 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

SignalFx defines the following variable tags:

  • {{key}}: Trigger key name

  • {{value}}: Trigger value

  • {{start_time}}: Start time of the link target’s minimum time window. To learn more, see the section Minimum time window.

  • {{end_time}}: End time of the link target’s minimum time window. 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

When you use a link target to search for metadata in an external system, SignalFx adds a time window to the URL. This time window reflects the trigger’s current time. For example, if the trigger appears in an alert modal, the time window is centered on the time that the alert occurred.

Because SignalFx is a dynamic system, the trigger’s time context may be a brief time period, and the time window that SignalFx adds to the URL is small. As a result, the search may fail because the data sent to the external system isn’t found in this brief time window.

To avoid this problem, you can specify a minimum time window that’s more broad that the typical time context for the trigger.

For example, suppose a chart usually shows data over the last 500 milliseconds. If you specify a minimum time window of 1 minute for a link target, the external system searches in its data for the last minute instead of the last 500 milliseconds.

Minimum time window variable tags

For a custom external URL, use the following variable tags to specify the start and end time of the minimum time window:

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

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

Time format

To ensure compatibility with external systems, SignalFx lets you set the time format for the minimum time window value, using the timeFormat property. You can specify one of these enumerated strings:

  • "Epoch": Unix epoch time. When you use this value, {{start_time}} and {{end_time}} are encoded as Unix epoch timestamps.

  • "ISO8601": ISO8601 time/date format. When you use this value {{start_time}} and {{end_time}} are encoded as ISO 8601-format strings

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

    • 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
{
    "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"
        },
        {
            "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 2019 SignalFx.

Third-party license information