SignalFx

Suggest Edits

/session

Creates a new session token

 
posthttps://api.signalfx.com/v2/session
curl -i \
   -H "Content-Type: application/json" \
   -X POST \
   -d \
   '{
     "email": "user@organization.com",
     "password": "userpassword"
   }' \
   https://api.signalfx.com/v2/session
A binary file was returned

You couldn't be authenticated

{
 'accessToken': '<access-token>',
 'createdBy': 'CkClZUKAIAQ',
 'createdMs': 1465239513540,
 'disabled': false,
 'email': 'user@organization.com',
 'expiryMs': 1467831513540,
 'id': 'CkSfGddAAAg',
 'organizationId': 'CMtLSYXAEJQ',
 'sessionType': 'ORG_USER',
 'updatedBy': null,
 'updatedMs': 1465239513540,
 'userId': 'CkClZUKAIAQ',
 'userName': null
}
{
    "type": "error",
    "status": 401,
    "message": "The email/password combination was entered incorrectly. Please try again."
}

Body Params

email
string

The email address of the user

password
string

The password for the user

organizationId
string

(Optional) The ID of the organization to associate with the new token. If no ID is specified, the token will use the default organization for the user.

 
Suggest Edits

/session

Invalidates an existing session token

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.signalfx.com/v2/session
curl -i \
   -H "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
   -H "Content-Type: application/json" \
   -X DELETE \
   https://api.signalfx.com/v2/session
A binary file was returned

You couldn't be authenticated

{
    "type": "error",
    "status": 401,
    "message": "The email/password combination was entered incorrectly. Please try again."
}

Body Params

X-SF-Token
string

The session's access token

 
Suggest Edits

/datapoint

Send metric data points to SignalFx

 
posthttps://ingest.signalfx.com/v2/datapoint
# Requires an org token as the access token. For more information, see 
# https://developers.signalfx.com/v2/docs/authentication-overview

curl -i \
  --header  "Content-Type: application/json" \
  --header "X-SF-TOKEN: YOUR_ORG_ACCESS_TOKEN" \
  -X POST \
  -d \
  '{ 
  	"gauge": [{ 
    	"metric": "test.gauge",
      "value": 42,
      "dimensions": { "host": "testserver" } 
    },
    { 
    	"metric": "test.gauge.with_timestamp",
      "value": 42,
      "timestamp": 1485801354682,
      "dimensions": { "host": "testserver" } 
    }],
    "counter": [{ 
    	"metric": "test.counter",
      "value": 1,
      "dimensions": { "host": "testserver" }
    }],
    "cumulative_counter": [{ 
    	"metric": "test.cumulative_counter",
      "value": 100,
      "dimensions": { "host": "testserver" }
    }]  
  }' \
  https://ingest.signalfx.com/v2/datapoint
A binary file was returned

You couldn't be authenticated

"OK"
<string error message>
"Unauthorized"

Body Params

gauge
array

Array of gauge metric datapoint objects

counter
array

Array of counter metric datapoint objects

cumulative_counter
array

Array of cumulative counter metric datapoint objects

 

Datapoint object model

The datapoint is map of key value pairs, some required, some optional:

  • metric (required) - a string conforming to the rules below

  • value (required) - a number, either floating point or integer

  • dimensions (optional) - a map of key value pairs conforming to the rules below

  • timestamp (optional) - the timestamp of the datapoint in milliseconds since epoch. The default is the time the datapoint is received by SignalFx. Note that the timestamp must be in milliseconds, not in seconds.

Note: To mark the datapoints for an MTS as high resolution, you must specify the value "sf_hires": "1" as a dimension. For an example of how to do this, see the test.cumulative_counter metric in the preceding curl example. To learn more about high-resolution MTS, see sf_hires dimension

Criteria for Metric and Dimension Names and Values

The following criteria describe acceptable metric and dimension information that can be sent in a datapoint.

  • Metric (the metric name) can be any non-empty UTF-8 string, with a maximum length <= 256 characters

  • Value (the metric value) can be any integer or float value ±1.79769313486231570E+308

  • Value (the metric value) can also be any non-empty UTF-8 string, with a maximum length <= 256 characters

  • Dimension names must conform to the following:

    • 128 character maximum length

    • Not start with _.

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

    • Start with a letter (upper or lower case). The rest of the name can contain letters, numbers, underscores _ and hyphens - . This requirement is expressed in the following regular expression:

      ^[a-zA-Z][a-zA-Z0-9_-]*$

SignalFx rejects any datapoint request that doesn't meet these criteria.

Note

The criteria for dimension names and values shown above also apply to custom properties that are not sent as part of a datapoint, but that may be set later. In addition, custom property names should not start with aws_.

Suggest Edits

/backfill

 

Header Auth

 Authentication is required for this endpoint.
posthttps://backfill.signalfx.com/v1/backfill
# Requires an org token as the access token. For more information, see 
# https://developers.signalfx.com/v2/docs/authentication-overview
# The following example shows how to send a backfill 4 datapoints for a counter type starting midnight, December 20th 2015 with values 100, 200, 400, 300:

$ curl \
  --request POST \
  --header "X-SF-TOKEN: YOUR_ORG_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"timestamp":1450569600000, "value":100}
          {"timestamp":1450569610000, "value":200}
          {"timestamp":1450569620000, "value":400}
          {"timestamp":1450569630000, "value":300}' \
  "https://backfill.signalfx.com/v1/backfill?orgid=MY_ORG_ID&sfxdim_mydimension=myvalue&metric=MY_METRIC_NAME&metric_type=counter"
A binary file was returned

You couldn't be authenticated

Body Params

orgid
string

your organization ID.

metric
string

the name of the metric being backfilled.

sfxdim_DIMENSION_NAME
string

replace DIMENSION_NAME with your dimension. The value should be the value of the dimension. Add one such parameter per dimension.

metric_type
string

type of your metric. Can be gauge, counter or cumulative_counter.

 

If you need to send historical data, SignalFx provides a backfill API endpoint that allows for datapoints to be ingested into the system in the past. This is in contrast to the the /datapoint endpoint, which is designed to accept datapoints in a streaming manner, as they are generated, and expects the timestamps of the datapoints to be in monotonically increasing order (when they are specified)

This ability comes with certain requirements/best practices that the user must keep in mind to ensure the desired results are obtained.

  • A given backfill call may only target a single metric time series, addressed by its dimensions, its metric type and its metric name.

  • Within a given backfill call, datapoints must be sent in chronological order (for the same reasons the /datapoint endpoint only accepts datapoints in order).

  • A single backfill call must contain exact multiples of one hour of datapoints starting from the top of an hour (7:00 AM to 8:00AM, 9:00PM to 3:00AM, etc). Each hour of data starts at 1 millisecond after the hour and ends on the following hour. That is, the range is exclusive of the starting hour but inclusive of the end hour (i.e., 07:00:00.001-08:00:00.000 is a valid hour-long window). It is recommended that each call contains a few thousand datapoints (for example, 1 day of 1 minute resolution points or 1 hour of 1 second resolution points).

  • Backfill calls should not contain significant gaps in the history of data being backfilled because they overwrite all existing data for the period being backfilled. If there is a need to backfill multiple disjoint periods of time, they should be backfilled through distinct API calls.

  • Backfill will overwrite any existing TSDB data. Derived metrics and the output of analytics in charts based on historical data that is being overwritten by a backfill call will not be recalculated with the new data.

The /backfill API endpoint supports the same ingest styles as the /datapoint endpoint with regard to content type (JSON and ProtocolBuffers) and the ability to stream multiple datapoints through the same HTTP POST request. Refer to the examples in Metric Data Overview for the corresponding documentation.

Specify metric, dimensions and metric type as query parameters.

  • For the metric, the query parameter is "metric".

  • For any dimension XYZ, the query parameter is sfxdim_XYZ. For example, to backfill for the dimension "host", one would use the query parameter sfxdim_host.

  • For metric type, the query parameter is metric_type. Just as for regular ingest, the available metric types are gauge, counter and cumulative_counter. The metric type for a particular metric should not be changed across different calls to the backfill API. If the metric is already in our system we will use the metric type of the existing metric. If it is not present we will create the metric with the metric type you specify. If the metric_type query parameter is absent then it is assumed to be a gauge.

Each datapoint should be represented as a JSON object within braces '{ .. }'. Successive values should be separated by a space (NOT by a comma). Make sure both the timestamp and the value are sent as numbers (NOT as strings).

Note: orgid can be looked up from the /organization endpoint.

Suggest Edits

/event

Send custom event to SignalFx

 

Header Auth

Query Auth

 Authentication is required for this endpoint.
posthttps://ingest.signalfx.com/v2/event
# the api takes an array of event objects
# Requires an org token as the access token. For more information, see 
# https://developers.signalfx.com/v2/docs/authentication-overview
curl -i \
  --header "Content-Type: application/json" \
  --header "X-SF-TOKEN: YOUR_ORG_ACCESS_TOKEN" \
  -X POST \
  -d \
  '[{
    "category": "USER_DEFINED",
    "eventType": "test event",
    "dimensions": { "environment": "production", "service": "API" },
    "properties": { "sha1": "1234567890abc" },
    "timestamp": 1480870800000
  }]' \
  https://ingest.signalfx.com/v2/event
A binary file was returned

You couldn't be authenticated

 

Custom events can be sent to SignalFx, and are commonly used to make a note of when code or infrastructure deployments happen, so that changes to key metrics can be correlated with the deployments.

For background information on how events are available to be viewed in the SignalFx web UI, see the documentation.

Object Model

This API takes an array of event objects of the form:

  • eventType: (required) The name used to define the "type" of the event and conforms to the rules below. For example: "code push", "database start". You will use this type to find your events.

  • dimensions: (optional) A map of name value pairs conforming to the rules below which will be used to distinguish different "types" of events. For example, environment information or database names. Dimension values should not change for each event you send.

  • properties: (optional) A map of name value pairs conforming to the rules below that are unique to the event that occurred. For example, SHA1 of the code commit pushed or who started the database.

  • category: (optional) The category of event. Defaults to USER_DEFINED but other allowable fields include ALERT, AUDIT, JOB, COLLECTD, SERVICE_DISCOVERY, and EXCEPTION.

  • timestamp:(optional) The timestamp of the event in milliseconds since epoch, defaulting to the time the event was received by SignalFx. Note that the timestamp must be in milliseconds, not in seconds.

If you want to send a single event, it would be an array with one element.

To see the events you have sent, click the Events button in the top right corner of any dashboard and a list of recently submitted events will appear on a pullout from the right. You can also type the "eventType" value of the event into a chart builder's signal entry field in order to overlay it on top of existing data.

Criteria for names and values passed to this API

The following criteria describe acceptable information that can be sent with an event.

  • eventType (the kind of event) can be any non-empty UTF-8 string, with a maximum length <= 256 characters

  • Dimension or property name:

    • has a maximum length of 128 characters

    • may not start with _ or sf_ (In addition, a property name should not start with aws_)

    • must start with a letter (upper or lower case). The rest of the name can contain letters, numbers, underscores _ and hyphens - . This requirement is expressed in the following regular expression:

      ^[a-zA-Z][a-zA-Z0-9_-]*$

  • Dimension or property values can be any non-empty UTF-8 string, with a maximum length <= 256 characters

Suggest Edits

/timeserieswindow

Retrieve datapoints from time series for a given time window

 

Header Auth

Query Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v1/timeserieswindow
$ curl \
   --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
   --header "Content-Type: application/json" \
   --request GET \
   'https://api.signalfx.com/v1/timeserieswindow?query=sf_metric:"test.gauge"&startMs=1447228800000&endMs=1447373079476&resolution=1000'
A binary file was returned

You couldn't be authenticated

{
    "data": {
        "CTpQ1J_AYAs": [
            [
                1447367652000,
                1
            ]
        ]
    },
    "errors": []
}

Query Params

query
string

Elasticsearch string query that specifies metric time series to retrieve. (Refer to our search syntax)

startMs
int32

Starting point of time window within which to find datapoints, in milliseconds since Unix epoch

endMs
int32

End point of time window within which to find datapoints, in milliseconds since Unix epoch

resolution
int32

The data resolution, in milliseconds, in which to return the data points. Acceptable values are 1000 (1s), 60000 (1m), 300000 (5m), and 3600000 (1h).

 
Suggest Edits

/event

Retrieve events from SignalFx

 

Header Auth

Query Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v1/event
curl -i \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  -X GET \
  https://api.signalfx.com/v1/event?query=*
 
# Return events in timestamp order
# Note that orderBy is "sf_timestamp" but return response is "timestamp"

curl -i \
   --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  -X GET \
  https://api.signalfx.com/v1/event?query=* \
  &orderBy=sf_timestamp
A binary file was returned

You couldn't be authenticated

 [{
  "id" : "EVENT_ID",
  "tsId" : "TIMESERIES_ID",
  "timestamp" : "USER_PROVIDED_TIMESTAMP_OR_EVENT_FIRED_TIMESTAMP",
  // all values in properties will be a string except for the following keys
  // "sources", "inputSources", "inputValues", and "inputs". Which will be
  // maps on objects with a sf_eventCategory of "ALERT"
  "properties" : "KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES",
  "metadata" : "KEY_VALUE_MAP_OF_EVENT_METADATA",
  "eventCreatedOnMs" : "WALLCLOCK_TIME_EVENT_WAS_CREATED"
},
//….more events….
]

// Example:

 [ {
  "id" : "Cxi8E57AIAA",
  "tsId" : "Cvkdh1NAAAA",
  "timestamp" : 1479473687302,
  "properties" : {
    "foo" : "bar"
  },
  "metadata" : {
    "sf_eventCategory" : "USER_DEFINED",
    "sf_eventType" : "test event"
  },
  "eventCreatedOnMs" : 1479473687606
},
//….more events….
]

// The response can be more complex depending on the event category, 
// for example, response for ALERT event

[ {
  "id" : "Cxi0Iu7AIAA",
  "tsId" : "CwSX6WXAAAA",
  "timestamp" : 1479471565000,
  "properties" : {
    "inputs" : {
      "high" : {
        "value" : 4.0
      },
      "in" : {
        "key" : {
          "sf_metric" : "jvm.cpu.load",
          "sf_source" : "myhost"
        },
        "value" : 3.607242375
      }
    },
    "was" : "too high",
    "is" : "ok",
    "sf_resolutionMs" : 1000,
    "sf_schema" : 3,
    "incidentId" : "CxizWsMAEAA"
  },
  "metadata" : {
    "sf_eventCategory" : "ALERT",
    "sf_eventType" : "test event"
  },
  "eventCreatedOnMs" : 1479471566534
},
//... more events ...
]

Query Params

query
string

Elasticsearch query that specifies events to retrieve (refer to our search syntax)

from
int32

Minimum event timestamp in milliseconds; relative to now if <= 0

to
int32

Maximum event timestamp in milliseconds; relative to now if <= 0

orderBy
string

Ordering to apply

offset
int32

Page offset from beginning of result set. 0 is the beginning of set.

limit
int32

Maximum page size or -1 to fetch 1000 entries. Number of fetched results may be less.

 
Suggest Edits

/metric

Search metrics

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/metric
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/metric?query=service:jetty

{
  "results" : [ {
    "creator" : "AAAAAAAAAAA",
    "lastUpdatedBy" : "ByZgBHNAYAA",
    "created" : 1438217683080,
    "lastUpdated" : 1449856007264,
    "customProperties" : {
      "service" : "jetty"
    },
    "tags" : [ "test-tag" ],
    "type": "GAUGE",
    "name" : "jvm.cpu.load",
    "description" : "CPU load guage"
  } ],
  "count" : 1
}
A binary file was returned

You couldn't be authenticated

{
  "results" : [ {
    "creator" : ID_OF_CREATOR,
    "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
    "created" : TIMESTAMP_OF_CREATION,
    "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
    "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
    "tags" : LIST_OF_TAG_STRINGS,
    "type" : TYPE_OF_METRIC,
    "name" : NAME_OF_METRIC,
    "description" : DESCRIPTION_OF_METRIC
  },
   //... more results ...
  ],
  "count" : TOTAL_NUMBER_OF_RESULTS
}

Query Params

query
string

An elasticsearch string query (refer to our search syntax)

orderBy
string

The property to order results by

offset
int32

The number of results to skip for pagination

limit
int32

How many results to return

 
Suggest Edits

/metric/:name

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/metric/name
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/metric/jvm.cpu.load

{
  "creator" : "AAAAAAAAAAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1438217683080,
  "lastUpdated" : 1449856007264,
  "customProperties" : {
    "service" : "jetty"
  },
  "tags" : [ "test-tag" ],
  "type": "GAUGE",
  "name" : "jvm.cpu.load",
  "description" : "CPU load guage"
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "tags" : LIST_OF_TAG_STRINGS,
  "type" : TYPE_OF_METRIC,
  "name" : NAME_OF_METRIC,
  "description" : DESCRIPTION_OF_METRIC
}

Path Params

name
string
required

Name of metric

 
Suggest Edits

/metric/:name

Create or update a metric object

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/metric/name
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "name" : "request_count", "description": "Number of requests", "type": "COUNTER", "tags": ["test-tag"], "customProperties": { "tier" : "web" } }' \
  https://api.signalfx.com/v2/metric/request_count
 
{
  "creator" : "ByZgBHNAYAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1450134495374,
  "lastUpdated" : 1450134531331,
  "customProperties" : {
    "tier" : "web"
  },
  "tags" : [ "test-tag" ],
  "type" : "COUNTER",
  "description": "Number of requests",
  "name" : "request_count"
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "tags" : LIST_OF_TAG_STRINGS,
  "description": DESCRIPTION,
  "type" : TYPE_OF_METRIC,
  "name" : NAME_OF_METRIC
}

Path Params

name
string
required

(Required) Name of metric. Refer to metric name criteria.

Body Params

type
string

(Required) The type of metric, one of: GAUGE, COUNTER, or CUMULATIVE_COUNTER

description
string

(Optional) A description for the metric

customProperties
object

(Optional) Properties to associate with this metric. Criteria for property names and values are the same as those listed for dimensions here.

 
tags
array of strings

(Optional) Tags to associate with this metric

 
Suggest Edits

/dimension

Search dimensions

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/dimension?query=query
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/dimension?query=region:japan

{
  "results" : [ {
    "creator" : "AAAAAAAAAAA",
    "lastUpdatedBy" : "ByZgBHNAYAA",
    "created" : 1438217683080,
    "lastUpdated" : 1449856007264,
    "customProperties" : {
      "region" : "japan"
    },
    "tags" : [ "test-tag" ],
    "key" : "host",
    "value" : "lb-tokyo",
    "description" : "A loadbalancer in Tokyo"
  } ],
  "count" : 1
}
A binary file was returned

You couldn't be authenticated

{
  "results" : [ {
    "creator" : ID_OF_CREATOR,
    "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
    "created" : TIMESTAMP_OF_CREATION,
    "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
    "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
    "tags" : LIST_OF_TAG_STRINGS,
    "key" : KEY_OF_DIMENSION,
    "value" : VALUE_OF_DIMENSION,
    "description" : DESCRIPTION
  },
   //... more results ...
  ],
  "count" : TOTAL_NUMBER_OF_RESULTS
}

Path Params

query
string
required

An elasticsearch string query (refer to our search syntax)

Query Params

orderBy
string

The property to order results by

offset
int32

The number of results to skip for pagination

limit
int32

How many results to return

 
Suggest Edits

/dimension/:key/:value

Get a dimension object

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/dimension/key/value
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/dimension/host/lb-tokyo

{
  "creator" : "AAAAAAAAAAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1438217683080,
  "lastUpdated" : 1449856007264,
  "customProperties" : {
    "region" : "japan"
  },
  "tags" : [ "test-tag" ],
  "key" : "host",
  "value" : "lb-tokyo",
  "description" : "A loadbalancer in Tokyo"
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "tags" : LIST_OF_TAG_STRINGS,
  "key" : KEY_OF_DIMENSION,
  "value" : VALUE_OF_DIMENSION,
  "description" : DESCRIPTION
}

Path Params

key
string
required

Dimension key

value
string
required

Dimension value

 
Suggest Edits

/dimension/:key/:value

Update (overwrite) metadata for a dimension

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/dimension/key/value
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "key" : "host", "value": "lb-tokyo", "tags": ["test-tag"], "customProperties": { "region" : "japan" } }' \
  https://api.signalfx.com/v2/dimension/host/lb-tokyo
 
{
  "creator" : "ByZgBHNAYAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1450134495374,
  "lastUpdated" : 1450134531331,
  "customProperties" : {
    "region" : "japan"
  },
  "tags" : [ "test-tag" ],
  "key" : "host",
  "value" : "lb-tokyo",
  "description" : null
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "tags" : LIST_OF_TAG_STRINGS,
  "key" : KEY_OF_DIMENSION,
  "value" : VALUE_OF_DIMENSION,
  "description" : DESCRIPTION
}

Path Params

key
string
required

(Required) Key for the dimension.

value
string
required

(Required) Value for the dimension.

Body Params

description
string

(Optional) A description for the dimension

customProperties
object

(Optional) Properties to associate with this dimension value

 
tags
array of strings

(Optional) Tags to associate with this dimension value

 
Suggest Edits

/metrictimeseries

Search metric time series

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/metrictimeseries?query=query
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/metrictimeseries?query=region:japan

{
  "results" : [ {
    "id" : "ABCDEFABCDE",
    "creator" : "AAAAAAAAAAA",
    "lastUpdatedBy" : "ByZgBHNAYAA",
    "created" : 1438217683080,
    "lastUpdated" : 1449856007264,
    "customProperties" : {
      "region" : "japan"
    },
    "dimensions" : {
      "host" : "lb-tokyo"
    },
    "tags" : [ "test-tag" ],
    "metric" : "request_count",
    "metricType" : "COUNTER"
  } ],
  "count" : 1
}
A binary file was returned

You couldn't be authenticated

{
  "results" : [ {
    "creator" : ID_OF_CREATOR,
    "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
    "created" : TIMESTAMP_OF_CREATION,
    "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
    "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
    "dimensions" : KEY_VALUE_MAP_OF_DIMENSIONS,
    "tags" : LIST_OF_TAG_STRINGS,
    "metric" : NAME_OF_METRIC,
    "metricType" : TYPE_OF_METRIC
  },
   //... more results ...
  ],
  "count" : TOTAL_NUMBER_OF_RESULTS
}

Path Params

query
string
required

An elasticsearch string query (refer to our search syntax)

Query Params

orderBy
string

The property to order results by

offset
int32

The number of results to skip for pagination

limit
int32

How many results to return

 
Suggest Edits

/metrictimeseries/:id

Get a metric time series object

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/metrictimeseries/id
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/metrictimeseries/ABCDEFABCDE

{
  "id" : "ABCDEFABCDE",
  "creator" : "AAAAAAAAAAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1438217683080,
  "lastUpdated" : 1449856007264,
  "customProperties" : {
    "region" : "japan"
  },
  "dimensions" : {
    "host" : "lb-tokyo"
  },
  "tags" : [ "test-tag" ],
  "metric" : "request_count",
  "metricType" : "COUNTER"
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "dimensions" : KEY_VALUE_MAP_OF_DIMENSIONS,
  "tags" : LIST_OF_TAG_STRINGS,
  "metric" : NAME_OF_METRIC,
  "metricType" : TYPE_OF_METRIC
}

Path Params

id
string
required

ID of a metric time series

 
Suggest Edits

/tag

Search tags

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/tag?query=query
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/tag?query=*

{
  "results" : [ {
    "creator" : "ByZgBHNAYAA",
    "lastUpdatedBy" : "ByZgBHNAYAA",
    "created" : 1450134495381,
    "lastUpdated" : 1450134495386,
    "customProperties" : { },
    "name" : "test-tag",
    "description" : "test description"
  }, {
    "creator" : "ByZgBHNAYAA",
    "lastUpdatedBy" : "ByZgBHNAYAA",
    "created" : 1449855986386,
    "lastUpdated" : 1449855986393,
    "customProperties" : { },
    "name" : "test-tag-2",
    "description" : ""
  }, {
    "creator" : "ByZgBHNAYAA",
    "lastUpdatedBy" : "ByZgBHNAYAA",
    "created" : 1450128386054,
    "lastUpdated" : 1450128386060,
    "customProperties" : { },
    "name" : "test-tag-3",
    "description": ""
  } ],
  "count" : 3
}
A binary file was returned

You couldn't be authenticated

{
  "results" : [ {
    "creator" : ID_OF_CREATOR,
    "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
    "created" : TIMESTAMP_OF_CREATION,
    "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
    "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
    "name" : NAME_OF_TAG,
    "description" : DESCRIPTION_OF_TAG
  },
   //... more results ...
  ],
  "count" : TOTAL_NUMBER_OF_RESULTS
}

Path Params

query
string
required

An elasticsearch string query (refer to our search syntax)

Query Params

orderBy
string

The property to order results by

offset
int32

The number of results to skip for pagination

limit
int32

How many results to return

 
Suggest Edits

/tag/:name

Get a tag object

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/tag/name
$ curl --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/tag/test-tag

{
  "creator" : "AAAAAAAAAAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1438217683080,
  "lastUpdated" : 1449856007264,
  "customProperties" : {},
  "name" : "test-tag",
  "description": "test description"
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "name" : NAME_OF_TAG,
  "description" : DESCRIPTION_OF_TAG
}

Path Params

name
string
required

Name of the tag to get

 
Suggest Edits

/tag/:name

Create or update tag objects

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/tag/name
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "description": "my test tag", "customProperties": { "tier" : "web" } }' \
  https://api.signalfx.com/v2/tag/test-tag
 
{
  "creator" : "ByZgBHNAYAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1450134495374,
  "lastUpdated" : 1450134531331,
  "customProperties" : {
    "tier" : "web"
  },
  "name" : "test-tag",
  "description" : "my test tag"
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "name" : NAME_OF_TAG,
  "description" : DESCRIPTION
}

Path Params

name
string
required

Name of the tag to create or update

Body Params

description
string

(Optional) Description for tags

customProperties
object

(Optional) Custom properties to associate with the tag and all objects associated with this tag

 
 
Suggest Edits

/tag/:name

Delete a tag

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.signalfx.com/v2/tag/name
$ curl --request DELETE --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" https://api.signalfx.com/v2/tag/test-tag

{
  "creator" : "AAAAAAAAAAA",
  "lastUpdatedBy" : "ByZgBHNAYAA",
  "created" : 1438217683080,
  "lastUpdated" : 1449856007264,
  "customProperties" : {},
  "name" : "test-tag"
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR,
  "lastUpdatedBy" : ID_OF_LAST_UPDATOR,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "customProperties" : KEY_VALUE_MAP_OF_CUSTOM_PROPERTIES,
  "name" : NAME_OF_TAG
}
"Unable to find the given tag."

Path Params

name
string
required

Name of the tag to delete

 
Suggest Edits

Detectors Overview

Detectors define a set of criteria for determining when to alert users about something and a set of rules regarding what notifications to send when that criteria is met.

 

Detectors define a set of criteria for determining when to alert about something and a set of rules regarding what notifications to send when that criteria is met.

Detectors contain rules that specify:

  • When the detector will be triggered, based on conditions defined via SignalFlow
  • The severity of the alert to be generated by the detector
  • Where and how notifications should be sent and what content should be included in those notifications

When a detector is triggered, it:

  • Generates an event that provides context about the data at the time the detector is triggered
  • Triggers an alert that indicates a predetermined condition has been met
  • Sends one or more notifications to inform people about the alert

When the detector clears, it generates a second event, removes the active alert, and sends a second set of notifications.

The API creates, modifies, and deletes v2 detectors. These detectors can be directly viewed in the web application using their id property as follows:

https://app.signalfx.com/#/detector/_id_/edit

including a visual representation of the condition value over time with indications when alerts are triggered and cleared:

Detector Visualization

Detectors will also appear by name in the catalog.

NOTE: Detectors created via API calls use a slightly different interface than detectors created directly in web application (which are v1.x detectors). Some information in the SignalFx detector documentation may not apply.

Write Permissions

Anyone within an organization may edit or delete detectors by default. Organizations which have the write permissions feature enabled may limit edits and deletions of specific detectors to individuals and/or teams. This is useful for preventing unauthorized or accidental modifications to detectors. If a user does not have access to edit a detector, they may clone it for modifications, leaving the original intact. Administrators always have the ability to modify write permissions, even for detectors which they don't have permission to edit; this allows administrators the ability to escalate their access for any detector.

SignalFlow

A SignalFlow program defined in the programText property populates each detector. This SignalFlow determines the conditions that trigger alerts and the conditions needed to clear them.

Trigger Conditions

Every detect function must contain a trigger condition (also called the on condition) evaluating to a boolean value. There are three basic types of simple trigger conditions:

  • evaluate immediately conditions (condition = X). These conditions only care about the current value of the input streams each time the condition is evaluated. These conditions are designed so that as soon as X is true an alert is triggered.
  • duration conditions (condition = when(X,Y)). These conditions care about the value of the input streams for a continuous amount of time backwards from the time the condition is evaluated. These conditions are defined using when functions with the first two parameters set and are designed to trigger an alert if X is continuously true for Y duration.
  • percentage of duration conditions (condition = when(X, Y, Z)). These conditions care about the value of the input streams for a percentage of the time backwards from the time the condition is evaluated. These conditions are defined using when functions with all three parameters set and are designed to trigger an alert if X is true for Z percentage of Y duration.

From a syntactic standpoint they are all just boolean expressions and can be used interchangeably or in combination (using boolean operators to combine expressions) in any detector depending on the condition you want to trigger an alert. For more information about this, see the Syntax Requirements for Conditions section below.

For more information about how to define conditions to trigger an alert, see the detect function documentation and the when function documentation.

Clear Conditions

In general, an alert clears as soon as the trigger condition in the detect function is no longer true. In other words, the alert clears when not condition is met.

  • The not condition for evaluate immediately trigger conditions (condition = X) is met as soon as X is no longer true. For example, if the condition is data('cpu.utilization').mean() > 70, the alert clears as soon as data('cpu.utilization').mean() = 70 or data('cpu.utilization').mean() < 70.
  • The not condition for duration trigger conditions (condition = when(X,Y)) is also met as soon as the condition is no longer true, not when X has been not true for Y amount of time. For example, if the condition is when(data('cpu.utilization').mean() > 70,'5m'), the alert clears as soon as data('cpu.utilization').mean() = 70 or data('cpu.utilization').mean() < 70.
  • The not condition for percentage of trigger conditions (condition = when(X,Y,Z)) is not met as soon as X is no longer true but rather when X is false for more than 100-Z percent of the last Y amount of time.

If this is not the desired behavior, an explicit clear condition (also called the off condition) can be set as the second parameter of the detect function. For example, by default an alert condition that triggers when a is greater than b continuously for the most recent 10 minutes (when(a >b,'10m')) will clear as soon as a is no longer greater than b (a <= b). If you prefer, you can require that a is not greater than b for more than 30 seconds (when(a <= b,'30s')) before clearing the alert.

For more information about clear conditions and how they interact with trigger conditions, see the detect function documentation.

SignalFlow Syntax

The SignalFlow program defining the detector must include one or more detect functions. Each detect function must contain a trigger condition and may also have an optional clear condition and an optional mode designation that determines when and how the conditions are evaluated (non-default modes are out of the scope of this overview).

Each detect function must also be modified by a publish stream method with a label that is unique across the program. If more than one line of SignalFlow is included, each line should be separated by either semi-colons (";") or new line characters ("\n").

Syntax Requirements for Conditions

Conditions in detectors are built from streams of data. They must have at least one stream constructor (often the data function) generating the base data. The resulting streams may be used as generated, modified by a set of chainable stream methods, or transformed into new streams using operators that perform some type of calculation on their input streams (examples include mathematical operations such as returning the square root or ln of input values, evaluations like the mean of all current values or the top 5 current values, or dropping values that fall or do not fall within a specified range).

After any modifications or transformations, boolean expressions are constructed from the streams either by comparing different streams or comparing streams to a constant value using equality, less than, or greater than operators. These expressions can be further modified by when functions if duration or percentage of duration conditions are desired.

The resulting expression is considered a simple condition and may be used as is or combined with other simple conditions using boolean expressions ("and", "or", and "and not") to construct a compound condition.

A simple trigger condition might want to trigger an alert if the amount of deviation in CPU usage is high as follows:

data('cpu.utilization').stddev() > 2

where data('cpu.utilization') is the constructed data stream being modified by the stddev stream method then compared to the constant 2, resulting in a single boolean expression.

A compound condition might consider both the mean and the standard deviation as follows:

(data('cpu.utilization').stddev() > 3 and data('cpu.utilization').mean() > 50) or when(data('cpu.utilization').stddev() > 3 and data('cpu.utilization').mean() > 30,'5m')

where data('cpu.utilization') is the constructed data stream being modified by the stddev stream method in two simple conditions and by the mean stream method in two more. Each instance of the stream is compared to a constant, resulting in four boolean expressions combined by the boolean and operator into two boolean expressions. Additionally, one of these two expressions is modified by a when function to create a duration requirement (the other one is left as is for immediate evaluation) before the two are combined into a single compound boolean expression using the boolean or operator. This final expression is the trigger condition evaluated to determine whether to trigger an alert.

Syntax Requirements for Custom Notification Messages

If you wish to support custom notification messages that include input data you must use variables to assign the streams within a detector's trigger and clear conditions. The input data can then be retrieved by referencing the appropriate variable.

For example, supplying the following SignalFlow statement results in a valid detector:

detect(data('cpu.utilization').mean() > 50).publish('highCpu')

but if you want to include the mean CPU utilization value in notifications when the alert is triggered, you must use this equivalent SignalFlow instead:

var1 = data('cpu.utilization').mean(); detect(var1 > 50).publish('highCpu')

where var1 is any valid variable name. This allows the value of var1 to be referenced in the custom notification message definition. More information about custom notification messages is provided later in this overview.

Detector Resolutions

Detectors have two distinct types of resolutions - the detector job resolution and the detector display resolution. These are completely different things and should not be confused. In general, the term "detector resolution" refers to the resolution of the detector job, or how often the underlying data is analyzed to determine if an alert should be triggered. This resolution is determined by the type of data being analyzed as well as any data transformations applied and remains constant throughout the life of the detector.

The data display resolution is the rate that data populates the detector visualization; the data display resolution is automatically set to the coarsest resolution of all of the publish statements associated with the detector since they are all displayed together in the same visualization and depends on the time window shown and the rollup applied to the data. The data display resolution may change when the time window for display is modified but the underlying detector job resolution is unaffected when this happens. See the SignalFx documentation for more information about rollups and resolution.

Null Values and Handling Missing Data

Data points in a stream can evaluate to null for a variety of reasons (such as dividing by 0). In addition, data points in a stream may not be reported or may be reported too late to participate in the computation result. By default, when that happens SignalFx replaces the missing data with a null after waiting for the number of milliseconds indicated in the maxDelay property of the detector. These null values are considered neither okay nor anomalous when evaluating a stream to determine if alerts should be triggered or cleared. This lack of conclusiveness can result in unexpected behavior, especially for duration-based conditions. In general, such conditions will automatically reset and restart the clock if a missing data point registers as null.

To avoid this, you can set an explicit value for missing data in several ways. The most common are:

  • Use the last value extrapolation policy. This is done by setting the extrapolation parameter in each data function to last_value. After waiting for the max delay period, this option automatically sets any missing data points to the value immediately preceding the gap. This means that a single missing data point will not interrupt an ongoing duration measure for the condition. By default this will set up to 100 consecutive missing data points to the last value received. To shorten this, set the maxExtrapolation parameter to the desired threshold of consecutive data points. In either case, the number of extrapolations is reset as soon as a valid data point is received. For example, the following SignalFlow statement allows detectors to ignore up to three consecutive missing data points before resetting the time for any ongoing duration:

detect(when(data('cpu.utilization', extrapolation='last_value',maxExtrapolations=3).mean() > 50),'10m')).publish('highCpu')

  • Use the fill stream method. The fill stream method is similar to the last value extrapolation policy except it lets you set an explicit replacement value for the missing data points and uses a time-based rather than a number-based limitation to determine when to stop replacing null values. In this case, the data is collected and pushed to the stream after the max delay has passed. At that point, any null values are replaced with the value in the fill method for the specified amount of time. As with the counter above, the duration of the fill is reset whenever valid data is present in the stream. This would allow you to ensure that the fill value matches (or doesn't match) the detector condition if desired. For example, the following SignalFlow statement sets any missing values to 75 for 15 seconds:

detect(when(data('cpu.utilization').fill(value=75,duration='15s').mean() > 50, '10m')).publish('highCpu')

NOTE: The fill method can also be used to substitute the last value received for a set amount of time as follows:

detect(when(data('cpu.utilization').fill(duration='15s').mean() > 50, '10m')).publish('highCpu')

Because it applies the substitution on the stream after it is constructed, the fill stream method performs its substitution for all null values, not just those generated by missing data. If you want to scrub all null values from your data, using the fill stream method is the better option.

Teams

Detectors can be associated with one or more teams. This means the detector and associated alerts are available from those teams' landing pages in the web application. It does not have any bearing on notifications; associating a detector with a team only affects display in the web application.

Notifications can also be sent to some or all members of one or more teams independent of whether the detectors generating those notifications are associated with the teams being notified. More information about sending notifications to teams is provided later in this overview.

Rules

Rules control how triggered and cleared alerts are processed. Each detect function is mapped to a severity and a set of notifications using the unique label inside the associated publish method.

Severity

Severity indicates how impactful a triggered alert might be. Alerts in the web application can be easily filtered by severity, allowing you to focus on the most important alerts first. SignalFx supports five severity levels: Critical, Warning, Major, Minor, and Info.

You are free to define your own meaning for each level of severity and judge which level is appropriate for different triggering conditions; however, in general, Critical is considered the most serious, followed by Warning, Major, Minor, and the least severe Info level.

Notifications

Each rule can include one or more notification definitions indicating where and how to send notifications.

Notification Recipients

Notifications can be sent to individual users or to teams and may be send via email, using a third-party messaging system, or using a third-party incident management system. Note that some third-party systems may have limits on the rate of messages allowed. Please consult their documentation for specifics and construct your detectors accordingly.

Email Notifications

Email notifications can be sent to a single email address, to selected members of a team, or to an entire team. Multiple notification configurations can be used to send emails to more than one individual user, more than one team, or to mix and match individuals and teams.

The following table outlines how to configure different types of email notifications:

Email Recipients Number of Notifications Notification Types Prerequisites
One user One Email None
Multiple users One per user Email None
One team One TeamEmail Team must exist
Multiple Teams One per team TeamEmail Teams must exist
Members of One Team One Team Team must exist. Team must have email notifications set up for specific members.
Members of Multiple Teams One per team TeamEmail Teams must exist. Teams must have email notifications set up for specific members.

Note that individual emails may be sent to any valid email address regardless of whether the recipient is a registered user of SignalFx. However, recipients without a SignalFx account with access to your organization will not be able to follow links to specific information about the incident (like the detector generating it) in the SignalFx web application.

MessagingNotifications

Messaging notifications can be sent to either Slack or HipChat or both. These messages are routed to a specified room or channel for display. If you want messages sent to multiple rooms or channels, create one notification per desired output venue. You may also be able to send notifications to other messaging services via webhooks.

The following table outlines how to configure different types of messaging notifications:

Messaging Provider Notification Types Prerequisites
HipChat HipChat HipChat integration installed and configured
Slack Slack Slack integration installed and configured
Other Webhook Webhook integration installed and configured; mechanism for processing notification and routing it to the messaging application from messages sent to the URL specified in webhook

You can check if your organization has the desired integration available using the Get Integrations API call with a type query parameter set to the desired notification type. If so, you'll need the ID of the relevant integration object to set up notifications using that integration; the same API call will return its value. If not, contact your local SignalFx administrator to set up the necessary integration.

Incident Management System Notifications

Notifications can be sent to PagerDuty, ServiceNow, VictorOps, or to other services via webhook. These messages are routed to a specified room or channel for display. If you want messages sent to multiple rooms or channels, create one notification per desired output venue.

The following table outlines how to configure different types of incident management notifications:

Incident Management System Notification Types Prerequisites
PagerDuty PagerDuty PagerDuty integration installed and configured
ServiceNow ServiceNow ServiceNow integration installed and configured
VictorOps VictorOps VictorOps integration installed and configured. One or more routing keys set up to indicate how to process notifications once received by VictorOps.
Other Webhook Webhook integration installed and configured; mechanism for processing notification and routing it to the incident management system from messages sent to the URL specified in webhook

You can check if your organization has the desired integration available using the Get Integrations API call with a type query parameter set to the desired notification type. If so, you'll need the ID of the relevant integration object to set up notifications using that integration; the same API call will return its value. If not, contact your local SignalFx administrator to set up the necessary integration.

Custom Notification Messages

SignalFx provides default notification messages for each supported type of notification (except webhooks; webhooks use a set JSON message payload described here). For example, the default alert triggered notification in Slack might look like this for a Minor alert looking at mean CPU value:

Alert triggered notification with default Slack message

and a corresponding alert cleared notification might look like this:

Alert cleared notification with default Slack message

If you prefer, you can specify custom messages instead.

NOTE: Custom notification messages are only available via the API for v2 detectors. They will not display and cannot be modified in the web application.

Custom messages include separate subject and body sections (specified as rules[x].parameterizedSubject and rules[x].parameterizedBody corresponding to the rule controlling the notification). All notification types accept plain text containing any valid UTF-8 character as well as any of a set of variables provided by SignalFx. Some notification types also render Markdown text in their messages. See the sections below for more information.

Variables in Custom Notification Messages

SignalFx supports several types of variables in custom notification messages. They provide information about the detector definition, the current state of the detector at the time an alert is either triggered or cleared, information about the detector job data including condition values and any dimensions present, and conditional statements (if-else and if exists) among other things.

Variables are indicated within the custom message definitions using curly braces; double curly braces indicate a variable that is substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable.

Some of the more useful variables include the following:

  • detectorName - the name of the detector (as specified in the name property)
  • detectorId - the ID of the detector (as specified in the id property); permits notification recipient to use API calls to obtain further information about the detector
  • ruleSeverity - the severity defined for the rule (as specified in the rules[x].severity property corresponding to the rule controlling the notification)
  • runbookUrl - a link to more information about how to process the notification (as specified in the rules[x].runbookUrl property corresponding to the rule controlling the notification)
  • tip - a quick first step to try upon receipt of the notification (as specified in the rules[x].tip property corresponding to the rule controlling the notification)
  • anomalous - true if the alert is currently triggered
  • normal - true if the alert is currently cleared
  • #if, ^if, else, /if - provides the ability to conditionalize text; most useful for providing alternate text in alert triggered and alert cleared messages. #if indicates the condition should be true to display the enclosed content, ^if (if not) indicates the condition should be false to display the enclosed content.
  • inputs.variable.value - the value of the detector condition indicated by the specified variable corresponding to a defined data stream. See the SignalFlow Syntax section above for more information.

A more complete list of supported variables is available in the SignalFx web application documentation.

For example, the following detector checks for mean CPU usage over 60% and sends alerts with Major severity to both a Slack channel and the on call email:

{
    "name":"High Mean CPU",
    "programText":"A = data('cpu.utilization').mean(); detect(A > 60).publish('highMeanCpu')",
    "tags":["CPU"],
    "rules":[{
        "detectLabel":"highMeanCpu",
        "notifications":[{
            "type":"Email",
            "email":"oncall@example.com"
        },{
            "type":"Slack",
            "credentialId":"_id_",
            "channel":"detector-alerts"
        }
        ],
        "runbookUrl":"http://runbook.example.com",
        "tip":"Add more machines!",
        "severity":"Major",
    "parameterizedSubject": "{{ruleSeverity}} Alert: {{{ruleName}}} {{{detectorName}}}",
        "parameterizedBody": "{{#if anomalous}}\nRule \"{{{ruleName}}}\" in detector \"{{{detectorName}}}\" triggered\n{{else}}\nRule \"{{{ruleName}}}\" in detector \"{{{detectorName}}}\" cleared{{/if}}\n\n{{#if anomalous}}\nTriggering condition: CPU utilization mean > 60\n{{/if}}\n\n{{#if anomalous}}Signal value: {{inputs.A.value}}\n{{else}}Current signal value: {{inputs.A.value}}\n{{/if}}\n\n{{#notEmpty dimensions}}\nSignal details:\n{{{dimensions}}}\n{{/notEmpty}}\n\n{{#if anomalous}}{{#if runbookUrl}}Runbook: {{{runbookUrl}}}{{/if}}\n\n{{#if tip}}Tip: {{{tip}}}{{/if}}\n{{/if}}"
  }]
}

When your alert triggers, you should see the following notification via email:

Alert triggered notification with custom email message

and the corresponding expanded notification in Slack:

Alert triggered notification with expanded custom Slack message

When the value clears, you should see the following notification via email

Alert cleared notification with custom email message

and the corresponding notification in Slack:

Alert cleared notification with custom Slack message

NOTE: The thresholds for triggering and clearing alerts were artificially lowered to 30 to generate the screenshots above.

Markdown Support in Custom Notification Messages

GitHub-flavored Markdown is also supported in the body of custom notification messages only (it is not supported in the message subject). However, it may or may not be rendered depending on the intended output format of the messages. Markdown in not supported in notifications sent to any third-party incident management system or in notifications sent to third-party messaging systems other than Slack.

Email notifications support all Markdown formatting excepting tables including:

  • Character styles. Italics or emphasis, bold or strong, and code styling are among the supported styling options
  • Headers. Headers will remain in effect until the message contains a new line character ("\n")
  • Links. Content of the form [description](url) will render as text with a live link to the specified URL.
  • Images. Content of the form ![alt text](image-url) will display the image found at image-url with the specified alt text.
  • Lists. Ordered and unordered lists are supported.
  • Horizontal rules. Three or more consecutive underscores, hyphens, or asterisks on their own line render as a horizontal rule. If you want a blank line before the next line of text, use a second new line character after the horizontal rule definition.

Slack notifications only support character styles. Header notation is stripped out and the link construct [description](url) and image construct ![alt](image-url) are replaced by the url itself. Unordered lists are displayed without the bullets while ordered lists use text representations of the numbers. Horizontal rules are removed entirely.

The markup is stripped out entirely from other types of notifications. A link noted as [text](url) will render as text url in those messages; similarly images noted as ![alt](image-url)] will render as alt image-url. Headers and character styles are ignored and their notation symbols removed. Lists are rendered as in Slack with unordered lists displayed without the bullets and ordered lists using text representations of the numbers. Horizontal rules are removed entirely.

A detector containing a simple custom notification message using markdown might be defined using the following request body:

{
    "name":"Low Mean CPU - Minor Alert",
    "programText":"A = data('cpu.utilization').mean(); detect(A < 15).publish('lowMeanCpu')",
    "tags":["CPU"],
    "rules":[{
        "detectLabel":"lowMeanCpu",
        "notifications":[{
            "type":"Email",
            "email":"oncall@example.com"
        },{
            "type":"Slack",
            "credentialId":"_id_",
            "channel":"detector-alerts"
        }
        ],
        "tip":"Consolidate Machines if possible to save money",
        "severity":"Minor",
    "parameterizedBody": "{{#if anomalous}}\n *Low CPU Usage* triggered \n\n {{#if tip}}Tip: {{{tip}}}{{/if}}\n{{/if}}"
  }]
}

Which renders as follows in email:

Email alert with custom Markdown

and as follows in Slack:

Slack alert with custom Markdown

Suggest Edits

Create Detector

The Create Detector API call creates a new v2 detector object.

 

The Create Detector API call creates a new v2 detector object. Detectors define a set of criteria for determining when to alert users about something and a set of rules regarding what notifications to send when that criteria is met or when an alert is cleared.

For more information on detectors including the types of notifications available, see the Detectors Overview.

Syntax

POST https://api.signalfx.com/v2/detector

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Create Detector call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Payload

The following properties are supported in the request payload for the Create Detector call:

Property Type Constraints Description
authorizedWriters object None Organization must have the write permissions feature enabled to use this field. Contains IDs of users and teams who have permission to edit or delete this detector. When null (the default value) anyone may edit the detector. Administrators cannot edit a detector without write permissions for it. However, they may always edit the authorizedWriters property to grant themselves (or others) such permissions, allowing them to make edits in subsequent API calls. The properties of the included object are indicated as authorizedWriters.propertyName in this documentation.
authorizedWriters.teams list of strings Team IDs Organization must have the write permissions feature enabled to use this field. IDs of teams who have permission to edit or delete this detector.
authorizedWriters.users list of strings User IDs Organization must have the write permissions feature enabled to use this field. IDs of users who have permission to edit or delete this detector.
customProperties object
  • maximum length of key = 128 characters
  • key name may only contain alphabetic characters, numerals, underscores ("_"), or hyphens ("-")
  • key name must start with an alphabetic character of either case
  • key name may not start with an underscore ("_"), sf followed by an underscore ("sf_"), aws followed by an underscore ("aws_"), gcp followed by an underscore ("gcp_"), or azure followed by an underscore ("azure_")
  • value is required if key is specified
  • value may not be an empty string
  • maximum length of value = 256 characters

NOTE: the key name constraints outlined above may be encapsulated in the following regular expression: ^[a-zA-Z][a-zA-Z0-9_-]*$
A set of user-defined key-value pairs containing metadata about the detector that may change over time. Custom properties may be used to store metadata that may not be known at detector creation or that may be expected to change in the future. These properties can be used to filter detectors or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string
  • Default is empty string
A description of the detector. Displays in the Detector Info window accessible via the Actions menu in the web application.
maxDelay integer
  • Maximum value is 900000 (15 minutes)
The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the detector analysis. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
name string
  • Required
  • Minimum characters = 1
The name of the detector. This value is used to identify the detector in the web application.
programText string
  • Required
