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:


Key-value pairs in 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 tags. Use them to associate dimensions with classification metadata.


Labels or keywords that you assign to dimensions, charts, and detectors. 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.

Using 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.

Dimensions, custom properties, and tags 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 Set value on a datapoint’s dimensions after sending datapoint

Can Set value on a datapoint’s dimensions 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)

Metadata for a dimension, tag, chart, or detector

Metadata for a dimension, chart, or detector

Always applied to a metric

Applied to a dimension, tag, chart, or detector

Applied to a dimension, chart, or detector

Key-value pair

Key-value pair


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.

Metadata criteria


The optional description property lets you provide a detailed description of a metric, dimension, or tag. You can use up to 1024 UTF-8 characters for description.

Dimension criteria

  • Dimension name:

    • UTF-8 string, maximum length of 128 characters (512 bytes)

    • Must start with an uppercase or lowercase letter. The rest of the name can contain letters, numbers, underscores (_) and hyphens (-).

    • Must not start with the underscore character (_)

    • Must not start with the prefix sf_, except for dimensions defined by SignalFx such as sf_hires

    • Must not start with the prefix aws_, gcp_, or azure_

Dimension values are UTF-8 strings with a maximum length of 256 UTF-8 characters (1024 bytes). Numbers are represented as numeric strings.

You can have up to 36 dimensions per MTS.

Custom properties criteria

Dimension criteria for names and values also apply to custom properties.

You can have up to 75 custom properties for a dimension or tag.

Tags criteria

Tags are UTF-8 strings with a maximum length of 256 UTF-8 characters/1024 bytes.

You can have up to 50 tags for a SignalFx entity. This includes:

  • Dimensions

  • Charts

  • Detectors

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 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


Selects any object which has a region property or dimension

The following example describes how to run a query to search for all dimensions that have a custom property for "region" equal to "japan".

$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN"
       --request GET

The response body is similar to the following:

    "results" : [
            "creator" : "<CREATOR_ID>",
            "lastUpdatedBy" : "<UPDATER_ID>",
            "created" : <CREATE_TIMESTAMP>,
            "lastUpdated" : <UPDATE_TIMESTAMP>,
            "customProperties" : { "region" : "eu-west-1" },
            "tags" : [ "test-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.


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.

The following curl command shows you how to retrieve MTS.

#The query parameter
#"region:japan AND NOT (host:server1 OR host:server2)"
#which must be URL-encoded
#Execute the request to find metric time series that match the query

$ curl \
    --header "X-SF-TOKEN: <YOUR_ACCESS_TOKEN>" \
    --request GET

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 2020 Splunk, Inc.

Third-party license information