SignalFx Developers Guide

Developer Home

Product Docs

SignalFx
Documentation Powered by ReDoc

Metrics Metadata API

API for creating, retrieving, updating, and deleting metric names and MTS metadata.

NOTE:* Although you can't set custom properties or tags for a metric, you can retrieve them for metrics and metric time series (MTS**).

Retrieve Dimensions Query

Retrieves dimensions based on a query

Retrieves the dimensions objects for the search criteria you specify in the query query parameter.

The query can contain one or more of the following:

  • Dimension names
  • Dimension names and values
  • Custom property names

The API first collects all of the matching results. This is known as the result set. Depending on the values you specify for offset and limit, the number of metadata objects in the response body can be smaller than than the result set. For example, if you specify offset=0 (the default) and limit=50, and the API finds 100 matches, you only receive the first 50 results.

query Parameters
query
string

Search criteria for the dimensions you want to retrieve

Use this syntax:

  • To search for a dimension name use query=key:<dimension_name>
  • To search for specific values of a dimension use the name and value as query=<name>:<value>. If <value> contains non-alphanumeric characters (for example, blanks), surround it with double quotes.
  • Use * as a wildcard character. For example, to search for all values of the region dimension, use query=region:*.
  • To search for the existence of dimensions, use _exists_ and _missing_. For example, to search for metadata that has the host_machine dimension, specify query=_exists_:host_machine.
  • A single dimension name or name-value pair (or wildcards) make up a predicate that implicitly returns a boolean.
  • Join predicates with the NOT, AND, and OR boolean operators.
  • Use parentheses '(' and ')' to change the evaluation order. For example, to retrieve all metadata that has the dimensions region:emea and hostname:france-*, use query=region:emea AND hostname:france-*.
orderBy
string

Metadata object property on which the API should sort the results. This must be a property of the dimensions metadata object.

offset
integer <int32>

Object in the result set at which the API should start returning results to you. If omitted, the API starts at the first result in the set.

limit
integer <int32>

Number of results to return from the result set

header Parameters
X-SF-TOKEN
required
string

Authentication token

Responses

Response Schema: application/json
count
integer <int64>

Number of metadata objects that matched the search criteria. This isn't the same as sizeOf(results), because the limit and offset query parameters affect the number of objects in the response body.

Array of objects (DimensionMetadata)

List of dimension metadata objects, in the form of an array of JSON objects. Each object contains metadata for a dimension that matched the query.

Response samples

Content type
application/json
{
  • "count": 0,
  • "results":
    [
    ]
}

Retrieve Dimension Metadata Name Value

Retrieves metadata for a dimension and value

Retrieves the metadata for the dimension and value specified in the key and value path parameters

path Parameters
key
required
string

Dimension name

value
required
string

Dimension value

header Parameters
X-SF-TOKEN
required
string

Authentication token

Responses

Response Schema: application/json
created
integer <int64>

Dimension creation timestamp, in Unix time

This property is set by the system, and you can't modify it.

creator
string

SignalFx-assigned ID of the user who "created" the dimension. This can be one of the following:

  • User who created the integration that sent the dimension
  • User who sent the dimension using the API
  • User who added the dimension using the UI

If the value is "AAAAAAAAAAA", SignalFx created the dimension.

object <= 50 items

Dimension custom properties, in the form of a JSON object containing custom property key-value pairs. Names and values have these requirements:

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 (_)

Value:

  • String: Maximum length 256 UTF-8 characters (1024 bytes)
  • Integer or float: Maximum length 8192 bits (1024 bytes)
description
string <UTF-8> [ 0 .. 1024 ] characters

Dimension description, up to 1024 UTF-8 characters

key
string <= 128 characters

Dimension name. It has these requirements:

  • 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_
lastUpdated
integer <int64>

Last updated timestamp, in Unix time

lastUpdatedBy
string

SignalFx-assigned ID of the user who last updated the dimension by modifying its metadata. If the value is "AAAAAAAAAAA", SignalFx last modified the dimension.

tags
Array of strings <= 50 items

Tags for the dimension, in the form of a JSON array of tag names

Each tag is a UTF-8 string, starting with an uppercase or lowercase alphabetic character. The maximum length is expressed in characters; if a string consists solely of single-byte UTF-8 entities, 1024 characters are available.

NOTE: You can't have more than 50 tags per MTS, so you can't have more than 50 tags total for all of the dimensions associated with the MTS.

value
string <= 256 characters

Dimension value. It has these requirements:

  • String: Maximum length 256 UTF-8 characters (1024 bytes)
  • Integer or float: Maximum length 8192 bits (1024 bytes)

Response samples

