SignalFx Developers Guide

Working with Metrics Metadata

SignalFx collects and provides metadata that lets users find, filter and aggregate metric time series and other objects. This metadata has three types:

Dimensions

Key-value pairs included as part of a datapoint sent to SignalFx. Dimensions usually identify the source of a metric, or some aspect of it; for example, the dimension hostname can contain a human-readable name of the machine that sends a cpu.utilization metric. Dimension values are usually non-numeric and don’t change over time. Each combination of dimensions and metric names sent to SignalFx uniquely identifies a metric time series and its datapoints.

Custom properties

Key-value pairs that you add to existing dimensions or metric names. Use them to do the following:

  • Associate metrics with classification metadata

  • Provide metadata that you don’t know or can’t conveniently send when you send data to SignalFx

  • Provide metadata when you don’t need to know the history of the data.

Tags

Tags act as labels or keywords assigned to dimensions, metrics and other objects. They’re simply values, not key-pairs. Use tags when a one-to-many relationship exists between the tag and its object. For example, suppose you have several hosts, each of which runs multiple apps. You can create a tag for each app, then apply multiple "app tag" values to each host dimension to indicate the apps that run on that host.

Criteria for metrics and dimensions

Metrics and dimensions you send to SignalFx with the /datapoint API must conform to the following criteria:

  • Metrics

    • Metric name must be a non-empty UTF-8 string with a maximum length ⇐ 256 characters.

    • A numeric metric value must be a 64-bit integer or float value.

    • A string metric value can also be any non-empty UTF-8 string with a maximum length ⇐ 256 characters.

  • Dimensions

    • Dimension names and values have a maximum length of 128 characters.

    • Dimension names must not start with the underscore character (_).

    • Dimension names must not start with the prefix sf_, except for dimensions defined by SignalFx such as sf_hires.

    • Dimension names and values must start with a letter (upper or lower case). The rest of the name can contain letters, numbers, underscores (_) and hyphens (-).

SignalFx rejects any POST request to /datapoint request that doesn’t meet the aforementioned criteria.

Rules for dimensions, custom properties, and tags

You can apply custom properties to tags as well as dimensions. When you do so, objects that have the tag inherit properties you associate with the tag. For example, if you associate the '"tier": "web"' custom property with the "apps-team" tag, any metric or dimension that you tag with "apps-team" also gets the '"tier": "web"' custom property.

You can apply dimensions, custom properties, and tags to datapoints, but they are different types of metadata with different intended uses.

Table 1. Differences between dimensions, properties, and tags
Dimension Property Tag

Must know value when sending datapoint

Can send value after sending datapoint

Can send value after sending datapoint

Defined when you send datapoint

Defined via web UI or REST API

Defined via web UI or REST API

With metric, defines a metric timeseries (MTS)

Additional classification for an existing MTS

Additional classification for an existing MTS

Always applied to a metric

Applied to a metric or a dimension

Applied to a metric, dimension, or detector

Key-value pair

Key-value pair

Keyword

Use to filter or group by

Use to filter or group by

Use to filter only

For more information on SignalFx metric metadata, see the product docs for metrics metadata.

Creating or updating metrics and dimensions

You do not have to explicitly create metric or dimension objects. If they don’t already exist, they are created automatically by SignalFx when received as a part of a datapoint request. Both the metric and dimension endpoints have "create or update" semantics, so if a PUT request is received for an object which doesn’t exist, it will be created, otherwise it will be updated. Here is an example request to create (or update) a dimension:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
$ curl \
    --request PUT \
    --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
    --header "Content-Type: application/json" \
    --data '
        {
            "key" : "<DIMENSION_NAME>", \
            "value": "<DIMENSION_VALUE>", \
            "tags": ["<TAG>"], \
            "customProperties": \
            { "<PROPERTY_NAME>" : "<PROPERTY_VALUE>" } \
        }' \
        https://api.<REALM>.signalfx.com/v2/dimension/host/lb-tokyo

The response body for this request is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    {
        "creator" : "<CREATOR_ID>",
        "lastUpdatedBy" : "<LAST_UPDATE_ID>",
        "created" : <CREATE_TIMESTAMP>,
         "lastUpdated" : <UPDATE_TIMESTAMP>,
         "customProperties" : { "<PROPERTY_NAME>" : "<PROPERTY_VALUE>" },
         "tags" : [ "<TAG>" ],
         "key" : "<DIMENSION_NAME>",
         "value" : "<DIMENSION_VALUE>"
     }