A SignalFlow program used to populate the detector. The program must include one or more detect functions and each detect function must be modified by a publish stream method with a label that's unique across the program. If you wish to support custom notification messages that include input data you must use variables to assign the detect conditions. If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n"). See the Detectors Overview for more information.
rules list of objects None A list of rules indicating the severity of alert conditions and how to send notifications when indicated conditions are met. Each rule binds a specific detect function in the programText property (using the value of the label in its publish method) to a set of one or more notification directives and an associated severity indicator. The same condition can be used in multiple rules if different severity indicators are desired for different notification methods. The properties of the included objects are indicated as rules[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the rules array.
rules[x].description string
  • Default is empty string
A description for the rule. Displays as the alert condition in the Alert Rules tab of the detector editor.
rules[x].detectLabel string
  • Required
The label of the publish statement associated with the detect function associated with this rule.
rules[x].disabled boolean
  • Default is false
Indicates whether the associated rule is turned on and being evaluated (false) or is currently turned off and will not fire even if the specified conditions are met (true).
rules[x].notifications list of objects None A set of notifications to send when the associated rule fires. The properties of the included objects are indicated as rules[x].notifications[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the rules array.
rules[x].notifications[y].channel string
  • Only available if the rules[x].notifications[y].type property is set to Slack
Indicates the name of the channel to display the notification message. The name should be specified without a leading # symbol. For example, channel #critical-notifications would be specified as "critical-notifications".
rules[x].notifications[y].credentialId string
  • Only available if the rules[x].notifications[y].type property is set to HipChat, PagerDuty, ServiceNow, Slack, VictorOps, or Webhook
Indicates which integration profile to use to send notifications when an alert fires, represented by the ID of the integration object for that profile. To get the IDs for all available integrations (including integrations not used for notifications) use the Get Integrations API call without query parameters. To limit the results to a specific type of integration, use the Get Integrations API call with the type query parameter set to the desired type. For example GET https://api.signalfx.com/v2/integration?type=HipChat will return all objects representing HipChat integration profiles.
rules[x].notifications[y].email string
  • Only available if the rules[x].notifications[y].type property is set to Email
The address to send an email notification. This email address is not validated in any way; you are responsible for ensuring that it is correct and in the correct format. Values that cannot be interpreted as legal email addresses may not be saved and may result in a notification without an assigned email address.
rules[x].notifications[y].room string
  • Only available if the rules[x].notifications[y].type property is set to HipChat
Indicates the name of the room to display the notification message.
rules[x].notifications[y].routingKey string
  • Only available if the rules[x].notifications[y].type property is set to VictorOps
Indicates the routing key used to determine how to process the notification message. This key indicates where the notification is posted and how related alerts are escalated. For more information see the VictorOps knowlegebase.
rules[x].notifications[y].secret string
  • Only available if the rules[x].notifications[y].type property is set to Webhook
A secret that identifies which Webhook integration to use when sending notifications and indicates this notification has permission to use it. If rules[x].notifications[y].credentialId is set, this property is ignored.
rules[x].notifications[y].team string
  • Only available if the rules[x].notifications[y].type property is set to Team or TeamEmail
The ID of the team getting the notification. The form of the notification is determined by the value of the rules[x].notifications[y].type property and is discussed further in its description.
rules[x].notifications[y].type enumerated string
  • Required
  • Supported values are: Email, HipChat, PagerDuty, ServiceNow, Slack, Team, TeamEmail, VictorOps, Webhook
Indicates the mechanism for sending the notification. Notifications can be sent to individual users or to teams and may be send via email, using a third-party messaging system, or using a third-party incident management system. Each element of the notifications list represents a single recipient, chat room or channel, or third party incident management system (in most cases any relevant configuration or routing selection is set system-wide; VictorOps supports multiple routing options and thus each element of the list represents a single routing option rather than all notifications for the system). A rule may have as many notification options configured as needed to send all desired notifications when the rule is triggered; these options may be different versions of the same type or chosen from as many of the supported types as needed. For more information, see the notifications section of the Detectors Overview.
rules[x].notifications[y].url string
  • Only available if the rules[x].notifications[y].type property is set to Webhook
The URL of a webhook integration. You must provide some mechanism for processing notifications sent to this URL and routing them to the proper chat or incident management system. If rules[x].notifications[y].credentialId is set, this property is ignored.
rules[x].parameterizedBody string None Custom notification message body for this rule when the alert is triggered. The content can contain any ASCII characters and is parsed as either plain text or Github-flavored markdown (see the Markdown Support in Custom Notification Messages section of the Detectors Overview for specifics). Quotes can be escaped by using backslash, and new line characters are indicated with "\n". Variables are indicated using curly braces; double curly braces indicate a variable that's substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable. For more information see the custom notification messages section of the Detectors Overview. A full list of available variables with their default notation recommendation is available in the SignalFx documentation.
rules[x].parameterizedSubject string None Custom notification message subject for this rule when the alert is triggered. The content can contain any ASCII characters and is parsed as plain text. Quotes can be escaped by using backslash, and new line characters are indicated with "\n". Variables are indicated using curly braces; double curly braces indicate a variable that's substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable. For more information see the custom notification messages section of the Detectors Overview. A full list of available variables with their default notation recommendation is available in the SignalFx documentation.
rules[x].runbookUrl string
  • Must be a fully escaped URI</ui>
URL of page to consult when an alert is triggered. This can be used with custom notification messages. It can be referenced using {{runbookUrl}} in the rules[x].parameterizedBody or rules[x].parameterizedSubject field.
rules[x].severity enumerated string
  • Supported values are: Critical, Info, Major, Minor, and Warning
Indicates how impactful a triggered alert might be. You are free to define your own meaning for each level of severity and judge which level is appropriate for different triggering conditions; however, in general Critical is considered the most serious, followed by Warning, Major, Minor, and the least severe Info level.
rules[x].tip string
  • Must be plain text
Plain text suggested first course of action, such as a command line to execute. This can be used with custom notification messages. It can be referenced using {{tip}} in the rules[x].parameterizedBody or rules[x].parameterizedSubject field.
tags list of strings
  • Maximum characters per element = 256
A set of keywords used to filter detectors or to search for all detectors with some common element. Among other things, tags may be used to indicate the state of a detector or its data source (for example, a prod tag could indicate all detectors monitoring a production environment).
teams list of strings None Specifies the IDs of teams associated with this detector. Teams associated with a detector see that detector and active alerts associated with the detector on the team's landing page in the web application. The list of teams associated with a detector is completely independent of the notification settings; teams specified here do not automatically get notified of new alerts and teams choosing to get alerts do not have to display the detector on their team landing page in the web application.
visualizationOptions object None Options for detector visualization. The properties of the included object are indicated as visualizationOptions.propertyName in this documentation.
visualizationOptions.disableSampling boolean
  • Default value is false
If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
visualizationOptions.showDataMarkers boolean
  • Default value is false
If true, markers will be drawn for each datapoint within the visualization.
visualizationOptions.showEventLines boolean
  • Default value is false
If true, a vertical line is displayed on the visualization when an event is triggered.
visualizationOptions.time object None Options for the time displayed in the detector visualization. In general, you should use the default values for this property. The properties of the included object are indicated as visualizationOptions.time.propertyName in this documentation.
visualizationOptions.time.end integer
  • Available if the visualizationOptions.time.type property is set to absolute
  • Default is 0
The timestamp of the last time to display in the visualization specified in milliseconds since midnight UTC on January 1, 1970
visualizationOptions.time.range integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.time.type property is set to relative
  • Default = 0
The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here, GCP metrics listed here, and Azure metrics listed here.
visualizationOptions.time.start integer
  • Available if the visualizationOptions.time.type property is set to absolute
  • Default is 0
The timestamp of the first time to display in the visualization specified in milliseconds since midnight UTC on January 1, 1970
visualizationOptions.time.type enumerated string
  • Supported values are: absolute and relative
Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Create Detector call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Create Detector call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Create Detector call:

Property Type Contexts Returned Description
authorizedWriters object All Organization must have the write permissions feature enabled to use this field. Contains IDs of users and teams who have permission to edit or delete this detector. When null (the default value) anyone may edit the detector. Administrators cannot edit a detector without write permissions for it. However, they may always edit the authorizedWriters property to grant themselves (or others) such permissions, allowing them to make edits in subsequent API calls. The properties of the included object are indicated as authorizedWriters.propertyName in this documentation.
authorizedWriters.teams list of strings All Organization must have the write permissions feature enabled to use this field. IDs of teams who have permission to edit or delete this detector.
authorizedWriters.users list of strings All Organization must have the write permissions feature enabled to use this field. IDs of users who have permission to edit or delete this detector.
created integer All The time the detector object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
creator string All The user ID of user who initially created this detector. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
customProperties object All A set of user-defined key-value pairs containing metadata about the detector that may change over time. Custom properties may be used to store metadata that may not be known at detector creation or that may be expected to change in the future. These properties can be used to filter detectors or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string All A description of the detector. Displays in the Detector Info window accessible via the Actions menu in the web application.
id string All The ID assigned to the detector object. This ID is unique and always set by the system.
labelResolution object All Indicates the resolution of the detector job (how often data is analyzed to determine if an alert should be triggered). This is different from the data display resolution used to populate the detector visualization; the data display resolution is automatically set to the coarsest resolution of all of the publish statements associated with the detector since they are all displayed together in the same visualization. The data display resolution may change when the time window for display is modified but the underlying detector job resolution as set in this property is unaffected. This property is set asynchronously by the system and is always returned as null for Create Detector requests then subsequently updated to reflect the proper data for each label.
lastUpdated integer All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application. This value is always set by the system.
lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
locked boolean All If true, the detector cannot be modified in any way. If false, any user with access to the detector may edit it.
maxDelay integer All The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the detector analysis. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
name string All The name of the detector. This value is used to identify the detector in the web application.
overMTSLimit boolean All If true one, or more statements in the detector matched too many time series and the matched set was forcefully limited. In this case, the detector is most likely looking at incomplete data or an incomplete aggregation. If this flag is set to true, you can use a series of partition_filter functions to split the data set into manageable pieces then use the union function to rejoin the results in a subsequent computation. Note that the union function still observes the time series limit; some type of aggregation on the partial streams must limit the data set prior to recombining the streams for this approach to work.
programText string All A SignalFlow program used to populate the detector. The program must include one or more detect functions and each detect function must be modified by a publish stream method with a label that's unique across the program. If you wish to support custom notification messages that include input data you must use variables to assign the detect conditions. If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n"). See the Detectors Overview for more information.
rules list of objects All A list of rules indicating the severity of alert conditions and how to send notifications when indicated conditions are met. Each rule binds a specific detect function in the programText property (using the value of the label in its publish method) to a set of one or more notification directives and an associated severity indicator. The same condition can be used in multiple rules if different severity indicators are desired for different notification methods. The properties of the included objects are indicated as rules[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the rules array.
rules[x].description string All A description for the rule. Displays as the alert condition in the Alert Rules tab of the detector editor.
rules[x].detectLabel string All The label of the publish statement associated with the detect function associated with this rule.
rules[x].disabled boolean All Indicates whether the associated rule is turned on and being evaluated (false) or is currently turned off and will not fire even if the specified conditions are met (true).
rules[x].notifications list of objects All A set of notifications to send when the associated rule fires. The properties of the included objects are indicated as rules[x].notifications[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the rules array.
rules[x].notifications[y].channel string rules[x].notifications[y].type property = Slack Indicates the name of the channel to display the notification message. The name should be specified without a leading # symbol. For example, channel #critical-notifications would be specified as "critical-notifications".
rules[x].notifications[y].credentialId string rules[x].notifications[y].type property = HipChat, PagerDuty, ServiceNow, Slack, VictorOps, or Webhook Indicates which integration profile to use to send notifications when an alert fires, represented by the ID of the integration object for that profile. To get the IDs for all available integrations (including integrations not used for notifications) use the Get Integrations API call without query parameters. To limit the results to a specific type of integration, use the Get Integrations API call with the type query parameter set to the desired type. For example GET https://api.signalfx.com/v2/integration?type=HipChat will return all objects representing HipChat integration profiles.
rules[x].notifications[y].email string rules[x].notifications[y].type property = Email The address to send an email notification. This email address is not validated in any way; you are responsible for ensuring that it is correct and in the correct format. Values that cannot be interpreted as legal email addresses may not be saved and may result in a notification without an assigned email address.
rules[x].notifications[y].room string rules[x].notifications[y].type = HipChat Indicates the name of the room to display the notification message.
rules[x].notifications[y].routingKey string rules[x].notifications[y].type = VictorOps Indicates the routing key used to determine how to process the notification message. This key indicates where the notification is posted and how related alerts are escalated. For more information see the VictorOps knowlegebase.
rules[x].notifications[y].secret string rules[x].notifications[y].type = Webhook A secret that identifies which Webhook integration to use when sending notifications and indicates this notification has permission to use it. If rules[x].notifications[y].credentialId is set, this property is ignored.
rules[x].notifications[y].team string rules[x].notifications[y].type property = Team or TeamEmail The ID of the team getting the notification. The form of the notification is determined by the value of the rules[x].notifications[y].type property and is discussed further in its description.
rules[x].notifications[y].type enumerated string All Indicates the mechanism for sending the notification. Notifications can be sent to individual users or to teams and may be send via email, using a third-party messaging system, or using a third-party incident management system. Each element of the notifications list represents a single recipient, chat room or channel, or third party incident management system (in most cases any relevant configuration or routing selection is set system-wide; VictorOps supports multiple routing options and thus each element of the list represents a single routing option rather than all notifications for the system). A rule may have as many notification options configured as needed to send all desired notifications when the rule is triggered; these options may be different versions of the same type or chosen from as many of the supported types as needed. For more information, see the notification section of the Detectors Overview.
rules[x].notifications[y].url string rules[x].notifications[y].type = Webhook The URL of a webhook integration. You must provide some mechanism for processing notifications sent to this URL and routing them to the proper chat or incident management system. If rules[x].notifications[y].credentialId is set, this property is ignored.
rules[x].parameterizedBody string All Custom notification message body for this rule when the alert is triggered. The content can contain any ASCII characters and is parsed as either plain text or Github-flavored markdown (see the Markdown Support in Custom Notification Messages section of the Detectors Overview for specifics). Quotes can be escaped by using backslash, and new line characters are indicated with "\n". Variables are indicated using curly braces; double curly braces indicate a variable that's substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable. For more information see the custom notification messages section of the Detectors Overview. A full list of available variables with their default notation recommendation is available in the SignalFx documentation.
rules[x].parameterizedSubject string All Custom notification message subject for this rule when the alert is triggered. The content can contain ASCII characters and is parsed as plain text. Quotes can be escaped by using backslash, and new line characters are indicated with "\n". Variables are indicated using curly braces; double curly braces indicate a variable that's substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable. For more information see the custom notification messages section of the Detectors Overview. A full list of available variables with their default notation recommendation is available in the SignalFx documentation.
rules[x].runbookUrl string All URL of page to consult when an alert is triggered. This can be used with custom notification messages. It can be referenced using {{runbookUrl}} in the rules[x].parameterizedBody or rules[x].parameterizedSubject field.
rules[x].severity enumerated string All Indicates how impactful a triggered alert might be. You are free to define your own meaning for each level of severity and judge which level is appropriate for different triggering conditions; however, in general Critical is considered the most serious, followed by Warning, Major, Minor, and the least severe Info level.
rules[x].tip string All Plain text suggested first course of action, such as a command line to execute. This can be used with custom notification messages. It can be referenced using {{tip}} in the rules[x].parameterizedBody or rules[y].parameterizedSubject field.
tags list of strings All A set of keywords used to filter detectors or to search for all detectors with some common element. Among other things, tags may be used to indicate the state of a detector or its data source (for example, a prod tag could indicate all detectors monitoring a production environment).
teams list of strings All Specifies the IDs of teams associated with this detector. Teams associated with a detector see that detector and active alerts associated with the detector on the team's landing page in the web application. The list of teams associated with a detector is completely independent of the notification settings; teams specified here do not automatically get notified of new alerts and teams choosing to get alerts do not have to display the detector on their team landing page in the web application.
visualizationOptions object All Options for detector visualization. The properties of the included object are indicated as visualizationOptions.propertyName in this documentation.
visualizationOptions.disableSampling boolean All If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
visualizationOptions.showDataMarkers boolean All If true, markers will be drawn for each datapoint within the visualization.
visualizationOptions.showEventLines boolean All If true, a vertical line is displayed on the visualization when an event is triggered.
visualizationOptions.time object All Options for the time displayed in the detector visualization. The properties of the included object are indicated as visualizationOptions.time.propertyName in this documentation.
visualizationOptions.time.end integer visualizationOptions.time.type property = absolute The timestamp of the last time to display in the visualization specified in milliseconds since midnight UTC on January 1, 1970
visualizationOptions.time.range integer visualizationOptions.time.type property = relative The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here, GCP metrics listed here, and Azure metrics listed here.
visualizationOptions.time.start integer visualizationOptions.time.type property = absolute The timestamp of the first time to display in the visualization specified in milliseconds since midnight UTC on January 1, 1970
visualizationOptions.time.type enumerated string All Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Validate Detector

The Validate Detector API call evaluates whether a request payload could be used to create a v2 detector object without actually creating any such object.

 

The Validate Detector API call evaluates whether a request payload could be used to create a v2 detector object without actually creating any such object.

To create a detector object, see the Create Detector API call. For more information on detectors including the types of notifications available, see the Detectors Overview.

Syntax

POST https://api.signalfx.com/v2/detector/validate

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Validate Detector call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Payload

The following properties are supported in the request payload for the Validate Detector call:

Property Type Constraints Description
customProperties object
  • maximum length of key = 128 characters
  • key name may only contain alphabetic characters, numerals, underscores ("_"), or hyphens ("-")
  • key name must start with an alphabetic character of either case
  • key name may not start with an underscore ("_"), sf followed by an underscore ("sf_"), aws followed by an underscore ("aws_"), gcp followed by an underscore ("gcp_"), or azure followed by an underscore ("azure_")
  • value is required if key is specified
  • value may not be an empty string
  • maximum length of value = 256 characters

NOTE: the key name constraints outlined above may be encapsulated in the following regular expression: ^[a-zA-Z][a-zA-Z0-9_-]*$
A set of user-defined key-value pairs containing metadata about the detector that may change over time. Custom properties may be used to store metadata that may not be known at detector creation or that may be expected to change in the future. These properties can be used to filter detectors or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string
  • Default is empty string
A description of the detector. Displays in the Detector Info window accessible via the Actions menu in the web application.
maxDelay integer
  • Maximum value is 900000 (15 minutes)
The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the detector analysis. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
name string
  • Required
  • Minimum characters = 1
The name of the detector. This value is used to identify the detector in the web application.
programText string
  • Required
A SignalFlow program used to populate the detector. The program must include one or more detect functions and each detect function must be modified by a publish stream method with a label that's unique across the program. If you wish to support custom notification messages that include input data you must use variables to assign the detect conditions. If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n"). See the Detectors Overview for more information.
rules list of objects None A list of rules indicating the severity of alert conditions and how to send notifications when indicated conditions are met. Each rule binds a specific detect function in the programText property (using the value of the label in its publish method) to a set of one or more notification directives and an associated severity indicator. The same condition can be used in multiple rules if different severity indicators are desired for different notification methods. The properties of the included objects are indicated as rules[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the rules array.
rules[x].description string
  • Default is empty string
A description for the rule. Displays as the alert condition in the Alert Rules tab of the detector editor.
rules[x].detectLabel string
  • Required
The label of the publish statement associated with the detect function associated with this rule.
rules[x].disabled boolean
  • Default is false
Indicates whether the associated rule is turned on and being evaluated (false) or is currently turned off and will not fire even if the specified conditions are met (true).
rules[x].notifications list of objects None A set of notifications to send when the associated rule fires. The properties of the included objects are indicated as rules[x].notifications[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the rules array.
rules[x].notifications[y].channel string
  • Only available if the rules[x].notifications[y].type property is set to Slack
Indicates the name of the channel to display the notification message. The name should be specified without a leading # symbol. For example, channel #critical-notifications would be specified as "critical-notifications".
rules[x].notifications[y].credentialId string
  • Only available if the rules[x].notifications[y].type property is set to HipChat, PagerDuty, ServiceNow, Slack, VictorOps, or Webhook
Indicates which integration profile to use to send notifications when an alert fires, represented by the ID of the integration object for that profile. To get the IDs for all available integrations (including integrations not used for notifications) use the Get Integrations API call without query parameters. To limit the results to a specific type of integration, use the Get Integrations API call with the type query parameter set to the desired type. For example GET https://api.signalfx.com/v2/integration?type=HipChat will return all objects representing HipChat integration profiles.
rules[x].notifications[y].email string
  • Only available if the rules[x].notifications[y].type property is set to Email
The address to send an email notification. This email address is not validated in any way; you are responsible for ensuring that it is correct and in the correct format. Values that cannot be interpreted as legal email addresses may not be saved and may result in a notification without an assigned email address.
rules[x].notifications[y].room string
  • Only available if the rules[x].notifications[y].type property is set to HipChat
Indicates the name of the room to display the notification message.
rules[x].notifications[y].routingKey string
  • Only available if the rules[x].notifications[y].type property is set to VictorOps
Indicates the routing key used to determine how to process the notification message. This key indicates where the notification is posted and how related alerts are escalated. For more information see the VictorOps knowlegebase.
rules[x].notifications[y].secret string
  • Only available if the rules[x].notifications[y].type property is set to Webhook
A secret that identifies which Webhook integration to use when sending notifications and indicates this notification has permission to use it. If rules[x].notifications[y].credentialId is set, this property is ignored.
rules[x].notifications[y].team string
  • Only available if the rules[x].notifications[y].type property is set to Team or TeamEmail
The ID of the team getting the notification. The form of the notification is determined by the value of the rules[x].notifications[y].type property and is discussed further in its description.
rules[x].notifications[y].type enumerated string
  • Required
  • Supported values are: Email, HipChat, PagerDuty, ServiceNow, Slack, Team, TeamEmail, VictorOps, Webhook
Indicates the mechanism for sending the notification. Notifications can be sent to individual users or to teams and may be send via email, using a third-party messaging system, or using a third-party incident management system. Each element of the notifications list represents a single recipient, chat room or channel, or third party incident management system (in most cases any relevant configuration or routing selection is set system-wide; VictorOps supports multiple routing options and thus each element of the list represents a single routing option rather than all notifications for the system). A rule may have as many notification options configured as needed to send all desired notifications when the rule is triggered; these options may be different versions of the same type or chosen from as many of the supported types as needed. For more information, see the notifications section of the Detectors Overview.
rules[x].notifications[y].url string
  • Only available if the rules[x].notifications[y].type property is set to Webhook
The URL of a webhook integration. You must provide some mechanism for processing notifications sent to this URL and routing them to the proper chat or incident management system. If rules[x].notifications[y].credentialId is set, this property is ignored.
rules[x].parameterizedBody string None Custom notification message body for this rule when the alert is triggered. The content can contain any ASCII characters and is parsed as either plain text or Github-flavored markdown (see the Markdown Support in Custom Notification Messages section of the Detectors Overview for specifics). Quotes can be escaped by using backslash, and new line characters are indicated with "\n". Variables are indicated using curly braces; double curly braces indicate a variable that's substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable. For more information see the custom notification messages section of the Detectors Overview. A full list of available variables with their default notation recommendation is available in the SignalFx documentation.
rules[x].parameterizedSubject string None Custom notification message subject for this rule when the alert is triggered. The content can contain any ASCII characters and is parsed as plain text. Quotes can be escaped by using backslash, and new line characters are indicated with "\n". Variables are indicated using curly braces; double curly braces indicate a variable that's substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable. For more information see the custom notification messages section of the Detectors Overview. A full list of available variables with their default notation recommendation is available in the SignalFx documentation.
rules[x].runbookUrl string
  • Must be a fully escaped URI</ui>
URL of page to consult when an alert is triggered. This can be used with custom notification messages. It can be referenced using {{runbookUrl}} in the rules[x].parameterizedBody or rules[x].parameterizedSubject field.
rules[x].severity enumerated string
  • Supported values are: Critical, Info, Major, Minor, and Warning
Indicates how impactful a triggered alert might be. You are free to define your own meaning for each level of severity and judge which level is appropriate for different triggering conditions; however, in general Critical is considered the most serious, followed by Warning, Major, Minor, and the least severe Info level.
rules[x].tip string
  • Must be plain text
Plain text suggested first course of action, such as a command line to execute. This can be used with custom notification messages. It can be referenced using {{tip}} in the rules[x].parameterizedBody or rules[x].parameterizedSubject field.
tags list of strings
  • Maximum characters per element = 256
A set of keywords used to filter detectors or to search for all detectors with some common element. Among other things, tags may be used to indicate the state of a detector or its data source (for example, a prod tag could indicate all detectors monitoring a production environment).
teams list of strings None Specifies the IDs of teams associated with this detector. Teams associated with a detector see that detector and active alerts associated with the detector on the team's landing page in the web application. The list of teams associated with a detector is completely independent of the notification settings; teams specified here do not automatically get notified of new alerts and teams choosing to get alerts do not have to display the detector on their team landing page in the web application.
visualizationOptions object None Options for detector visualization. The properties of the included object are indicated as visualizationOptions.propertyName in this documentation.
visualizationOptions.disableSampling boolean
  • Default value is false
If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
visualizationOptions.showDataMarkers boolean
  • Default value is false
If true, markers will be drawn for each datapoint within the visualization.
visualizationOptions.showEventLines boolean
  • Default value is false
If true, a vertical line is displayed on the visualization when an event is triggered.
visualizationOptions.time object None Options for the time displayed in the detector visualization. The properties of the included object are indicated as visualizationOptions.time.propertyName in this documentation.
visualizationOptions.time.end integer
  • Available if the visualizationOptions.time.type property is set to absolute
  • Default is 0
The timestamp of the last time to display in the visualization specified in milliseconds since midnight UTC on January 1, 1970
visualizationOptions.time.range integer
  • Available if the visualizationOptions.time.type property is set to relative
  • Default is 0
The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here, GCP metrics listed here, and Azure metrics listed here.
visualizationOptions.time.start integer
  • Available if the visualizationOptions.time.type property is set to absolute
  • Default is 0
The timestamp of the first time to display in the visualization specified in milliseconds since midnight UTC on January 1, 1970
visualizationOptions.time.type enumerated string
  • Supported values are: absolute and relative
Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Validate Detector call will return a 204 No Content status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Validate Detector call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The Validate Detector API call does not support a response payload.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Get Detectors

The Get Detectors API call retrieves one or more v2 detector objects identified by optional search criteria.

 

The Get Detectors API call retrieves one or more v2 detector objects identified by optional search criteria. If no search criteria is specified, the first 50 detectors visible to the user are returned. Paging of results is controlled using the offset and limit path parameters to specify the starting point of the results and the maximum number of results to return respectively. See the path parameter documentation below for more information on search criteria and paging.

For more information on detectors, see the Detectors Overview.

Syntax

GET https://api.signalfx.com/v2/detector[?[name=_detectorName_][&][_tagSpecification_][&][offset=_startValue_][&][limit=_requestedNumberReturned_]]

where tagSpecification has the following syntax:

tags=tag1[&tags=tag2][&....tags=tagK]

NOTE: [content] indicates that content is an optional block that may or may not be needed depending on the desired query

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Get Detectors call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Query Parameters

The Get Detectors API call supports the following query parameters as indicated in the syntax line above:

Parameter Value Type Constraints Description
limit integer
  • Default=50
  • minimum value=1
The maximum number of objects to return in the response. Unrecognized values are ignored and result in the default value of 50 being used.
name string None a search string acting as a full or partial match to the value in the name property of detector objects. Any UTF-8 characters may be included in the search string and strings will match against any portion of the name property; for example, name=per will match all of the following names:
  • ..... dropped per day...
  • ...95th percentile
  • personal disk usage...
Empty strings will be ignored and return objects with any name value that match the rest of the query.
offset integer
  • Default=0
  • minimum value=0
The starting index value of the returned objects; this assumes all of the possible returns are put in a 0-based indexed list in the appropriate sort order and identified by their order in the list. If the offset value is greater than the number of possible results, no objects are returned in the response.
tags string
  • Parameter is repeatable
a search string acting as a full match to an element in the tags array property of detector objects. Any UTF-8 characters may be included in the search strings. Partial matches will not be returned.

Payload

The Get Detectors API call does not support a request payload.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Get Detectors call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Get Detectors call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Get Detectors call:

Property Type Contexts Returned Description
count integer All Indicates the number of objects that match the search query. It does not provide any information on the number of objects actually returned in the request; if paging is employed the number of objects should be equivalent to either the value of the limit path parameter or the remainder of the objects after the supplied value of the offset parameter.
results list of objects All List of detector objects matching the request criteria. The properties of the included results objects are indicated as results[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the results array.
results[x].authorizedWriters object All Organization must have the write permissions feature enabled Contains IDs of users and teams who have permission to edit or delete this detector. When null (the default value) anyone may edit the detector. Administrators cannot edit a detector without write permissions for it. However, they may always edit the authorizedWriters property to grant themselves (or others) such permissions, allowing them to make edits in subsequent API calls. The properties of the included object are indicated as authorizedWriters.propertyName in this documentation.
results[x].authorizedWriters.teams list of strings All Organization must have the write permissions feature enabled IDs of teams who have permission to edit or delete this detector.
results[x].authorizedWriters.users list of strings All Organization must have the write permissions feature enabled IDs of users who have permission to edit or delete this detector.
results[x].created integer All The time the detector object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
results[x].creator string All The user ID of user who initially created this detector. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
results[x].customProperties object All A set of user-defined key-value pairs containing metadata about the detector that may change over time. Custom properties may be used to store metadata that may not be known at detector creation or that may be expected to change in the future. These properties can be used to filter detectors or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
results[x].description string All A description of the detector. Displays in the Detector Info window accessible via the Actions menu in the web application.
results[x].id string All The ID assigned to the detector object. This ID is unique and always set by the system.
results[x].labelResolution object All Indicates the resolution of the detector job (how often data is analyzed to determine if an alert should be triggered). This is different from the data display resolution used to populate the detector visualization; the data display resolution is automatically set to the coarsest resolution of all of the publish statements associated with the detector since they are all displayed together in the same visualization. The data display resolution may change when the time window for display is modified but the underlying detector job resolution as set in this property is unaffected. The proper value of the object and its properties are determined asynchronously. If available, the existing values computed after the detector was created or last updated are returned. The properties of this object use the name of the label of each publish statement in the detector as their names. These properties are indicated as labelResolution.label in this documentation.
results[x].labelResolution.label integer All Indicates the resolution in milliseconds of the SignalFlow using the publish statement with the specified label (how often data is analyzed to determine if an alert should be triggered). This is different from the data display resolution used to populate the detector visualization; the data display resolution is automatically set to the coarsest resolution of all of the publish statements associated with the detector since they are all displayed together in the same visualization. The data display resolution may change when the time window for display is modified but the underlying detector job resolution as set in this property is unaffected. This value is set automatically by the system after the detector job is analyzed and cannot be updated manually. In most cases the value is set to 1000 (1 second).
results[x].lastUpdated integer All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application. This value is always set by the system.
results[x].lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
results[x].locked boolean All If true, the detector cannot be modified in any way. If false, any user with access to the detector may edit it.
results[x].maxDelay integer All The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the detector analysis. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
results[x].name string All The name of the detector. This value is used to identify the detector in the web application.
results[x].overMTSLimit boolean All If true one, or more statements in the detector matched too many time series and the matched set was forcefully limited. In this case, the detector is most likely looking at incomplete data or an incomplete aggregation. If this flag is set to true, you can use a series of partition_filter functions to split the data set into manageable pieces then use the union function to rejoin the results in a subsequent computation. Note that the union function still observes the time series limit; some type of aggregation on the partial streams must limit the data set prior to recombining the streams for this approach to work.
results[x].programText string All A SignalFlow program used to populate the detector. The program must include one or more detect functions and each detect function must be modified by a publish stream method with a label that's unique across the program. If you wish to support custom notification messages that include input data you must use variables to assign the detect conditions. If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n"). See the Detectors Overview for more information.
results[x].rules list of objects All A list of rules indicating the severity of alert conditions and how to send notifications when indicated conditions are met. Each rule binds a specific detect function in the programText property (using the value of the label in its publish method) to a set of one or more notification directives and an associated severity indicator. The same condition can be used in multiple rules if different severity indicators are desired for different notification methods. The properties of the included objects are indicated as results[x].rules[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the rules array.
results[x].rules[y].description string All A description for the rule. Displays as the alert condition in the Alert Rules tab of the detector editor.
results[x].rules[y].detectLabel string All The label of the publish statement associated with the detect function associated with this rule.
results[x].rules[y].disabled boolean All Indicates whether the associated rule is turned on and being evaluated (false) or is currently turned off and will not fire even if the specified conditions are met (true).
results[x].rules[y].notifications list of objects All A set of notifications to send when the associated rule fires. The properties of the included objects are indicated as results[x].rules[y].notifications[z].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the rules array.
results[x].rules[y].notifications[z].channel string results[x].rules[y].notifications[z].type property = Slack Indicates the name of the channel to display the notification message. The name should be specified without a leading # symbol. For example, channel #critical-notifications would be specified as "critical-notifications".
results[x].rules[y].notifications[z].credentialId string results[x].rules[y].notifications[z].type property = HipChat, PagerDuty, ServiceNow, Slack, VictorOps, or Webhook Indicates which integration profile to use to send notifications when an alert fires, represented by the ID of the integration object for that profile. To get the IDs for all available integrations (including integrations not used for notifications) use the Get Integrations API call without query parameters. To limit the results to a specific type of integration, use the Get Integrations API call with the type query parameter set to the desired type. For example GET https://api.signalfx.com/v2/integration?type=HipChat will return all objects representing HipChat integration profiles.
results[x].rules[y].notifications[z].email string results[x].rules[y].notifications[z].type property = Email The address to send an email notification. This email address is not validated in any way; you are responsible for ensuring that it is correct and in the correct format. Values that cannot be interpreted as legal email addresses may not be saved and may result in a notification without an assigned email address.
results[x].rules[y].notifications[z].room string results[x].rules[y].notifications[z].type = HipChat Indicates the name of the room to display the notification message.
results[x].rules[y].notifications[z].routingKey string results[x].rules[y].notifications[z].type = VictorOps Indicates the routing key used to determine how to process the notification message. This key indicates where the notification is posted and how related alerts are escalated. For more information see the VictorOps knowlegebase.
results[x].rules[y].notifications[z].secret string results[x].rules[y].notifications[z].type = Webhook A secret that identifies which Webhook integration to use when sending notifications and indicates this notification has permission to use it. If results[x].rules[y].notifications[z].credentialId is set, this property is ignored.
results[x].rules[y].notifications[z].team string results[x].rules[y].notifications[z].type property = Team or TeamEmail The ID of the team getting the notification. The form of the notification is determined by the value of the results[x].rules[y].notifications[z].type property and is discussed further in its description.
results[x].rules[y].notifications[z].type enumerated string All Indicates the mechanism for sending the notification. Notifications can be sent to individual users or to teams and may be send via email, using a third-party messaging system, or using a third-party incident management system. Each element of the notifications list represents a single recipient, chat room or channel, or third party incident management system (in most cases any relevant configuration or routing selection is set system-wide; VictorOps supports multiple routing options and thus each element of the list represents a single routing option rather than all notifications for the system). A rule may have as many notification options configured as needed to send all desired notifications when the rule is triggered; these options may be different versions of the same type or chosen from as many of the supported types as needed. For more information, see the notification section of the Detectors Overview.
results[x].rules[y].notifications[z].url string results[x].rules[y].notifications[z].type = Webhook The URL of a webhook integration. You must provide some mechanism for processing notifications sent to this URL and routing them to the proper chat or incident management system. If results[x].rules[y].notifications[z].credentialId is set, this property is ignored.
results[x].rules[y].parameterizedBody string All Custom notification message body for this rule when the alert is triggered. The content can contain any ASCII characters and is parsed as either plain text or Github-flavored markdown (see the Markdown Support in Custom Notification Messages section of the Detectors Overview for specifics). Quotes can be escaped by using backslash, and new line characters are indicated with "\n". Variables are indicated using curly braces; double curly braces indicate a variable that's substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable. For more information see the custom notification messages section of the Detectors Overview. A full list of available variables with their default notation recommendation is available in the SignalFx documentation.
results[x].rules[y].parameterizedSubject string All Custom notification message subject for this rule when the alert is triggered. The content can contain ASCII characters and is parsed as plain text. Quotes can be escaped by using backslash, and new line characters are indicated with "\n". Variables are indicated using curly braces; double curly braces indicate a variable that's substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable. For more information see the custom notification messages section of the Detectors Overview. A full list of available variables with their default notation recommendation is available in the SignalFx documentation.
results[x].rules[y].runbookUrl string All URL of page to consult when an alert is triggered. This can be used with custom notification messages. It can be referenced using {{runbookUrl}} in the results[x].rules[y].parameterizedBody or results[x].rules[y].parameterizedSubject field.
results[x].rules[y].severity enumerated string All Indicates how impactful a triggered alert might be. You are free to define your own meaning for each level of severity and judge which level is appropriate for different triggering conditions; however, in general Critical is considered the most serious, followed by Warning, Major, Minor, and the least severe Info level.
results[x].rules[y].tip string All Plain text suggested first course of action, such as a command line to execute. This can be used with custom notification messages. It can be referenced using {{tip}} in the results[x].rules[y].parameterizedBody or results[x].rules[y].parameterizedSubject field.
results[x].tags list of strings All A set of keywords used to filter detectors or to search for all detectors with some common element. Among other things, tags may be used to indicate the state of a detector or its data source (for example, a prod tag could indicate all detectors monitoring a production environment).
results[x].teams list of strings All Specifies the IDs of teams associated with this detector. Teams associated with a detector see that detector and active alerts associated with the detector on the team's landing page in the web application. The list of teams associated with a detector is completely independent of the notification settings; teams specified here do not automatically get notified of new alerts and teams choosing to get alerts do not have to display the detector on their team landing page in the web application.
results[x].visualizationOptions object All Options for detector visualization. The properties of the included object are indicated as visualizationOptions.propertyName in this documentation.
results[x].visualizationOptions.disableSampling boolean All If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
results[x].visualizationOptions.showDataMarkers boolean All If true, markers will be drawn for each datapoint within the visualization.
results[x].visualizationOptions.showEventLines boolean All If true, a vertical line is displayed on the visualization when an event is triggered.
results[x].visualizationOptions.time object All Options for the time displayed in the detector visualization. The properties of the included object are indicated as results[x].visualizationOptions.time.propertyName in this documentation.
results[x].visualizationOptions.time.end integer results[x].visualizationOptions.time.type property = absolute The timestamp of the last time to display in the visualization specified in milliseconds since midnight UTC on January 1, 1970
results[x].visualizationOptions.time.range integer results[x].visualizationOptions.time.type property = relative The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here, GCP metrics listed here, and Azure metrics listed here.
results[x].visualizationOptions.time.start integer results[x].visualizationOptions.time.type property = absolute The timestamp of the first time to display in the visualization specified in milliseconds since midnight UTC on January 1, 1970
results[x].visualizationOptions.time.type enumerated string All Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Get Detector

The Get Detector API retrieves a single v2 detector identified by its id value.

 

The Get Detector API retrieves a single v2 detector identified by its id value. This API call only supports v2 detector objects; an error will be thrown if you try to retrieve a v1 detector object.

For more information on detectors including the types of notifications available, see the Detectors Overview.

Syntax

GET https://api.signalfx.com/v2/detector/_id_

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Get Detector call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Path Parameters

The Get Detector API call supports one path parameter as indicated in the syntax line above:

Path parameter Type Description
id string The system assigned identifier of an existing detector object.

Payload

The Get Detector API call does not support a request payload.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Get Detector call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Get Detector call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Get Detector call:

Property Type Contexts Returned Description
authorizedWriters object All Organization must have the write permissions feature enabled Contains IDs of users and teams who have permission to edit or delete this detector. When null (the default value) anyone may edit the detector. Administrators cannot edit a detector without write permissions for it. However, they may always edit the authorizedWriters property to grant themselves (or others) such permissions, allowing them to make edits in subsequent API calls. The properties of the included object are indicated as authorizedWriters.propertyName in this documentation.
authorizedWriters.teams list of strings All Organization must have the write permissions feature enabled IDs of teams who have permission to edit or delete this detector.
authorizedWriters.users list of strings All Organization must have the write permissions feature enabled IDs of users who have permission to edit or delete this detector.
created integer All The time the detector object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
creator string All The user ID of user who initially created this detector. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
customProperties object All A set of user-defined key-value pairs containing metadata about the detector that may change over time. Custom properties may be used to store metadata that may not be known at detector creation or that may be expected to change in the future. These properties can be used to filter detectors or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string All A description of the detector. Displays in the Detector Info window accessible via the Actions menu in the web application.
id string All The ID assigned to the detector object. This ID is unique and always set by the system.
labelResolution object All Indicates the resolution of the detector job (how often data is analyzed to determine if an alert should be triggered). This is different from the data display resolution used to populate the detector visualization; the data display resolution is automatically set to the coarsest resolution of all of the publish statements associated with the detector since they are all displayed together in the same visualization. The data display resolution may change when the time window for display is modified but the underlying detector job resolution as set in this property is unaffected. The proper value of the object and its properties are determined asynchronously. If available, the existing values computed after the detector was created or last updated are returned. The properties of this object use the name of the label of each publish statement in the detector as their names. These properties are indicated as labelResolution.label in this documentation.
labelResolution.label integer All Indicates the resolution in milliseconds of the SignalFlow using the publish statement with the specified label (how often data is analyzed to determine if an alert should be triggered). This is different from the data display resolution used to populate the detector visualization; the data display resolution is automatically set to the coarsest resolution of all of the publish statements associated with the detector since they are all displayed together in the same visualization. The data display resolution may change when the time window for display is modified but the underlying detector job resolution as set in this property is unaffected. This value is set automatically by the system after the detector job is analyzed and cannot be updated manually. In most cases the value is set to 1000 (1 second).
lastUpdated integer All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application. This value is always set by the system.
lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
locked boolean All If true, the detector cannot be modified in any way. If false, any user with access to the detector may edit it.
maxDelay integer All The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the detector analysis. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
name string All The name of the detector. This value is used to identify the detector in the web application.
overMTSLimit boolean All If true one, or more statements in the detector matched too many time series and the matched set was forcefully limited. In this case, the detector is most likely looking at incomplete data or an incomplete aggregation. If this flag is set to true, you can use a series of partition_filter functions to split the data set into manageable pieces then use the union function to rejoin the results in a subsequent computation. Note that the union function still observes the time series limit; some type of aggregation on the partial streams must limit the data set prior to recombining the streams for this approach to work.
programText string All A SignalFlow program used to populate the detector. The program must include one or more detect functions and each detect function must be modified by a publish stream method with a label that's unique across the program. If you wish to support custom notification messages that include input data you must use variables to assign the detect conditions. If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n"). See the Detectors Overview for more information.
rules list of objects All A list of rules indicating the severity of alert conditions and how to send notifications when indicated conditions are met. Each rule binds a specific detect function in the programText property (using the value of the label in its publish method) to a set of one or more notification directives and an associated severity indicator. The same condition can be used in multiple rules if different severity indicators are desired for different notification methods. The properties of the included objects are indicated as rules[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the rules array.
rules[x].description string All A description for the rule. Displays as the alert condition in the Alert Rules tab of the detector editor.
rules[x].detectLabel string All The label of the publish statement associated with the detect function associated with this rule.
rules[x].disabled boolean All Indicates whether the associated rule is turned on and being evaluated (false) or is currently turned off and will not fire even if the specified conditions are met (true).
rules[x].notifications list of objects All A set of notifications to send when the associated rule fires. The properties of the included objects are indicated as rules[x].notifications[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the rules array.
rules[x].notifications[y].channel string rules[x].notifications[y].type property = Slack Indicates the name of the channel to display the notification message. The name should be specified without a leading # symbol. For example, channel #critical-notifications would be specified as "critical-notifications".
rules[x].notifications[y].credentialId string rules[x].notifications[y].type property = HipChat, PagerDuty, ServiceNow, Slack, VictorOps, or Webhook Indicates which integration profile to use to send notifications when an alert fires, represented by the ID of the integration object for that profile. To get the IDs for all available integrations (including integrations not used for notifications) use the Get Integrations API call without query parameters. To limit the results to a specific type of integration, use the Get Integrations API call with the type query parameter set to the desired type. For example GET https://api.signalfx.com/v2/integration?type=HipChat will return all objects representing HipChat integration profiles.
rules[x].notifications[y].email string rules[x].notifications[y].type property = Email The address to send an email notification. This email address is not validated in any way; you are responsible for ensuring that it is correct and in the correct format. Values that cannot be interpreted as legal email addresses may not be saved and may result in a notification without an assigned email address.
rules[x].notifications[y].room string rules[x].notifications[y].type = HipChat Indicates the name of the room to display the notification message.
rules[x].notifications[y].routingKey string rules[x].notifications[y].type = VictorOps Indicates the routing key used to determine how to process the notification message. This key indicates where the notification is posted and how related alerts are escalated. For more information see the VictorOps knowlegebase.
rules[x].notifications[y].secret string rules[x].notifications[y].type = Webhook A secret that identifies which Webhook integration to use when sending notifications and indicates this notification has permission to use it. If rules[x].notifications[y].credentialId is set, this property is ignored.
rules[x].notifications[y].team string rules[x].notifications[y].type property = Team or TeamEmail The ID of the team getting the notification. The form of the notification is determined by the value of the rules[x].notifications[y].type property and is discussed further in its description.
rules[x].notifications[y].type enumerated string All Indicates the mechanism for sending the notification. Notifications can be sent to individual users or to teams and may be send via email, using a third-party messaging system, or using a third-party incident management system. Each element of the notifications list represents a single recipient, chat room or channel, or third party incident management system (in most cases any relevant configuration or routing selection is set system-wide; VictorOps supports multiple routing options and thus each element of the list represents a single routing option rather than all notifications for the system). A rule may have as many notification options configured as needed to send all desired notifications when the rule is triggered; these options may be different versions of the same type or chosen from as many of the supported types as needed. For more information, see the notification section of the Detectors Overview.
rules[x].notifications[y].url string rules[x].notifications[y].type = Webhook The URL of a webhook integration. You must provide some mechanism for processing notifications sent to this URL and routing them to the proper chat or incident management system. If rules[x].notifications[y].credentialId is set, this property is ignored.
rules[x].parameterizedBody string All Custom notification message body for this rule when the alert is triggered. The content can contain any ASCII characters and is parsed as either plain text or Github-flavored markdown (see the Markdown Support in Custom Notification Messages section of the Detectors Overview for specifics). Quotes can be escaped by using backslash, and new line characters are indicated with "\n". Variables are indicated using curly braces; double curly braces indicate a variable that's substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable. For more information see the custom notification messages section of the Detectors Overview. A full list of available variables with their default notation recommendation is available in the SignalFx documentation.
rules[x].parameterizedSubject string All Custom notification message subject for this rule when the alert is triggered. The content can contain ASCII characters and is parsed as plain text. Quotes can be escaped by using backslash, and new line characters are indicated with "\n". Variables are indicated using curly braces; double curly braces indicate a variable that's substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable. For more information see the custom notification messages section of the Detectors Overview. A full list of available variables with their default notation recommendation is available in the SignalFx documentation.
rules[x].runbookUrl string All URL of page to consult when an alert is triggered. This can be used with custom notification messages. It can be referenced using {{runbookUrl}} in the rules[x].parameterizedBody or rules[x].parameterizedSubject field.
rules[x].severity enumerated string All Indicates how impactful a triggered alert might be. You are free to define your own meaning for each level of severity and judge which level is appropriate for different triggering conditions; however, in general Critical is considered the most serious, followed by Warning, Major, Minor, and the least severe Info level.
rules[x].tip string All Plain text suggested first course of action, such as a command line to execute. This can be used with custom notification messages. It can be referenced using {{tip}} in the rules[x].parameterizedBody or rules[y].parameterizedSubject field.
tags list of strings All A set of keywords used to filter detectors or to search for all detectors with some common element. Among other things, tags may be used to indicate the state of a detector or its data source (for example, a prod tag could indicate all detectors monitoring a production environment).
teams list of strings All Specifies the IDs of teams associated with this detector. Teams associated with a detector see that detector and active alerts associated with the detector on the team's landing page in the web application. The list of teams associated with a detector is completely independent of the notification settings; teams specified here do not automatically get notified of new alerts and teams choosing to get alerts do not have to display the detector on their team landing page in the web application.
visualizationOptions object All Options for detector visualization. The properties of the included object are indicated as visualizationOptions.propertyName in this documentation.
visualizationOptions.disableSampling boolean All If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
visualizationOptions.showDataMarkers boolean All If true, markers will be drawn for each datapoint within the visualization.
visualizationOptions.showEventLines boolean All If true, a vertical line is displayed on the visualization when an event is triggered.
visualizationOptions.time object All Options for the time displayed in the detector visualization. The properties of the included object are indicated as visualizationOptions.time.propertyName in this documentation.
visualizationOptions.time.end integer visualizationOptions.time.type property = absolute The timestamp of the last time to display in the visualization specified in milliseconds since midnight UTC on January 1, 1970
visualizationOptions.time.range integer visualizationOptions.time.type property = relative The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here, GCP metrics listed here, and Azure metrics listed here.
visualizationOptions.time.start integer visualizationOptions.time.type property = absolute The timestamp of the first time to display in the visualization specified in milliseconds since midnight UTC on January 1, 1970
visualizationOptions.time.type enumerated string All Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Update Detector

The Update Detector API call modifies an existing v2 detector object identified by its id value.

 

The Update Detector API call modifies an existing v2 detector object identified by its id value.

For more information on detectors including the types of notifications available, see the Detectors Overview.

Syntax

PUT https://api.signalfx.com/v2/detector/_id_

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Update Detector call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Path Parameters

The Update Detector API call supports one path parameter as indicated in the syntax line above:

Path parameter Type Description
id string The system assigned identifier of an existing detector object.

Payload

The following properties are supported in the request payload for the Update Detector call:

Property Type Constraints Description
authorizedWriters object None Organization must have the write permissions feature enabled Contains IDs of users and teams who have permission to edit or delete this detector. When null (the default value) anyone may edit the detector. Administrators cannot edit a detector without write permissions for it. However, they may always edit the authorizedWriters property to grant themselves (or others) such permissions, allowing them to make edits in subsequent API calls. The properties of the included object are indicated as authorizedWriters.propertyName in this documentation.
authorizedWriters.teams list of strings Team IDs Organization must have the write permissions feature enabled IDs of teams who have permission to edit or delete this detector.
authorizedWriters.users list of strings User IDs Organization must have the write permissions feature enabled IDs of users who have permission to edit or delete this detector.
customProperties object
  • maximum length of key = 128 characters
  • key name may only contain alphabetic characters, numerals, underscores ("_"), or hyphens ("-")
  • key name must start with an alphabetic character of either case
  • key name may not start with an underscore ("_"), sf followed by an underscore ("sf_"), aws followed by an underscore ("aws_"), gcp followed by an underscore ("gcp_"), or azure followed by an underscore ("azure_")
  • value is required if key is specified
  • value may not be an empty string
  • maximum length of value = 256 characters

NOTE: the key name constraints outlined above may be encapsulated in the following regular expression: ^[a-zA-Z][a-zA-Z0-9_-]*$
A set of user-defined key-value pairs containing metadata about the detector that may change over time. Custom properties may be used to store metadata that may not be known at detector creation or that may be expected to change in the future. These properties can be used to filter detectors or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string
  • Default is empty string
A description of the detector. Displays in the Detector Info window accessible via the Actions menu in the web application.
maxDelay integer
  • Maximum value is 900000 (15 minutes)
The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the detector analysis. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
name string
  • Required
  • Minimum characters = 1
The name of the detector. This value is used to identify the detector in the web application.
programText string
  • Required
A SignalFlow program used to populate the detector. The program must include one or more detect functions and each detect function must be modified by a publish stream method with a label that's unique across the program. If you wish to support custom notification messages that include input data you must use variables to assign the detect conditions. If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n"). See the Detectors Overview for more information.
rules list of objects None A list of rules indicating the severity of alert conditions and how to send notifications when indicated conditions are met. Each rule binds a specific detect function in the programText property (using the value of the label in its publish method) to a set of one or more notification directives and an associated severity indicator. The same condition can be used in multiple rules if different severity indicators are desired for different notification methods. The properties of the included objects are indicated as rules[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the rules array.
rules[x].description string
  • Default is empty string
A description for the rule. Displays as the alert condition in the Alert Rules tab of the detector editor.
rules[x].detectLabel string
  • Required
The label of the publish statement associated with the detect function associated with this rule.
rules[x].disabled boolean
  • Default is false
Indicates whether the associated rule is turned on and being evaluated (false) or is currently turned off and will not fire even if the specified conditions are met (true).
rules[x].notifications list of objects None A set of notifications to send when the associated rule fires. The properties of the included objects are indicated as rules[x].notifications[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the rules array.
rules[x].notifications[y].channel string
  • Only available if the rules[x].notifications[y].type property is set to Slack
Indicates the name of the channel to display the notification message. The name should be specified without a leading # symbol. For example, channel #critical-notifications would be specified as "critical-notifications".
rules[x].notifications[y].credentialId string
  • Only available if the rules[x].notifications[y].type property is set to HipChat, PagerDuty, ServiceNow, Slack, VictorOps, or Webhook
Indicates which integration profile to use to send notifications when an alert fires, represented by the ID of the integration object for that profile. To get the IDs for all available integrations (including integrations not used for notifications) use the Get Integrations API call without query parameters. To limit the results to a specific type of integration, use the Get Integrations API call with the type query parameter set to the desired type. For example GET https://api.signalfx.com/v2/integration?type=HipChat will return all objects representing HipChat integration profiles.
rules[x].notifications[y].email string
  • Only available if the rules[x].notifications[y].type property is set to Email
The address to send an email notification. This email address is not validated in any way; you are responsible for ensuring that it is correct and in the correct format. Values that cannot be interpreted as legal email addresses may not be saved and may result in a notification without an assigned email address.
rules[x].notifications[y].room string
  • Only available if the rules[x].notifications[y].type property is set to HipChat
Indicates the name of the room to display the notification message.
rules[x].notifications[y].routingKey string
  • Only available if the rules[x].notifications[y].type property is set to VictorOps
Indicates the routing key used to determine how to process the notification message. This key indicates where the notification is posted and how related alerts are escalated. For more information see the VictorOps knowlegebase.
rules[x].notifications[y].secret string
  • Only available if the rules[x].notifications[y].type property is set to Webhook
A secret that identifies which Webhook integration to use when sending notifications and indicates this notification has permission to use it. If rules[x].notifications[y].credentialId is set, this property is ignored.
rules[x].notifications[y].team string
  • Only available if the rules[x].notifications[y].type property is set to Team or TeamEmail
The ID of the team getting the notification. The form of the notification is determined by the value of the rules[x].notifications[y].type property and is discussed further in its description.
rules[x].notifications[y].type enumerated string
  • Required
  • Supported values are: Email, HipChat, PagerDuty, ServiceNow, Slack, Team, TeamEmail, VictorOps, Webhook
Indicates the mechanism for sending the notification. Notifications can be sent to individual users or to teams and may be send via email, using a third-party messaging system, or using a third-party incident management system. Each element of the notifications list represents a single recipient, chat room or channel, or third party incident management system (in most cases any relevant configuration or routing selection is set system-wide; VictorOps supports multiple routing options and thus each element of the list represents a single routing option rather than all notifications for the system). A rule may have as many notification options configured as needed to send all desired notifications when the rule is triggered; these options may be different versions of the same type or chosen from as many of the supported types as needed. For more information, see the notifications section of the Detectors Overview.
rules[x].notifications[y].url string
  • Only available if the rules[x].notifications[y].type property is set to Webhook
The URL of a webhook integration. You must provide some mechanism for processing notifications sent to this URL and routing them to the proper chat or incident management system. If rules[x].notifications[y].credentialId is set, this property is ignored.
rules[x].parameterizedBody string None Custom notification message body for this rule when the alert is triggered. The content can contain any ASCII characters and is parsed as either plain text or Github-flavored markdown (see the Markdown Support in Custom Notification Messages section of the Detectors Overview for specifics). Quotes can be escaped by using backslash, and new line characters are indicated with "\n". Variables are indicated using curly braces; double curly braces indicate a variable that's substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable. For more information see the custom notification messages section of the Detectors Overview A full list of available variables with their default notation recommendation is available in the SignalFx documentation.
rules[x].parameterizedSubject string None Custom notification message subject for this rule when the alert is triggered. The content can contain any ASCII characters and is parsed as plain text. Quotes can be escaped by using backslash, and new line characters are indicated with "\n". Variables are indicated using curly braces; double curly braces indicate a variable that's substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable. For more information see the custom notification messages section of the Detectors Overview. A full list of available variables with their default notation recommendation is available in the SignalFx documentation.
rules[x].runbookUrl string
  • Must be a fully escaped URI</ui>
URL of page to consult when an alert is triggered. This can be used with custom notification messages. It can be referenced using {{runbookUrl}} in the rules[x].parameterizedBody or rules[x].parameterizedSubject field.
rules[x].severity enumerated string
  • Supported values are: Critical, Info, Major, Minor, and Warning
Indicates how impactful a triggered alert might be. You are free to define your own meaning for each level of severity and judge which level is appropriate for different triggering conditions; however, in general Critical is considered the most serious, followed by Warning, Major, Minor, and the least severe Info level.
rules[x].tip string
  • Must be plain text
Plain text suggested first course of action, such as a command line to execute. This can be used with custom notification messages. It can be referenced using {{tip}} in the rules[x].parameterizedBody or rules[x].parameterizedSubject field.
tags list of strings
  • Maximum characters per element = 256
A set of keywords used to filter detectors or to search for all detectors with some common element. Among other things, tags may be used to indicate the state of a detector or its data source (for example, a prod tag could indicate all detectors monitoring a production environment).
teams list of strings None Specifies the IDs of teams associated with this detector. Teams associated with a detector see that detector and active alerts associated with the detector on the team's landing page in the web application. The list of teams associated with a detector is completely independent of the notification settings; teams specified here do not automatically get notified of new alerts and teams choosing to get alerts do not have to display the detector on their team landing page in the web application.
visualizationOptions object None Options for detector visualization. The properties of the included object are indicated as visualizationOptions.propertyName in this documentation.
visualizationOptions.disableSampling boolean
  • Default value is false
If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
visualizationOptions.showDataMarkers boolean
  • Default value is false
If true, markers will be drawn for each datapoint within the visualization.
visualizationOptions.showEventLines boolean
  • Default value is false
If true, a vertical line is displayed on the visualization when an event is triggered.
visualizationOptions.time object None Options for the time displayed in the detector visualization. In general, you should use the default values for this property. The properties of the included object are indicated as visualizationOptions.time.propertyName in this documentation.
visualizationOptions.time[x].end integer
  • Available if the visualizationOptions.time.type property is set to absolute
  • Default is 0
The timestamp of the last time to display in the visualization specified in milliseconds since midnight UTC on January 1, 1970
visualizationOptions.time[x].range integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.time.type property is set to relative
  • Default = 0
The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here, GCP metrics listed here, and Azure metrics listed here
visualizationOptions.time[x].start integer
  • Available if the visualizationOptions.time.type property is set to absolute
  • Default is 0
The timestamp of the first time to display in the visualization specified in milliseconds since midnight UTC on January 1, 1970
visualizationOptions.time[x].type enumerated string
  • Supported values are: absolute and relative
Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Update Detector call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Update Detector call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Update Detector call:

Property Type Contexts Returned Description
authorizedWriters object All Organization must have the write permissions feature enabled Contains IDs of users and teams who have permission to edit or delete this detector. When null (the default value) anyone may edit the detector. Administrators cannot edit a detector without write permissions for it. However, they may always edit the authorizedWriters property to grant themselves (or others) such permissions, allowing them to make edits in subsequent API calls. The properties of the included object are indicated as authorizedWriters.propertyName in this documentation.
authorizedWriters.teams list of strings All Organization must have the write permissions feature enabled IDs of teams who have permission to edit or delete this detector.
authorizedWriters.users list of strings All Organization must have the write permissions feature enabled IDs of users who have permission to edit or delete this detector.
created integer All The time the detector object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
creator string All The user ID of user who initially created this detector. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
customProperties object All A set of user-defined key-value pairs containing metadata about the detector that may change over time. Custom properties may be used to store metadata that may not be known at detector creation or that may be expected to change in the future. These properties can be used to filter detectors or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string All A description of the detector. Displays in the Detector Info window accessible via the Actions menu in the web application.
id string All The ID assigned to the detector object. This ID is unique and always set by the system.
labelResolution object All Indicates the resolution of the detector job (how often data is analyzed to determine if an alert should be triggered). This is different from the data display resolution used to populate the detector visualization; the data display resolution is automatically set to the coarsest resolution of all of the publish statements associated with the detector since they are all displayed together in the same visualization. The data display resolution may change when the time window for display is modified but the underlying detector job resolution as set in this property is unaffected. If the underlying detector job is modified in this Update Detector call, the response will return a null value; the proper value of the object and its properties are determined asynchronously. Otherwise, the existing values computed after the detector was created or last updated are returned. The properties of this object use the name of the label of each publish statement in the detector as their names. These properties are indicated as labelResolution.label in this documentation.
labelResolution.label integer All Indicates the resolution in milliseconds of the SignalFlow using the publish statement with the specified label (how often data is analyzed to determine if an alert should be triggered). This is different from the data display resolution used to populate the detector visualization; the data display resolution is automatically set to the coarsest resolution of all of the publish statements associated with the detector since they are all displayed together in the same visualization. The data display resolution may change when the time window for display is modified but the underlying detector job resolution as set in this property is unaffected. This value is set automatically by the system after the detector job is analyzed and cannot be updated manually. In most cases the value is set to 1000 (1 second).
lastUpdated string All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application. This value is always set by the system.
lastUpdatedBy integer All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
locked boolean All If true, the detector cannot be modified in any way. If false, any user with access to the detector may edit it.
maxDelay integer All The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the detector analysis. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
name string All The name of the detector. This value is used to identify the detector in the web application.
overMTSLimit boolean All If true one, or more statements in the detector matched too many time series and the matched set was forcefully limited. In this case, the detector is most likely looking at incomplete data or an incomplete aggregation. If this flag is set to true, you can use a series of partition_filter functions to split the data set into manageable pieces then use the union function to rejoin the results in a subsequent computation. Note that the union function still observes the time series limit; some type of aggregation on the partial streams must limit the data set prior to recombining the streams for this approach to work.
programText string All A SignalFlow program used to populate the detector. The program must include one or more detect functions and each detect function must be modified by a publish stream method with a label that's unique across the program. If you wish to support custom notification messages that include input data you must use variables to assign the detect conditions. If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n"). See the Detectors Overview for more information.
rules list of objects All A list of rules indicating the severity of alert conditions and how to send notifications when indicated conditions are met. Each rule binds a specific detect function in the programText property (using the value of the label in its publish method) to a set of one or more notification directives and an associated severity indicator. The same condition can be used in multiple rules if different severity indicators are desired for different notification methods. The properties of the included objects are indicated as rules[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the rules array.
rules[x].description string All A description for the rule. Displays as the alert condition in the Alert Rules tab of the detector editor.
rules[x].detectLabel string All The label of the publish statement associated with the detect function associated with this rule.
rules[x].disabled boolean All Indicates whether the associated rule is turned on and being evaluated (false) or is currently turned off and will not fire even if the specified conditions are met (true).
rules[x].notifications list of objects All A set of notifications to send when the associated rule fires. The properties of the included objects are indicated as rules[x].notifications[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the rules array.
rules[x].notifications[y].channel string rules[x].notifications[y].type property = Slack Indicates the name of the channel to display the notification message. The name should be specified without a leading # symbol. For example, channel #critical-notifications would be specified as "critical-notifications".
rules[x].notifications[y].credentialId string rules[x].notifications[y].type property = HipChat, PagerDuty, ServiceNow, Slack, VictorOps, or Webhook Indicates which integration profile to use to send notifications when an alert fires, represented by the ID of the integration object for that profile. To get the IDs for all available integrations (including integrations not used for notifications) use the Get Integrations API call without query parameters. To limit the results to a specific type of integration, use the Get Integrations API call with the type query parameter set to the desired type. For example GET https://api.signalfx.com/v2/integration?type=HipChat will return all objects representing HipChat integration profiles.
rules[x].notifications[y].email string rules[x].notifications[y].type property = Email The address to send an email notification. This email address is not validated in any way; you are responsible for ensuring that it is correct and in the correct format. Values that cannot be interpreted as legal email addresses may not be saved and may result in a notification without an assigned email address.
rules[x].notifications[y].room string rules[x].notifications[y].type = HipChat Indicates the name of the room to display the notification message.
rules[x].notifications[y].routingKey string rules[x].notifications[y].type = VictorOps Indicates the routing key used to determine how to process the notification message. This key indicates where the notification is posted and how related alerts are escalated. For more information see the VictorOps knowlegebase.
rules[x].notifications[y].secret string rules[x].notifications[y].type = Webhook A secret that identifies which Webhook integration to use when sending notifications and indicates this notification has permission to use it. If rules[x].notifications[y].credentialId is set, this property is ignored.
rules[x].notifications[y].team string rules[x].notifications[y].type property = Team or TeamEmail The ID of the team getting the notification. The form of the notification is determined by the value of the rules[x].notifications[y].type property and is discussed further in its description.
rules[x].notifications[y].type enumerated string All Indicates the mechanism for sending the notification. Notifications can be sent to individual users or to teams and may be send via email, using a third-party messaging system, or using a third-party incident management system. Each element of the notifications list represents a single recipient, chat room or channel, or third party incident management system (in most cases any relevant configuration or routing selection is set system-wide; VictorOps supports multiple routing options and thus each element of the list represents a single routing option rather than all notifications for the system). A rule may have as many notification options configured as needed to send all desired notifications when the rule is triggered; these options may be different versions of the same type or chosen from as many of the supported types as needed. For more information, see the notification section of the Detectors Overview.
rules[x].notifications[y].url string rules[x].notifications[y].type = Webhook The URL of a webhook integration. You must provide some mechanism for processing notifications sent to this URL and routing them to the proper chat or incident management system. If rules[x].notifications[y].credentialId is set, this property is ignored.
rules[x].parameterizedBody string All Custom notification message body for this rule when the alert is triggered. The content can contain any ASCII characters and is parsed as either plain text or Github-flavored markdown (see the Markdown Support in Custom Notification Messages section of the Detectors Overview for specifics). Quotes can be escaped by using backslash, and new line characters are indicated with "\n". Variables are indicated using curly braces; double curly braces indicate a variable that's substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable. For more information see the custom notification messages section of the Detectors Overview. A full list of available variables with their default notation recommendation is available in the SignalFx documentation.
rules[x].parameterizedSubject string All Custom notification message subject for this rule when the alert is triggered. The content can contain ASCII characters and is parsed as plain text. Quotes can be escaped by using backslash, and new line characters are indicated with "\n". Variables are indicated using curly braces; double curly braces indicate a variable that's substituted in place as is (and thus certain characters may be interpreted by the back end rather than rendered as supplied in the eventual output) while triple curly braces indicate a variable that gets escaped as needed so characters like quotation marks and angle brackets render properly in notification messages. Any variable may use either notation at the discretion of the message author. If unsure which style of variable to use, use triple braces; all content should render properly in messages using this notation. That said, SignalFx provides recommendations for the notation style to use with each supported variable. For more information see the custom notification messages section of the Detectors Overview. A full list of available variables with their default notation recommendation is available in the SignalFx documentation.
rules[x].runbookUrl string All URL of page to consult when an alert is triggered. This can be used with custom notification messages. It can be referenced using {{runbookUrl}} in the rules[x].parameterizedBody or rules[x].parameterizedSubject field.
rules[x].severity enumerated string All Indicates how impactful a triggered alert might be. You are free to define your own meaning for each level of severity and judge which level is appropriate for different triggering conditions; however, in general Critical is considered the most serious, followed by Warning, Major, Minor, and the least severe Info level.
rules[x].tip string All Plain text suggested first course of action, such as a command line to execute. This can be used with custom notification messages. It can be referenced using {{tip}} in the rules[x].parameterizedBody or rules[y].parameterizedSubject field.
tags list of strings All A set of keywords used to filter detectors or to search for all detectors with some common element. Among other things, tags may be used to indicate the state of a detector or its data source (for example, a prod tag could indicate all detectors monitoring a production environment).
teams list of strings All Specifies the IDs of teams associated with this detector. Teams associated with a detector see that detector and active alerts associated with the detector on the team's landing page in the web application. The list of teams associated with a detector is completely independent of the notification settings; teams specified here do not automatically get notified of new alerts and teams choosing to get alerts do not have to display the detector on their team landing page in the web application.
visualizationOptions object All Options for detector visualization. The properties of the included object are indicated as visualizationOptions.propertyName in this documentation.
visualizationOptions.disableSampling boolean All If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
visualizationOptions.showDataMarkers boolean All If true, markers will be drawn for each datapoint within the visualization.
visualizationOptions.showEventLines boolean All If true, a vertical line is displayed on the visualization when an event is triggered.
visualizationOptions.time object All Options for the time displayed in the detector visualization. The properties of the included object are indicated as visualizationOptions.time.propertyName in this documentation.
visualizationOptions.time.end integer visualizationOptions.time.type property = absolute The timestamp of the last time to display in the visualization specified in milliseconds since midnight UTC on January 1, 1970
visualizationOptions.time.range integer visualizationOptions.time.type property = relative The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here, GCP metrics listed here, and Azure metrics listed here.
visualizationOptions.time.start integer visualizationOptions.time.type property = absolute The timestamp of the first time to display in the visualization specified in milliseconds since midnight UTC on January 1, 1970
visualizationOptions.time.type enumerated string All Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Enable Detector

The Enable Detector API call restarts one or more previously disabled detector jobs associated with a v2 detector object, allowing them to resume triggering or clearing alerts as the current data warrants.

 

The Enable Detector API call restarts one or more previously disabled detector jobs associated with a v2 detector object, allowing them to resume triggering or clearing alerts as the current data warrants. This is different from unmuting the muted alerts which enables notifications for jobs that are already processing data. If a disabled detector is also muted it will remain muted when enabled; notifications must be turned on separately.

The Enable Detector API call is idempotent; calling it on a detector that is already enabled results in a successful call and a detector that remains enabled. Thus, you may safely call it without first checking the current state of the detector.

The following table shows the expected alert visibility and notification delivery for different states of a detector:

Detector State Alert Condition Not Met Alert Condition Newly Met Alert Newly Cleared
enabled, normal no active alert shown active alert shown, notifications sent no active alert shown, notifications sent
enabled, muted no active alert shown active alert shown, no notifications sent no active alert shown, no notifications sent
disabled during alert, normal active alert shown active alert shown, no notifications sent active alert shown, no notifications sent
disabled during alert, muted active alert shown active alert shown, no notifications sent active alert shown, no notifications sent
disabled while clear, normal no active alert shown no active alert shown, no notifications sent no active alert shown, no notifications sent
disabled while clear, muted no active alert shown no active alert shown, no notifications sent no active alert shown, no notifications sent

The enable detector request is sent as a list of publish statement labels inside an array; there is no overarching request object. The detector job associated with each label is enabled; if the detector contains other valid publish statements they will retain their previous state.

For more information on detectors including the types of notifications available, see the Detectors Overview.

Syntax

PUT https://api.signalfx.com/v2/detector/_id_/enable

Request Format

The request consists of the call path above, HTTP headers, and a JSON array payload in the body. This payload is an array of strings; request payloads containing a single JSON object or an array of JSON objects will be rejected.

Headers

The following HTTP headers are required for the Enable Detector call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Path Parameters

The Enable Detector API call supports one path parameter as indicated in the syntax line above:

Path parameter Type Description
id string The system assigned identifier of an existing detector object.

Payload

The Enable Detector request payload consists solely of an array of strings; it contains no JSON properties or key-value pairs of any sort. These strings must map to a valid label of a publish statement in the detector's SignalFlow definition (found in the programText property of the detector).

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Enable Detector call will return a 204 No Content status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Enable Detector call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The Enable Detector API call does not support a response payload.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Disable Detector

The Disable Detector API call stops one or more detector jobs associated with a v2 detector object, preventing them from triggering or clearing alerts.

 

The Disable Detector API call stops one or more detector jobs associated with a v2 detector object, preventing them from triggering or clearing alerts. This is different from muting the alerts which prevents sending new notifications but still processes the indicated jobs and presents information related to their state in the web application. Essentially, muting alerts retains pull notifications while turning off push notifications whereas disabling the detector job prevents both push and pull notifications, removing all ability to accurately view the current detector state.

The Disable Detector API call is idempotent; calling it on a detector that is already disabled results in a successful call and a detector that remains disabled. Thus, you may safely call it without first checking the current state of the detector.

Disabling a detector freezes it in place, preventing future state changes until such time as the conditions for that state change occur after the detector is enabled again. In particular, disabling a detector does not clear any active alerts; rather it keeps them in place until such time as the clear condition is met after the detector is enabled again.

The following table shows the expected alert visibility and notification delivery for different states of a detector:

Detector State Alert Condition Not Met Alert Condition Newly Met Alert Newly Cleared
enabled, normal no active alert shown active alert shown, notifications sent no active alert shown, notifications sent
enabled, muted no active alert shown active alert shown, no notifications sent no active alert shown, no notifications sent
disabled during alert, normal active alert shown active alert shown, no notifications sent active alert shown, no notifications sent
disabled during alert, muted active alert shown active alert shown, no notifications sent active alert shown, no notifications sent
disabled while clear, normal no active alert shown no active alert shown, no notifications sent no active alert shown, no notifications sent
disabled while clear, muted no active alert shown no active alert shown, no notifications sent no active alert shown, no notifications sent

The disable detector request is sent as a list of publish statement labels inside an array; there is no overarching request object. The detector job associated with each label is disabled; if the detector contains other valid publish statements they will retain their previous state.

For more information on detectors including the types of notifications available, see the Detectors Overview.

Syntax

PUT https://api.signalfx.com/v2/detector/_id_/disable

Request Format

The request consists of the call path above, HTTP headers, and a JSON array payload in the body. This payload is an array of strings; request payloads containing a single JSON object or an array of JSON objects will be rejected.

Headers

The following HTTP headers are required for the Disable Detector call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Path Parameters

The Disable Detector API call supports one path parameter as indicated in the syntax line above:

Path parameter Type Description
id string The system assigned identifier of an existing detector object.

Payload

The Disable Detector request payload consists solely of an array of strings; it contains no JSON properties or key-value pairs of any sort. These strings must map to a valid label of a publish statement in the detector's SignalFlow definition (found in the programText property of the detector).

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Disable Detector call will return a 204 No Content status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Disable Detector call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The Disable Detector API call does not support a response payload.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Delete Detector

The Delete Detector API call permanently deletes a single v2 detector identified by its id value.

 

The Delete Detector API call permanently deletes a single v2 detector identified by its id value.

For more information on detectors, see the Detectors Overview.

Syntax

DELETE https://api.signalfx.com/v2/detector/_id_

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Delete Detector call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Path Parameters

The Delete Detector API call supports one path parameters as indicated in the syntax line above:

Path parameter Type Description
id string The system assigned identifier of an existing detector object.

Payload

The Delete Detector API call does not support a request payload.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Delete Detector call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Delete Detector call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The Delete Detector API call does not send a response payload.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

/detector/:id/events

Get events generated by a detector

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/detector/id/events
$ curl \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/detector/ABCDEFGHIJ/events
A binary file was returned

You couldn't be authenticated

{
  ...
}

Path Params

id
string
required

Query Params

from
int64

Starting point of the time range for which events will be selected, in milliseconds from epoch

to
int64

End point of the time range for which events will be selected, in milliseconds from epoch

limit
int32

Number of results to return

offset
int32

Offset of results to return

 

API supports only v2 detectors

Detector APIs are supported only for v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Suggest Edits

/detector/:id/incidents

Show active incidents for a detector.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/detector/id/incidents
$ curl \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/detector/ABCDEFGHIJ/incidents
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

Query Params

limit
int64

Number of results to return

offset
int64

Offset of results to return

 

API supports only v2 detectors

Detector APIs are supported only for v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Suggest Edits

Incident Model

 

An incident is a collection of related events generated by a detector. Each incident has a triggering (or "alerting") event, when an alert notification is sent to the notification recipients, and a clearing (or "resolving") event, when an "ok" notification is sent.

Some incident APIs support only v2 detectors

Some incident APIs are supported only for v2 detectors. A v2 detector is one that was created using the SignalFx v2 API. See individual APIs for specifics.

Incident Model

Property
Type
Description

incidentId

String

ID of incident

detectorId

String

ID of detector

detectLabel

String

Label for originating detect function in detector

active

boolean

True when the incident hasn't been resolved yet

severity

String

Detector rule severity, one of: Critical, Warning, Major, Minor, Info

anomalyState

String

Current anomaly state, one of: TOO_HIGH, OK, TOO_LOW, ANOMALOUS, INCONCLUSIVE, STOPPED, CLEARED

events

List of IncidentEvents

Events associated with the incident

duration

long

For resolved incidents, milliseconds elapsed between the triggering event and the resolving event. Only present if the incident has already been resolved.

IncidentEvent Model

Property
Type
Description

id

String

ID of event

timestamp

long

The timestamp for the event

detectorId

String

ID of originating detector for the event

detectLabel

String

Label for the originating detect function for event

severity

String

Rule Severity for the originating detect label. One of: Critical, Warning, Major, Minor, Info.

incidentId

String

ID of incident the event is a part of

anomalyState

String

Anomaly state for event, one of: TOO_LOW, OK, TOO_HIGH, ANOMALOUS, INCONCLUSIVE, STOPPED, CLEARED

inputs

List of IncidentEventSources

Inputs involved in the event

IncidentEventSource Model

Property
Type
Description

dimensions

String to String Map

Dimension key/value pairs identifying the source

value

Number

The value of the source at the time of the event

fragment

String

SignalFlow program fragment the source is computed from

Suggest Edits

/incident

Return information for incidents

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/incident
$ curl \
  --request GET \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/incident
A binary file was returned

You couldn't be authenticated

{
  "results": [{
    incidentId: ID_OF_INCIDENT,
    detectorId: ID_OF_ORIGINATING_DETECTOR,
    detectLabel: LABEL_OF_ORIGINATING_DETECT_FUNCTION,
    active: WHETHER_INCIDENT_IS_ONGOING,
    severity: INCIDENT_SEVERITY,
    anomalyState: CURRENT_ANOMALY_STATE,
    events: LIST_OF_EVENTS_FOR_INCIDENT,
    duration: DURATION_OF_INCIDENT
  }]
}

Query Params

offset
int32

Offset of results to return

limit
int32

Number of results to return

includeResolved
boolean

Whether to return incidents which have already resolved

 

API supports only v2 detectors

This API is supported only for incidents related to v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Suggest Edits

/incident/:id

Get incident information for a detector

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/incident/id
$ curl \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/incident/ABCDEFGHIJ
A binary file was returned

You couldn't be authenticated

{
	incidentId: ID_OF_INCIDENT,
  detectorId: ID_OF_ORIGINATING_DETECTOR,
  detectLabel: LABEL_OF_ORIGINATING_DETECT_FUNCTION,
  active: WHETHER_INCIDENT_IS_ONGOING,
  severity: INCIDENT_SEVERITY,
  anomalyState: CURRENT_ANOMALY_STATE,
  events: LIST_OF_EVENTS_FOR_INCIDENT,
  duration: DURATION_OF_INCIDENT
}

Path Params

id
string
required
 

API supports only v2 detectors

This API is supported only for incidents related to v2 detectors. A v2 detector is one that was created using the SignalFx v2 API.

Suggest Edits

/incident/:id/clear

Manually clear (resolve) an incident

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/incident/id/clear
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/incident/ABCDEFGHIJ/clear
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required
 

API supports incidents for all detectors

Unlike some incident APIs, this API can be used with incidents related to detectors created in the SignalFx web UI as well as with detectors created using the v2 API.

Suggest Edits

/alertmuting

Retrieve alert muting rules

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/alertmuting
$ curl \
  --request GET \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/alertmuting
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

include
string

Types of muting rules to be included (Past, Future, Ongoing, Open, All)

query
string

Query string to search for muting rules

orderBy
array of strings

Fields to sort result by; default is start time in ms since epoch

limit
int32

Number of results to return

offset
int32

Offset of results to return

 

API supports muting rules for all detectors

Unlike the detector APIs, the alertmuting APIs can be used with detectors created in the SignalFx web UI as well as with detectors created using the v2 API.

Suggest Edits

/alertmuting

Create new alert muting rule

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/alertmuting
$ curl \
  --request POST \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --data-binary @- \
  https://api.signalfx.com/v2/alertmuting << EOF
{
  "startTime": 1473224400050,
  "stopTime": 1473310800050,
  "filters": [{"not": false, "property": "customer", "propertyValue": "abc"}]
}
EOF
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

filters
array

List of filters. Example of filter {"property":"availabilityZone", "propertyValue":"us-east-1a", "NOT":false}

startTime
int64

Start time of muting period in milliseconds since epoch. If startTime is not specified, it will default its value to the current time in UTC milliseconds.

stopTime
int64

Stop time of muting period in milliseconds since epoch. 0 indicates that the detectors matching this rule will be muted indefinitely. If stopTime is not specified, the value will default to 0.

description
string

Description of the muting rule

 

API supports muting rules for all detectors

Unlike the detector APIs, the alertmuting APIs can be used with detectors created in the SignalFx web UI as well as with detectors created using the v2 API.

Suggest Edits

/alertmuting/:id

Retrieve alert muting rule by ID

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/alertmuting/id
$ curl \
  --request GET \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/alertmuting/ABCD1234
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

ID of the muting rule object

 

API supports muting rules for all detectors

Unlike the detector APIs, the alertmuting APIs can be used with detectors created in the SignalFx web UI as well as with detectors created using the v2 API.

Suggest Edits

/alertmuting/:id

Update an alert muting rule

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/alertmuting/id
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --data-binary @- \
  https://api.signalfx.com/v2/alertmuting/abcd1234 << EOF
{
  "startTime": 1473224400050,
  "stopTime": 1473310800050,
  "filters": [{"not": false, "property": "customer", "propertyValue": "abc"}]
}
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

ID of the muting

Body Params

filters
array

List of filters. Example of filter {"property":"availabilityZone", "propertyValue":"us-east-1a", "NOT":false}. Example for filter by detector {"property":"sf_detectorId", "propertyValue":"theDetectorId", "NOT":false}

startTime
int64

Start time of muting period in milliseconds since epoch. If startTime is not specified, it will default its value to the current time in UTC milliseconds.

stopTime
int64

Stop time of muting period in milliseconds since epoch. 0 indicates that the detectors matching this rule will be muted indefinitely. If stopTime is not specified, the value will default to 0.

description
string

Description of the muting rule

 

API supports muting rules for all detectors

Unlike the detector APIs, the alertmuting APIs can be used with detectors created in the SignalFx web UI as well as with detectors created using the v2 API.

Suggest Edits

/alertmuting/:id

Delete an alert muting rule scheduled to start in the future

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.signalfx.com/v2/alertmuting/id
$ curl \
  --request DELETE \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/alertmuting/abcd1234
A binary file was returned

You couldn't be authenticated

Cannot delete alert muting in the past.
Unable to find the given alert muting.

Path Params

id
string
required

ID of the muting rule

 

API supports muting rules for all detectors

Unlike the detector APIs, the alertmuting APIs can be used with detectors created in the SignalFx web UI as well as with detectors created using the v2 API.

Suggest Edits

/alertmuting/:id/unmute

End a muting period that is currently active. Updates stop time to server current time.

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/alertmuting/id/unmute
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/alertmuting/Cqe64MjAAAE/unmute
A binary file was returned

You couldn't be authenticated

{
  "created" : 1471890049324,
  "creator" : "CqewHrdAAAI",
  "description" : "",
  "filters" : [ {
    "NOT" : false,
    "property" : "demo_customer",
    "propertyValue" : "thefountain.org"
  } ],
  "id" : "Cqe64MjAAAE",
  "lastUpdated" : 1471890103224,
  "lastUpdatedBy" : "CqewHrdAAAI",
  "startTime" : 1471890049311,
  "stopTime" : 1471890103193
}
"Cannot update alert muting that has already ended."
Unable to find the given alert muting.

Path Params

id
string
required

Body Params

description
string

(optional) Text to update the current muting rule description

 

API supports muting rules for all detectors

Unlike the detector APIs, the alertmuting APIs can be used with detectors created in the SignalFx web UI as well as with detectors created using the v2 API.

Suggest Edits

Charts Overview

Charts enable you to visualize the metrics you are sending in to SignalFx

 

Charts enable you to visualize the metrics you are sending in to SignalFx. A metric is anything that is measurable (you can assign a numerical value to it) and variable (changes over time). A chart may contain a single plot or multiple related plots in a single visualization.

Within the web application, every chart belongs to one dashboard which in turn is part of one dashboard group. These are one-to-many relationships; each dashboard may contain multiple charts but each chart belongs to only one dashboard. These relationships are stored in the containing object; charts do not know their associated dashboard but dashboards contain a list of the charts associated with them. However, charts created via API call do not automatically belong to a dashboard; this relationship must be manually set using dashboard API calls. Until that happens, a chart is considered an orphan by the SignalFx web application and will only be accessible via direct request. Charts created by API calls can be directly viewed in the web application using their id property as follows:

https://app.signalfx.com/#/chart/v2/_id_

and will also appear by name in the catalog and in their associated dashboard.

In general, each chart is based on a specified SignalFlow program; users creating or updating charts are expected to understand SignalFlow and be able to create, edit, and interpret statements using it. That said, the SignalFlow associate with a specific chart may be modified by filters associated with its dashboard so the chart definition is not entirely self-contained.

Charts may contain watermarks highlighting regions of interest or high and low threshold values visually indicating when outliers occur.

Types of Charts

SignalFx supports five types of charts:

Single Value Charts

Single value charts show a single data point's value as it changes over time. This type of chart is typically used on wall TV displays (and elsewhere) to display very important single metrics with a low information density. Common examples of single value charts include host counts, the number of active processes, and the number of X served in the past day.

Single Value Chart Example -narrow

Single Value charts typically have no historical context - once the value changes to the next bit of data in the stream the previous values are gone and cannot be restored or viewed again. The current value can be set to display specific colors based on thresholds; for instance when the number of X served in a particular day meets the daily goal the color can be switched from red to green so everyone knows the goal has been met.

If a stream with more than one time series is set to display in a single value chart, the chart will display the first time series it finds and disregard the rest.

Prefix and Suffix Values

Prefix and suffix values can be added to help describe the value being shown on the chart:

Single Value Chart Prefix and Suffix Example -narrow

Secondary Visualizations

Single value charts can have sparkline, radial, or linear secondary visualizations in addition to the displayed value; no secondary visualization is used by default. A sparkline visualization shows recent trends of the value, a radial visualization displays a dial indicating where the current value falls among the expected range of values, and a linear visualization displays a bar indicating where the current value falls among the expected range of values.

A single value chart with a sparkline visualization might look like this:
Sparkline Secondary Visualization

A single value chart with a radial visualization might look like this:
Radial Secondary Visualization Example

A single value chart with a linear visualization might look like this:
Linear Secondary Visualization Example

List Charts

List charts are similar to single value charts but they support displaying more than one data point at a time and showing recent trends in the data without the ability to look at the historical data in any detail. They support up to 100 items displayed in the chart simultaneously but work best with 20 or fewer items shown. A common usage for list charts is to display the Top N of something, for example the hosts with the highest CPU usage.

List Chart Example

Sorting List Charts

Values on list charts can be sorted based on criteria chosen by the chart creator using the options.sortBy property. Every list chart supports sorting based on three keywords representing the value of the data point, the name of the metric being displayed, or the publish label of the plot. The keywords are specified as follows:

Keyword Corresponding option in the web application Description
sf_metric Plot Name The publish label of the SignalFlow statement generating the data being displayed. This is also the plot name of the corresponding signal in the web application.
sf_originatingMetric Metric The name of the metric used to generate the data being displayed.
value Value The current value of the data point displayed.

For example, the list chart below displays CPU utilization sorted by value in descending order; note that the top values are 100, meaning a few of the machines being monitored are completely maxed out:

List Chart Sorting Example

In addition, sorting by any dimension associated with any metric displayed on the chart is also supported. The list of available dimensions varies depending on your chart criteria. If you need help identifying which dimensions are available on your chart, you can paste the SignalFlow for your chart into the SignalFlow editor in the New Chart interface and switch to the Data Table to see a list of available options:

List Chart Sort Options in Data Table

The Data Table indicates that the following dimensions are available as sort options for a data stream based on CPU utilization:

  • host
  • dnsname
  • plugin
  • plugin_instance

A different SignalFlow statement would result in different dimensions. In addition to these dimensions, the Data Table always lists the options corresponding to the three keywords. Note that the metric name appears in the sf_metric column; despite this, you must use the sf_originatingMetric keyword to sort by metric name.

You could also switch to a List chart in the New Chart interface and look at the dropdown menu for the Sort field under Chart Options; this field maps directly to the options.sortBy property of a list chart. It will show the same values, again equating Metric with sf_metric instead of the required value of sf_originatingMetric:

List Chart Sort Options from UI

Because data is streaming and values change over time, the order of the data associated with a specific publish label at any given moment may change depending on your sort criteria (including as you scroll through the list).

Prefix and Suffix Values

Prefix and suffix values can be added to help describe the values being shown on the chart:

Line Chart Prefix and Suffix Example

Secondary Visualizations

List charts can have sparkline, radial, or linear secondary visualizations for each item in addition to the displayed value or just display the value without a secondary visualization; a sparkline secondary visualization is used by default (see above for an example of what this looks like). A sparkline visualization shows recent trends of the value, a radial visualization displays a dial indicating where the current value falls among the expected range of values, and a linear visualization displays a bar indicating where the current value falls among the expected range of values.

A list chart with a radial visualization might look like this:

Radial Secondary Visualization List Example

A list chart with a linear visualization might look like this:

Linear Secondary Visualization Example

Time Series Charts

Time series charts expand the number of data points that can be displayed at once and retain a larger set of historical data with timestamps to make it easier to locate. Time series charts may include a legend indicating which color represents each value of a particular dimension of a plot. For example, a series of plot lines might be colored by AWS availability zone with red indicating us-east-1, green indicating us-east-2, and purple indicating eu-west-1.

Displaying Units and Other Labels

Plots on a chart can specify a unit of value, which will be scaled up and down based on the value in order to improve readability. Units fall into three groups:

Bits
Name Abbreviation Scale Factor
Bit b 1
Kilobit Kb 103
Megabit Mb 106
Gigabit Gb 109
Terabit Tb 1012
Petabit Pb 1015
Exabit Eb 1018
Zettabit Zb 1021
Yottabit Yb 1024
Bytes
Name Abbreviation Scale Factor
Byte B 1
Kibibyte KiB 1024
Mebibyte MiB 10242
Gigibyte GiB 10243
Tebibyte TiB 10244
Pebibyte PiB 10245
Exbibyte EiB 10246
Zebibyte ZiB 10247
Yobibyte YiB 10248
Time
Name Abbreviation
Nanosecond ns
Microsecond μs
Millisecond ms
Second s
Minute m
Hour h
Day d
Week w

In addition, prefix and suffix values can be added to help describe the values being shown on the chart if no units are specified:

Time Series Chart Prefix and Suffix Example

Visualizations

Time series charts may be visualized in any of four ways: using a line chart, an area chart, a column or bar chart, or a histogram.

Line Charts

The LineChart plot type displays the data in a plot with datapoints connected by a series of straight lines as follows:

Time Series Chart Line Chart Example

Area Charts

The AreaChart plot type displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in as follows:

Time Series Chart Area Chart Example

Column Charts

The ColumnChart plot type lists the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. By default each plot point is shown as an independent bar closely plotted next to each other as follows:

Time Series Chart Column Chart Example

Column charts can also be stacked, meaning that the bars representing each value at each moment in time are stacked vertically on top of each other at the relevant time point along the x-axis rather than being grouped next to each other near that point as follows:

Time Series Chart Stacked Column Chart Example

Histograms

Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar or darker shades of a single color might indicate a higher density of plot points with the relevant value than a higher shade of that same color as follows:

Time Series Chart Histogram Chart Example

The values of a histogram plot display in a random order by default but may be organized into two levels of grouping to hone in on the behavior of specific sets of data. For example, data might be grouped by AWS region or availability zone to make it easier to track performance within each region or availability zone.

Heatmap Charts

Heatmap charts present a series of squares each representing a single data point of the selected metric. The color of each square represents the value range of the metric allowing quick identification of values that are higher or lower than desired.

Heatmap Example

Grouping

The data points in a heatmap can be grouped by up to two properties to highlight the health of a specific aspect of the data being viewed. For example, the following heatmap groups CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping.


Heatmap Example with Grouping -wide

Prefix and suffix values can be added to help describe the value being shown on the chart:
Heatmap Prefix and Suffix Example

Text Charts

Text charts allow users to add descriptive text or other information to a dashboard. The chart essentially displays any specified GitHub style Markdown within the chart location and is used to provide information about one or more other charts in the same dashboard.

Text Chart Example -wide

Color Palette

Some elements of SignalFx charts are restricted to a 21-color palette. To choose a color, you specify its index (0-based) in the appropriate property of the request payload.

Note: Some properties only accept the first 16 colors in the palette. These properties are called
out in the property descriptions in the documentation for a specific endpoing.

The 21-color palette contains these colors:

Index Hex Value Sample Swatch
0 #999999 color #999999 -wide
1 #0077c2 color #0077c2 -wide
2 #00b9ff color #00b9ff -wide
3 #6ca2b7 color #6ca2b7 -wide
4 #b04600 color #b04600 -wide
5 #f47e00 color #f47e00 -wide
6 #e5b312 color #e5b312 -wide
7 #bd468d color #bd468d -wide
8 #e9008a color #e9008a -wide
9 #ff8dd1 color #ff8dd1 -wide
10 #876ff3 color #876ff3 -wide
11 #a747ff color #a747ff -wide
12 #ab99bc color #ab99bc -wide
13 #007c1d color #007c1d -wide
14 #05ce00 color #05ce00 -wide
15 #0dba8f color #0dba8f -wide
16 #ea1849 color #ea1849 -wide
17 #eac24b color #eac24b -wide
18 #e5e517 color #e5e517 -wide
19 #acef7f color #acef7f -wide
20 #6bd37e color #6bd37e -wide


Users who select the colorblind-friendly alternative for color display see different colors, depending on the option they choose. The palette mapping for these options is shown in the following
table:

Index Normal Setting Red-Green Color blindness Setting Yellow-Blue Color-blindness Setting
0 #999999 #999999 #005160
1 #0077c2 #000982 #007186
2 #00b9ff #0814b6 #0089a2
3 #6ca2b7 #0b1ae4 #00a2c0
4 #b04600 #7c730b #85005e
5 #f47e00 #aba734 #a40074
6 #e5b312 #c5bf1c #c20089
7 #bd468d #dad30a #e400a1
8 #e9008a #535353 #555555
9 #ff8dd1 #787878 #666666
10 #876ff3 #b0b0b0 #787878
11 #a747ff #c1c1c1 #888888
12 #ab99bc #bc82b6 #999999
13 #007c1d #b36dac #aaaaaa
14 #05ce00 #b241a6 #bbbbbb
15 #0dba8f #b0009d #cccccc
16 #ea1849 #b0009d #e400a1
17 #eac24b #7c730b #005160
18 #e5e517 #aba734 #007186
19 #acef7f #c5bf1c #0089a2
20 #6bd37e #c1c1c1 #c1c1c1

Note: SignalFx changes the entire mapping based on the colorblindness option chosen by the user. Developers can't change individual colors in the mapping.

Suggest Edits

Create Chart

The Create Chart API call creates a new v2 chart.

 

The Create Chart API call creates a new v2 chart. Before the chart has real context in the web application, it must be added to a dashboard using one of the Create Dashboard or Update Dashboard API calls. Once it belongs to a dashboard, the chart will appear within that dashboard and be individually viewable via the chart v2 interface (which may be slightly different from the v1 chart interface described in the SignalFx web application documentation here). It will also be listed by name in the chart section of the catalog for the relevant organization.

For more information on charts including the types of charts supported and the different ways they can be visualized, see the Charts Overview.

Syntax

POST https://api.signalfx.com/v2/chart

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Create Chart call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Payload

The following properties are supported in the request payload for the Create Chart call:

Property Type Constraints Description
customProperties object
  • maximum length of key = 128 characters
  • key name may only contain alphabetic characters, numerals, underscores ("_"), or hyphens ("-")
  • key name must start with an alphabetic character of either case
  • key name may not start with an underscore ("_"), sf followed by an underscore ("sf_"), aws followed by an underscore ("aws_"), gcp followed by an underscore ("gcp_"), or azure followed by an underscore ("azure_")
  • value is required if key is specified
  • value may not be an empty string
  • maximum length of value = 256 characters

NOTE: the key name constraints outlined above may be encapsulated in the following regular expression: ^[a-zA-Z][a-zA-Z0-9_-]*$
A set of user-defined key-value pairs containing metadata about the chart that may change over time. Custom properties may be used to store metadata that may not be known at chart creation or that may be expected to change in the future. These properties can be used to filter charts or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string None The description of the chart. This value appears underneath the chart name in the SignalFx web application.
name string
  • required
  • minimum characters = 1
The name of the chart. The name is used to identify the chart in the SignalFx web application and should be descriptive The name may be truncated in the UI if it does not fit in the allocated space so put important information first. It may be desirable to use unique names for charts but this is not enforced by the API.
options object
  • default values as indicated in specific properties of the object
The options applied to this chart. The options include information about the type of chart and are different for different types of charts. The properties of the included object are indicated as options.propertyName in this documentation. By default all listed properties of the options object are available in any options object. The constraints column will note if a listed property is only available within certain contexts (such as for one or more chart types).
options.areaChartOptions object
  • Only available if the options.type property is set to TimeSeriesChart
  • Only available if the options.defaultPlotType property is set to AreaChart
The area chart options applied to this chart. The properties of the included options object are indicated as options.areaChartOptions.propertyName in this documentation.
options.areaChartOptions.showDataMarkers boolean
  • Only available if the options.type property is set to TimeSeriesChart
  • Only available if the options.defaultPlotType property is set to AreaChart
  • Default value is false
When true, markers will be drawn for each datapoint within the visualization.
options.axes list of objects
  • Only available if the options.type property is set to TimeSeriesChart
Y axis configuration for the left and right side of a chart. The first element of the array corresponds to the left side of the chart and the second element of the array corresponds to the right side of the array. Subsequent elements are accepted but ignored. The properties of the included objects are indicated as options.axes[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the axes array.
options.axes[x].highWatermark float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be equal to or less than the value of the options.axes[x].max property of the same element
  • Value must be greater than the value of the options.axes[x].lowWatermark property of the same element
Indicates a value to draw a horizontal line across the chart as the top of an area of interest to highlight.
options.axes[x].highWatermarkLabel string
  • Only available if the options.type property is set to TimeSeriesChart and options.axes[x].highWatermark is set
  • maximum characters = 1000
Indicates a label for the high watermark line on the chart. If the element corresponds to the left axis (element 0), the label is placed near the line starting at the left edge of the chart. If the element corresponds to the right axis (element 1), the label is placed near the line ending at the right edge of the chart.
options.axes[x].label string
  • Only available if the options.type property is set to TimeSeriesChart
A description for the Y axis of the chart, displayed to the left of the axis value labels for left side axes and to the right of the axis value labels for right side axes.
options.axes[x].lowWatermark float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be equal to or greater than the value of the options.axes[x].min property of the same element
  • Value must be less than the value of the options.axes[x].highWatermark property of the same element
Indicates a value to draw a horizontal line across the chart as the bottom of an area of interest to highlight.
options.axes[x].lowWatermarkLabel string
  • Only available if the options.type property is set to TimeSeriesChart and options.axes[x].lowWatermark is set
  • maximum characters = 1000
Indicates a label for the low watermark line on the chart. If the element corresponds to the left axis (element 0), the label is placed near the line starting at the left edge of the chart. If the element corresponds to the right axis (element 1), the label is placed near the line ending at the right edge of the chart.
options.axes[x].max float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be greater than the value of the options.axes[x].min property of the same element
Indicates the largest value to display on the chart. Overrides options.includeZero if the properties are set to incompatible values.
options.axes[x].min float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be less than the value of the options.axes[x].max property of the same element
Indicates the smallest value to display on the chart. Overrides options.includeZero if the properties are set to incompatible values.
options.axisPrecision integer
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be an integer between 3 and 10
  • Value is 3 by default
Indicates the number of significant digits included for values plotted on the chart. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 100000 and 100010, using a precision of 3 would result in a value of 100000 for all data points. Instead, set the precision to 6 to capture differences in integer values; higher precision values would also capture fractional variations.
options.colorBy enumerated string
  • Not available if the options.type property is set to Text
  • If the options.type property is set to Heatmap:
    • Supported values are: Range and Scale
    • Default value is Range
  • If the options.type property is set to List:
    • Supported values are: Dimension, Metric, and Scale
    • Default value is Metric
  • If the options.type property is set to SingleValue:
    • Supported values are: Dimension, Metric, and Scale
    • Default value is Metric
  • If the options.type property is set to TimeSeriesChart:
    • Supported values are: Dimension and Metric
    • Default value is Dimension
Indicates the mechanism for applying the color scheme to the values in the chart. If color is desired in a text chart it should be applied using HTML within the markdown property.
options.colorRange object
  • Only available if the options.type property is set to Heatmap
The range of values to be colored in this chart and the color to span across that range. The number of variations of that color within the specified range is controlled by the colorScale property. The properties of the included object are indicated as options.colorRange.propertyName in this documentation.
options.colorRange.color string
  • Only available if the options.type property is set to Heatmap
  • Expected to have seven characters as follows:
    • The first character is always a pound sign ("#")
    • The other characters may be any numeral or a capital letter between A and F inclusive
The hex value of the color used to represent values in a heatmap chart. Different tones of this color are then applied as indicated by the values of the colorScale property. The color specified is the lowest value of the color gradient in the chart; the number of variations of that color within the specified range is controlled by the colorScale property. We recommend using one of the twenty one colors in the official color palette for best results.
options.colorRange.max string
  • Only available if the options.type property is set to Heatmap
The largest value assigned a color in the heatmap. In general this should correspond to the highest expected value of the input criteria.
options.colorRange.min string
  • Only available if the options.type property is set to Heatmap
The smallest value assigned a color in the heatmap. In general this should correspond to the smallest expected value of the input criteria.
options.colorScale object
  • Available if the options.type property is set to Heatmap, SingleValue, or List
Indicates the borders of color ranges in charts and whether the range should be applied in the default order or inverted. If options.colorScale2 is specified, this property will be overridden by the settings there. The properties of the included object are indicated as options.colorScale.propertyName in this documentation.
options.colorScale.inverted boolean
  • Available if the options.type property is set to Heatmap, SingleValue, or List
  • Set to false by default
If true, the colors are applied to the specified ranges in reverse order from the default application. For heatmap charts using options.colorBy set to Range, this means darker tones indicate lower values. For other chart types, it means that red represents lower values and green higher values in the default color scheme (other color schemes may be applied for users who select a color blind mode).
options.colorScale.thresholds list of floats
  • Available if the options.type property is set to Heatmap, SingleValue, or List
Indicates the border values for color ranges in the chart. Values should be specified from lowest to highest and only the first six values have meaning (additional elements are ignored). Values outside of the range will not be colored; in general the first value in the array should map to the lowest value expected for the plotted data and the last (meaningful) value in the array should correspond to the highest value expected for the plotted data.
options.colorScale2 list of objects
  • Available if the options.type property is set to List, SingleValue, or Heatmap
Each element of the array contains the information about a single color range including both the color to display for that range and the borders of the range. Collectively the set of elements specify the entire range displayed in the secondary visualization or heatmap chart. The elements do not need to be specified in any order; they will automatically be ordered by value in the display and the lowest value specified in the set of elements will automatically become the left border of any secondary visualization and the highest value specified in the set of elements will automatically become the right border of any secondary visualization. The properties of the included object are indicated as options.colorScale2[x].propertyName in this documentation.
options.colorScale2[x].gt float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].lt or options.colorScale2[x].lte property of the same element
  • Cannot have both options.colorScale2[x].gt and options.colorScale2[x].gte set at the same time
Indicates the lower threshold non-inclusive value for this range.
options.colorScale2[x].gte float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].lt or options.colorScale2[x].lte property of the same element
  • Cannot have both options.colorScale2[x].gt and options.colorScale2[x].gte set at the same time
Indicates the lower threshold inclusive value for this range.
options.colorScale2[x].lt float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].gt or options.colorScale2[x].gte property of the same element
  • Cannot have both options.colorScale2[x].lt and options.colorScale2[x].lte set at the same time
Indicates the upper threshold non-inculsive value for this range.
options.colorScale2[x].lte float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].gt or options.colorScale2[x].gte property of the same element
  • Cannot have both options.colorScale2[x].lt and options.colorScale2[x].lte set at the same time
Indicates the upper threshold inclusive value for this range.
options.colorScale2[x].paletteIndex integer
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Minimum value = 0
  • Maximum value = 20
  • Required
Indicates the index number of color to use for values in the specified range. The list of 21 supported colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users, depending on the selected settings for color blindness. For sample swatches of the colors and the mappings used for color-blind users, see the color palette documentation at the bottom of the Charts Overview.
options.defaultPlotType enumerated string
  • Supported Values are: LineChart, AreaChart, ColumnChart, and Histogram
  • Default value is LineChart
Indicates which of the supported plot types should be used for this chart. LineChart displays the data in a plot with datapoints connected by a series of straight lines. AreaChart displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in. Column charts list the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar.
options.groupBy list of strings
  • Available if the options.type property is set to Heatmap
Indicates one or more properties to group together in the histogram. The value of each element should map to a valid key name specified in the customProperties property or to a valid custom property supplied by default. The first element is a top level grouping, the second element indicates a grouping inside each of the top level groups. Subsequent elements are ignored. For example, a heatmap grouping CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping is shown in the Charts Overview.
options.histogramChartOptions object
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to Histogram
The histogram chart options applied to this chart. The properties of the included options object are indicated as options.histogramChartOptions.propertyName in this documentation.
options.histogramChartOptions.colorThemeIndex integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to Histogram
  • Minimum value = 0
  • Maximum value = 20
  • Default value = 16
Indicates the index number of the color to use for the theme of this chart when viewed as a histogram. The chart will use variations of this color, with greater opacity indicating greater values. The list of 21 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e
options.includeZero boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Default is false
If true, 0 will always be included when dynamically calculating Y-axis ranges. This is a chart-wide setting applied to all axes in use. However, if options[x].axes.min or options[x].axes.max settings exclude 0 from the displayed range on a particular axis, 0 will not be displayed on that axis even if options.includeZero is set to true.
options.legendOptions object
  • Available if the options.type property is set to TimeSeriesChart or List
  • Default is to show all properties in the legend
Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included object are indicated as options.legendOptions.propertyName in this documentation.
options.legendOptions.fields list of objects
  • Available if the options.type property is set to TimeSeriesChart or List
  • Default is to show all properties in the legend
Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included objects are indicated as options.legendOptions.fields[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the fields array.
options.legendOptions.fields[x].enabled boolean
  • Available if the options.type property is set to TimeSeriesChart or List
  • Default value is true
Indicates whether the associated property is shown (true) or hidden (false) in the data table.
options.legendOptions.fields[x].property string
  • Available if the options.type property is set to TimeSeriesChart or List
The key name of a custom property specified for this chart (or supplied by default by SignalFx) to hide or show in the data table.
options.lineChartOptions object
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to LineChart
Sets options specific to a line chart. The properties of the included object are indicated as options.lineChartOptions.propertyName in this documentation.
options.lineChartOptions.showDataMarkers boolean
  • Available if the is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to LineChart
  • Default value is false
Indicates whether the actual data points are indicated by filled circles on the chart or if the plot is shown as a smooth line with no such indicators.
options.markdown string
  • Only available if the options.type property is set to Text
The content of a text chart as specified using GitHub-flavored Markdown; any Markdown or HTML supported within a *.md file in GitHub is supported in this value.
options.maximumPrecision integer
  • Only available if the options.type property is set to List or SingleValue
  • Value must be an integer
Indicates the number of significant digits included for values plotted on the chart but only applies to fractional portions of the number; all integer digits are included regardless of the desired precision. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 0.001 and 0.01, significant information will be lost unless the precision is set to at least 4. If no value is supplied, the chart visualization will adjust the precision to fit in the available space.
options.onChartLegendOptions object
  • Available if the options.type property is set to TimeSeriesChart
Determines whether a legend is shown and, if so, which dimension is shown on the legend. The properties of the included object are indicated as options.onChartLegendOptions.propertyName in this documentation.
options.onChartLegendOptions.dimensionInLegend string
  • Available if the options.type property is set to TimeSeriesChart
Determines which dimension is shown in the legend. For meaningful values, ensure the dimension sent exists and has different values for each plot in the chart.
options.onChartLegendOptions.showLegend boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Default is false
If true show a legend at the bottom of the chart. The legend lists the each value of the dimension specified in the options.onChartLegendsOptions.dimensionInLegend property next to the color associated with that data point in the chart.
options.programOptions object
  • Available if the options.type property is set to anything but Text
General options applied to the chart. The properties of the included object are indicated as options.programOptions.propertyName in this documentation.
options.programOptions.disableSampling boolean
  • Available if the options.type property is set to anything but Text
  • Default is false.
If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
options.programOptions.maxDelay integer
  • Available if the options.type property is set to anything but Text
  • Maximum value is 900000 (15 minutes)
The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the chart. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.programOptions.minimumResolution integer
  • Available if the options.type property is set to anything but Text
  • Maximum value is 900000 (15 minutes)
The minimum resolution to use for computing the underlying program, specified in milliseconds. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.publishLabelOptions list of objects
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
General options for the plot related to a specific SignalFlow statement applied to the chart. The order of elements in the list is retained as sent but is not significant; label values are used to map options with specific publish() statements in the related SignalFlow. Heatmaps do not support full publishLabelOptions objects; the Constraints column lists the supported chart types for each property. The properties of the included objects are indicated as options.publishLabelOptions[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the publishLabelOptions array.
options.publishLabelOptions[x].displayName string
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
Indicates an alternate value for the Plot Name column of the Data Table associated with the chart.
options.publishLabelOptions[x].label string
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
  • Required
Indicates the value of the string inside the publish function of the SignalFlow statement being configured by this element.
options.publishLabelOptions[x].paletteIndex integer
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
  • Minimum value = 0
  • Maximum value = 15
Indicates the index number of color to use for all plots related to this SignalFlow statement. The list of 16 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f


Different colors may be presented to users, depending on the selected settings for color blindness. For sample swatches of the colors and the mappings used for color-blind users, see the first 16 colors in the color palette documentation at the bottom of the Charts Overview.
options.publishLabelOptions[x].plotType enumerated string
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
  • Supported Values are: LineChart, AreaChart, ColumnChart, and Histogram
Overrides the value of options.defaultPlotType for the output of this SignalFlow statement.
options.publishLabelOptions[x].valuePrefix string
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
Indicates a string to prepend to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview. This setting will be overridden if options.publishLabelOptions[x].valueUnit is set on the same plot.
options.publishLabelOptions[x].valueSuffix string
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
Indicates a string to append to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview. This setting will be overridden if options.publishLabelOptions[x].valueUnit is set on the same plot.
options.publishLabelOptions[x].valueUnit enumerated string
  • Supported values are: Bit, Kilobit, Megabit, Gigabit, Terabit, Petabit, Exabit, Zettabit, Yottabit, Byte, Kibibyte, Mebibyte, Gigibyte, Tebibyte, Pebibyte, Exbibyte, Zebibyte, Yobibyte, Nanosecond, Microsecond, Millisecond, Second, Minute, Hour, Day, and Week
  • Available if the options.type property is set to anything but Text
Indicates display units for the values in the chart. The plot values will be presented in a readable way based on the assumption that the raw values are denominated in the selected unit. For instance, a value of 1000 on a plot with options.publishLabelOptions[x].valueUnit set to bits will be presented as 1 Kilobit, and a value of 1024 on a plot with Bytes selected will be presented as 1 Kebibyte. Each unit will be scaled up and down in this way within its own kind (Bits, Bytes, and Units of Time; see Charts Overview for a full specification).

Plots with options.publishLabelOptions[x].valueUnit are scaled and labelled with the unit's abbreviation when presented in chart tooltips, axes, and data tables. Where options.publishLabelOptions[x].valueUnit affects presentation it overrides options.publishLabelOptions[x].valuePrefix, options.publishLabelOptions[x].valueSuffix, and options.unitPrefix.
options.publishLabelOptions[x].yAxis integer
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
  • Minimum value = 0
  • Maximum value = 1
Indicates whether the Y-axis for the plot associated with this SignalFlow statement is on the left side (0) or the right side of the chart. If not specified, the left side Y-axis is used.
options.refreshInterval integer
  • Available if the options.type property is set to List or SingleValue
Indicates how often the data should be refreshed in the chart in milliseconds. The default is usually 10000 (10 seconds) but may be 3600000 (1 hour) instead if the resolution of the data cannot be detected.
options.secondaryVisualization enumerated string
  • Available if the options.type property is set to List or SingleValue
  • Supported Values are: None, Radial, Linear, Sparkline.
  • If the options.type property is set to List:
    • Default value is Sparkline
  • If options.type property is set to SingleValue:
    • Default value is None
Indicates the secondary visualization to display the value of the metric. Examples of the visualizations are shown in Charts Overview.
options.showEventLines boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Default is false
If true, a vertical line is displayed on the chart when an event is triggered.
options.showSparkLine boolean
  • Available if the options.type property is set to SingleValue
  • Default is false
If true, a graphical representation of recent trends without axes or annotations is shown underneath the value in the chart. For example, the following chart shows a sparkline: sparkline -auto This property will be overridden if options.secondaryVisualization is set.
options.sortBy string
  • Available if the options.type property is set to List
Indicates how to sort the individual entries of a list chart. The first character of the value must be either a minus sign ("-") indicating that the data is displayed in descending order or a plus sign ("+") indicating that the data is displayed in ascending order. The rest of the value indicates the sort criteria, either a keyword (representing the value of the data point, the name of the metric being displayed, or the publish label of the SignalFlow statement generating the data) or the name of a dimension available to the chart. The default sort is on the publish label in ascending order which corresponds to Auto in the web application; values that do not map to a keyword or a valid dimension will use the default sort. Nulls are placed at the start of the list when using ascending order and at the end of the list when using descending order. For information about the available keywords and how the sort options map between the API and the web application, see the Charts Overview.
options.sortDirection enumerated string
  • Available if the options.type property is set to Heatmap
  • Supported values are: Ascending and Descending
  • Default value is Ascending
Indicates whether to put lower or higher values first when sorting the values on a heatmap chart.
options.sortProperty string
  • Available if the options.type property is set to Heatmap
The custom property to use as the sorting criteria for the heatmap chart. The value should map to a valid key name specified in the customProperties property or to a valid custom property available by default. If no value is specified, the values are displayed without an obvious order.
options.stacked boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to AreaChart or ColumnChart
  • Default is false
If true, the plots in the chart are stacked on top of each other and their values added together to create the values indicated by the axis labels. Individual values can still be viewed when highlighting specific points in time on the chart within the visible colored area representing the desired plot or by viewing the data table.
options.includeZero boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Default is false
If true, 0 will always be included when dynamically calculating Y-axis ranges. This is a chart-wide setting applied to all axes in use. However, if options[x].axes.min or options[x].axes.max settings exclude 0 from the displayed range on a particular axis, 0 will not be displayed on that axis even if options.includeZero is set to true.
options.time object
  • Available if the options.type property is set to TimeSeriesChart
Options for the time displayed on the chart. The properties of the included object are indicated as options.time.propertyName in this documentation.
options.time.end integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.time.type property is set to absolute
  • Default = 0
The timestamp of the last time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.range integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.time.type property is set to relative
  • Default = 0
The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here, GCP metrics listed here, and Azure metrics listed here.
options.time.start integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.time.type property is set to absolute
  • Default = 0
The timestamp of the first time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.type enumerated string
  • Available if the options.type property is set to TimeSeriesChart
  • Supported values are: absolute and relative
Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.
options.timestampHidden boolean
  • Available if the options.type property is set to Heatmap or SingleValue
  • Default is false
If true, the timestamp is shown below the displayed values on the chart.
options.type enumerated string
  • Required
  • Supported values are: Heatmap, List, SingleValue, Text, TimeSeriesChart
The visualization mechanism used in the chart. The Heatmap option displays each value in an ordered set of boxes colored to indicate the health of the value. The List option displays each value in its own row with an unlabeled plot showing recent trends. The SingleValue option displays the current value of one data point colored to indicate the health of the value. The Text option displays constant, pre-defined Markdown. The TimeSeriesChart option displays the value of multiple data points together in one of four visualization modes, retaining historical data. See the Charts Overview for a brief discussion and screenshot of each type of chart or see Choosing a Chart Type for more information about using each option within the web application.
options.unitPrefix enumerated string
  • Available if the options.type property is set to anything but Text
  • Supported values are: Binary and Metric
  • Default value is Metric
Indicates whether units should be displayed and labeled using metric units where k stands for kilo- meaning 1000 of the the item in question or in a binary format where K stands for Kibi- meaning 1024 of the item in question.
packageSpecifications string
  • Value must be signalfx
Indicates one or more SignalFlow packages to import for use in the programText value. Currently the only the signalfx package is available.
programText string
  • required for all chart types except Text
A SignalFlow program used to populate the chart. If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n").
tags list of strings
  • Maximum characters per element = 256
A set of keywords used to filter charts or to search for all charts with some common element. Among other things, tags may be used to indicate the state of a chart or its data source (for example, a prod tag could indicate all charts displaying data from a production environment).

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Create Chart call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Create Chart call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Create Chart call:

Property Type Contexts Returned Description
created integer All The time the member object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
creator string All The user ID of the administrator requesting that the invitation be sent. This value is always set by the system. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
customProperties object All A set of user-defined key-value pairs containing metadata about the chart that may change over time. Custom properties may be used to store metadata that may not be known at chart creation or that may be expected to change in the future. These properties can be used to filter charts or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string All The description of the chart. This value appears underneath the chart name in the SignalFx web application.
id string All The ID assigned to the chart object. This ID is unique and always set by the system.
lastUpdated integer All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application
lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
name string All The name of the chart. The name is used to identify the chart in the SignalFx web application and should be descriptive The name may be truncated in the UI if it does not fit in the allocated space so put important information first.
options object All The options applied to this chart. The options include information about the type of chart and are different for different types of charts. The properties of the included object are indicated as options.propertyName in this documentation. By default all listed properties of the options object are available in any options object. The constraints column will note if a listed property is only available within certain contexts (such as for one or more chart types).
options.areaChartOptions object options.type property=TimeSeriesChart, options.defaultPlotType=AreaChart The area chart options applied to this chart. The properties of the included options object are indicated as options.areaChartOptions.propertyName in this documentation.
options.areaChartOptions.showDataMarkers boolean options.type property=TimeSeriesChart, options.defaultPlotType=AreaChart When true, markers will be drawn for each datapoint within the visualization.
options.axes list of objects options.type property=TimeSeriesChart Y axis configuration for the left and right side of a chart. The first element of the array corresponds to the left side of the chart and the second element of the array corresponds to the right side of the array. Subsequent elements are accepted but ignored. The properties of the included objects are indicated as options.axes[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the axes array.
options.axes[x].highWatermark float options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the top of an area of interest to highlight.
options.axes[x].highWatermarkLabel string options.type property=TimeSeriesChart Indicates a label for the high watermark line on the chart. If the element corresponds to the left axis (element 0), the label is placed near the line starting at the left edge of the chart. If the element corresponds to the right axis (element 1), the label is placed near the line ending at the right edge of the chart.
options.axes[x].label string options.type property=TimeSeriesChart A description for the Y axis of the chart, displayed to the left of the axis value labels for left side axes and to the right of the axis value labels for right side axes.
options.axes[x].lowWatermark float options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the bottom of an area of interest to highlight.
options.axes[x].lowWatermarkLabel string options.type property=TimeSeriesChart Indicates a label for the low watermark line on the chart. If the element corresponds to the left axis (element 0), the label is placed near the line starting at the left edge of the chart. If the element corresponds to the right axis (element 1), the label is placed near the line ending at the right edge of the chart.
options.axes[x].max float options.type property=TimeSeriesChart Indicates the largest value to display on the chart. Overrides options.includeZero if the properties are set to incompatible values.
options.axes[x].min float options.type property=TimeSeriesChart Indicates the smallest value to display on the chart. Overrides options.includeZero if the properties are set to incompatible values.
options.axisPrecision integer options.type property=TimeSeriesChart Indicates the number of significant digits included for values plotted on the chart. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 100000 and 100010, using a precision of 3 would result in a value of 100000 for all data points. Instead, set the precision to 6 to capture differences in integer values; higher precision values would also capture fractional variations.
options.colorBy enumerated string options.type property=Heatmap, List, SingleValue, or TimeSeriesChart Indicates the mechanism for applying the color scheme to the values in the chart. If color is desired in a text chart it should be applied using HTML within the markdown property.
options.colorRange object options.type property=Heatmap The range of values to be colored in this chart and the color to span across that range. The number of variations of that color within the specified range is controlled by the colorScale property. The properties of the included object are indicated as options.colorRange.propertyName in this documentation.
options.colorRange.color string options.type property=Heatmap The hex value of the color used to represent values in a heatmap chart. Different tones of this color are then applied as indicated by the values of the colorScale property. The color specified is the lowest value of the color gradient in the chart; the number of variations of that color within the specified range is controlled by the colorScale property. We recommend using one of the twenty one colors in the official color palette for best results.
options.colorRange.max string options.type property=Heatmap The largest value assigned a color in the heatmap. In general this should correspond to the highest expected value of the input criteria.
options.colorRange.min string options.type property=Heatmap The smallest value assigned a color in the heatmap. In general this should correspond to the smallest expected value of the input criteria.
options.colorScale object options.type property=Heatmap, SingleValue, or List Indicates the borders of color ranges in charts and whether the range should be applied in the default order or inverted. If options.colorScale2 is specified, this property will be overridden by the settings there. The properties of the included object are indicated as options.colorScale.propertyName in this documentation.
options.colorScale.inverted boolean options.type property=Heatmap, SingleValue, or List If true, the colors are applied to the specified ranges in reverse order from the default application. For heatmap charts using options.colorBy set to Range, this means darker tones indicate lower values. For other chart types, it means that red represents lower values and green higher values in the default color scheme (other color schemes may be applied for users who select a color blind mode).
options.colorScale.thresholds list of floats options.type property=Heatmap, SingleValue, or List Indicates the border values for color ranges in the chart. Values should be specified from lowest to highest and only the first six values have meaning (additional elements are ignored). Values outside of the range will not be colored; in general the first value in the array should map to the lowest value expected for the plotted data and the last (meaningful) value in the array should correspond to the highest value expected for the plotted data.
options.colorScale2 list of objects options.type property=SingleValue, List, or Heatmap Each element of the array contains the information about a single color range including both the color to display for that range and the borders of the range. Collectively the set of elements specify the entire range displayed in the secondary visualization or heatmap chart. The elements do not need to be specified in any order; they will automatically be ordered by value in the display and the lowest value specified in the set of elements will automatically become the left border of any secondary visualization and the highest value specified in the set of elements will automatically become the right border of any secondary visualization. The properties of the included object are indicated as options.colorScale2[x].propertyName in this documentation.
options.colorScale2[x].gt float options.type property=List, SingleValue, or Heatmap Indicates the lower threshold non-inclusive value for this range.
options.colorScale2[x].gte float options.type property=List, SingleValue, or Heatmap Indicates the lower threshold inclusive value for this range.
options.colorScale2[x].lt float options.type property=List, SingleValue, or Heatmap Indicates the upper threshold non-inclusive value for this range.
options.colorScale2[x].lte float options.type property=List, SingleValue, or Heatmap Indicates the upper threshold inclusive value for this range.
options.colorScale2[x].paletteIndex integer
  • options.type property=List, SingleValue, or Heatmap
  • Minimum value = 0
  • Maximum value = 20.
Indicates the index number of color to use for values in the specified range. The list of 21 supported colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users, depending on the selected settings for color blindness. For sample swatches of the colors and the mappings used for color-blind users, see the color palette documentation at the bottom of the Charts Overview.
options.defaultPlotType enumerated string options.type property=TimeSeriesChart Indicates which of the supported plot types should be used for this chart. LineChart displays the data in a plot with datapoints connected by a series of straight lines. AreaChart displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in. Column charts list the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar.
options.groupBy list of strings options.type property=Heatmap Indicates one or more properties to group together in the histogram. The value of each element should map to a valid key name specified in the customProperties property or to a valid custom property supplied by default. The first element is a top level grouping, the second element indicates a grouping inside each of the top level groups. Subsequent elements are ignored. For example, a heatmap grouping CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping is shown in the Charts Overview.
options.histogramChartOptions object options.type property=TimeSeriesChart, options.defaultPlotType property=Histogram The histogram chart options applied to this chart. The properties of the included options object are indicated as options.histogramChartOptions.propertyName in this documentation.
options.histogramChartOptions.colorThemeIndex integer options.type property=TimeSeriesChart, options.defaultPlotType property=Histogram Indicates the index number of the color to use for the theme of this chart when viewed as a histogram. The chart will use variations of this color, with greater opacity indicating greater values. The list of 21 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10:#876ff3
  • 11: #a747ff
  • 12: ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e
options.includeZero boolean options.type property=TimeSeriesChart If true, 0 will always be included when dynamically calculating Y-axis ranges. This is a chart-wide setting applied to all axes in use. However, if options[x].axes.min or options[x].axes.max settings exclude 0 from the displayed range on a particular axis, 0 will not be displayed on that axis even if options.includeZero is set to true.
options.legendOptions object options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included object are indicated as options.legendOptions.propertyName in this documentation.
options.legendOptions.fields list of objects options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included objects are indicated as options.legendOptions.fields[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the fields array.
options.legendOptions.fields[x].enabled boolean options.type property=TimeSeriesChart or List Indicates whether the associated property is shown (true) or hidden (false) in the data table.
options.legendOptions.fields[x].property string options.type property=TimeSeriesChart or List The key name of a custom property specified for this chart (or supplied by default by SignalFx) to hide or show in the data table.
options.lineChartOptions object options.type property=TimeSeriesChart, options.defaultPlotType=LineChartTimeSeriesChart Sets options specific to a line chart. The properties of the included object are indicated as options.lineChartOptions.propertyName in this documentation.
options.lineChartOptions.showDataMarkers boolean options.type property=TimeSeriesChart, options.defaultPlotType=LineChart Indicates whether the actual data points are indicated by filled circles on the chart or if the plot is shown as a smooth line with no such indicators.
options.markdown string options.type property=Text The content of a text chart as specified using GitHub-flavored Markdown; any Markdown or HTML supported within a *.md file in GitHub is supported in this value.
options.maximumPrecision integer options.type property=List or SingleValue Indicates the number of significant digits included for values plotted on the chart but only applies to fractional portions of the number; all integer digits are included regardless of the desired precision. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 0.001 and 0.01, significant information will be lost unless the precision is set to at least 4. If no value is supplied, the chart visualization will adjust the precision to fit in the available space.
options.onChartLegendOptions object options.type property=TimeSeriesChart Determines whether a legend is shown and, if so, which dimension is shown on the legend. The properties of the included object are indicated as options.onChartLegendOptions.propertyName in this documentation.
options.onChartLegendOptions.dimensionInLegend string options.type property=TimeSeriesChart Determines which dimension is shown in the legend. For meaningful values, ensure the dimension sent exists and has different values for each plot in the chart.
options.onChartLegendOptions.showLegend boolean options.type property=TimeSeriesChart If true show a legend at the bottom of the chart. The legend lists the each value of the dimension specified in the options.onChartLegendsOptions.dimensionInLegend property next to the color associated with that data point in the chart.
options.programOptions object options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options applied to the chart. The properties of the included object are indicated as options.programOptions.propertyName in this documentation.
options.programOptions.disableSampling boolean options.type property=TimeSeriesChart, List, SingleValue, or Heatmap If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
options.programOptions.maxDelay integer options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the chart. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.programOptions.minimumResolution integer options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The minimum resolution to use for computing the underlying program, specified in milliseconds. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.publishLabelOptions list of objects options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options for the plot related to a specific SignalFlow statement applied to the chart. The order of elements in the list is retained as sent but is not significant; label values are used to map options with specific publish() statements in the related SignalFlow. Heatmaps do not support full publishLabelOptions objects; the Constraints column lists the supported chart types for each property. The properties of the included objects are indicated as options.publishLabelOptions[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the publishLabelOptions array.
options.publishLabelOptions[x].displayName string options.type property=TimeSeriesChart, List, or SingleValue Indicates an alternate value for the Plot Name column of the Data Table associated with the chart.
options.publishLabelOptions[x].label string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates the value of the string inside the publish function of the SignalFlow statement being configured by this element.
options.publishLabelOptions[x].paletteIndex integer
  • options.type property=TimeSeriesChart, List, or SingleValue
  • Minimum value = 0
  • Maximum value =15
Indicates the index number of color to use for all plots related to this SignalFlow statement. The list of 16 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f


Different colors may be presented to users, depending on the selected settings for color blindness. For sample swatches of the colors and the mappings used for color-blind users, see the first 16 colors in the color palette documentation at the bottom of the Charts Overview
options.publishLabelOptions[x].plotType enumerated string options.type property=TimeSeriesChart, List, or SingleValue Overrides the value of options.defaultPlotType for the output of this SignalFlow statement.
options.publishLabelOptions[x].valuePrefix string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to prepend to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview. This setting will be overridden if options.publishLabelOptions[x].valueUnit is set on the same plot.
options.publishLabelOptions[x].valueSuffix string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to append to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview. This setting will be overridden if options.publishLabelOptions[x].valueUnit is set on the same plot.
options.publishLabelOptions[x].valueUnit enumerated string
  • Supported values are: Bit, Kilobit, Megabit, Gigabit, Terabit, Petabit, Exabit, Zettabit, Yottabit, Byte, Kibibyte, Mebibyte, Gigibyte, Tebibyte, Pebibyte, Exbibyte, Zebibyte, Yobibyte, Nanosecond, Microsecond, Millisecond, Second, Minute, Hour, Day, and Week
  • Available if the options.type property is set to anything but Text
Indicates display units for the values in the chart. The plot values will be presented in a readable way based on the assumption that the raw values are denominated in the selected unit. For instance, a value of 1000 on a plot with options.publishLabelOptions[x].valueUnit set to bits will be presented as 1 Kilobit, and a value of 1024 on a plot with Bytes selected will be presented as 1 Kebibyte. Each unit will be scaled up and down in this way within its own kind (Bits, Bytes, and Units of Time; see Charts Overview for a full specification).

Plots with options.publishLabelOptions[x].valueUnit are scaled and labelled with the unit's abbreviation when presented in chart tooltips, axes, and data tables. Where options.publishLabelOptions[x].valueUnit affects presentation it overrides options.publishLabelOptions[x].valuePrefix, options.publishLabelOptions[x].valueSuffix, and options.unitPrefix.
options.publishLabelOptions[x].yAxis integer options.type property=TimeSeriesChart, List, or SingleValue Indicates whether the Y-axis for the plot associated with this SignalFlow statement is on the left side (0) or the right side of the chart. If not specified, the left side Y-axis is used.
options.refreshInterval integer options.type property=List or SingleValue Indicates how often the data should be refreshed in the chart in milliseconds. The default is usually 10000 (10 seconds) but may be 3600000 (1 hour) instead if the resolution of the data cannot be detected.
options.secondaryVisualization enumerated string options.type property=List or SingleValue Indicates the secondary visualization to display the value of the metric. Examples of the visualizations are shown in Charts Overview.
options.showEventLines boolean options.type property=TimeSeriesChart If true, a vertical line is displayed on the chart when an event is triggered.
options.showSparkLine boolean options.type property=SingleValue If true, a graphical representation of recent trends without axes or annotations is shown underneath the value in the chart. For example, the following chart shows a sparkline: sparkline -auto This property will be overridden if options.secondaryVisualization is set.
options.sortBy string options.type property= List Indicates how to sort the individual entries of a list chart. The first character of the value must be either a minus sign ("-") indicating that the data is displayed in descending order or a plus sign ("+") indicating that the data is displayed in ascending order. The rest of the value indicates the sort criteria, either a keyword (representing the value of the data point, the name of the metric being displayed, or the publish label of the SignalFlow statement generating the data) or the name of a dimension available to the chart. The default sort is on the publish label in ascending order which corresponds to Auto in the web application; values that do not map to a keyword or a valid dimension will use the default sort. Nulls are placed at the start of the list when using ascending order and at the end of the list when using descending order. For information about the available keywords and how the sort options map between the API and the web application, see the Charts Overview.
options.sortDirection enumerated string options.type property=Heatmap Indicates whether to put lower or higher values first when sorting the values on a heatmap chart.
options.sortProperty string options.type property=Heatmap The custom property to use as the sorting criteria for the heatmap chart. The value should map to a valid key name specified in the customProperties property or to a valid custom property available by default. If no value is specified, the values are displayed without an obvious order.
options.stacked boolean options.type property=TimeSeriesChart, options.defaultPlotType=AreaChart or ColumnChart If true, the plots in the chart are stacked on top of each other and their values added together to create the values indicated by the axis labels. Individual values can still be viewed when highlighting specific points in time on the chart within the visible colored area representing the desired plot or by viewing the data table.
options.includeZero boolean options.type property=TimeSeriesChart If true, 0 will always be included when dynamically calculating Y-axis ranges. This is a chart-wide setting applied to all axes in use. However, if options[x].axes.min or options[x].axes.max settings exclude 0 from the displayed range on a particular axis, 0 will not be displayed on that axis even if options.includeZero is set to true.
options.time object options.type property=TimeSeriesChart Options for the time displayed on the chart. The properties of the included object are indicated as options.time.propertyName in this documentation.
options.time.end integer options.type property =TimeSeriesChart, options.time.type property=absolute The timestamp of the last time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.range integer options.type property =TimeSeriesChart, options.time.type property=relative The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here, GCP metrics listed here, and Azure metrics listed here.
options.time.start integer options.type property =TimeSeriesChart, options.time.type property=absolute The timestamp of the first time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.type enumerated string options.type property =TimeSeriesChart Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.
options.timestampHidden boolean options.type property=Heatmap If true, the timestamp is shown below the displayed values on the chart.
options.type enumerated string All The visualization mechanism used in the chart. The Heatmap option displays each value in an ordered set of boxes colored to indicate the health of the value. The List option displays each value in its own row with an unlabeled plot showing recent trends. The SingleValue option displays the current value of one data point colored to indicate the health of the value. The Text option displays constant, pre-defined Markdown. The TimeSeriesChart option displays the value of multiple data points together in one of four visualization modes, retaining historical data. See the Charts Overview for a brief discussion and screenshot of each type of chart or see Choosing a Chart Type for more information about using each option within the web application.
options.unitPrefix enumerated string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates whether units should be displayed and labeled using metric units where k stands for kilo- meaning 1000 of the the item in question or in a binary format where K stands for Kibi- meaning 1024 of the item in question. This setting may be overridden by options.publishLabelOptions[x].valueUnit settings on plots.
packageSpecifications string All Indicates one or more SignalFlow packages to import for use in the programText value.
programText string option.type property=Heatmap, List, SingleValue, or TimeSeriesChart A SignalFlow program used to populate the chart. If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n").
tags list of strings All A set of keywords used to filter charts or to search for all charts with some common element. Among other things, tags may be used to indicate the state of a chart or its data source (for example, a prod tag could indicate all charts displaying data from a production environment).

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Get Charts

The Get Charts API retrieves one or more v2 charts identified by optional search criteria.

 

The Get Charts API retrieves one or more v2 charts identified by optional search criteria. If no search criteria is specified, the first 50 charts visible to the user are returned. Paging of results is controlled using the offset and limit path parameters to specify the starting point of the results and the maximum number of results to return respectively. See the path parameter documentation below for more information on search criteria and paging.

For more information on charts including the types of charts supported and the different ways they can be visualized, see Charts Overview.

Syntax

GET https://api.signalfx.com/v2/chart[?[name=_chartName_][&][_tagSpecification_][&][offset=_startValue_][&][limit=_requestedNumberReturned_]]

where tagSpecification has the following syntax:

tags=tag1[&tags=tag2][&....tags=tagK]

NOTE: [content] indicates that content is an optional block that may or may not be needed depending on the desired query

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Get Charts call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Query Parameters

The Get Charts API call supports the following query parameters as indicated in the syntax line above:

Parameter Value Type Constraints Description
limit integer
  • Default=50
  • minimum value=1
The maximum number of objects to return in the response. Unrecognized values are ignored and result in the default value of 50 being used.
name string None a search string acting as a full or partial match to the value in the name property of chart objects. Any UTF-8 characters may be included in the search string and strings will match against any portion of the name property; for example, name=per will match all of the following names:
  • ..... dropped per day...
  • ...95th percentile
  • personal disk usage...
Empty strings will be ignored and return objects with any name value that match the rest of the query.
offset integer
  • Default=0
  • minimum value=0
The starting index value of the returned objects; this assumes all of the possible returns are put in a 0-based indexed list in the appropriate sort order and identified by their order in the list. If the offset value is greater than the number of possible results, no objects are returned in the response.
tags string
  • Parameter is repeatable
a search string acting as a full or partial match to an element in the tags array property of chart objects. Any UTF-8 characters may be included in the search strings and strings will match against any portion of the value of any element in the tags array; for example tags=dat will match all of the following tags:
  • data
  • date
  • datetime
  • metadata

Payload

The Get Charts API call does not support a request payload.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Get Charts call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Get Charts call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Get Charts call:

Property Type Contexts Returned Description
count integer All Indicates the number of objects that match the search query. It does not provide any information on the number of objects actually returned in the request; if paging is employed the number of objects should be equivalent to either the value of the limit path parameter or the remainder of the objects after the supplied value of the offset parameter.
results list of objects List of chart objects matching the request criteria. The properties of the included results objects are indicated as results[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the results array.
results[x].created integer All The time the member object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
results[x].creator string All The user ID of the administrator requesting that the invitation be sent. This value is always set by the system. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
results[x].customProperties object All A set of user-defined key-value pairs containing metadata about the chart that may change over time. Custom properties may be used to store metadata that may not be known at chart creation or that may be expected to change in the future. These properties can be used to filter charts or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
results[x].description string All The description of the chart. This value appears underneath the chart name in the SignalFx web application.
results[x].id string All The ID assigned to the chart object. This ID is unique and always set by the system.
results[x].lastUpdated integer All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application
results[x].lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
results[x].name string All The name of the chart. The name is used to identify the chart in the SignalFx web application and should be descriptive The name may be truncated in the UI if it does not fit in the allocated space so put important information first.
results[x].options object All The options applied to this chart. The options include information about the type of chart and are different for different types of charts. The properties of the included object are indicated as results[x].options.propertyName in this documentation. By default all listed properties of the options object are available in any options object. The constraints column will note if a listed property is only available within certain contexts (such as for one or more chart types).
results[x].options.areaChartOptions object results[x].options.type property=TimeSeriesChart, results[x].options.defaultPlotType=AreaChart The area chart options applied to this chart. The properties of the included options object are indicated as results[x].options.areaChartOptions.propertyName in this documentation.
results[x].options.areaChartOptions.showDataMarkers boolean results[x].options.type property=TimeSeriesChart, results[x].options.defaultPlotType=AreaChart When true, markers will be drawn for each datapoint within the visualization.
results[x].options.axes list of objects results[x].options.type property=TimeSeriesChart Y axis configuration for the left and right side of a chart. The first element of the array corresponds to the left side of the chart and the second element of the array corresponds to the right side of the array. Subsequent elements are accepted but ignored. The properties of the included objects are indicated as results[x].options.axes[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the axes array.
results[x].options.axes[y].highWatermark float results[x].options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the top of an area of interest to highlight.
results[x].options.axes[y].highWatermarkLabel string results[x].options.type property=TimeSeriesChart Indicates a label for the high watermark line on the chart. If the element corresponds to the left axis (element 0), the label is placed near the line starting at the left edge of the chart. If the element corresponds to the right axis (element 1), the label is placed near the line ending at the right edge of the chart.
results[x].options.axes[y].label string results[x].options.type property=TimeSeriesChart A description for the Y axis of the chart, displayed to the left of the axis value labels for left side axes and to the right of the axis value labels for right side axes.
results[x].options.axes[y].lowWatermark float results[x].options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the bottom of an area of interest to highlight.
results[x].options.axes[y].lowWatermarkLabel string results[x].options.type property=TimeSeriesChart Indicates a label for the low watermark line on the chart. If the element corresponds to the left axis (element 0), the label is placed near the line starting at the left edge of the chart. If the element corresponds to the right axis (element 1), the label is placed near the line ending at the right edge of the chart.
results[x].options.axes[y].max float results[x].options.type property = TimeSeriesChart Indicates the largest value to display on the chart. Overrides resuts[x].options.includeZero if the properties are set to incompatible values.
results[x].options.axes[y].min float results[x].options.type property=TimeSeriesChart Indicates the smallest value to display on the chart. Overrides results[x].options.includeZero if the properties are set to incompatible values.
results[x].options.axisPrecision integer results[x].options.type property=TimeSeriesChart Indicates the number of significant digits included for values plotted on the chart. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 100000 and 100010, using a precision of 3 would result in a value of 100000 for all data points. Instead, set the precision to 6 to capture differences in integer values; higher precision values would also capture fractional variations.
results[x].options.colorBy enumerated string results[x].options.type property=Heatmap, List, SingleValue, or TimeSeriesChart Indicates the mechanism for applying the color scheme to the values in the chart. If color is desired in a text chart it should be applied using HTML within the markdown property.
results[x].options.colorRange object results[x].options.type property=Heatmap The range of values to be colored in this chart and the color to span across that range. The number of variations of that color within the specified range is controlled by the colorScale property. The properties of the included object are indicated as results[x].options.colorRange.propertyName in this documentation.
results[x].options.colorRange.color string results[x].options.type property=Heatmap The hex value of the color used to represent values in a heatmap chart. Different tones of this color are then applied as indicated by the values of the colorScale property. The color specified is the lowest value of the color gradient in the chart; the number of variations of that color within the specified range is controlled by the colorScale property. We recommend using one of the twenty one colors in the official color palette for best results.
results[x].options.colorRange.max string results[x].options.type property=Heatmap The largest value assigned a color in the heatmap. In general this should correspond to the highest expected value of the input criteria.
results[x].options.colorRange.min string results[x].options.type property=Heatmap The smallest value assigned a color in the heatmap. In general this should correspond to the smallest expected value of the input criteria.
results[x].options.colorScale object results[x].options.type property=Heatmap or SingleValue Indicates the borders of color ranges in charts and whether the range should be applied in the default order or inverted. If results[x].options.colorScale2 is specified, this property will be overridden by the settings there. The properties of the included object are indicated as results[x].options.colorScale.propertyName in this documentation.
results[x].options.colorScale.inverted boolean results[x].options.type property=Heatmap or SingleValue If true, the colors are applied to the specified ranges in reverse order from the default application. For heatmap charts using results[x].options.colorBy set to Range, this means darker tones indicate lower values. For other chart types, it means that red represents lower values and green higher values in the default color scheme (other color schemes may be applied for users who select a color blind mode).
results[x].options.colorScale.thresholds list of floats results[x].options.type property=Heatmap or SingleValue Indicates the border values for color ranges in the chart. Values should be specified from lowest to highest and only the first six values have meaning (additional elements are ignored). Values outside of the range will not be colored; in general the first value in the array should map to the lowest value expected for the plotted data and the last (meaningful) value in the array should correspond to the highest value expected for the plotted data.
results[x].options.colorScale2 list of objects results[x].options.type property=SingleValue, List, or Heatmap Each element of the array contains the information about a single color range including both the color to display for that range and the borders of the range. Collectively the set of elements specify the entire range displayed in the secondary visualization or heatmap chart. The elements do not need to be specified in any order; they will automatically be ordered by value in the display and the lowest value specified in the set of elements will automatically become the left border of any secondary visualization and the highest value specified in the set of elements will automatically become the right border of any secondary visualization. The properties of the included object are indicated as results[x].options.colorScale2[y].propertyName in this documentation.
results[x].options.colorScale2[y].gt float results[x].options.type property=List, SingleValue, or Heatmap Indicates the lower threshold non-inclusive value for this range.
results[x].options.colorScale2[y].gte float results[x].options.type property=List, SingleValue, or Heatmap Indicates the lower threshold inclusive value for this range.
results[x].options.colorScale2[y].lt float results[x].options.type property=List, SingleValue, or Heatmap Indicates the upper threshold non-inclusive value for this range.
results[x].options.colorScale2[y].lte float results[x].options.type property=List, SingleValue, or Heatmap Indicates the upper threshold inclusive value for this range.
results[x].options.colorScale2[y].paletteIndex integer
  • results[x].options.type property=List, SingleValue, or Heatmap
  • Minimum value = 0
  • Maximum value = 20.
Indicates the index number of color to use for values in the specified range. The list of 21 supported colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users, depending on the selected settings for color blindness. For sample swatches of the colors and the mappings used for color-blind users, see the color palette documentation at the bottom of the Charts Overview.
results[x].options.defaultPlotType enumerated string results[x].options.type property=TimeSeriesChart Indicates which of the supported plot types should be used for this chart. LineChart displays the data in a plot with datapoints connected by a series of straight lines. AreaChart displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in. Column charts list the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar.
results[x].options.groupBy list of strings results[x].options.type property=Heatmap Indicates one or more properties to group together in the histogram. The value of each element should map to a valid key name specified in the results[x].customProperties property or to a valid custom property supplied by default. The first element is a top level grouping, the second element indicates a grouping inside each of the top level groups. Subsequent elements are ignored. For example, a heatmap grouping CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping is shown in the Charts Overview.
results[x].options.histogramChartOptions object results[x].options.type property=TimeSeriesChart, results[x].options.defaultPlotType property=Histogram The histogram chart options applied to this chart. The properties of the included options object are indicated as results[x].options.histogramChartOptions.propertyName in this documentation.
results[x].options.histogramChartOptions.colorThemeIndex integer results[x].options.type property=TimeSeriesChart, results[x].options.defaultPlotType property=Histogram Indicates the index number of the color to use for the theme of this chart when viewed as a histogram. The chart will use variations of this color, with greater opacity indicating greater values. The list of 21 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10:#876ff3
  • 11: #a747ff
  • 12: ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e
results[x].options.includeZero boolean results[x].options.type property=TimeSeriesChart If true, 0 will always be included when dynamically calculating Y-axis ranges. This is a chart-wide setting applied to all axes in use. However, if results[x].options[y].axes.min or results[x].options[y].axes.max settings exclude 0 from the displayed range on a particular axis, 0 will not be displayed on that axis even if results[x].options.includeZero is set to true.
results[x].options.legendOptions object results[x].options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included object are indicated as results[x].options.legendOptions.propertyName in this documentation.
results[x].options.legendOptions.fields list of objects results[x].options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included objects are indicated as results[x].options.legendOptions.fields[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the fields array.
results[x].options.legendOptions.fields[y].enabled boolean results[x].options.type property=TimeSeriesChart or List Indicates whether the associated property is shown (true) or hidden (false) in the data table.
results[x].options.legendOptions.fields[y].property string results[x].options.type property=TimeSeriesChart or List The key name of a custom property specified for this chart (or supplied by default by SignalFx) to hide or show in the data table.
results[x].options.lineChartOptions object results[x].options.type property=TimeSeriesChart, options.defaultPlotType=LineChartTimeSeriesChart Sets options specific to a line chart. The properties of the included object are indicated as results[x].options.lineChartOptions.propertyName in this documentation.
results[x].options.lineChartOptions.showDataMarkers boolean results[x].options.type property=TimeSeriesChart, results[x].options.defaultPlotType property =LineChart Indicates whether the actual data points are indicated by filled circles on the chart or if the plot is shown as a smooth line with no such indicators.
results[x].options.markdown string results[x].options.type property=Text The content of a text chart as specified using GitHub-flavored Markdown; any Markdown or HTML supported within a *.md file in GitHub is supported in this value.
results[x].options.maximumPrecision integer results[x].options.type property=List or SingleValue Indicates the number of significant digits included for values plotted on the chart but only applies to fractional portions of the number; all integer digits are included regardless of the desired precision. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 0.001 and 0.01, significant information will be lost unless the precision is set to at least 4. If no value is supplied, the chart visualization will adjust the precision to fit in the available space.
results[x].options.onChartLegendOptions object results[x].options.type property=TimeSeriesChart Determines whether a legend is shown and, if so, which dimension is shown on the legend. The properties of the included object are indicated as results[x].options.onChartLegendOptions.propertyName in this documentation.
results[x].options.onChartLegendOptions.dimensionInLegend string results[x].options.type property=TimeSeriesChart Determines which dimension is shown in the legend. For meaningful values, ensure the dimension sent exists and has different values for each plot in the chart.
results[x].options.onChartLegendOptions.showLegend boolean results[x].options.type property=TimeSeriesChart If true show a legend at the bottom of the chart. The legend lists the each value of the dimension specified in the results[x].options.onChartLegendsOptions.dimensionInLegend property next to the color associated with that data point in the chart.
results[x].options.programOptions object results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options applied to the chart. The properties of the included object are indicated as results[x].options.programOptions.propertyName in this documentation.
results[x].options.programOptions.disableSampling boolean options.type property=TimeSeriesChart, List, SingleValue, or Heatmap If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
results[x].options.programOptions.maxDelay integer results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the chart. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
results[x].options.programOptions.minimumResolution integer results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The minimum resolution to use for computing the underlying program, specified in milliseconds. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
results[x].options.publishLabelOptions list of objects results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options for the plot related to a specific SignalFlow statement applied to the chart. The order of elements in the list is retained as sent but is not significant; label values are used to map options with specific publish() statements in the related SignalFlow. Heatmaps do not support full publishLabelOptions objects; the Constraints column lists the supported chart types for each property. The properties of the included objects are indicated as results[x].options.publishLabelOptions[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the publishLabelOptions array.
results[x].options.publishLabelOptions[y].displayName string results[x].options.type property=TimeSeriesChart, List, or SingleValue Indicates an alternate value for the Plot Name column of the Data Table associated with the chart.
results[x].options.publishLabelOptions[y].label string results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates the value of the string inside the publish function of the SignalFlow statement being configured by this element.
results[x].options.publishLabelOptions[y].paletteIndex integer
  • results[x].options.type property=TimeSeriesChart, List, or SingleValue
  • Minimum value = 0
  • Maximum value = 15.
Indicates the index number of color to use for all plots related to this SignalFlow statement.The list of 16 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f

Different colors may be presented to users, depending on the selected settings for color blindness. For sample swatches of the colors and the mappings used for color-blind users, see the first 16 colors in the color palette documentation at the bottom of the Charts Overview.
results[x].options.publishLabelOptions[y].plotType enumerated string results[x].options.type property=TimeSeriesChart, List, or SingleValue Overrides the value of results[x].options.defaultPlotType for the output of this SignalFlow statement.
results[x].options.publishLabelOptions[y].valuePrefix string results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to prepend to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview. This setting will be overridden if results[x].options.publishLabelOptions[y].valueUnit is set on the same plot.
results[x].options.publishLabelOptions[y].valueSuffix string results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to append to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview. This setting will be overridden if results[x].options.publishLabelOptions[y].valueUnit is set on the same plot.
results[x].options.publishLabelOptions[x].valueUnit enumerated string
  • Supported values are: Bit, Kilobit, Megabit, Gigabit, Terabit, Petabit, Exabit, Zettabit, Yottabit, Byte, Kibibyte, Mebibyte, Gigibyte, Tebibyte, Pebibyte, Exbibyte, Zebibyte, Yobibyte, Nanosecond, Microsecond, Millisecond, Second, Minute, Hour, Day, and Week
  • Available if the options.type property is set to anything but Text
Indicates display units for the values in the chart. The plot values will be presented in a readable way based on the assumption that the raw values are denominated in the selected unit. For instance, a value of 1000 on a plot with results[x].options.publishLabelOptions[y].valueUnit set to bits will be presented as 1 Kilobit, and a value of 1024 on a plot with Bytes selected will be presented as 1 Kebibyte. Each unit will be scaled up and down in this way within its own kind (Bits, Bytes, and Units of Time; see Charts Overview for a full specification).

Plots with results[x].options.publishLabelOptions[y].valueUnit are scaled and labelled with the unit's abbreviation when presented in chart tooltips, axes, and data tables. Where results[x].options.publishLabelOptions[y].valueUnit affects presentation it overrides results[x].options.publishLabelOptions[y].valuePrefix, results[x].options.publishLabelOptions[y].valueSuffix, and unitPrefix.
results[x].options.publishLabelOptions[y].yAxis integer results[x].options.type property=TimeSeriesChart, List, or SingleValue Indicates whether the Y-axis for the plot associated with this SignalFlow statement is on the left side (0) or the right side of the chart. If not specified, the left side Y-axis is used.
results[x].options.refreshInterval integer results[x].options.type property=List or SingleValue Indicates how often the data should be refreshed in the chart in milliseconds. The default is usually 10000 (10 seconds) but may be 3600000 (1 hour) instead if the resolution of the data cannot be detected.
options.secondaryVisualization enumerated string results[x].options.type property=List or SingleValue Indicates the secondary visualization to display the value of the metric. Examples of the visualizations are shown in Charts Overview.
results[x].options.showEventLines boolean results[x].options.type property=TimeSeriesChart If true, a vertical line is displayed on the chart when an event is triggered.
results[x].options.showSparkLine boolean results[x].options.type property=SingleValue If true, a graphical representation of recent trends without axes or annotations is shown underneath the value in the chart. For example, the following chart shows a sparkline: sparkline -auto This property will be overridden if results[x].options.secondaryVisualization is set.
results[x].options.sortBy string results[x].options.type property=List Indicates how to sort the individual entries of a list chart. The first character of the value must be either a minus sign ("-") indicating that the data is displayed in descending order or a plus sign ("+") indicating that the data is displayed in ascending order. The rest of the value indicates the sort criteria, either a keyword (representing the value of the data point, the name of the metric being displayed, or the publish label of the SignalFlow statement generating the data) or the name of a dimension available to the chart. The default sort is on the publish label in ascending order which corresponds to Auto in the web application; values that do not map to a keyword or a valid dimension will use the default sort. Nulls are placed at the start of the list when using ascending order and at the end of the list when using descending order. For information about the available keywords and how the sort options map between the API and the web application, see the Charts Overview.
results[x].options.sortDirection enumerated string results[x].options.type property=Heatmap Indicates whether to put lower or higher values first when sorting the values on a heatmap chart.
results[x].options.sortProperty string results[x].options.type property=Heatmap The custom property to use as the sorting criteria for the heatmap chart. The value should map to a valid key name specified in the customProperties property or to a valid custom property available by default. If no value is specified, the values are displayed without an obvious order.
results[x].options.stacked boolean results[x].options.type property=TimeSeriesChart, options.defaultPlotType=AreaChart or ColumnChart If true, the plots in the chart are stacked on top of each other and their values added together to create the values indicated by the axis labels. Individual values can still be viewed when highlighting specific points in time on the chart within the visible colored area representing the desired plot or by viewing the data table.
results[x].options.includeZero boolean results[x].options.type property=TimeSeriesChart If true, 0 will always be included when dynamically calculating Y-axis ranges. This is a chart-wide setting applied to all axes in use. However, if options[x].axes.min or options[x].axes.max settings exclude 0 from the displayed range on a particular axis, 0 will not be displayed on that axis even if options.includeZero is set to true.
results[x].options.time object results[x].options.type property=TimeSeriesChart Options for the time displayed on the chart. The properties of the included object are indicated as results[x].options.time.propertyName in this documentation.
results[x].options.time.end integer results[x].options.type property =TimeSeriesChart, results[x].options.time.type property=absolute The timestamp of the last time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
results[x].options.time.range integer results[x].options.type property =TimeSeriesChart, results[x].options.time.type property=relative The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here, GCP metrics listed here, and Azure metrics listed here.
results[x].options.time.start integer results[x].options.type property =TimeSeriesChart, results[x].options.time.type property=absolute The timestamp of the first time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
results[x].options.time.type enumerated string results[x].options.type property =TimeSeriesChart Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.
results[x].options.timestampHidden boolean results[x].options.type property=Heatmap If true, the timestamp is shown below the displayed values on the chart.
results[x].options.type enumerated string All The visualization mechanism used in the chart. The Heatmap option displays each value in an ordered set of boxes colored to indicate the health of the value. The List option displays each value in its own row with an unlabeled plot showing recent trends. The SingleValue option displays the current value of one data point colored to indicate the health of the value. The Text option displays constant, pre-defined Markdown. The TimeSeriesChart option displays the value of multiple data points together in one of four visualization modes, retaining historical data. See the Charts Overview for a brief discussion and screenshot of each type of chart or see Choosing a Chart Type for more information about using each option within the web application.
results[x].options.unitPrefix enumerated string results[x].options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates whether units should be displayed and labeled using metric units where k stands for kilo- meaning 1000 of the the item in question or in a binary format where K stands for Kibi- meaning 1024 of the item in question.
results[x].packageSpecifications string All Indicates one or more SignalFlow packages to import for use in the programText value.
results[x].programText string results[x].option.type property=Heatmap, List, SingleValue, or TimeSeriesChart A SignalFlow program used to populate the chart. If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n").
results[x].tags list of strings All A set of keywords used to filter charts or to search for all charts with some common element. Among other things, tags may be used to indicate the state of a chart or its data source (for example, a prod tag could indicate all charts displaying data from a production environment).

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Get Chart

The Get Chart API retrieves a single v2 chart identified by its id value.

 

The Get Chart API retrieves a single v2 chart identified by its id value. This API call only supports v2 chart objects; an error will be thrown if you try to retrieve a v1 chart object.

For more information on charts including the types of charts supported and the different ways they can be visualized, see Charts Overview.

Syntax

GET https://api.signalfx.com/v2/chart/_id_

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Get Chart call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Path Parameters

The Get Chart API call supports one path parameter as indicated in the syntax line above:

Path parameter Type Description
id string The system assigned identifier of an existing chart object.

Payload

The Get Chart API call does not support a request payload.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Get Chart call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Get Chart call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Get Chart call:

Property Type Contexts Returned Description
created integer All The time the member object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
creator string All The user ID of the administrator requesting that the invitation be sent. This value is always set by the system. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
customProperties object All A set of user-defined key-value pairs containing metadata about the chart that may change over time. Custom properties may be used to store metadata that may not be known at chart creation or that may be expected to change in the future. These properties can be used to filter charts or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string All The description of the chart. This value appears underneath the chart name in the SignalFx web application.
id string All The ID assigned to the chart object. This ID is unique and always set by the system.
lastUpdated integer All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application
lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
name string All The name of the chart. The name is used to identify the chart in the SignalFx web application and should be descriptive The name may be truncated in the UI if it does not fit in the allocated space so put important information first.
options object All The options applied to this chart. The options include information about the type of chart and are different for different types of charts. The properties of the included object are indicated as options.propertyName in this documentation. By default all listed properties of the options object are available in any options object. The constraints column will note if a listed property is only available within certain contexts (such as for one or more chart types).
options.areaChartOptions object options.type property=TimeSeriesChart, results[x].options.defaultPlotType=AreaChart The area chart options applied to this chart. The properties of the included options object are indicated as options.areaChartOptions.propertyName in this documentation.
options.areaChartOptions.showDataMarkers boolean options.type property=TimeSeriesChart, results[x].options.defaultPlotType=AreaChart When true, markers will be drawn for each datapoint within the visualization.
options.axes list of objects options.type property=TimeSeriesChart Y axis configuration for the left and right side of a chart. The first element of the array corresponds to the left side of the chart and the second element of the array corresponds to the right side of the array. Subsequent elements are accepted but ignored. The properties of the included objects are indicated as options.axes[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the axes array.
options.axes[x].highWatermark float options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the top of an area of interest to highlight.
options.axes[x].highWatermarkLabel string options.type property=TimeSeriesChart Indicates a label for the high watermark line on the chart. If the element corresponds to the left axis (element 0), the label is placed near the line starting at the left edge of the chart. If the element corresponds to the right axis (element 1), the label is placed near the line ending at the right edge of the chart.
options.axes[x].label string options.type property=TimeSeriesChart A description for the Y axis of the chart, displayed to the left of the axis value labels for left side axes and to the right of the axis value labels for right side axes.
options.axes[x].lowWatermark float options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the bottom of an area of interest to highlight.
options.axes[x].lowWatermarkLabel string options.type property=TimeSeriesChart Indicates a label for the low watermark line on the chart. If the element corresponds to the left axis (element 0), the label is placed near the line starting at the left edge of the chart. If the element corresponds to the right axis (element 1), the label is placed near the line ending at the right edge of the chart.
options.axes[x].max float options.type property=TimeSeriesChart Indicates the largest value to display on the chart. Overrides options.includeZero if the properties are set to incompatible values.
options.axes[x].min float options.type property=TimeSeriesChart Indicates the smallest value to display on the chart. Overrides options.includeZero if the properties are set to incompatible values.
options.axisPrecision integer options.type property=TimeSeriesChart Indicates the number of significant digits included for values plotted on the chart. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 100000 and 100010, using a precision of 3 would result in a value of 100000 for all data points. Instead, set the precision to 6 to capture differences in integer values; higher precision values would also capture fractional variations.
options.colorBy enumerated string options.type property=Heatmap, List, SingleValue, or TimeSeriesChart Indicates the mechanism for applying the color scheme to the values in the chart. If color is desired in a text chart it should be applied using HTML within the markdown property.
options.colorRange object options.type property=Heatmap The range of values to be colored in this chart and the color to span across that range. The number of variations of that color within the specified range is controlled by the colorScale property. The properties of the included object are indicated as options.colorRange.propertyName in this documentation.
options.colorRange.color string options.type property=Heatmap The hex value of the color used to represent values in a heatmap chart. Different tones of this color are then applied as indicated by the values of the colorScale property. The color specified is the lowest value of the color gradient in the chart; the number of variations of that color within the specified range is controlled by the colorScale property. We recommend using one of the twenty one colors in the official color palette for best results.
options.colorRange.max string options.type property=Heatmap The largest value assigned a color in the heatmap. In general this should correspond to the highest expected value of the input criteria.
options.colorRange.min string options.type property=Heatmap The smallest value assigned a color in the heatmap. In general this should correspond to the smallest expected value of the input criteria.
options.colorScale object options.type property=Heatmap, SingleValue, or List Indicates the borders of color ranges in charts and whether the range should be applied in the default order or inverted. If options.colorScale2 is specified, this property will be overridden by the settings there. The properties of the included object are indicated as options.colorScale.propertyName in this documentation.
options.colorScale.inverted boolean options.type property=Heatmap, SingleValue, or List If true, the colors are applied to the specified ranges in reverse order from the default application. For heatmap charts using options.colorBy set to Range, this means darker tones indicate lower values. For other chart types, it means that red represents lower values and green higher values in the default color scheme (other color schemes may be applied for users who select a color blind mode).
options.colorScale.thresholds list of floats options.type property=Heatmap, SingleValue, or List Indicates the border values for color ranges in the chart. Values should be specified from lowest to highest and only the first six values have meaning (additional elements are ignored). Values outside of the range will not be colored; in general the first value in the array should map to the lowest value expected for the plotted data and the last (meaningful) value in the array should correspond to the highest value expected for the plotted data.
options.colorScale2 list of objects options.type property=SingleValue, List, or Heatmap Each element of the array contains the information about a single color range including both the color to display for that range and the borders of the range. Collectively the set of elements specify the entire range displayed in the secondary visualization or heatmap chart. The elements do not need to be specified in any order; they will automatically be ordered by value in the display and the lowest value specified in the set of elements will automatically become the left border of any secondary visualization and the highest value specified in the set of elements will automatically become the right border of any secondary visualization. The properties of the included object are indicated as options.colorScale2[x].propertyName in this documentation.
options.colorScale2[x].gt float options.type property=List, SingleValue, or Heatmap Indicates the lower threshold non-inclusive value for this range.
options.colorScale2[x].gte float options.type property=List, SingleValue, or Heatmap Indicates the lower threshold inclusive value for this range.
options.colorScale2[x].lt float options.type property=List, SingleValue, or Heatmap Indicates the upper threshold non-inculsive value for this range.
options.colorScale2[x].lte float options.type property=List, SingleValue, or Heatmap Indicates the upper threshold inclusive value for this range.
options.colorScale2[x].paletteIndex integer
  • options.type property=List, SingleValue, or Heatmap
  • Minimum value = 0
  • Maximum value = 20
Indicates the index number of color to use for values in the specified range. The list of 21 supported colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users, depending on the selected settings for color blindness. For sample swatches of the colors and the mappings used for color-blind users, see the color palette documentation at the bottom of the Charts Overview.
options.defaultPlotType enumerated string options.type property=TimeSeriesChart Indicates which of the supported plot types should be used for this chart. LineChart displays the data in a plot with datapoints connected by a series of straight lines. AreaChart displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in. Column charts list the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar.
options.groupBy list of strings options.type property=Heatmap Indicates one or more properties to group together in the histogram. The value of each element should map to a valid key name specified in the customProperties property or to a valid custom property supplied by default. The first element is a top level grouping, the second element indicates a grouping inside each of the top level groups. Subsequent elements are ignored. For example, a heatmap grouping CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping is shown in the Charts Overview.
options.histogramChartOptions object options.type property=TimeSeriesChart, options.defaultPlotType property=Histogram The histogram chart options applied to this chart. The properties of the included options object are indicated as options.histogramChartOptions.propertyName in this documentation.
options.histogramChartOptions.colorThemeIndex integer options.type property=TimeSeriesChart, options.defaultPlotType property=Histogram Indicates the index number of the color to use for the theme of this chart when viewed as a histogram. The chart will use variations of this color, with greater opacity indicating greater values. The list of 21 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10:#876ff3
  • 11: #a747ff
  • 12: ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e
options.includeZero boolean options.type property=TimeSeriesChart If true, 0 will always be included when dynamically calculating Y-axis ranges. This is a chart-wide setting applied to all axes in use. However, if options[x].axes.min or options[x].axes.max settings exclude 0 from the displayed range on a particular axis, 0 will not be displayed on that axis even if options.includeZero is set to true.
options.legendOptions object options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included object are indicated as options.legendOptions.propertyName in this documentation.
options.legendOptions.fields list of objects options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included objects are indicated as options.legendOptions.fields[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the fields array.
options.legendOptions.fields[x].enabled boolean options.type property=TimeSeriesChart or List Indicates whether the associated property is shown (true) or hidden (false) in the data table.
options.legendOptions.fields[x].property string options.type property=TimeSeriesChart or List The key name of a custom property specified for this chart (or supplied by default by SignalFx) to hide or show in the data table.
options.lineChartOptions object options.type property=TimeSeriesChart, options.defaultPlotType=LineChartTimeSeriesChart Sets options specific to a line chart. The properties of the included object are indicated as options.lineChartOptions.propertyName in this documentation.
options.lineChartOptions.showDataMarkers boolean options.type property=TimeSeriesChart, options.defaultPlotType=LineChart Indicates whether the actual data points are indicated by filled circles on the chart or if the plot is shown as a smooth line with no such indicators.
options.markdown string options.type property=Text The content of a text chart as specified using GitHub-flavored Markdown; any Markdown or HTML supported within a *.md file in GitHub is supported in this value.
options.maximumPrecision integer options.type property=List or SingleValue Indicates the number of significant digits included for values plotted on the chart but only applies to fractional portions of the number; all integer digits are included regardless of the desired precision. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 0.001 and 0.01, significant information will be lost unless the precision is set to at least 4. If no value is supplied, the chart visualization will adjust the precision to fit in the available space.
options.onChartLegendOptions object options.type property=TimeSeriesChart Determines whether a legend is shown and, if so, which dimension is shown on the legend. The properties of the included object are indicated as options.onChartLegendOptions.propertyName in this documentation.
options.onChartLegendOptions.dimensionInLegend string options.type property=TimeSeriesChart Determines which dimension is shown in the legend. For meaningful values, ensure the dimension sent exists and has different values for each plot in the chart.
options.onChartLegendOptions.showLegend boolean options.type property=TimeSeriesChart If true show a legend at the bottom of the chart. The legend lists the each value of the dimension specified in the options.onChartLegendsOptions.dimensionInLegend property next to the color associated with that data point in the chart.
options.programOptions object options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options applied to the chart. The properties of the included object are indicated as options.programOptions.propertyName in this documentation.
options.programOptions.disableSampling boolean options.type property=TimeSeriesChart, List, SingleValue, or Heatmap If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
options.programOptions.maxDelay integer options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the chart. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.programOptions.minimumResolution integer options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The minimum resolution to use for computing the underlying program, specified in milliseconds. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.publishLabelOptions list of objects options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options for the plot related to a specific SignalFlow statement applied to the chart. The order of elements in the list is retained as sent but is not significant; label values are used to map options with specific publish() statements in the related SignalFlow. Heatmaps do not support full publishLabelOptions objects; the Constraints column lists the supported chart types for each property. The properties of the included objects are indicated as options.publishLabelOptions[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the publishLabelOptions array.
options.publishLabelOptions[x].displayName string options.type property=TimeSeriesChart, List, or SingleValue Indicates an alternate value for the Plot Name column of the Data Table associated with the chart.
options.publishLabelOptions[x].label string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates the value of the string inside the publish function of the SignalFlow statement being configured by this element.
options.publishLabelOptions[x].paletteIndex integer
  • options.type property=TimeSeriesChart, List, or SingleValue
  • Minimum value = 0
  • Maximum value = 15
Indicates the index number of color to use for all plots related to this SignalFlow statement. The list of 16 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f

Different colors may be presented to users, depending on the selected settings for color blindness. For sample swatches of the colors and the mappings used for color-blind users, see the first 16 colors in the color palette documentation at the bottom of the Charts Overview.
options.publishLabelOptions[x].plotType enumerated string options.type property=TimeSeriesChart, List, or SingleValue Overrides the value of options.defaultPlotType for the output of this SignalFlow statement.
options.publishLabelOptions[x].valuePrefix string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to prepend to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview. This setting will be overridden if options.publishLabelOptions[x].valueUnit is set on the same plot.
options.publishLabelOptions[x].valueSuffix string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to append to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview. This setting will be overridden if options.publishLabelOptions[x].valueUnit is set on the same plot.
options.publishLabelOptions[x].valueUnit enumerated string
  • Supported values are: Bit, Kilobit, Megabit, Gigabit, Terabit, Petabit, Exabit, Zettabit, Yottabit, Byte, Kibibyte, Mebibyte, Gigibyte, Tebibyte, Pebibyte, Exbibyte, Zebibyte, Yobibyte, Nanosecond, Microsecond, Millisecond, Second, Minute, Hour, Day, and Week
  • Available if the options.type property is set to anything but Text
Indicates display units for the values in the chart. The plot values will be presented in a readable way based on the assumption that the raw values are denominated in the selected unit. For instance, a value of 1000 on a plot with options.publishLabelOptions[x].valueUnit set to bits will be presented as 1 Kilobit, and a value of 1024 on a plot with Bytes selected will be presented as 1 Kebibyte. Each unit will be scaled up and down in this way within its own kind (Bits, Bytes, and Units of Time; see Charts Overview for a full specification).

Plots with options.publishLabelOptions[x].valueUnit are scaled and labelled with the unit's abbreviation when presented in chart tooltips, axes, and data tables. Where options.publishLabelOptions[x].valueUnit affects presentation it overrides options.publishLabelOptions[x].valuePrefix, options.publishLabelOptions[x].valueSuffix, and options.unitPrefix.
options.publishLabelOptions[x].yAxis integer options.type property=TimeSeriesChart, List, or SingleValue Indicates whether the Y-axis for the plot associated with this SignalFlow statement is on the left side (0) or the right side of the chart. If not specified, the left side Y-axis is used.
options.refreshInterval integer options.type property=List or SingleValue Indicates how often the data should be refreshed in the chart in milliseconds. The default is usually 10000 (10 seconds) but may be 3600000 (1 hour) instead if the resolution of the data cannot be detected.
options.secondaryVisualization enumerated string options.type property=List or SingleValue Indicates the secondary visualization to display the value of the metric. Examples of the visualizations are shown in Charts Overview.
options.showEventLines boolean options.type property=TimeSeriesChart If true, a vertical line is displayed on the chart when an event is triggered.
options.showSparkLine boolean options.type property=SingleValue If true, a graphical representation of recent trends without axes or annotations is shown underneath the value in the chart. For example, the following chart shows a sparkline: sparkline -auto This property will be overridden if options.secondaryVisualization is set.
options.sortBy string options.type property=List Indicates how to sort the individual entries of a list chart. The first character of the value must be either a minus sign ("-") indicating that the data is displayed in descending order or a plus sign ("+") indicating that the data is displayed in ascending order. The rest of the value indicates the sort criteria, either a keyword (representing the value of the data point, the name of the metric being displayed, or the publish label of the SignalFlow statement generating the data) or the name of a dimension available to the chart. The default sort is on the publish label in ascending order which corresponds to Auto in the web application; values that do not map to a keyword or a valid dimension will use the default sort. Nulls are placed at the start of the list when using ascending order and at the end of the list when using descending order. For information about the available keywords and how the sort options map between the API and the web application, see the Charts Overview.
options.sortDirection enumerated string options.type property=Heatmap Indicates whether to put lower or higher values first when sorting the values on a heatmap chart.
options.sortProperty string options.type property=Heatmap The custom property to use as the sorting criteria for the heatmap chart. The value should map to a valid key name specified in the customProperties property or to a valid custom property available by default. If no value is specified, the values are displayed without an obvious order.
options.stacked boolean options.type property=TimeSeriesChart, options.defaultPlotType=AreaChart or ColumnChart If true, the plots in the chart are stacked on top of each other and their values added together to create the values indicated by the axis labels. Individual values can still be viewed when highlighting specific points in time on the chart within the visible colored area representing the desired plot or by viewing the data table.
options.includeZero boolean options.type property=TimeSeriesChart If true, 0 will always be included when dynamically calculating Y-axis ranges. This is a chart-wide setting applied to all axes in use. However, if options[x].axes.min or options[x].axes.max settings exclude 0 from the displayed range on a particular axis, 0 will not be displayed on that axis even if options.includeZero is set to true.
options.time object options.type property=TimeSeriesChart Options for the time displayed on the chart. The properties of the included object are indicated as options.time.propertyName in this documentation.
options.time.end integer options.type property =TimeSeriesChart, options.time.type property=absolute The timestamp of the last time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.range integer options.type property =TimeSeriesChart, options.time.type property=relative The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here, GCP metrics listed here, and Azure metrics listed here.
options.time.start integer options.type property =TimeSeriesChart, options.time.type property=absolute The timestamp of the first time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.type enumerated string options.type property =TimeSeriesChart Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.
options.timestampHidden boolean options.type property=Heatmap If true, the timestamp is shown below the displayed values on the chart.
options.type enumerated string All The visualization mechanism used in the chart. The Heatmap option displays each value in an ordered set of boxes colored to indicate the health of the value. The List option displays each value in its own row with an unlabeled plot showing recent trends. The SingleValue option displays the current value of one data point colored to indicate the health of the value. The Text option displays constant, pre-defined Markdown. The TimeSeriesChart option displays the value of multiple data points together in one of four visualization modes, retaining historical data. See the Charts Overview for a brief discussion and screenshot of each type of chart or see Choosing a Chart Type for more information about using each option within the web application.
options.unitPrefix enumerated string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates whether units should be displayed and labeled using metric units where k stands for kilo- meaning 1000 of the the item in question or in a binary format where K stands for Kibi- meaning 1024 of the item in question.
packageSpecifications string All Indicates one or more Signal Flow packages to import for use in the programText value.
programText string option.type property=Heatmap, List, SingleValue, or TimeSeriesChart A SignalFlow program used to populate the chart. If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n").
tags list of strings All A set of keywords used to filter charts or to search for all charts with some common element. Among other things, tags may be used to indicate the state of a chart or its data source (for example, a prod tag could indicate all charts displaying data from a production environment).

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Update Chart

The Update Chart API call modifies an existing v2 chart identified by its id value.

 

The Update Chart API call modifies an existing v2 chart identified by its id value.

The Update Chart call is a full update; any properties not included in the update call will be removed or reset to their default state. In particular, if you change the type of the chart, those properties that do not apply to the new chart type will be removed. If you later change the chart back to the original type, the previous values are not retained and must be resent in the update call if desired.

For more information on charts including the types of charts supported and the different ways they can be visualized, see the Charts Overview.

Syntax

PUT https://api.signalfx.com/v2/chart/_id_

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Update Chart call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Path Parameters

The Update Chart API call supports one path parameter as indicated in the syntax line above:

Path parameter Type Description
id string The system assigned identifier of an existing chart object to modify.

Payload

The following properties are supported in the request payload for the Update Chart call:

Property Type Constraints Description
customProperties object
  • maximum length of key = 128 characters
  • key name may only contain alphabetic characters, numerals, underscores ("_"), or hyphens ("-")
  • key name must start with an alphabetic character of either case
  • key name may not start with an underscore ("_"), sf followed by an underscore ("sf_"), aws followed by an underscore ("aws_"), gcp followed by an underscore ("gcp_"), or azure followed by an underscore ("azure_")
  • value is required if key is specified
  • value may not be an empty string
  • maximum length of value = 256 characters

NOTE: the key name constraints outlined above may be encapsulated in the following regular expression: ^[a-zA-Z][a-zA-Z0-9_-]*$
A set of user-defined key-value pairs containing metadata about the chart that may change over time. Custom properties may be used to store metadata that may not be known at chart creation or that may be expected to change in the future. These properties can be used to filter charts or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string None The description of the chart. This value appears underneath the chart name in the SignalFx web application.
name string
  • required
  • minimum characters = 1
The name of the chart. The name is used to identify the chart in the SignalFx web application and should be descriptive The name may be truncated in the UI if it does not fit in the allocated space so put important information first. It may be desirable to use unique names for charts but this is not enforced by the API.
options object
  • default values as indicated in specific properties of the object
The options applied to this chart. The options include information about the type of chart and are different for different types of charts. The properties of the included object are indicated as options.propertyName in this documentation. By default all listed properties of the options object are available in any options object. The constraints column will note if a listed property is only available within certain contexts (such as for one or more chart types).
options.areaChartOptions object
  • Only available if the options.type property is set to TimeSeriesChart
  • Only available if the options.defaultPlotType property is set to AreaChart
The area chart options applied to this chart. The properties of the included options object are indicated as options.areaChartOptions.propertyName in this documentation.
options.areaChartOptions.showDataMarkers boolean
  • Only available if the options.type property is set to TimeSeriesChart
  • Only available if the options.defaultPlotType property is set to AreaChart
  • Default value is false
When true, markers will be drawn for each datapoint within the visualization.
options.axes list of objects
  • Only available if the options.type property is set to TimeSeriesChart
Y axis configuration for the left and right side of a chart. The first element of the array corresponds to the left side of the chart and the second element of the array corresponds to the right side of the array. Subsequent elements are accepted but ignored. The properties of the included objects are indicated as options.axes[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the axes array.
options.axes[x].highWatermark float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be equal to or less than the value of the options.axes[x].max property of the same element
  • Value must be greater than the value of the options.axes[x].lowWatermark property of the same element
Indicates a value to draw a horizontal line across the chart as the top of an area of interest to highlight.
options.axes[x].highWatermarkLabel string
  • Only available if the options.type property is set to TimeSeriesChart and options.axes[x].highWatermark is set
  • maximum characters = 1000
Indicates a label for the high watermark line on the chart. If the element corresponds to the left axis (element 0), the label is placed near the line starting at the left edge of the chart. If the element corresponds to the right axis (element 1), the label is placed near the line ending at the right edge of the chart.
options.axes[x].label string
  • Only available if the options.type property is set to TimeSeriesChart
A description for the Y axis of the chart, displayed to the left of the axis value labels for left side axes and to the right of the axis value labels for right side axes.
options.axes[x].lowWatermark float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be equal to or greater than the value of the options.axes[x].min property of the same element
  • Value must be less than the value of the options.axes[x].highWatermark property of the same element
Indicates a value to draw a horizontal line across the chart as the bottom of an area of interest to highlight.
options.axes[x].lowWatermarkLabel string
  • Only available if the options.type property is set to TimeSeriesChart and options.axes[x].lowWatermark is set
  • maximum characters = 1000
Indicates a label for the low watermark line on the chart. If the element corresponds to the left axis (element 0), the label is placed near the line starting at the left edge of the chart. If the element corresponds to the right axis (element 1), the label is placed near the line ending at the right edge of the chart.
options.axes[x].max float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be greater than the value of the options.axes[x].min property of the same element
Indicates the largest value to display on the chart. Overrides options.includeZero if the properties are set to incompatible values.
options.axes[x].min float
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be less than the value of the options.axes[x].max property of the same element
Indicates the smallest value to display on the chart. Overrides options.includeZero if the properties are set to incompatible values.
options.axisPrecision integer
  • Only available if the options.type property is set to TimeSeriesChart
  • Value must be an integer between 3 and 10
  • Value is 3 by default
Indicates the number of significant digits included for values plotted on the chart. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 100000 and 100010, using a precision of 3 would result in a value of 100000 for all data points. Instead, set the precision to 6 to capture differences in integer values; higher precision values would also capture fractional variations.
options.colorBy enumerated string
  • Not available if the options.type property is set to Text
  • If the options.type property is set to Heatmap:
    • Supported values are: Range and Scale
    • Default value is Range
  • If the options.type property is set to List:
    • Supported values are: Dimension, Metric, and Scale
    • Default value is Metric
  • If the options.type property is set to SingleValue:
    • Supported values are: Dimension, Metric, and Scale
    • Default value is Metric
  • If the options.type property is set to TimeSeriesChart:
    • Supported values are: Dimension and Metric
    • Default value is Dimension
Indicates the mechanism for applying the color scheme to the values in the chart. If color is desired in a text chart it should be applied using HTML within the markdown property.
options.colorRange object
  • Only available if the options.type property is set to Heatmap
The range of values to be colored in this chart and the color to span across that range. The number of variations of that color within the specified range is controlled by the colorScale property. The properties of the included object are indicated as options.colorRange.propertyName in this documentation.
options.colorRange.color string
  • Only available if the options.type property is set to Heatmap
  • Expected to have seven characters as follows:
    • The first character is always a pound sign ("#")
    • The other characters may be any numeral or a capital letter between A and F inclusive
The hex value of the color used to represent values in a heatmap chart. Different tones of this color are then applied as indicated by the values of the colorScale property. The color specified is the lowest value of the color gradient in the chart; the number of variations of that color within the specified range is controlled by the colorScale property. We recommend using one of the twenty one colors in the official color palette for best results.
options.colorRange.max string
  • Only available if the options.type property is set to Heatmap
The largest value assigned a color in the heatmap. In general this should correspond to the highest expected value of the input criteria.
options.colorRange.min string
  • Only available if the options.type property is set to Heatmap
The smallest value assigned a color in the heatmap. In general this should correspond to the smallest expected value of the input criteria.
options.colorScale object
  • Available if the options.type property is set to Heatmap, SingleValue, or List
Indicates the borders of color ranges in charts and whether the range should be applied in the default order or inverted. If options.colorScale2 is specified, this property will be overridden by the settings there. The properties of the included object are indicated as options.colorScale.propertyName in this documentation.
options.colorScale.inverted boolean
  • Available if the options.type property is set to Heatmap, SingleValue, or List
  • Set to false by default
If true, the colors are applied to the specified ranges in reverse order from the default application. For heatmap charts using options.colorBy set to Range, this means darker tones indicate lower values. For other chart types, it means that red represents lower values and green higher values in the default color scheme (other color schemes may be applied for users who select a color blind mode).
options.colorScale.thresholds list of floats
  • Available if the options.type property is set to Heatmap, SingleValue, or List
Indicates the border values for color ranges in the chart. Values should be specified from lowest to highest and only the first six values have meaning (additional elements are ignored). Values outside of the range will not be colored; in general the first value in the array should map to the lowest value expected for the plotted data and the last (meaningful) value in the array should correspond to the highest value expected for the plotted data.
options.colorScale2 list of objects
  • Available if the options.type property is set to List, SingleValue, or Heatmap
Each element of the array contains the information about a single color range including both the color to display for that range and the borders of the range. Collectively the set of elements specify the entire range displayed in the secondary visualization or heatmap chart. The elements do not need to be specified in any order; they will automatically be ordered by value in the display and the lowest value specified in the set of elements will automatically become the left border of any secondary visualization and the highest value specified in the set of elements will automatically become the right border of any secondary visualization. The properties of the included object are indicated as options.colorScale2[x].propertyName in this documentation.
options.colorScale2[x].gt float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].lt or options.colorScale2[x].lte property of the same element
  • Cannot have both options.colorScale2[x].gt and options.colorScale2[x].gte set at the same time
Indicates the lower threshold non-inclusive value for this range.
options.colorScale2[x].gte float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].lt or options.colorScale2[x].lte property of the same element
  • Cannot have both options.colorScale2[x].gt and options.colorScale2[x].gte set at the same time
Indicates the lower threshold inclusive value for this range.
options.colorScale2[x].lt float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].gt or options.colorScale2[x].gte property of the same element
  • Cannot have both options.colorScale2[x].lt and options.colorScale2[x].lte set at the same time
Indicates the upper threshold non-inculsive value for this range.
options.colorScale2[x].lte float
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Value must be less than the value of the options.colorScale2[x].gt or options.colorScale2[x].gte property of the same element
  • Cannot have both options.colorScale2[x].lt and options.colorScale2[x].lte set at the same time
Indicates the upper threshold inclusive value for this range.
options.colorScale2[x].paletteIndex integer
  • Available if the options.type property is set to List, SingleValue, or Heatmap
  • Minimum value = 0
  • Maximum value = 20
  • Required
Indicates the index number of color to use for values in the specified range. The list of 21 supported colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users, depending on the selected settings for color blindness. For sample swatches of the colors and the mappings used for color-blind users, see the color palette documentation at the bottom of the Charts Overview.
options.defaultPlotType enumerated string
  • Supported Values are: LineChart, AreaChart, ColumnChart, and Histogram
  • Default value is LineChart
Indicates which of the supported plot types should be used for this chart. LineChart displays the data in a plot with datapoints connected by a series of straight lines. AreaChart displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in. Column charts list the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar.
options.groupBy list of strings
  • Available if the options.type property is set to Heatmap
Indicates one or more properties to group together in the histogram. The value of each element should map to a valid key name specified in the customProperties property or to a valid custom property supplied by default. The first element is a top level grouping, the second element indicates a grouping inside each of the top level groups. Subsequent elements are ignored. For example, a heatmap grouping CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping is shown in the Charts Overview.
options.histogramChartOptions object
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to Histogram
The histogram chart options applied to this chart. The properties of the included options object are indicated as options.histogramChartOptions.propertyName in this documentation.
options.histogramChartOptions.colorThemeIndex integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to Histogram
  • Minimum value = 0
  • Maximum value = 20
  • Default value = 16
Indicates the index number of the color to use for the theme of this chart when viewed as a histogram. The chart will use variations of this color, with greater opacity indicating greater values. The list of 21 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e
options.includeZero boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Default is false
If true, 0 will always be included when dynamically calculating Y-axis ranges. This is a chart-wide setting applied to all axes in use. However, if options[x].axes.min or options[x].axes.max settings exclude 0 from the displayed range on a particular axis, 0 will not be displayed on that axis even if options.includeZero is set to true.
options.legendOptions object
  • Available if the options.type property is set to TimeSeriesChart or List
  • Default is to show all properties in the legend
Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included object are indicated as options.legendOptions.propertyName in this documentation.
options.legendOptions.fields list of objects
  • Available if the options.type property is set to TimeSeriesChart or List
  • Default is to show all properties in the legend
Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included objects are indicated as options.legendOptions.fields[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the fields array.
options.legendOptions.fields[x].enabled boolean
  • Available if the options.type property is set to TimeSeriesChart or List
  • Default value is true
Indicates whether the associated property is shown (true) or hidden (false) in the data table.
options.legendOptions.fields[x].property string
  • Available if the options.type property is set to TimeSeriesChart or List
The key name of a customProperty specified for this chart (or supplied by default by SignalFx) to hide or show in the data table.
options.lineChartOptions object
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to LineChart
Sets options specific to a line chart. The properties of the included object are indicated as options.lineChartOptions.propertyName in this documentation.
options.lineChartOptions.showDataMarkers boolean
  • Available if the is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to LineChart
  • Default value is false
Indicates whether the actual data points are indicated by filled circles on the chart or if the plot is shown as a smooth line with no such indicators.
options.markdown string
  • Only available if the options.type property is set to Text
The content of a text chart as specified using GitHub-flavored Markdown; any Markdown or HTML supported within a *.md file in GitHub is supported in this value.
options.maximumPrecision integer
  • Only available if the options.type property is set to List or SingleValue
  • Value must be an integer
Indicates the number of significant digits included for values plotted on the chart but only applies to fractional portions of the number; all integer digits are included regardless of the desired precision. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 0.001 and 0.01, significant information will be lost unless the precision is set to at least 4. If no value is supplied, the chart visualization will adjust the precision to fit in the available space.
options.onChartLegendOptions object
  • Available if the options.type property is set to TimeSeriesChart
Determines whether a legend is shown and, if so, which dimension is shown on the legend. The properties of the included object are indicated as options.onChartLegendOptions.propertyName in this documentation.
options.onChartLegendOptions.dimensionInLegend string
  • Available if the options.type property is set to TimeSeriesChart
Determines which dimension is shown in the legend. For meaningful values, ensure the dimension sent exists and has different values for each plot in the chart.
options.onChartLegendOptions.showLegend boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Default is false
If true show a legend at the bottom of the chart. The legend lists the each value of the dimension specified in the options.onChartLegendsOptions.dimensionInLegend property next to the color associated with that data point in the chart.
options.programOptions object
  • Available if the options.type property is set to anything but Text
General options applied to the chart. The properties of the included object are indicated as options.programOptions.propertyName in this documentation.
options.programOptions.disableSampling boolean
  • Available if the options.type property is set to anything but Text
  • Default is false.
If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
options.programOptions.maxDelay integer
  • Available if the options.type property is set to anything but Text
  • Maximum value is 900000 (15 minutes)
The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the chart. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.programOptions.minimumResolution integer
  • Available if the options.type property is set to anything but Text
  • Maximum value is 900000 (15 minutes)
The minimum resolution to use for computing the underlying program, specified in milliseconds. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.publishLabelOptions list of objects
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
General options for the plot related to a specific SignalFlow statement applied to the chart. The order of elements in the list is retained as sent but is not significant; label values are used to map options with specific publish() statements in the related SignalFlow. Heatmaps do not support full publishLabelOptions objects; the Constraints column lists the supported chart types for each property. The properties of the included objects are indicated as options.publishLabelOptions[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the publishLabelOptions array.
options.publishLabelOptions[x].displayName string
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
Indicates an alternate value for the Plot Name column of the Data Table associated with the chart.
options.publishLabelOptions[x].label string
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
  • Required
Indicates the value of the string inside the publish function of the SignalFlow statement being configured by this element.
options.publishLabelOptions[x].paletteIndex integer
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
  • Minimum value = 0
  • Maximum value =15
Indicates the index number of color to use for all plots related to this SignalFlow statement. The list of 16 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f

Different colors may be presented to users, depending on the selected settings for color blindness. For sample swatches of the colors and the mappings used for color-blind users, see the first 16 colors in the color palette documentation at the bottom of the Charts Overview.
options.publishLabelOptions[x].plotType enumerated string
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
  • Supported Values are: LineChart, AreaChart, ColumnChart, and Histogram
Overrides the value of options.defaultPlotType for the output of this SignalFlow statement.
options.publishLabelOptions[x].valuePrefix string
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
Indicates a string to prepend to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview. This setting will be overridden if options.publishLabelOptions[x].valueUnit is set on the same plot.
options.publishLabelOptions[x].valueSuffix string
  • Available if the options.type property is set to TimeSeriesChart, List, SingleValue, or Heatmap
Indicates a string to append to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview. This setting will be overridden if options.publishLabelOptions[x].valueUnit is set on the same plot.
options.publishLabelOptions[x].valueUnit enumerated string
  • Supported values are: Bit, Kilobit, Megabit, Gigabit, Terabit, Petabit, Exabit, Zettabit, Yottabit, Byte, Kibibyte, Mebibyte, Gigibyte, Tebibyte, Pebibyte, Exbibyte, Zebibyte, Yobibyte, Nanosecond, Microsecond, Millisecond, Second, Minute, Hour, Day, and Week
  • Available if the options.type property is set to anything but Text
Indicates display units for the values in the chart. The plot values will be presented in a readable way based on the assumption that the raw values are denominated in the selected unit. For instance, a value of 1000 on a plot with options.publishLabelOptions[x].valueUnit set to bits will be presented as 1 Kilobit, and a value of 1024 on a plot with Bytes selected will be presented as 1 Kebibyte. Each unit will be scaled up and down in this way within its own kind (Bits, Bytes, and Units of Time; see Charts Overview for a full specification).

Plots with options.publishLabelOptions[x].valueUnit are scaled and labelled with the unit's abbreviation when presented in chart tooltips, axes, and data tables. Where options.publishLabelOptions[x].valueUnit affects presentation it overrides options.publishLabelOptions[x].valuePrefix, options.publishLabelOptions[x].valueSuffix, and options.unitPrefix.
options.publishLabelOptions[x].yAxis integer
  • Available if the options.type property is set to TimeSeriesChart, List, or SingleValue
  • Minimum value = 0
  • Maximum value = 1
Indicates whether the Y-axis for the plot associated with this SignalFlow statement is on the left side (0) or the right side of the chart. If not specified, the left side Y-axis is used.
options.refreshInterval integer
  • Available if the options.type property is set to List or SingleValue
Indicates how often the data should be refreshed in the chart in milliseconds. The default is usually 10000 (10 seconds) but may be 3600000 (1 hour) instead if the resolution of the data cannot be detected.
options.secondaryVisualization enumerated string
  • Available if the options.type property is set to List or SingleValue
  • Supported Values are: None, Radial, Linear, Sparkline.
  • If the options.type property is set to List:
    • Default value is Sparkline
  • If options.type property is set to SingleValue:
    • Default value is None
Indicates the secondary visualization to display the value of the metric. Examples of the visualizations are shown in Charts Overview.
options.showEventLines boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Default is false
If true, a vertical line is displayed on the chart when an event is triggered.
options.showSparkLine boolean
  • Available if the options.type property is set to SingleValue
  • Default is false
If true, a graphical representation of recent trends without axes or annotations is shown underneath the value in the chart. For example, the following chart shows a sparkline: sparkline -auto This property will be overridden if options.secondaryVisualization is set.
options.sortBy string
  • Available if the options.type property is set to List
Indicates how to sort the individual entries of a list chart. The first character of the value must be either a minus sign ("-") indicating that the data is displayed in descending order or a plus sign ("+") indicating that the data is displayed in ascending order. The rest of the value indicates the sort criteria, either a keyword (representing the value of the data point, the name of the metric being displayed, or the publish label of the SignalFlow statement generating the data) or the name of a dimension available to the chart. The default sort is on the publish label in ascending order which corresponds to Auto in the web application; values that do not map to a keyword or a valid dimension will use the default sort. Nulls are placed at the start of the list when using ascending order and at the end of the list when using descending order. For information about the available keywords and how the sort options map between the API and the web application, see the Charts Overview.
options.sortDirection enumerated string
  • Available if the options.type property is set to Heatmap
  • Supported values are: Ascending and Descending
  • Default value is Ascending
Indicates whether to put lower or higher values first when sorting the values on a heatmap chart.
options.sortProperty string
  • Available if the options.type property is set to Heatmap
The custom property to use as the sorting criteria for the heatmap chart. The value should map to a valid key name specified in the customProperties property or to a valid custom property available by default. If no value is specified, the values are displayed without an obvious order.
options.stacked boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.defaultPlotType property is set to AreaChart or ColumnChart
  • Default is false
If true, the plots in the chart are stacked on top of each other and their values added together to create the values indicated by the axis labels. Individual values can still be viewed when highlighting specific points in time on the chart within the visible colored area representing the desired plot or by viewing the data table.
options.includeZero boolean
  • Available if the options.type property is set to TimeSeriesChart
  • Default is false
If true, 0 will always be included when dynamically calculating Y-axis ranges. This is a chart-wide setting applied to all axes in use. However, if options[x].axes.min or options[x].axes.max settings exclude 0 from the displayed range on a particular axis, 0 will not be displayed on that axis even if options.includeZero is set to true.
options.time object
  • Available if the options.type property is set to TimeSeriesChart
Options for the time displayed on the chart. The properties of the included object are indicated as options.time.propertyName in this documentation.
options.time.end integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.time.type property is set to absolute
  • Default = 0
The timestamp of the last time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.range integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.time.type property is set to relative
  • Default = 0
The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here, GCP metrics listed here, and Azure metrics listed here
options.time.start integer
  • Available if the options.type property is set to TimeSeriesChart
  • Available if the options.time.type property is set to absolute
  • Default = 0
The timestamp of the first time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.type enumerated string
  • Available if the options.type property is set to TimeSeriesChart
  • Supported values are: absolute and relative
Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.
options.timestampHidden boolean
  • Available if the options.type property is set to Heatmap or SingleValue
  • Default is false
If true, the timestamp is shown below the displayed values on the chart.
options.type enumerated string
  • Required
  • Supported values are: Heatmap, List, SingleValue, Text, TimeSeriesChart
The visualization mechanism used in the chart. The Heatmap option displays each value in an ordered set of boxes colored to indicate the health of the value. The List option displays each value in its own row with an unlabeled plot showing recent trends. The SingleValue option displays the current value of one data point colored to indicate the health of the value. The Text option displays constant, pre-defined Markdown. The TimeSeriesChart option displays the value of multiple data points together in one of four visualization modes, retaining historical data. See the Charts Overview for a brief discussion and screenshot of each type of chart or see Choosing a Chart Type for more information about using each option within the web application.
options.unitPrefix enumerated string
  • Available if the options.type property is set to anything but Text
  • Supported values are: Binary and Metric
  • Default value is Metric
Indicates whether units should be displayed and labeled using metric units where k stands for kilo- meaning 1000 of the the item in question or in a binary format where K stands for Kibi- meaning 1024 of the item in question.
packageSpecifications string
  • Value must be signalfx
Indicates one or more SignalFlow packages to import for use in the programText value. Currently the only the signalfx package is available.
programText string
  • required for all chart types except Text
A SignalFlow program used to populate the chart. If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n").
tags list of strings
  • Maximum characters per element = 256
A set of keywords used to filter charts or to search for all charts with some common element. Among other things, tags may be used to indicate the state of a chart or its data source (for example, a prod tag could indicate all charts displaying data from a production environment).

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Update Chart call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Update Chart call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Update Chart call:

Property Type Contexts Returned Description
created integer All The time the member object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
creator string All The user ID of the administrator requesting that the invitation be sent. This value is always set by the system. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
customProperties object All A set of user-defined key-value pairs containing metadata about the chart that may change over time. Custom properties may be used to store metadata that may not be known at chart creation or that may be expected to change in the future. These properties can be used to filter charts or as grouping criteria. Consistency in key names is not enforced across the system; it is up to the user to ensure that keys with the same meaning use exactly the same name.
description string All The description of the chart. This value appears underneath the chart name in the SignalFx web application.
id string All The ID assigned to chart object. This ID is unique and always set by the system.
lastUpdated integer All The last time the object was updated in UTC milliseconds. This includes system actions and activity coming from the web application
lastUpdatedBy string All The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.
name string All The name of the chart. The name is used to identify the chart in the SignalFx web application and should be descriptive The name may be truncated in the UI if it does not fit in the allocated space so put important information first.
options object All The options applied to this chart. The options include information about the type of chart and are different for different types of charts. The properties of the included object are indicated as options.propertyName in this documentation. By default all listed properties of the options object are available in any options object. The constraints column will note if a listed property is only available within certain contexts (such as for one or more chart types).
options.areaChartOptions object options.type property=TimeSeriesChart, options.defaultPlotType=AreaChart The area chart options applied to this chart. The properties of the included options object are indicated as options.areaChartOptions.propertyName in this documentation.
options.areaChartOptions.showDataMarkers boolean options.type property=TimeSeriesChart, options.defaultPlotType=AreaChart When true, markers will be drawn for each datapoint within the visualization.
options.axes list of objects options.type property=TimeSeriesChart Y axis configuration for the left and right side of a chart. The first element of the array corresponds to the left side of the chart and the second element of the array corresponds to the right side of the array. Subsequent elements are accepted but ignored. The properties of the included objects are indicated as options.axes[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the axes array.
options.axes[x].highWatermark float options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the top of an area of interest to highlight.
options.axes[x].label string options.type property=TimeSeriesChart A description for the Y axis of the chart, displayed to the left of the axis value labels for left side axes and to the right of the axis value labels for right side axes.
options.axes[x].highWatermarkLabel string options.type property=TimeSeriesChart Indicates a label for the high watermark line on the chart. If the element corresponds to the left axis (element 0), the label is placed near the line starting at the left edge of the chart. If the element corresponds to the right axis (element 1), the label is placed near the line ending at the right edge of the chart.
options.axes[x].lowWatermark float options.type property=TimeSeriesChart Indicates a value to draw a horizontal line across the chart as the bottom of an area of interest to highlight.
options.axes[x].lowWatermarkLabel string options.type property=TimeSeriesChart Indicates a label for the low watermark line on the chart. If the element corresponds to the left axis (element 0), the label is placed near the line starting at the left edge of the chart. If the element corresponds to the right axis (element 1), the label is placed near the line ending at the right edge of the chart.
options.axes[x].max float options.type property=TimeSeriesChart Indicates the largest value to display on the chart. Overrides options.includeZero if the properties are set to incompatible values.
options.axes[x].min float options.type property=TimeSeriesChart Indicates the smallest value to display on the chart. Overrides options.includeZero if the properties are set to incompatible values.
options.axisPrecision integer options.type property=TimeSeriesChart Indicates the number of significant digits included for values plotted on the chart. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 100000 and 100010, using a precision of 3 would result in a value of 100000 for all data points. Instead, set the precision to 6 to capture differences in integer values; higher precision values would also capture fractional variations.
options.colorBy enumerated string options.type property=Heatmap, List, SingleValue, or TimeSeriesChart Indicates the mechanism for applying the color scheme to the values in the chart. If color is desired in a text chart it should be applied using HTML within the markdown property.
options.colorRange object options.type property=Heatmap The range of values to be colored in this chart and the color to span across that range. The number of variations of that color within the specified range is controlled by the colorScale property. The properties of the included object are indicated as options.colorRange.propertyName in this documentation.
options.colorRange.color string options.type property=Heatmap The hex value of the color used to represent values in a heatmap chart. Different tones of this color are then applied as indicated by the values of the colorScale property. The color specified is the lowest value of the color gradient in the chart; the number of variations of that color within the specified range is controlled by the colorScale property. We recommend using one of the twenty one colors in the official color palette for best results.
options.colorRange.max string options.type property=Heatmap The largest value assigned a color in the heatmap. In general this should correspond to the highest expected value of the input criteria.
options.colorRange.min string options.type property=Heatmap The smallest value assigned a color in the heatmap. In general this should correspond to the smallest expected value of the input criteria.
options.colorScale object options.type property=Heatmap, SingleValue, or List Indicates the borders of color ranges in charts and whether the range should be applied in the default order or inverted. If options.colorScale2 is specified, this property will be overridden by the settings there. The properties of the included object are indicated as options.colorScale.propertyName in this documentation.
options.colorScale.inverted boolean options.type property=Heatmap, SingleValue, or List If true, the colors are applied to the specified ranges in reverse order from the default application. For heatmap charts using options.colorBy set to Range, this means darker tones indicate lower values. For other chart types, it means that red represents lower values and green higher values in the default color scheme (other color schemes may be applied for users who select a color blind mode).
options.colorScale.thresholds list of floats options.type property=Heatmap, SingleValue, or List Indicates the border values for color ranges in the chart. Values should be specified from lowest to highest and only the first six values have meaning (additional elements are ignored). Values outside of the range will not be colored; in general the first value in the array should map to the lowest value expected for the plotted data and the last (meaningful) value in the array should correspond to the highest value expected for the plotted data.
options.colorScale2 list of objects options.type property=SingleValue, List, or Heatmap Each element of the array contains the information about a single color range including both the color to display for that range and the borders of the range. Collectively the set of elements specify the entire range displayed in the secondary visualization or heatmap chart. The elements do not need to be specified in any order; they will automatically be ordered by value in the display and the lowest value specified in the set of elements will automatically become the left border of any secondary visualization and the highest value specified in the set of elements will automatically become the right border of any secondary visualization. The properties of the included object are indicated as options.colorScale2[x].propertyName in this documentation.
options.colorScale2[x].gt float options.type property=List, SingleValue, or Heatmap Indicates the lower threshold non-inclusive value for this range.
options.colorScale2[x].gte float options.type property=List, SingleValue, or Heatmap Indicates the lower threshold inclusive value for this range.
options.colorScale2[x].lt float options.type property=List, SingleValue, or Heatmap Indicates the upper threshold non-inculsive value for this range.
options.colorScale2[x].lte float options.type property=List, SingleValue, or Heatmap Indicates the upper threshold inclusive value for this range.
options.colorScale2[x].paletteIndex integer
  • options.type property=List, SingleValue, or Heatmap
  • Minimum value = 0
  • Maximum value = 20.
Indicates the index number of color to use for values in the specified range. The list of 21 supported colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e


Different colors may be presented to users, depending on the selected settings for color blindness. For sample swatches of the colors and the mappings used for color-blind users, see the color palette documentation at the bottom of the Charts Overview.
options.defaultPlotType enumerated string options.type property=TimeSeriesChart Indicates which of the supported plot types should be used for this chart. LineChart displays the data in a plot with datapoints connected by a series of straight lines. AreaChart displays the data in a plot with datapoints connected by a series of straight lines with the area between the plot line and the x-axis colored in. Column charts list the plot points as shaded bars from the x-axis to the plot value without any direct connector from one plot point to the next. Histograms show colored rectangular bins indicating how many plot points fall at that value; for example, a green bar might indicate a higher density of plot points with the relevant value than a red bar.
options.groupBy list of strings options.type property=Heatmap Indicates one or more properties to group together in the histogram. The value of each element should map to a valid key name specified in the customProperties property or to a valid custom property supplied by default. The first element is a top level grouping, the second element indicates a grouping inside each of the top level groups. Subsequent elements are ignored. For example, a heatmap grouping CPU utilization by AWS availability zone as the primary grouping and number of host CPU cores as the secondary grouping is shown in the Charts Overview.
options.histogramChartOptions object options.type property=TimeSeriesChart, options.defaultPlotType property=Histogram The histogram chart options applied to this chart. The properties of the included options object are indicated as options.histogramChartOptions.propertyName in this documentation.
options.histogramChartOptions.colorThemeIndex integer options.type property=TimeSeriesChart, options.defaultPlotType property=Histogram Indicates the index number of the color to use for the theme of this chart when viewed as a histogram. The chart will use variations of this color, with greater opacity indicating greater values. The list of 21 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10:#876ff3
  • 11: #a747ff
  • 12: ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f
  • 16: #ea1849
  • 17: #eac24b
  • 18: #e5e517
  • 19: #acef7f
  • 20: #6bd37e
options.includeZero boolean options.type property=TimeSeriesChart If true, 0 will always be included when dynamically calculating Y-axis ranges. This is a chart-wide setting applied to all axes in use. However, if options[x].axes.min or options[x].axes.max settings exclude 0 from the displayed range on a particular axis, 0 will not be displayed on that axis even if options.includeZero is set to true.
options.legendOptions object options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included object are indicated as options.legendOptions.propertyName in this documentation.
options.legendOptions.fields list of objects options.type property=TimeSeriesChart or List Sets options for the data table including which properties (if any) are omitted from the data table. The properties of the included objects are indicated as options.legendOptions.fields[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the fields array.
options.legendOptions.fields[x].enabled boolean options.type property=TimeSeriesChart or List Indicates whether the associated property is shown (true) or hidden (false) in the data table.
options.legendOptions.fields[x].property string options.type property=TimeSeriesChart or List The key name of a customProperty specified for this chart (or supplied by default by SignalFx) to hide or show in the data table.
options.lineChartOptions object options.type property=TimeSeriesChart, options.defaultPlotType=LineChartTimeSeriesChart Sets options specific to a line chart. The properties of the included object are indicated as options.lineChartOptions.propertyName in this documentation.
options.lineChartOptions.showDataMarkers boolean options.type property=TimeSeriesChart, options.defaultPlotType=LineChart Indicates whether the actual data points are indicated by filled circles on the chart or if the plot is shown as a smooth line with no such indicators.
options.markdown string options.type property=Text The content of a text chart as specified using GitHub-flavored Markdown; any Markdown or HTML supported within a *.md file in GitHub is supported in this value.
options.maximumPrecision integer options.type property=List or SingleValue Indicates the number of significant digits included for values plotted on the chart but only applies to fractional portions of the number; all integer digits are included regardless of the desired precision. The value chosen should reflect the data being displayed and ensure that the variations in that data can be accurately reflected with the specified precision. For example, if the values of the represented data typically fluctuates between 0.001 and 0.01, significant information will be lost unless the precision is set to at least 4. If no value is supplied, the chart visualization will adjust the precision to fit in the available space.
options.onChartLegendOptions object options.type property=TimeSeriesChart Determines whether a legend is shown and, if so, which dimension is shown on the legend. The properties of the included object are indicated as options.onChartLegendOptions.propertyName in this documentation.
options.onChartLegendOptions.dimensionInLegend string options.type property=TimeSeriesChart Determines which dimension is shown in the legend. For meaningful values, ensure the dimension sent exists and has different values for each plot in the chart.
options.onChartLegendOptions.showLegend boolean options.type property=TimeSeriesChart If true show a legend at the bottom of the chart. The legend lists the each value of the dimension specified in the options.onChartLegendsOptions.dimensionInLegend property next to the color associated with that data point in the chart.
options.programOptions object options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options applied to the chart. The properties of the included object are indicated as options.programOptions.propertyName in this documentation.
options.programOptions.disableSampling boolean options.type property=TimeSeriesChart, List, SingleValue, or Heatmap If true, all data points are displayed in the plot instead of sampling the data to provide better performance.
options.programOptions.maxDelay integer options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the chart. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.programOptions.minimumResolution integer options.type property=TimeSeriesChart, List, SingleValue, or Heatmap The minimum resolution to use for computing the underlying program, specified in milliseconds. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).
options.publishLabelOptions list of objects options.type property=TimeSeriesChart, List, SingleValue, or Heatmap General options for the plot related to a specific SignalFlow statement applied to the chart. The order of elements in the list is retained as sent but is not significant; label values are used to map options with specific publish() statements in the related SignalFlow. Heatmaps do not support full publishLabelOptions objects; the Constraints column lists the supported chart types for each property. The properties of the included objects are indicated as options.publishLabelOptions[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the publishLabelOptions array.
options.publishLabelOptions[x].displayName string options.type property=TimeSeriesChart, List, or SingleValue Indicates an alternate value for the Plot Name column of the Data Table associated with the chart.
options.publishLabelOptions[x].label string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates the value of the string inside the publish function of the SignalFlow statement being configured by this element.
options.publishLabelOptions[x].paletteIndex integer
  • options.type property=TimeSeriesChart, List, or SingleValue
  • Minimum value = 0
  • Maximum value = 15
Indicates the index number of color to use for all plots related to this SignalFlow statement. The list of 16 supported plot colors is as follows:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f

Different colors may be presented to users, depending on the selected settings for color blindness. For sample swatches of the colors and the mappings used for color-blind users, see the first 16 colors in the color palette documentation at the bottom of the Charts Overview.
options.publishLabelOptions[x].plotType enumerated string options.type property=TimeSeriesChart, List, or SingleValue Overrides the value of options.defaultPlotType for the output of this SignalFlow statement.
options.publishLabelOptions[x].valuePrefix string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to prepend to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview. This setting will be overridden if options.publishLabelOptions[x].valueUnit is set on the same plot.
options.publishLabelOptions[x].valueSuffix string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates a string to append to the values displayed when you are viewing a single value or list chart, the data table for a chart, and the tooltip when hovering over a point on a chart. Examples of the visualizations are shown in Charts Overview. This setting will be overridden if options.publishLabelOptions[x].valueUnit is set on the same plot.
options.publishLabelOptions[x].valueUnit enumerated string
  • Supported values are: Bit, Kilobit, Megabit, Gigabit, Terabit, Petabit, Exabit, Zettabit, Yottabit, Byte, Kibibyte, Mebibyte, Gigibyte, Tebibyte, Pebibyte, Exbibyte, Zebibyte, Yobibyte, Nanosecond, Microsecond, Millisecond, Second, Minute, Hour, Day, and Week
  • Available if the options.type property is set to anything but Text
Indicates display units for the values in the chart. The plot values will be presented in a readable way based on the assumption that the raw values are denominated in the selected unit. For instance, a value of 1000 on a plot with options.publishLabelOptions[x].valueUnit set to bits will be presented as 1 Kilobit, and a value of 1024 on a plot with Bytes selected will be presented as 1 Kebibyte. Each unit will be scaled up and down in this way within its own kind (Bits, Bytes, and Units of Time; see Charts Overview for a full specification).

Plots with options.publishLabelOptions[x].valueUnit are scaled and labelled with the unit's abbreviation when presented in chart tooltips, axes, and data tables. Where options.publishLabelOptions[x].valueUnit affects presentation it overrides options.publishLabelOptions[x].valuePrefix, options.publishLabelOptions[x].valueSuffix, and options.unitPrefix.
options.publishLabelOptions[x].yAxis integer options.type property=TimeSeriesChart, List, or SingleValue Indicates whether the Y-axis for the plot associated with this SignalFlow statement is on the left side (0) or the right side of the chart. If not specified, the left side Y-axis is used.
options.refreshInterval integer options.type property=List or SingleValue Indicates how often the data should be refreshed in the chart in milliseconds. The default is usually 10000 (10 seconds) but may be 3600000 (1 hour) instead if the resolution of the data cannot be detected.
options.secondaryVisualization enumerated string options.type property=List or SingleValue Indicates the secondary visualization to display the value of the metric. Examples of the visualizations are shown in Charts Overview.
options.showEventLines boolean options.type property=TimeSeriesChart If true, a vertical line is displayed on the chart when an event is triggered.
options.showSparkLine boolean options.type property=SingleValue If true, a graphical representation of recent trends without axes or annotations is shown underneath the value in the chart. For example, the following chart shows a sparkline: sparkline -auto. This property will be overridden if options.secondaryVisualization is set.
options.sortBy string options.type property=List Indicates how to sort the individual entries of a list chart. The first character of the value must be either a minus sign ("-") indicating that the data is displayed in descending order or a plus sign ("+") indicating that the data is displayed in ascending order. The rest of the value indicates the sort criteria, either a keyword (representing the value of the data point, the name of the metric being displayed, or the publish label of the SignalFlow statement generating the data) or the name of a dimension available to the chart. The default sort is on the publish label in ascending order which corresponds to Auto in the web application; values that do not map to a keyword or a valid dimension will use the default sort. Nulls are placed at the start of the list when using ascending order and at the end of the list when using descending order. For information about the available keywords and how the sort options map between the API and the web application, see the Charts Overview.
options.sortDirection enumerated string options.type property=Heatmap Indicates whether to put lower or higher values first when sorting the values on a heatmap chart.
options.sortProperty string options.type property=Heatmap The custom property to use as the sorting criteria for the heatmap chart. The value should map to a valid key name specified in the customProperties property or to a valid custom property available by default. If no value is specified, the values are displayed without an obvious order.
options.stacked boolean options.type property=TimeSeriesChart, options.defaultPlotType=AreaChart or ColumnChart If true, the plots in the chart are stacked on top of each other and their values added together to create the values indicated by the axis labels. Individual values can still be viewed when highlighting specific points in time on the chart within the visible colored area representing the desired plot or by viewing the data table.
options.includeZero boolean options.type property=TimeSeriesChart If true, when dynamically calculating yAxis ranges, 0 will always been incorporated.
options.time object options.type property=TimeSeriesChart Options for the time displayed on the chart. The properties of the included object are indicated as options.time.propertyName in this documentation.
options.time.end integer options.type property =TimeSeriesChart, options.time.type property=absolute The timestamp of the last time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.range integer options.type property =TimeSeriesChart, options.time.type property=relative The number of milliseconds to display in the chart. The range used is a rolling range with the current time at the right border of the chart display. Use 0 to indicate using the default behavior; this corresponds to -15m for most metrics and -1h for AWS metrics listed here, GCP metrics listed here, and Azure metrics listed here.
options.time.start integer options.type property =TimeSeriesChart, options.time.type property=absolute The timestamp of the first time to display in the chart specified in milliseconds since midnight UTC on January 1, 1970
options.time.type enumerated string options.type property =TimeSeriesChart Indicates whether to use an explicit time range or to always show a relative time of the last N milliseconds. If not specified, relative will be used.
options.timestampHidden boolean options.type property=Heatmap If true, the timestamp is shown below the displayed values on the chart.
options.type enumerated string All The visualization mechanism used in the chart. The Heatmap option displays each value in an ordered set of boxes colored to indicate the health of the value. The List option displays each value in its own row with an unlabeled plot showing recent trends. The SingleValue option displays the current value of one data point colored to indicate the health of the value. The Text option displays constant, pre-defined Markdown. The TimeSeriesChart option displays the value of multiple data points together in one of four visualization modes, retaining historical data. See the Charts Overview for a brief discussion and screenshot of each type of chart or see Choosing a Chart Type for more information about using each option within the web application.
options.unitPrefix enumerated string options.type property=TimeSeriesChart, List, SingleValue, or Heatmap Indicates whether units should be displayed and labeled using metric units where k stands for kilo- meaning 1000 of the the item in question or in a binary format where K stands for Kibi- meaning 1024 of the item in question.
packageSpecifications string All Indicates one or more SignalFlow packages to import for use in the programText value.
programText string option.type property=Heatmap, List, SingleValue, or TimeSeriesChart A SignalFlow program used to populate the chart. If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n").
tags list of strings All A set of keywords used to filter charts or to search for all charts with some common element. Among other things, tags may be used to indicate the state of a chart or its data source (for example, a prod tag could indicate all charts displaying data from a production environment).

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Delete Chart

The Delete Chart API permanently deletes a single v2 chart identified by its id value.

 

The Delete Chart API permanently deletes a single v2 chart identified by its id value.

For more information on charts including the types of charts supported and the different ways they can be visualized, see the Charts Overview.

Syntax

DELETE https://api.signalfx.com/v2/chart/_id_

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Delete Chart call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Path Parameters

The Delete Chart API call supports one path parameter as indicated in the syntax line above:

Path parameter Type Description
id string The system assigned identifier of an existing Chart object.

Payload

The Delete Chart API call does not support a request payload.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Delete Chart call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Delete Chart call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The Delete Chart API call does not send a response payload.

Errors

Documentation about errors will be provided in a future revision.

Notes

Any additional notes relevant to this call will be provided in a future revision.

Examples

Examples will be provided in a future revision.

Suggest Edits

Dashboards Overview

Dashboards are a grouping of charts organized to display together and subject to the same filtering options.

 

Dashboards are a grouping of charts organized to display together and subject to the same filtering options. Dashboards are a 12x100 grid with one or more charts assigned to specific grid locations. A chart associated with the dashboard may be any size from 1x1 to 12x3; if charts are assigned overlapping dashboard locations an attempt to resize or automatically reorganize the layout is made to ensure all of charts fit within the allotted space.

Every dashboard must belong to a dashboard group. This is a one-to-many relationship; each dashboard belongs to one and only one dashboard group but a dashboard group may contain multiple dashboards. If an existing dashboard group is not specified when a dashboard is created, a container dashboardgroup object is also created for the new dashboard object. Although the dashboard group ID is stored in the dashboard to ensure that one exists, the dashboard group -> dashboard relationship is officially managed by the containing dashboard group; the dashboards property of the associated dashboardgroup object is the system of record for determining which dashboards belong to which dashboard group. For more information on dashboard groups, see the Dashboard Groups Overview.

Similarly, the dashboard object is the system of record for the one-to-many dashboard->charts relationship. The relationship itself is stored in the charts property and many of the other properties of a dashboard object are designed to control the display of the underlying charts associated with the dashboard. For more information about charts, see the Charts Overview. More information about the specific properties of the dashboard object can be found in the payload sections of individual API calls.

Existing dashboards can also be cloned into additional dashboard groups with or without minor modifications. Any dashboard can be cloned including built-in dashboards and user specific dashboards. If you test or develop new dashboards in your user specific dashboard group, you would promote them to production when ready using a Clone Dashboard into Dashboard Group call. Similarly, if you want to modify a built-in dashboard to better suit your needs you would clone it first then edit the cloned version however you wish.

When a dashboard is deleted, the underlying charts are orphaned. They are essentially in the same state as when they are newly created and may be added to a new dashboard if desired. However, when a dashboard group is deleted, the underlying dashboards are automatically deleted as well, as are the charts associated with those dashboards.

Write Permissions

Anyone within an organization may edit or delete dashboards by default. Organizations which have the write permissions feature enabled may limit edits and deletions of specific dashboards to individuals and/or teams. This is useful for preventing unauthorized or accidental modifications to dashboards and the charts within them. If a user does not have access to edit a dashboard or a chart within a dashboard, they may clone it for modifications, leaving the original intact. Administrators always have the ability to modify write permissions, even for dashboards which they don't have permission to edit; this allows administrators the ability to escalate their access for any dashboard.

Dashboards created by API calls can be directly viewed in the web application using their id property as follows:

https://app.signalfx.com/#/dashboard/_id_

and will also appear by name in the catalog and in their associated dashboard group.

Types of Dashboards

SignalFx supports three types of dashboards:

Built-in Dashboards

Built-in dashboards are not editable but are returned in Get Dashboard and Get Dashboards calls. Built-in dashboards all have their creator property set to the system user ID "AAAAAAAAAAA".

In addition, these dashboards typically have descriptive names and descriptions.

The charts associated with built-in dashboards are all v1 charts and are not accessible via SignalFx API calls. To interact with these charts you must use the web application.

Every organization starts with dashboards related to their organization and a set of dashboards with sample data. Additional built-in dashboards are added with each integration added to the organization.

User Default Dashboards

Part of the new user account creation process involves setting up a new dashboard (and associated new dashboard group) for that user. This dashboard is a place where that user can experiment, develop, and tweak dashboards before they're ready for wider use.

User default dashboards are created automatically when a user is invited to an organization and can be updated after creation. They are returned in Get Dashboard and Get Dashboards calls and can be identified as follows:

  • The name of the dashboard is the email address of the associated user
  • The description of the dashboard is "Default dashboard."
  • The creator property of the dashboard is set to the associated user's ID (instead of the system user ID used for most actions taken directly by the system)
  • The chartDensity property is set to DEFAULT
  • All other user-settable properties are null by default

NOTE: Every user in the organization has the ability to edit every user's default dashboard. We strongly recommend that each user manage their own user default dashboard and that users only modify their own user dashboard not those associated with other users in the organization but this is not enforced by the system.

Custom Dashboards

All dashboards created via the SignalFx API are custom dashboards. These are the production dashboards used by an organization to monitor their systems. There are two types of custom dashboards:

Standard Dashboards

Standard Dashboards are created using the Create Dashboard API call and provide full control of the number of included charts and their layout to their creator. They also support filters and event overlays for finer control over the chart data displayed within the dashboard. Standard dashboards are typically references just as dashboards with no additional qualifier.

Simple Dashboards

Simple Dashboards are dashboards created using the Create Simple Dashboard API call. This submits new chart object definitions without any additional information. These chart definitions are turned into new chart objects and added to a new dashboard in a new dashboard group using a default layout. The resulting simple dashboard contains no filters or event overlays.

Once created, a simple dashboard is indistinguishable from a standard dashboard that doesn't define filters or event overlays and that uses the default simple dashboard layout rules; both types of dashboards are stored in the dashboard object type. If desired, layout adjustments can be made and filters and event overlays can be added to simple dashboards using Update Dashboard calls. However, the expectation is that dashboards requiring significant deviation from the simple dashboard defaults will be created as standard dashboards.

Suggest Edits

Create Dashboard

The Create Dashboard API call creates a new v2 dashboard object.

 

The Create Dashboard API call creates a new v2 dashboard object. Dashboards act as a container for one or more charts to be displayed in a single view in the web application. In turn, dashboards are contained within dashboard groups that link similar or related groups together in the web application.

Every dashboard must belong to a dashboard group. This is a one-to-many relationship; each dashboard belongs to one and only one dashboard group but a dashboard group may contain multiple dashboards. If an existing dashboard is not specified in the groupId property of the Create Dashboard request payload, a container dashboardgroup object is also created for the new dashboard object. Automatically created dashboardgroup objects will use the same name as the dashboard generating its creation, have an empty string for its description, and set the user ID associated with the Create Dashboard call as its creator; its ID will be returned in the groupId property of the response to the Create Dashboard call. Although the dashboard group ID is stored in the dashboard to ensure that one exists, the dashboard group -> dashboard relationship is officially managed by the containing dashboard group and the dashboards property of the associated dashboardgroup object is the system of record for determining which dashboards belong to which dashboard group. The dashboards property of an automatically created dashboardgroup object will contain the ID of the new dashboard it was created to contain.

Once created, a dashboard will appear within its dashboard group in the web application and be individually viewable via the dashboard interface described in the SignalFx web application documentation here. It will also be listed by name in the dashboard section of the catalog for the relevant organization.

For more information on dashboards including the types of dashboards, see the Dashboards Overview.

Syntax

POST https://api.signalfx.com/v2/dashboard

Request Format

The request consists of the call path above, HTTP headers, and a JSON object payload in the body.

Headers

The following HTTP headers are required for the Create Dashboard call:

Header Description
Content-Type Indicates the format of the request payload. Must be set to application/json; charset=utf8
X-SF-Token A valid token for the relevant organization.

Payload

The following properties are supported in the request payload for the Create Dashboard call:

Property Type Constraints Description
authorizedWriters object
  • Organization must have the write permissions feature enabled
Contains IDs of users and teams who have permission to edit or delete this dashboard or the charts within it. When null (the default value) anyone may edit the dashboard or charts within it. Administrators cannot edit a dashboard without write permissions for it. However, they may always edit the authorizedWriters property to grant themselves (or others) such permissions, allowing them to make edits in subsequent API calls. The properties of the included object are indicated as authorizedWriters.propertyName in this documentation.
authorizedWriters.teams list of strings
  • Organization must have the write permissions feature enabled
IDs of teams who have permission to edit or delete this dashboard or the charts within it.
authorizedWriters.users list of strings
  • Organization must have the write permissions feature enabled
IDs of users who have permission to edit or delete this dashboard or the charts within it.
chartDensity enumerated string
  • Supported values are: DEFAULT, LOW, HIGH, HIGHEST
  • Default value is DEFAULT
Controls the number of data points displayed in the chart over the specified time span (x-axis). DEFAULT maps to approximately 60 data points, LOW maps to approximately 30 data points, HIGH maps to approximately 120 data points, and HIGHEST maps to approximately 240 data points.
charts list of objects None An array of charts associated with the dashboard. Each chart is identified by its object ID and accompanied by positioning information indicating the preferred location of the chart within the dashboard (this is just a preference; if possible this preference will be respected but the dashboard will automatically calculate the layout based on a variety of factors and may override specific positioning requests if needed to make the full dashboard display viable). The properties of the included objects are indicated as charts[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the charts array.
charts[x].chartId string
  • Required
  • Must map to a valid chart object
  • Must be unique across all dashboards
The ID of a valid chart object to add to this dashboard. Charts may only belong to one dashboard so this ID must be unique across all dashboards.
charts[x].column integer
  • Required
  • Minimum value = 0
  • Maximum value = 11
A 0-based index into the horizontal position of the chart on the dashboard. The value represents the left-most edge of the chart. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 11 will be treated as if 11 were specified when the dashboard is displayed in the web application. If that column is already occupied in the specified row, the chart will be displayed in the first free row from the top in the specified column.
charts[x].height integer
  • Required
  • Minimum value = 1
  • Maximum value = 3
The number of rows this chart should span. The maximum value is not currently enforced by the API but any value greater than 3 will be treated as if 3 were specified. If the total height of all specified charts in a column is greater than 100, the layout will be recalculated to fit all specified charts into the display
charts[x].row integer
  • Required
  • Minimum value = 0
  • Maximum value = 99
A 0-based index into the vertical position of the chart on the dashboard. The value represents the top-most edge of the chart. Vertical gaps are not allowed on the dashboard; charts will fall upward as needed to fill these gaps. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 99 will be treated as if 0 were specified when the dashboard is displayed in the web application. If the 0 position is already occupied, the chart will be displayed in the first free row from the top in the specified column.
charts[x].width integer
  • Required
  • Minimum value = 1
  • Maximum value = 12
The number of columns this chart should span. The maximum value is not currently enforced by the API but any value greater than 12 will be treated as if 12 were specified. If the total width of all specified charts in a row is greater than 100, the layout will be recalculated to fit all specified charts into the display
customProperties object
  • maximum length of key = 128 characters
  • key name may only contain alphabetic characters, numerals, underscores ("_"), or hyphens ("-")
  • key name must start with an alphabetic character of either case
  • key name may not start with an underscore ("_"), sf followed by an underscore ("sf_"), aws followed by an underscore ("aws_"), or gcp followed by an underscore ("gcp_")
  • value is required if key is specified
  • value may not be an empty string
  • maximum length of value = 256 characters

NOTE: the key name constraints outlined above may be encapsulated in the following regular expression: ^[a-zA-Z][a-zA-Z0-9_-]*$
Reserved for future use
description string
  • Default is empty string
A description of the dashboard. Displays in the tooltip for the dashboard's tab in the dashboard group in the web application.
eventOverlays list of objects None A list of event overlay definitions that could be applied to all of the charts on this dashboard. When applied, all active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. The objects in this list map to the suggested event overlays in the web application; they are not applied as active overlays by default. To set default active event overlays, use the selectedEventOverlays property instead. The properties of the included objects are indicated as eventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the eventOverlays array.
eventOverlays[x].eventLine boolean
  • Default is false
Indicates whether a vertical line should be displayed in the plot at the time the event occurs.
eventOverlays[x].eventSignal object
  • Required
The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as eventOverlays[x].eventSignal.propertyName in this documentation.
eventOverlays[x].eventSignal.eventSearchText string
  • Required
The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
eventOverlays[x].eventSignal.eventType enumerated string
  • Supported values are: detectorEvents and eventTimeSeries
Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
eventOverlays[x].eventColorIndex integer
  • Default value=0
The color used for the event marker and, if turned on, the event line on the plot. The list of 16 supported colors is as follows by default:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f

Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
eventOverlays[x].label string None The text displaying in the dropdown menu used to select this event overlay as an active overlay for the dashboard.
eventOverlays[x].overlayId string None A unique ID for this event overlay. This ID can be used by any element of the selectedEventOverlays property to apply this overlay to a dashboard. This property will be generated if it is not defined.
eventOverlays[x].sources list of objects
  • Must contain at least one element if specified
Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as eventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
eventOverlays[x].sources[y].NOT boolean
    Default is false
If true, only data that does not match the specified value of the specified property appear in the event overlay. If false, only positive matches of the specified value of the specified property appear in the overlay.
eventOverlays[x].sources[y].property string
  • Required
The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the eventOverlays[x].sources[y].NOT property is set to true.
eventOverlays[x].sources[y].value list of strings
  • Required
  • Minimum elements = 1
A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
filters object None A set of filters applied to the dashboard. Filters allow fine grained control over the data displayed in the charts within the dashboard. They can be adhoc or saved as variables to allow easy reuse of filter criteria. Filters can also be used to apply a custom time window to all of the charts in the dashboard. The properties of the included object are indicated as filters.propertyName in this documentation.
filters.sources list of objects
  • Must contain at least one element if specified
Each element represents an adhoc filter to apply to the charts within the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as filters.sources[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
filters.sources[x].NOT boolean
  • Default is false
If true, only data that does not match the specified value of the specified property appear in the charts of this dashboard. If false, only positive matches of the specified value of the specified property appear in the charts.
filters.sources[x].applyIfExists boolean
  • Default is false
If true, data that either matches the specified value of the specified property or does not have the specified property will appear in the charts of this dashboard. If false, only matches of the specified value of the specified property appear in the charts.
filters.sources[x].property string
  • Required
The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches and could result in suppressing all data in the associated charts if the filters.sources[x].NOT property is set to true.
filters.sources[x].value list of strings
  • Required
  • Minimum elements = 1
A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
filters.time object None The time range to show in all charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart. The properties of the included objects are indicated as filters.time.propertyName in this documentation.
filters.time.end enumerated string or integer
  • Must be an integer if filters.time.start is an integer
  • Must be a string if filters.time.start is a string
  • If integer:
    • Minimum value = 0
    • Value must be larger than value of filters.time.start
  • If string:
    • Allowed value is Now
The end of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
filters.time.start string or integer
  • Must be an integer if filters.time.end is an integer
  • Must be a string if filters.time.end is a string
  • If integer:
    • Minimum value = 0
    • Value must be smaller than value of filters.time.end
  • If string:
    • Value must start with a negative sign
    • A positive integer must follow the negative sign
    • Value must end with a units indicator. Allowed units indicators are m, h, d, w representing minutes, hours, days, and weeks respectively
The start of the time range to show in all charts in the dashboard. This value overrides the settings in individual charts in the dashboard. If no value is supplied, the individual chart settings are used for each chart.
filters.variables list of objects
  • Must contain at least one element if specified
A set of predefined filters that are available by default at the top of the dashboard.The properties of the included objects are indicated as filters.variables[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the variables array.
filters.variables[x].alias string
  • Required
The handle to this variable filter. The alias will display as a label preceding the input textarea for the variable in the web application; you may wish to append a space followed by a colon (":") to the desired text value to crystalize this relationship in the UI.
filters.variables[x].applyIfExists boolean
  • Default is false
If true, data that either matches the specified value of the specified property or does not have the specified property will appear in the charts of this dashboard. If false, only matches of the specified value of the specified property appear in the charts.
filters.variables[x].preferredSuggestions list of strings None A list of values to place at the top of the suggested values dropdown for this variable filter in the web application. If filters.variables[x].restricted is set to true, the value of the filter will be restricted to one of the values supplied in this property.
filters.variables[x].property string
  • Required
The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the charts associated with the dashboard the filter criteria will never have any matches.
filters.variables[x].required boolean
  • Default is false
If true this filter must be set to display any data in the dashboard. If false the filter can be removed from the dashboard.
filters.variables[x].restricted boolean
  • Default is false
If true, only the values set in the filters.variables[x].preferredSuggestions property are valid values for the filter criteria.
filters.variables[x].value list of strings
  • Must contain at least one element if specified
A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.
groupId string None The ID of the dashboard group to associate with this dashboard. If no value is supplied a new dashboard group is created and its ID is assigned to this property as part of processing the create request.
maxDelayOverride integer
  • Minimum value is 0
  • Maximum value is 900000 (15 minutes)
The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the charts in the dashboard. This value will override the individual max delay setting for every chart in the dashboard, but it will not change the settings of the charts. If this value is not specified, the chart settings will be used. The default for each chart is to detect and apply a sensible value automatically. This option can be explicitly chosen as the override for the dashboard by setting the property to 0.
name string
  • Required
  • Minimum characters = 1
The name of the dashboard. This value is used to identify the dashboard within its dashboard group in the web application.
selectedEventOverlays list of objects None A list of event overlays currently applied to all of the charts on this dashboard. All active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. To set inactive options for easy future selection of event overlays, use the eventOverlays property instead. The properties of the included objects are indicated as selectedEventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the selectedEventOverlays array.
selectedEventOverlays[x].eventSignal object
  • Required
The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as selectedEventOverlays[x].eventSignal.propertyName in this documentation.
selectedEventOverlays[x].eventSignal.eventSearchText string
  • Required
The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
selectedEventOverlays[x].eventSignal.eventType enumerated string
  • Supported values are: detectorEvent and eventTimeSeries
Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
selectedEventOverlays[x].overlayId string None Indicates this overlay should use the specific event overlay definition represented by an element of the eventOverlays property with the matching ID value.
selectedEventOverlays[x].sources list of objects
  • Must contain at least one element if specified
Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as selectedEventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
selectedEventOverlays[x].sources[y].NOT boolean
    Default is false
If true, only data that does not match the specified value of the specified property appear in the event overlay.
selectedEventOverlays[x].sources[y].property string
  • Required
The name of the custom property or dimension to filter against. If the value does not map to a valid custom property or dimension defined in one or more of the events associated with the dashboard the filter criteria will never have any matches. This could result in suppressing all events if the selectedEventOverlays[x].sources[y].NOT property is set to true.
selectedEventOverlays[x].sources[y].value list of strings
  • Required
  • Minimum elements = 1
A list of values to check in the filter. If more than one value is specified, they are combined into an OR query; matching any one of the values triggers the filter.

Response Format

The response consists of an HTTP status code, HTTP headers, and a JSON object payload in the body.

Status Code

Successful responses to the Create Dashboard call will return a 200 OK status code. The status codes supported in error responses are discussed below under Errors.

Headers

The following HTTP headers may be included in responses to the Create Dashboard call:

Header Default Description
Access-Control-Allow-Credentials true Indicates that the response can be exposed to the user even if they've authenticated with a front end client using cookies.
Access-Control-Allow-Origin user agent making the request Indicates which URIs may access the results of the request.
Access-Control-Expose-Headers Date Indicates which response headers may be exposed to front end clients
Connection keep-alive Indicates that a single connection should be used for a series of API calls rather than opening a new connection for each call then closing it as soon as the call completes.
Content-Encoding gzip Indicates that the payload is compressed using the GNU zip format.
Content-Type application/json Indicates the format of the response payload. In general, the result will use JSON as indicated by either "application/json" or "application/json; charset=utf8" but some error responses currently use "text/html" or "text/plain" instead.
Date time response sent timestamp of response in Day, DD Month YYYY HH:mm:SS GMT format
Transfer-Encoding chunked Indicates that the response is sent in non-overlapping chunks that may be independently sent and received.
Vary Accept-Encoding, User-Agent Indicates that the content sent in the response may be encoded or compressed differently depending on the source of the request. This is primarily used to inform caching agents whether content is static or may vary depending on the request settings.
X-Content-Type-Options nosniff Indicates that front end clients should not attempt to determine the data format and adjust the content-type to match their expectations.

Payload

The following properties are returned in the response payload for the Create Dashboard call:

Property Type Contexts Returned Description
authorizedWriters object Organization must have the write permissions feature enabled Contains IDs of users and teams who have permission to edit or delete this dashboard or the charts within it. When null (the default value) anyone may edit the dashboard or charts within it. Administrators cannot edit a dashboard without write permissions for it. However, they may always edit the authorizedWriters property to grant themselves (or others) such permissions, allowing them to make edits in subsequent API calls. The properties of the included object are indicated as authorizedWriters.propertyName in this documentation.
authorizedWriters.teams list of strings Organization must have the write permissions feature enabled IDs of teams who have permission to edit or delete this dashboard or the charts within it.
authorizedWriters.users list of strings Organization must have the write permissions feature enabled IDs of users who have permission to edit or delete this dashboard or the charts within it.
chartDensity enumerated string All Controls the number of data points displayed in the chart over the specified time span (x-axis). DEFAULT maps to approximately 60 data points, LOW maps to approximately 30 data points, HIGH maps to approximately 120 data points, and HIGHEST maps to approximately 240 data points.
charts list of objects All An array of charts associated with the dashboard. Each chart is identified by its object ID and accompanied by positioning information indicating the preferred location of the chart within the dashboard (this is just a preference; if possible this preference will be respected but the dashboard will automatically calculate the layout based on a variety of factors and may override specific positioning requests if needed to make the full dashboard display viable). The properties of the included objects are indicated as charts[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the charts array.
charts[x].chartId string All The ID of a valid chart object to add to this dashboard. Charts may only belong to one dashboard so this ID must be unique across all dashboards.
charts[x].column integer All A 0-based index into the horizontal position of the chart on the dashboard. The value represents the left-most edge of the chart. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 11 will be treated as if 11 were specified when the dashboard is displayed in the web application. If that column is already occupied in the specified row, the chart will be displayed in the first free row from the top in the specified column.
charts[x].height integer All The number of rows this chart should span. The maximum value is not currently enforced by the API but any value greater than 3 will be treated as if 3 were specified. If the total height of all specified charts in a column is greater than 100, the layout will be recalculated to fit all specified charts into the display
charts[x].row integer All A 0-based index into the vertical position of the chart on the dashboard. The value represents the top-most edge of the chart. Vertical gaps are not allowed on the dashboard; charts will fall upward as needed to fill these gaps. If more than one chart is supplied with the same combination of column and row, the dashboard will attempt to automatically reconfigure the layout. If space allows, the dashboards will retain the column value and spread out over additional rows. The maximum value is not currently enforced by the API but any value greater than 99 will be treated as if 0 were specified when the dashboard is displayed in the web application. If the 0 position is already occupied, the chart will be displayed in the first free row from the top in the specified column.
charts[x].width integer All The number of columns this chart should span. The maximum value is not currently enforced by the API but any value greater than 12 will be treated as if 12 were specified. If the total width of all specified charts in a row is greater than 100, the layout will be recalculated to fit all specified charts into the display
created integer All The time the member object was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.
creator string All The user ID of the administrator requesting that the invitation be sent. This value is always set by the system. If the object was created by the system, the value is "AAAAAAAAAA" This value is always set by the system.
customProperties object All Reserved for future use
description string All A description of the dashboard. Displays in the tooltip for the dashboard's tab in the dashboard group in the web application.
discoveryOptions object All Reserved for system use.
eventOverlays list of objects All A list of event overlay definitions that could be applied to all of the charts on this dashboard. When applied, all active events matching the specified search term and an optional filter are displayed on all charts in the dashboard using the specified color and, if selected, with lines extending the vertical span of the plot. The objects in this list map to the suggested event overlays in the web application; they are not applied as active overlays by default. To set default active event overlays, use the selectedEventOverlays property instead. The properties of the included objects are indicated as eventOverlays[x].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the eventOverlays array.
eventOverlays[x].eventLine boolean All Indicates whether a vertical line should be displayed in the plot at the time the event occurs.
eventOverlays[x].eventSignal object All The search term used to find events of the specified type to be overlaid on the charts in this dashboard. The properties of the included object are indicated as eventOverlays[x].eventSignal.propertyName in this documentation.
eventOverlays[x].eventSignal.eventSearchText string All The name or partial name of an event to suggest as an overlay on the charts in this dashboard.
eventOverlays[x].eventSignal.eventType enumerated string All Indicates whether the event comes from a detector or a time series. Other event types are reserved for future use and should not be sent in request payloads.
eventOverlays[x].eventColorIndex integer All The color used for the event marker and, if turned on, the event line on the plot. The list of 16 supported colors is as follows by default:
  • 0: #999999
  • 1: #0077c2
  • 2: #00b9ff
  • 3: #6ca2b7
  • 4: #b04600
  • 5: #f47e00
  • 6: #e5b312
  • 7: #bd468d
  • 8: #e9008a
  • 9: #ff8dd1
  • 10: #876ff3
  • 11: #a747ff
  • 12: #ab99bc
  • 13: #007c1d
  • 14: #05ce00
  • 15: #0dba8f

Different colors may be presented to users with one of the color blind settings selected. For sample swatches of the colors and the mappings used for color blind users, see the color palette documentation at the bottom of the Charts Overview.
eventOverlays[x].label string All The text displaying in the dropdown menu used to select this event overlay as an active overlay for the dashboard.
eventOverlays[x].overlayId string All A unique ID for this event overlay. This ID can be used by any element of the selectedEventOverlays property to apply this overlay to a dashboard. This property will be generated if it is not defined.
eventOverlays[x].sources list of objects All Each element represents a filter to apply to the events overlaid on the charts in the dashboard. Each filter can key off of one dimension or custom property (either user defined or supplied by default) and can either include or exclude all data matching the supplied criteria. The properties of the included objects are indicated as eventOverlays[x].sources[y].propertyName in this documentation; this notation means the propertyName property is part of the object in each element of the sources array.
eventOverlays[x].sources[y].NOT boolean All If true, only data that does not match the specified value of the specified property appear in the event overlay. If false, only positive matches of the specified value of the specified property appear in the overlay.
eventOverlays[x].sources[y].property string All</