Content type
application/json
{
  • "created": 1555065030000,
  • "creator": "string",
  • "customProperties": { },
  • "description": "string",
  • "key": "string",
  • "lastUpdated": 1555237830000,
  • "lastUpdatedBy": "string",
  • "tags":
    [
    ],
  • "value": "string"
}

Update Dimension Metadata

Overwrites metadata for the specified dimension

Overwrites metadata for the dimension specified by the name and value in the path parameters.

This method uses overwrite semantics. Properties in the request body overwrite existing values. If a property exists and you omit it from the request body, the API sets it to null.

path Parameters
key
required
string

Name of the dimension you want to update

value
required
string

Value of the dimension you want to update

header Parameters
X-SF-TOKEN
required
string

Authentication token

Request Body schema: application/json

Custom properties or tags (or both) that you want to add or update for the specified dimension key and value

object

Custom property updates. Because PUT /dimension/{key}/{value} has overwrite semantics, you need to include existing custom properties when you update; otherwise, they're deleted.

  • To change the value of a custom property, use "<property_name>": "<new_value>".
  • To add a custom property, use "<new_property_name>": "<value>"
description
string <UTF-8> [ 0 .. 1024 ] characters

Updated dimension description

key
string <= 128 characters

Dimension name for which you want to update metadata

tags
Array of strings <= 50 items

List of tags you want to add, in the form of a JSON array. Because PUT /dimension/{key}/{value} has overwrite semantics, you need to include existing tags when you update tags or custom properties; otherwise, they're deleted.

value
string <= 256 characters

Dimension value for which you want to update metadata

Responses

Response Schema: application/json
created
integer <int64>

Creation timestamp, in Unix time

This property is set by the system, and you can't modify it.

creator
string

SignalFx-assigned ID of the user who "created" the dimension. This can be one of the following:

  • User who created the integration that sent the dimension
  • User who sent the dimension using the API
  • User who added the dimension using the UI

If the value is "AAAAAAAAAAA", SignalFx created the dimension.

object <= 50 items

Custom properties for the dimension, in the form of a JSON object containing custom property key-value pairs

description
string <UTF-8> [ 0 .. 1024 ] characters

Dimension description, up to 1024 UTF-8 characters

key
string <= 128 characters

Name of the updated dimension

lastUpdated
integer <int64>

Last updated timestamp, in Unix time

lastUpdatedBy
string

SignalFx-assigned ID of the user who last updated the metric by modifying its metadata. If the value is "AAAAAAAAAAA", SignalFx last modified the metric.

tags
Array of strings <= 50 items

List of tags for the dimension, in the form of a JSON array of strings

value
string <= 256 characters

Value of the updated dimension

Request samples

Content type
application/json
{
  • "customProperties": { },
  • "description": "string",
  • "key": "string",
  • "tags":
    [
    ],
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "created": 1557484230100,
  • "creator": "string",
  • "customProperties": { },
  • "description": "string",
  • "key": "string",
  • "lastUpdated": 1557570630000,
  • "lastUpdatedBy": "string",
  • "tags":
    [
    ],
  • "value": "string"
}

Retrieve Metadata Metrics Query

Retrieve metadata for metrics

Retrieves metadata objects for which the metrics name matches the search criteria.

The API first collects all of the matching results. This is known as the result set. Depending on the values you specify for offset and limit, the number of metadata objects in the response body can be smaller than than the result set. For example, if you specify offset=0 (the default) and limit=50, and the API finds 100 matches, you only receive the first 50 results.

query Parameters
query
string

Metric name search string. The string always starts with name:. You have the following search options:

  • To search by metric name, use name:<metric_name>. This returns all of the metadata for that metric.
  • To search for names using wildcards, use * as the wildcard character. For example, to search for all the metrics that start with cpu., use name:cpu.*. This returns metadata for cpu.utilization, cpu.num_cores, and so forth.
orderBy
string

Result object property on which the API should sort the results. This must be a property of the metrics metadata object.

offset
integer <int32>
Default: 0

Object in the result set at which the API should start returning results to you. If omitted, the API starts at the first result in the set.

limit
integer <int32>

Number of results to return from the set of all metrics that match the query.

header Parameters
X-SF-TOKEN
required
string

Authentication token

Responses

Response Schema: application/json
count
integer <int64>

Number of metadata objects that matched the specified metrics name. This isn't the same as sizeOf(results), because the limit and offset query parameters affect the number of objects the API returns in the response body.

Array of objects (MetricsMetadata)

List of results, in the form of a JSON array of metadata objects

Response samples

Content type
application/json
{
  • "count": 0,
  • "result":
    [
    ]
}

Retrieve Metadata Metric Name

Retrieves the metadata for a metric name

Retrieves the metadata for the metric name specified in the {name} path parameter. The API returns all of the metadata for this metric.

path Parameters
name
required
string
Example: network.usage.rx_bytes