Searching for metrics, dimensions, or properties

The API search syntax is similar to Elasticsearch syntax:

  • Specify search terms as key-value pairs using the syntax key:value. Notice that key and value are not delimited with quotes.

  • * is the multi-character wildcard. It’s allowed anywhere in a string

  • ? is the single-character wildcard. It’s allowed anywhere in a string

  • The logical operators AND, OR, and NOT can join terms or expressions

  • Use parentheses ( and ) to control evaluation order.

Search doesn’t differentiate between dimensions and custom properties. Queries such as region:japan search for the dimension "region" with a value of "japan" as well as a custom property "region" with a value of "japan".

The following examples show you how to do queries:

region:japan AND tags:"web-tier" AND NOT tags:"production"

Selects objects that are in the japan region, have the tag "web-tier", but do not have the tag "production"

(region:japan AND tags:"web-tier") OR region:emea

Selects objects that have the dimension or property japan and the tag web-tier, or objects that have the dimension or property emea.

region:* Selects any object which has a region property or dimension.

The following code is a full example of running a query to search for all dimensions that have a custom property for "region" equal to "japan":

1
2
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN"
       https://api.<REALM>.signalfx.com/v2/dimension?query=region:japan

The response might contain the following JSON:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
    "results" : [
        {
            "creator" : "AAAAAAAAAAA",
            "lastUpdatedBy" : "ByZgBHNAYAA",
            "created" : 1438217683080,
            "lastUpdated" : 1449856007264,
            "customProperties" : { "region" : "japan" },
            "tags" : [ "<TAG>" ],
            "key" : "host",
            "value" : "lb-tokyo"
        }
    ],
    "count" : 1
}

AND / OR / NOT operators

By default, the API combines search terms using the OR operator. Given the query region:japan host:server5, the result contains objects that either have a region of japan or host of server5 (or both) as a dimension or custom property.

To specify that both terms must match, use AND to join the terms. For example, searching region:japan AND host:server5 returns results that have both the japan region and the server5 host as a dimension or custom property.

Use NOT to exclude results that contain a term. For example, searching region:japan AND NOT host:server5 returns results that contain the japan region, but only if they don’t include the server5 host.

Grouping

Parenthesis group terms or expressions. For example, the query region:japan AND (host:server5 OR env:production) returns results that contain the japan region and either the server5 host or the production env.

Wildcard searches

Use ? as a single character wildcard and as a multiple character wildcard in string terms. For example, host:webServer returns results that have a host dimension or custom property value with the prefix "webServer".

Range queries

To specify alphabetic or numeric range terms, use brackets and the TO operator.

For example, lastUpdated:[1420099200000 TO 1451635200000] returns results that were last updated between January 1, 2015 00:00 and December 31, 2015 24:00, inclusive. In this case, the values are in Unix time format.

As another example, customer:[Alice TO Charlie] returns any results that contain a customer value between Alice and Charlie (inclusive).

To make a range query exclusive, enclose it in curly brackets instead of square brackets. For example, lastUpdated:{1420099200000 TO 1420099200002} only searches for the lastUpdated value of 1420099200001.

Property existence checks

To search for results that contain a property key, use the exists pseudofield key. It always appears as the key in a key:value pair, and it means "the associated value is the name of a custom property".

To search for results that don’t contain a property key, use the missing pseudofield key. It means "the associated value is not the name of any custom property."

For example, to find results that contain the host_machine property, regardless of value, search for exists:host_machine.

Filtering and grouping time series

When you create charts or alerts, you select the timeseries by creating a filter that matches metric names, dimensions, custom properties, or tags.

You can also use shared dimensions or custom properties to group time series data together.

For example:

1
2
3
4
5
6
7
8
# The query parameter
# "region:japan AND NOT (host:server1 OR host:server2)"
# which must be URLencoded
QUERY="region:japan+AND+NOT+%28host:server1+OR+host:server2%29"
# Execute the request to find metric time series that match the query

$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN"
  https://api.<REALM>.signalfx.com/v2/metrictimeseries?query=${QUERY},

The result of this curl request is all the time series that have region:japan, except for timeseries that have host of server1 or server2. As previously noted, the query matches both dimensions and custom properties.

© Copyright 2019 SignalFx.

Third-party license information