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

 
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.

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

  • Dimension name:

    • has a maximum length of 128 characters

    • may not start with _ or sf_

    • 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 value can be any non-empty UTF-8 string, with a maximum length <= 256 characters

SignalFx will reject any datapoint request that doesn't meet the above 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.

 

All the examples in this document are shown using the httpie command-line utility, which provides very convenient interactions with JSON-based HTTP REST APIs.

If you need to send historical data, SignalFx provides a distinct "backfill" API endpoint at https://backfill.signalfx.com/v1/backfill 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 (e.g. 7:00 AM to 8:00AM, 9:00PM to 3:00AM). It is recommended that each call contains a few thousand datapoints (e.g. 1 day or 1-min resolution points, or 1 hour of 1-sec 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 each 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.

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?query=query
$ 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
}

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

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

 

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

Detector Model

 

A detector is a collection of rules that define who should be notified when certain detect functions within SignalFlow fire alerts. Each rule maps a detect label to a severity and a list of notifications. When the conditions within the given detect function are fulfilled, notifications will be sent to the destinations defined in the rule for that detect function.

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.

Detector Model

Property
Type
Description

id

String

ID of the detector

name

String

Name of the detector

description

String

Description for the detector

rules

List of Rules

Rules that bind detect blocks in the program text to notification destinations

programText

String

Signalflow program text for the detector

maxDelay

Long

Used to handle late datapoints. Upper limit is 15 minutes( 900000) see help documentation for details

visualizationOptions

Visualization options to use when viewing the detector in the SignalFx web UI

tags

List of Strings

Tags associated with the detector

teams

List of Team IDs

Team IDs to associate the detector to.

Rule Model

Property
Type
Description

detectLabel

String

A detectLabel which matches a detect label within the program text.

description

String

(optional) Human-readable description for this rule.

severity

SeverityType

The severity of the rule, must be one of: Critical, Warning, Major, Minor, Info.

disabled

boolean

(false by default) When true, notifications and events will not be generated for the detect label.

notifications

Array of Notifications

See the Notifications models below. Determines where notifications will be sent when an incident occurs.

parameterizedBody

String

Custom notification message body 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". For an example message, see Detector update. To use the variables available, surround the variables with double brackets {{ variable }}. Triple brackets can be used to indicate that this variable value will not get escaped. For a full list of available variables, go to the documentation.

parameterizedSubject

String

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". For an example message, see Detector update. To use the variables available, surround the variables with double brackets {{ variable }}. Triple brackets can be used to indicate that this variable value will not get escaped. For a full list of available variables, go to the documentation.

Notifications Models

Email

Property
Type
Description

type

String

Must be "Email"

email

String

The email address to send the notification to

PagerDuty

Property
Type
Description

type

String

Must be "PagerDuty"

credentialId

String

ID of a PagerDuty credential

Slack

Property
Type
Description

type

String

Must be "Slack"

credentialId

String

ID of a Slack credential

channel

String

A Slack channel name

HipChat

Property
Type
Description

type

String

Must be "HipChat"

credentialId

String

ID of a HipChat credential

room

String

A HipChat room name

VictorOps

Property
Type
Description

type

String

Must be "VictorOps"

credentialId

String

ID of a VictorOps credential

routingKey

String

A VictorOps routing key

Webhook

Property
Type
Description

type

String

Must be "Webhook"

url

String

The URL to call

secret

String

(Optional) When provided, the HTTP request will contain a X-SFX-Signature header containing the Base64 encoded HMAC-SHA1 digest of the request body using the shared secret.

Team

Property
Type
Description

type

String

Must be "Team"

team

String

ID of a team

TeamEmail

Property
Type
Description

type

String

Must be "TeamEmail"

team

String

ID of a team

VisualizationOptions Model

Property
Type
Description

time

Controls the time span visualized.

showDataMarkers

boolean

(false by default) When true, markers will be drawn for each datapoint within the visualization.

TimeConfig

Property
Type
Description

type

string

Must be "relative" or "absolute". The type of time span defined.

range

long

(relative only) The time range prior to now to visualize, in milliseconds. For example, 60000 would visualize the last 60 seconds.

start

long

(absolute only) Milliseconds since epoch.

end

long

(absolute only) Milliseconds since epoch.

Suggest Edits

/detector

Return information for all or specified detectors

 

Header Auth

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

You couldn't be authenticated

{
  "count": 1,
  "results": [{
    "id": "...",
    "name": "My detector",
    "tags": ["mytag"],
    ...
  }]
}

Query Params

name
string

A name or part of a name for detectors to search for

tags
string

Tag names that detectors must have to be returned (use multiple query parameters to filter by multiple tags). All given tags must be present on a detector for it to be returned.

offset
int32

Offset of results to return

limit
int32

Number 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

Create a detector

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/detector
# Consider using detector/validate before posting your detector
# See https://developers.signalfx.com/v2/docs/detectorvalidate
$ curl \
  --request POST \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @- \
  https://api.signalfx.com/v2/detector << EOF
{
  "name": "CPU load too high",
  "programText": "detect(data('jvm.cpu.load') > 50).publish('Load above 50%')",
  "rules": [{
    "severity": "Critical",
    "detectLabel": "Load above 50%",
    "notifications": [{ "type": "Email", "email": "person@example.com" }]
  }]
}
EOF
A binary file was returned

You couldn't be authenticated

{
    "created": 1470704945599,
    "creator": "ABCDEFGHIJ",
    "customProperties": {},
    "description": null,
    "id": "ABCDEFGHIJ",
    "lastUpdated": 1470705776335,
    "lastUpdatedBy": "ABCDEFGHIJ",
    "maxDelay": null,
    "name": "CPU load too high",
    "programText": "detect(data('jvm.cpu.load') > 50).publish('Load above 50%')",
    "rules": [
        {
            "description": null,
            "detectLabel": "Load above 50%",
            "disabled": false,
            "notifications": [
                {
                    "type": "Email",
                    "email": "person@example.com"
                }
            ],
            "severity": "Critical"
        }
    ],
    "tags": [],
    "visualizationOptions": null
}

Body Params

name
string

The name of the detector

programText
string

SignalFlow program text for the detector

rules
array
description
string

(optional) A human-readable description for the detector

maxDelay
int64

(optional) How long to wait for late datapoints, in milliseconds (see SignalFx web UI documentation for details)

visualizationOptions
object
 
tags
array of strings

(optional) List of tags to associate with the detector

 
Suggest Edits

/detector/:id

Get a detector

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/detector/id
$ curl \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  https://api.signalfx.com/v2/detector/ABCDEF123456
{
    "created": 1470704945599,
    "creator": "ABCDEFGHIJ",
    "customProperties": {},
    "description": null,
    "id": "ABCDEF123456",
    "lastUpdated": 1470705776335,
    "lastUpdatedBy": "ABCDEFGHIJ",
    "maxDelay": null,
    "name": "CPU load too high",
    "programText": "detect(data('jvm.cpu.load') > 50).publish('Load above 50%')",
    "rules": [
        {
            "description": null,
            "detectLabel": "Load above 50%",
            "disabled": false,
            "notifications": [
                {
                    "type": "Email",
                    "email": "person@example.com"
                }
            ],
            "severity": "Critical"
        }
    ],
    "tags": [],
    "visualizationOptions": null
}
A binary file was returned

You couldn't be authenticated

{
    "created": CREATED_ON_TIMESTAMP,
    "creator": CREATOR_ID,
    "customProperties": CUSTOM_PROPERTIES_MAP,
    "description": DESCRIPTION_TEXT,
    "id": DETECTOR_ID,
    "lastUpdated": LAST_UPDATED_ON_TIMESTAMP,
    "lastUpdatedBy": LAST_UPDATED_BY_ID,
    "maxDelay": MAX_DELAY_VALUE,
    "name": NAME_OF_DETECTOR,
    "programText": SIGNALFLOW_PROGRAM,
    "rules": [
        {
            "description": RULE_DESCRIPTION,
            "detectLabel": SIGNALFLOW_DETECT_LABEL,
            "enabled": RULE_ENABLED_STATE,
            "notifications": RULE_NOTIFICATIONS,
            "severity": RULE_SEVERITY
        }
    ],
    "tags": DETECTOR_TAGS,
    "visualizationOptions": VISUALIZATION_OPTIONS
}

Path Params

id
string
required

(Required) ID of detector

 

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

Update a detector

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/detector/id
# Consider using detector/validate before updating your detector
# See https://developers.signalfx.com/v2/docs/detectorvalidate
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @- \
  https://api.signalfx.com/v2/detector/ABCDEFGHIJ <<EOF
{
  "name": "CPU load too high",
  "programText": "detect(data('jvm.cpu.load') > 50).publish('Load above 50%')",
  "rules": [{
    "severity": "Critical",
    "detectLabel": "Load above 50%",
    "notifications": [{ "type": "Email", "email": "person@example.com" }]
    "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: {{{readableRule}}}\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}}"
  }]
}
EOF
A binary file was returned

You couldn't be authenticated

{
    "authorizedWriters": {
        "teams": [],
        "users": []
    },
    "created": 1507735007857,
    "creator": "ABCDEFGHIJ",
    "customProperties": {},
    "description": "",
    "id": "ABCDEFGHIJ",
    "labelResolutions": {
        "Load above 50%": 1000
    },
    "lastUpdated": 1507735366261,
    "lastUpdatedBy": "ABCDEFGHIJ",
    "locked": false,
    "maxDelay": null,
    "name": "CPU load too high",
    "overMTSLimit": false,
    "packageSpecifications": "",
    "programText": "detect(data('jvm.cpu.load') > 50).publish('Load above 50%')",
    "rules": [
        {
            "description": null,
            "detectLabel": "Load above 50%",
            "disabled": false,
            "notifications": [
                {
                    "type": "Email",
                    "email": "person@example.com"
                }
            ],
            "parameterizedBody": "{{#if anomalous}}\nRule \"{{{ruleName}}}\" in detector \"{{{detectorName}}}\" triggered\n{{else}}\nRule \"{{{ruleName}}}\" in detector \"{{{detectorName}}}\" cleared{{/if}}\n\n{{#if anomalous}}\nTriggering condition: {{{readableRule}}}\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}}",
            "parameterizedSubject": "{{ruleSeverity}} Alert: {{{ruleName}}} {{{detectorName}}}",
            "severity": "Critical"
        }
    ],
    "tags": [],
    "teams": [],
    "visualizationOptions": null
}

Path Params

id
string
required

Body Params

name
string

The name of the detector

programText
string

Signalflow program text for the detector

rules
array
description
string

(optional) A human-readable description for the detector

maxDelay
int64

(optional) How long to wait for late datapoints, in milliseconds (see SignalFx web UI documentation for details)

visualizationOptions
object
 
tags
array of strings

(optional) List of tags to associate with the detector

 

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

Delete a detector and clear all of its active alerts

 

Header Auth

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

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

(Required) ID of detector

 

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

Enable all or part of a detector

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/detector/id/enable
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '["my detect label"]' \
  https://api.signalfx.com/v2/detector/ABCDEFGHIJ/enable
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

Body Params

body
array of strings

List of detect labels to enable. If no list is provided, all detect functions will be enabled.

 

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

Disable all or part of a detector

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/detector/id/disable
$ curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '["my detect label"]' \
  https://api.signalfx.com/v2/detector/ABCDEFGHIJ/disable
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

Body Params

body
array of strings

List of detect labels to disable. If no list is provided, all detect functions will be disabled.

 

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

/detector/validate

Validating a detector before posting it is recommended.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/detector/validate
$ curl \
  --request POST \
  --header "X-SF-Token: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @- \
  https://api.signalfx.com/v2/detector/validate << EOF
{
  "name": "CPU load too high",
  "programText": "detect(data('jvm.cpu.load') > 50).publish('Load above 50%')",
  "rules": [{
    "severity": "Critical",
    "detectLabel": "Load above 50%",
    "notifications": [{ "type": "Email", "email": "person@example.com" }]
  }]
}
EOF
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

name
string

The name of the detector

programText
string

SignalFlow program text for the detector

rules
array
description
string

(optional) A human-readable description for the detector

maxDelay
int64

(optional) How long to wait for late datapoints, in milliseconds (see SignalFx web UI documentation for details)

visualizationOptions
object
 
tags
array of strings

(optional) List of tags to associate with the detector

 
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

isActive

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

Events associated with the incident

duration

long

For resolved incidents, milliseconds elapsed between the triggering event and the resolving event.

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

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

{
  "count": 1,
  "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

stopTime
int64

Stop time of muting period in milliseconds since epoch

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

stopTime
int64

Stop time of muting period in milliseconds since epoch

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

Chart Model

 

API supports only v2 charts

Chart APIs are supported only for v2 charts. A v2 chart is one that was created using the SignalFx v2 API.

Chart Model

Property
Type
Description

id

String

ID of the chart

name

String

Name of the chart

description

String

Description of the chart

options

Options to configure the behavior of the chart, depending on type. Type can be "TimeSeriesChart", "SingleValue", "List", "Text", or "Heatmap" (Creating an event feed chart is not currently supported.)

programText

String

Signalflow program text for the chart. Required for types TimeSeriesChart, SingleValue, List, HeatmapChart

ChartOptions Model

TimeSeriesChart

Property
Type
Description

type

String

Always "TimeSeriesChart"

unitPrefix

String (default "Metric")

Must be "Metric" or "Binary"

colorBy

String (default "Dimension")

Must be "Dimension" or "Metric"

programOptions

Options specific to how the program underlying the visualization should be run

time

Time configuration for this chart

axes

List of AxisOptions

Axis options

legendOptions

Legend options

showEventLines

Boolean (default false)

Whether vertical highlight lines should be drawn in the visualizations at times when events occurred

lineChartOptions

Options specific to plots displayed in line charts

areaChartOptions

Options specific to plots displayed in area charts

stacked

Boolean (default false)

Whether area and bar charts in the visualization should be stacked

defaultPlotType

String (default "LineChart")

The default plot display style for the visualization. Must be "LineChart", "AreaChart", "ColumnChart", or "Histogram".

publishLabelOptions

Plot-level customization options, associated with a publish statement.

axisPrecision

Integer

Force a specific number of significant digits in the y-axis.

onChartLegendOptions

Options regarding on-chart-legend

AreaChartOptions

Property
Type
Desciption

showDataMarkers

Boolean (default false)

Show markers (circles) for each datapoint used to draw area charts.

LineChartOptions

Property
Type
Description

showDataMarkers

Boolean (default false)

Show markers (circles) for each datapoint used to draw line charts.

AxisOptions

Property
Type
Description

min

Number

The minimum value for the axis

max

Number

The maximum value for the axis

label

String

Label of the axis

highWatermark

Number

A line to draw as a high watermark

lowWatermark

Number

A line to draw as a low watermark

LegendOptions

Property
Type
Description

fields

List of FieldOptions

List of fields to display in the legend

FieldOptions

Property
Type
Description

property

String

Property that may be a part of a metric time series in the visualization

enabled

Boolean

Whether the property should be displayed in the legend

TimeConfig

Property
Type
Description

type

String

"absolute" or "relative"

range

Integer

(type "relative" only) Absolute millisecond offset from now to visualize.

start

Integer

(type "absolute" only) Milliseconds since epoch to start the visualization.

end

Integer

(type "absolute" only) Milliseconds since epoch to end the visualization.

PublishLabelOptions

Property
Type
Description

label

String

The label used in the publish statement that displays the plot (metric time series data) you want to customize.

yAxis

Integer

The Y-axis associated with values for this plot. 0 (Left) or 1 (Right).

paletteIndex

Integer

The indexed palette color (0-15) to use for all plot lines. See PaletteColor.

plotType

String

The visualization style to use. Must be "LineChart", "AreaChart", "ColumnChart", or "Histogram".

displayName

String

An alternate name to show in the legend, instead of the publish label. Often used to identify this stream of data in a user readable manner.

OnChartLegendOptions

Property
Type
Description

showLegend

Boolean

Whether the on-chart-legend is shown on the chart

dimensionInLegend

String

The dimension used to label the plots in the legend

PaletteColor

Index Hex Code Color Sample
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

Heatmap

Property
Type
Description

type

String

Always "Heatmap"

colorBy

String (default "Range")

Must be "Range" or "Scale". Range maps to Auto and Scale maps to Fixed in the UI.

unitPrefix

String (default "Metric")

Must be "Metric", or "Binary"

programOptions

Options specific to how the program underlying the visualization should be run.

groupBy

List of Strings

Properties to group by in the heatmap (in nesting order)

sortProperty

String

The property to use when sorting the elements.

sortDirection

String (default "Ascending")

"Ascending" or "Descending"

colorRange

Values and color for the color range.

colorScale

Values for each color in the range

timestampHidden

Boolean (default false)

Whether to show the timestamp in the chart.

ColorRange

Property
Type
Description

min

Double

The minimum value within the coloring range.

max

Double

The maximum value within the coloring range.

color

String

The color range to use.

colorRange : { min : 0, max : 100, color : "#00FF00" }

ColorScale

Property
Type
Description

thresholds

List<Double>

The thresholds to set for the color range being used. Values must be in descending order.

inverted

Boolean (default false)

If false or omitted, values are red if they are above the highest specified value. If true, values are red if they are below the lowest specified value.

colorScale : { thresholds : [100, 50, 0] }

colorScale : { thresholds : [80, 60, 40, 20, 0], inverted : true }

SingleValue

Property
Type
Description

type

String

Always "SingleValue"

colorBy

String (default "Metric")

Must be "Metric", "Dimension", or "Scale". "Scale" maps to Color by Value in the UI.

unitPrefix

String (default "Metric")

Must be "Metric" or "Binary"

programOptions

Options specific to how the program underlying the visualization should be run.

refreshInterval

Integer

How often (in milliseconds) to refresh the values of the list.

maximumPrecision

Integer

The maximum precision to for values displayed in the list.

timestampHidden

Boolean (default false)

Whether to hide the timestamp in the chart.

showSparkLine

Boolean (default false)

Whether to show a trend line below the current value.

colorScale

Values for each color in the range.

publishLabelOptions

Plot-level customization options

List

Property
Type
Desciption

type

String

Always "List"

colorBy

String (default "Metric")

Must be "Metric" or "Dimension"

unitPrefix

String (default "Metric")

Must be "Metric", or "Binary"

programOptions

Options specific to how the program underlying the visualization should be run.

sortBy

String

A property of the metric time series to sort by.

refreshInterval

Integer

How often (in milliseconds) to refresh the values of the list.

legendOptions

Configurations for the labels in shown in the list.

maximumPrecision

Integer

The maximum precision to for values displayed in the list.

publishLabelOptions

Per-publish label visualization customization options.

ProgramOptions Model

Text

Property
Type
Description

minimumResolution

Integer

The minimum resolution to use for computing the underlying program

maxDelay

Integer

How long to wait for late datapoints, in ms. Upper limit is 900000 (15 minutes).

disableSampling

Boolean (default false)

If false, samples a subset of the output MTS, which improves UI performance.

Property
Type
Description

type

String

Always "Text"

markdown

String

Markdown text to display. Required.

Suggest Edits

/chart

Return information for all or specified charts

 

Header Auth

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

You couldn't be authenticated

{
  "count": 1,
  "results": [{
    "id": "...",
    "name": "mysql chart",
    ...
  }]
}

Query Params

name
string

A name or part of a name for charts to search for

tags
string

Tag names that charts must have to be returned (use multiple query parameters to filter by multiple tags). All given tags must be present on a chart for it to be returned.

offset
int32

Offset of results to return

limit
int32

Number of results to return

 

API supports only v2 charts

Chart APIs are supported only for v2 charts. A v2 chart is one that was created using the SignalFx v2 API.

Suggest Edits

/chart

Create a chart

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/chart
$ curl \
  --request POST \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data-binary @- \
  https://api.signalfx.com/v2/chart << EOF
{
  "name": "CPU load",
  "programText": "data('cpu.load').publish()"
}
EOF
A binary file was returned

You couldn't be authenticated

{
    "created": 1477347160569,
    "creator": "BqDQY5OAAAA",
    "description": "",
    "id": "CvkFy8TAIAA",
    "lastUpdated": 1477347160569,
    "lastUpdatedBy": "BqDQY5OAAAA",
    "name": "CPU load",
    "options": {
        "type": "TimeSeriesChart",
        "areaChartOptions": null,
        "axes": null,
        "colorBy": "Dimension",
        "defaultPlotType": "LineChart",
        "legendOptions": null,
        "lineChartOptions": null,
        "programOptions": null,
        "showEventLines": false,
        "stacked": false,
        "time": null,
        "unitPrefix": "Metric"
    },
    "programText": "data('cpu.load').publish()"
}

Body Params

body
object
required

A Chart Model

 
 

test

API supports only v2 charts

Chart APIs are supported only for v2 charts. A v2 chart is one that was created using the SignalFx v2 API.

Suggest Edits

/chart/:id

Get a chart

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/chart/id
curl \
  --request GET \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  https://api.signalfx.com/v2/chart/ID_OF_CHART
A binary file was returned

You couldn't be authenticated

{
    "created": 1477347160569,
    "creator": "BqDQY5OAAAA",
    "description": "",
    "id": "CvkFy8TAIAA",
    "lastUpdated": 1477347160569,
    "lastUpdatedBy": "BqDQY5OAAAA",
    "name": "CPU load",
    "options": {
        "type": "TimeSeriesChart",
        "areaChartOptions": null,
        "axes": null,
        "colorBy": "Dimension",
        "defaultPlotType": "LineChart",
        "legendOptions": null,
        "lineChartOptions": null,
        "programOptions": null,
        "showEventLines": false,
        "stacked": false,
        "time": null,
        "unitPrefix": "Metric"
    },
    "programText": "data('cpu.load').publish()"
}

Path Params

id
string
required

ID of the chart

 

API supports only v2 charts

Chart APIs are supported only for v2 charts. A v2 chart is one that was created using the SignalFx v2 API.

Suggest Edits

/chart/:id

Update a chart

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/chart/id
curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data \
  '{
  	"name": "CPU load",
  	"programText": "data('cpu.load').publish()"
	}' \
  https://api.signalfx.com/v2/chart/ID_OF_CHART
A binary file was returned

You couldn't be authenticated

{
    "created": 1477347160569,
    "creator": "BqDQY5OAAAA",
    "description": "",
    "id": "CvkFy8TAIAA",
    "lastUpdated": 1477347160569,
    "lastUpdatedBy": "BqDQY5OAAAA",
    "name": "CPU load",
    "options": {
        "type": "TimeSeriesChart",
        "areaChartOptions": null,
        "axes": null,
        "colorBy": "Dimension",
        "defaultPlotType": "LineChart",
        "legendOptions": null,
        "lineChartOptions": null,
        "programOptions": null,
        "showEventLines": false,
        "stacked": false,
        "time": null,
        "unitPrefix": "Metric"
    },
    "programText": "data('cpu.load').publish()"
}

Path Params

id
string
required

ID of the chart

Body Params

body
object
required

A Chart Model

 
 

API supports only v2 charts

Chart APIs are supported only for v2 charts. A v2 chart is one that was created using the SignalFx v2 API.

Suggest Edits

/chart/:id

Delete a chart

 

Header Auth

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

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

ID of the chart

 

API supports only v2 charts

Chart APIs are supported only for v2 charts. A v2 chart is one that was created using the SignalFx v2 API.

Suggest Edits

Dashboard Model

 

API supports all dashboards

Unlike the chart APIs, the dashboard APIs can be used with dashboards created in the SignalFx web UI as well as with dashboards created using the v2 API.

Dashboard Model

Property
Type
Description

id

String

The unique ID of the dashboard

groupId

String

The ID of the dashboard group that contains the dashboard. If an ID is not provided during creation, the dashboard will be placed in a newly created dashboard group

name

String

Name of the dashboard

description

String

Description of the dashboard

filters

Filters to apply to the charts when displaying the dashboard

charts

Chart IDs and layout information for the charts in the dashboard

chartDensity

String (optional)

Specifies the chart data display resolution for charts in this dashboard. Value can be one of "DEFAULT", "LOW", "HIGH", or "HIGHEST".

eventOverlays

List of EventOverlays

List of event overlays available for this dashboard

selectedEventOverlays

List of event overlays actively selected for display on this dashboard

DashboardChart Model

The DashboardChart model specifies which charts (by chartId) should be displayed in the dashboard, along with layout information determining where on the dashboard the charts should be displayed.

Property
Type
String

chartId

String

ID of the chart to display

row

Integer (greater than or equal to 0)

The row to show the chart in (zero-based); if height > 1, this value represents the topmost row of the chart

column

Integer (between 0 and 11)

The column to show the chart in (zero-based); this value always represents the leftmost column of the chart

width

Integer (between 1 and 12)

How many columns (out of a total of 12) the chart should take up

height

Integer (greater than or equal to 1)

How many rows the chart should take up

DashboardFilters Model

Property
Type
String

sources

List of SourceFilters

Filters to apply to each chart in the dashboard

variables

Dashboard variables to apply to each chart in the dashboard

time

The time range the charts in the dashboard should reflect. This value overrides individual chart time ranges.

SourceFilter Model

Property
Type
String

property

String

A metric time series dimension or property name

NOT

Boolean

Whether this filter should be a "not" filter.

value

String or List of Strings

A string or a JSON list of strings (which will be treated as an OR filter on the property).

VariableFilter Model

Dashboard variables let you pin frequently used filters to the dashboard, removing the guesswork about which dimensions or properties to use.. For example, creating a dashboard variable for "region" would display a filter field named "region" at the top of the dashboard, and the user could choose a value for “region” from a dropdown list.

Property
Type
String

property

String

A metric time series dimension or property name

alias

String

An alias for the dashboard variable. This text will appear as the label for the dropdown field on the dashboard

value

String or List of Strings

A string or a JSON list of strings (which will be treated as an OR filter on the property).

required

Boolean (optional, default: false)

Determines whether a value is required for this variable (and therefore whether it will be possible to view this dashboard without this filter applied).

preferredSuggestions

List of Strings (optional)

a JSON list of strings of suggested values for this variable; these suggestions will receive priority when values are autosuggested for this variable.

restricted

Boolean (optional, default: false)

If true, this variable may only be set to the values listed in preferredSuggestions. and only these values will appear in autosuggestion menus.

TimeFilter Model

The time filter can either be defined as an absolute range or a relative range. For absolute ranges both the start and end properties should be integers, for relative ranges they should be strings.

Property
Type
String

start

Integer (absolute ranges only)

Milliseconds since epoch to start displaying data

end

Integer (absolute ranges only)

Milliseconds since epoch to end displaying data

start

String (relative ranges only)

A time string, a combination of a negative symbol, an integer, and a unit ("m" for minutes, "h" for hours, or "d" for days). Example: "-5h"

end

String (relative ranges only)

(Optional) Must be "Now".

EventOverlay Model

Property
Type
Description

eventSignal

The event signal information for this event overlay.

eventColorIndex

Integer

The index of the color of this event overlay.

sources

List of SourceFilter

The filters to apply to the event time series selected for the event overlay.

label

String

A label identifying the event overlay. This text will represent the event overlay in SIgnalFx UI elements such as selection dropdown menus.

eventLine

Boolean

If true, event lines are shown when this this event overlay is displayed on a dashboard. If false, no event lines are shown.

EventSignal Model

Property
Type
Description

eventType

String

Type of this event (either “eventTimeSeries” or “detectorEvents”).

eventSearchText

String

The string used to search events for matches to associate with this event overlay.

SelectedEventOverlay Model

eventSignal

The event signal information for this event overlay.

sources

List of SourceFilter

The filters to apply to the event time series selected for the event overlay.

Suggest Edits

/dashboard

Return information for all or specified dashboards

 

Header Auth

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

You couldn't be authenticated

{
  "count": 1,
  "results": [{
    "id": "...",
    "name": "Mysql dashboard",
    ...
  }]
}

Query Params

name
string

A name or part of a name for dashboards to search for

offset
int32

Offset of results to return

limit
int32

Number of results to return

 
Suggest Edits

/dashboard

Create a dashboard

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/dashboard
curl \
  --request POST \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data \
  '{
  	"name": "My new dashboard",
  	"charts": [
    	{
      	"chartId": "CvkFy8TAIAA",
        "row": 0,
        "column": 0,
        "height": 1,
        "width": 6
      }
    ]
	}' \
  https://api.signalfx.com/v2/dashboard
A binary file was returned

You couldn't be authenticated

{
    "charts": [
        {
            "chartId": "CvkFy8TAIAA",
            "row": 0,
            "column": 0,
            "height": 1,
            "width": 6
        }
    ],
    "created": 1477349028264,
    "creator": "BqDQY5OAAAA",
    "description": "",
    "filters": null,
    "groupId": "CvkFzXtAIAA",
    "id": "CvkFzX7AEAA",
    "lastUpdated": 1477349028362,
    "lastUpdatedBy": "BqDQY5OAAAA",
    "name": "My new dashboard"
}

Body Params

body
object
required

A Dashboard Model

 
 

If a dashboard is created without a groupId, a new dashboard group will be created for it.

Suggest Edits

/dashboard/:id

Get a dashboard

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/dashboard/id
curl \
  --request GET \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  https://api.signalfx.com/v2/dashboard/ID_OF_DASHBOARD
A binary file was returned

You couldn't be authenticated

{
    "charts": [
        {
            "chartId": "CvkGG1vAAAA",
            "column": 0,
            "height": 1,
            "row": 0,
            "width": 6
        }
    ],
    "created": 1477349028264,
    "creator": "BqDQY5OAAAA",
    "description": "",
    "filters": null,
    "groupId": "CvkFzXtAIAA",
    "id": "CvkFzX7AEAA",
    "lastUpdated": 1477349028362,
    "lastUpdatedBy": "BqDQY5OAAAA",
    "name": "my dashboard"
}

Path Params

id
string
required

ID of the dashboard

 
Suggest Edits

/dashboard/:id

Update a dashboard

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/dashboard/id
curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data \
  '{
  	"name": "DevOps Dashboard",
  	"groupId": "GROUP_ID_OF_DASHBOARD",
  	"charts": [
    	{
      	"chartId": "CHART_ID_TO_ADD_TO_DASHBOARD",
        "column": 0,
        "height": 1,
        "row": 0,
        "width": 6
      }
    ]
	}' \
  https://api.signalfx.com/v2/dashboard/ID_OF_DASHBOARD
A binary file was returned

You couldn't be authenticated


{
  "charts" : [ {
    "chartId" : "CzBVssgAAAA",
    "column" : 0,
    "height" : 1,
    "row" : 0,
    "width" : 6
  } ],
  "created" : 1481063549059,
  "creator" : "Cc_RMPFAAAM",
  "customProperties" : { },
  "description" : "",
  "filters" : null,
  "groupId" : "CzBYGmwAAAA",
  "id" : "CzBYGu6AIAA",
  "lastUpdated" : 1481064990656,
  "lastUpdatedBy" : "BqDQY5OAAAA",
  "name" : "DevOps Dashboard",
  "tags" : [ ]
}

Path Params

id
string
required

ID of dashboard

Body Params

body
object
required

A Dashboard Model

 
 
Suggest Edits

/dashboard/:id/lock

Sets a dashboard to Read-Only status, preventing edits until it is either unlocked via the API or set to allow edits in the UI.

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/dashboard/id/lock
curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  https://api.signalfx.com/v2/dashboard/ID_OF_DASHBOARD/lock
A binary file was returned

You couldn't be authenticated

{
  "chartDensity" : "HIGH",
  "charts" : [ {
    "chartId" : "C9aJ6C8AIAA",
    "column" : 0,
    "height" : 1,
    "row" : 0,
    "width" : 4
  } ],
  "created" : 1492212550393,
  "creator" : "CqqXlCNAAAg",
  "customProperties" : null,
  "description" : "Demonstrating read-only dashboard endpoints",
  "discoveryOptions" : null,
  "filters" : {
    "sources" : null,
    "time" : {
      "end" : "Now",
      "start" : "-12h"
    },
    "variables" : [ {
      "alias" : "Service",
      "description" : null,
      "preferredSuggestions" : [ ],
      "property" : "aws_tag_service",
      "required" : false,
      "restricted" : false,
      "value" : ""
    } ]
  },
  "groupId" : "CqqXlDhAIAA",
  "id" : "ID_OF_DASHBOARD",
  "lastUpdated" : 1493941554594,
  "lastUpdatedBy" : "CqqXlCNAAAg",
  "locked" : true,
  "name" : "Locking Demo",
  "tags" : null
}

Path Params

id
string
required

ID of dashboard

 

For more information on read-only status, see the SignalFx documentation.

Suggest Edits

/dashboard/:id/unlock

Allow edits to a dashboard that was either locked via the API or set to Read-Only status via the UI.

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/dashboard/id/unlock
curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  https://api.signalfx.com/v2/dashboard/ID_OF_DASHBOARD/unlock
A binary file was returned

You couldn't be authenticated

{
  "chartDensity" : "HIGH",
  "charts" : [ {
    "chartId" : "C9aJ6C8AIAA",
    "column" : 0,
    "height" : 1,
    "row" : 0,
    "width" : 4
  } ],
  "created" : 1492212550393,
  "creator" : "CqqXlCNAAAg",
  "customProperties" : null,
  "description" : "Demonstrating read-only dashboard endpoints",
  "discoveryOptions" : null,
  "filters" : {
    "sources" : null,
    "time" : {
      "end" : "Now",
      "start" : "-12h"
    },
    "variables" : [ {
      "alias" : "Service",
      "description" : null,
      "preferredSuggestions" : [ ],
      "property" : "aws_tag_service",
      "required" : false,
      "restricted" : false,
      "value" : ""
    } ]
  },
  "groupId" : "CqqXlDhAIAA",
  "id" : "ID_OF_DASHBOARD",
  "lastUpdated" : 1493941554594,
  "lastUpdatedBy" : "CqqXlCNAAAg",
  "locked" : false,
  "name" : "Locking Demo",
  "tags" : null
}

Path Params

id
string
required

ID of dashboard

 

For more information on read-only status, see the SignalFx documentation.

Suggest Edits

/dashboard/:id

Delete a dashboard

 

Header Auth

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

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

ID of dashboard to delete

 

Charts which are a part of the dashboard are not deleted when the dashboard is deleted.

Suggest Edits

/dashboard/simple

A helper endpoint that creates a dashboard from a list of new chart models

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/dashboard/simple
curl \
  --request POST \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data \
  '[{
  	"name": "my jvm.cpu.load chart", 
  	"programText": "data('jvm.cpu.load').publish()"
  }]' \
  https://api.signalfx.com/v2/dashboard/simple?name=testdashboard
A binary file was returned

You couldn't be authenticated

{
    "charts": [
        {
            "chartId": "Cvtdr8oAEAA",
            "column": 0,
            "height": 1,
            "row": 0,
            "width": 6
        }
    ],
    "created": 1477505196319,
    "creator": "BqDQY5OAAAA",
    "description": "",
    "filters": null,
    "groupId": "Cvtdr9SAAAA",
    "id": "Cvtdr9hAIAA",
    "lastUpdated": 1477505196375,
    "lastUpdatedBy": "BqDQY5OAAAA",
    "name": "testdashboard"
}

Query Params

name
string

The name for the dashboard; if not provided, the name of the first chart will be used as the dashboard name.

groupId
string

The ID of the dashboard group to add the dashboard to; if not provided, a new dashboard group will be created.

Body Params

body
array
required

A list of chart models

 
Suggest Edits

Dashboard Groups Overview

Overview of dashboard groups and cloning a dashboard into a dashboard group

 

In the SignalFx web UI, a dashboard group is a collection of dashboards. A dashboard, which is a curated collection of specific charts, supports dimensional filters, dashboard variables and time range options. These options are applied to all charts in the dashboard, providing a consistent view of the data displayed in that dashboard. This also means that when you open a chart to drill down for more details, you are viewing the same data that is visible in the dashboard view.

This section contains APIs you can use to create a new dashboard group and clone an existing dashboard and its filters into a specified dashboard group.

Cloning a dashboard is particularly useful when a dashboard has been created that can be used as a template. That is, a dashboard has been created that needs to be used by various teams but with different filters, dashboard variables, and/or time ranges. These values can be overridden with new values when cloning the dashboard.

Suggest Edits

Dashboard Group Model

 

DashboardGroup Model

Property
Type
Description

id

String

Unique ID of the dashboard group

name

String

Name of the dashboard group

description

String

Description of the dashboard group

dashboards

List of dashboard IDs

Dashboards that are a part of the dashboard group

teams

List of Team IDs

Teams which are related to this dashboard group

Suggest Edits

/dashboardgroup

Return information for all or specified dashboard groups

 

Header Auth

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

You couldn't be authenticated

{
  "count": 1,
  "results": [{
    "id": "...",
    "name": "My dashboard group",
    ...
  }]
}

Query Params

offset
int32

Offset of results to return

limit
int32

Number of results to return

name
string
 
Suggest Edits

/dashboardgroup

Create a new dashboard group

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/dashboardgroup
curl \
  --request POST \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "name" : "Kafka", "description": "Dashboards showing Kafka metrics by service", "dashboards": ["AAAAAAAAAAA"] }' \
  https://api.signalfx.com/v2/dashboardgroup
A binary file was returned

You couldn't be authenticated

{
"creator" : "BqR13zSAAAA",
"lastUpdatedBy" : "BqR13zSAAAA",
"created" : 1461635401795,
"lastUpdated" : 1461635401795,
"id": "Cg1LvHfAAAA",
"name": "Kafka",
"description": "Dashboards showing Kafka metrics by service", 
"dashboards": ["AAAAAAAAAAA"]
}

Body Params

name
string
required

Name of dashboard group

description
string

Description for dashboard group

dashboards
array of strings
required

List of dashboard IDs for dashboards in this group

 
Suggest Edits

/dashboardgroup/:id

Retrieve a dashboard group

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/dashboardgroup/id
curl \
  --request GET \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  https://api.signalfx.com/v2/dashboardgroup/ID_OF_DASHBOARD_GROUP
A binary file was returned

You couldn't be authenticated

{
"creator" : "BqR13zSAAAA",
"lastUpdatedBy" : "BqR13zSAAAA",
"created" : 1461635401795,
"lastUpdated" : 1461635401795,
"id": "Cg1LvHfAAAA",
"name": "Kafka",
"description": "Dashboards showing Kafka metrics by service",
"dashboards": ["AAAAAAAAAAA"]
}

Path Params

id
string
required

ID of the dashboard group

 
Suggest Edits

/dashboardgroup/:id

Update a dashboard group

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/dashboardgroup/id
curl \
  --request PUT \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "name" : "Kafka", "description": "Dashboards showing Kafka metrics by service", "dashboards": ["AAAAAAAAAAA"] }' \
  https://api.signalfx.com/v2/dashboardgroup/ID_OF_DASHBOARD_GROUP
A binary file was returned

You couldn't be authenticated

{
"creator" : "BqR13zSAAAA",
"lastUpdatedBy" : "BqR13zSAAAA",
"created" : 1461635401795,
"lastUpdated" : 1461635401795,
"id": "Cg1LvHfAAAA",
"name": "Kafka",
"description": "Dashboards showing Kafka metrics by service",
"dashboards": ["AAAAAAAAAAA"]
}

Path Params

id
string
required

ID of the dashboard group

Body Params

name
string
required

Name of dashboard group

description
string

Description for dashboard group

dashboards
array of strings
required

List of dashboard IDs for the dashboard group

 
Suggest Edits

/dashboardgroup/:id

Delete a dashboard group

 

Header Auth

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

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

ID of the dashboard group

 
Suggest Edits

/dashboardgroup/:id/dashboard

Clone a dashboard into a dashboard group with optional overriding filters

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/dashboardgroup/id/dashboard
DESTINATION_DASHBOARD_GROUP_ID="Cg1LvHfAAAA"
curl \
  --request POST \
  --header "X-SF-TOKEN: YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ 
    "sourceDashboard": "CerIh9pAAAQ", 
    "filters": { 
      "sources": [
          {
            "property": "aws_availablility_zone",
            "value": "us-east-1a"
          } 
      ] 
    } 
  }' \
  https://api.signalfx.com/v2/dashboardgroup/$DESTINATION_DASHBOARD_GROUP_ID/dashboard
A binary file was returned

You couldn't be authenticated

{
  "id": "Cg1LvHiAIAA"
}

Response ID is that of the cloned dashboard.

Path Params

id
string
required

ID of destination dashboard group

Body Params

sourceDashboard
string
required

ID of source dashboard that should be cloned

name
string

name to use for new cloned dashboard

description
string

description of new cloned dashboard

filters
object

filters to use for the cloned dashboard

 
 

Specifying filters

filters : {
sources : [list of source-filters], (optional, can be empty, null or not specified at all),
variables : [list of variables to override], (optional, can be empty, null or not specified at all),
time : { time range }
}


Specifying sources

A source filter is a property and corresponding value definition. Its JSON format is;
{
property : "property name",
value : "property value",
NOT : true | false (optional boolean indicating whether to invert the filter)
}

example
restrict charts to show data from AWS availability zone us-east-1a
{ property : "aws_availability_zone", value : "us-east-1a" }

allow charts to show all data except from AWS availability zone us-east-1a
{ property : "aws_availability_zone", value : "us-east-1a", NOT : true }


Overriding variables

Variables are source filters, pre-defined for the dashboard by its curator. Variables have user friendly names, called an 'alias' - this hides technical property names. New variables cannot be introduced at the time of cloning a dashboard, however, values for existing variables can be overridden.
Its JSON format is;
{
alias : "original variable alias",
property : "original variable property name",
value : "new value to use for this variable"
}
Variables do not support inverting the condition with a NOT.

example
If the source dashboard has a variable alias 'AZ' for property 'aws_availability_zone', and if the cloned dashboard needs to show data from 'us-east-1b' - here's how to override the variable filter.
{ alias : "AZ", property : "aws_availability_zone", value : "us-east-1b" }


Specifying time

Time range is the duration for which charts should show data. This can be a relative period such as for the last hour, or, an absolute period such as from a specific date to another date.
Its JSON format is;
{
start : "relative start time"
}
or,
{
start : "absolute UTC representing a start date",
end : "absolute UTC representing an end date"
}

Relative time supported units are;
'm' minute, 'h' hour, 'd' day, 'w' week, 'M' month
Values for relative time should match the regex /^-(\d+[mhdwM])+$/

example
last 6 hours { start : "-6h" }
last 3 hours and 45 minutes { start : "-3h45m" }, or, { start : "-45m3h" }
when using multiple time units, order of magnitude/unit is not relevant.

from 04/13/2016 12:00:00 am to 04/22/2016 12:00:00 am
{ start : "1460530800000", end : "1461308400000" }

Suggest Edits

Integrations Overview

 

SignalFx offers support for a broad range of integrations to:

  • collect data from other monitoring systems
  • let your users log in to SignalFx using your existing Single Sign-on system
  • send out alerts using your preferred messaging, chat or incident management service

In order to use these integrations, they must be registered with SignalFx and then configured to enable the systems to communicate. The APIs in this section allow you to automate the management of these integrations.

Suggest Edits

AWS Integration

 

Setting up an AWS Integration is a two step process.

Very similar to SAML integrations, first, create the AWSCloudWatch integration as you would for any other integrations.

curl \
	--request POST \
  --header 'X-SF-Token: YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --url https://api.signalfx.com/v2/integration
  --data \
  '{
  		"type": "AWSCloudWatch",
      "name": YOUR_INTEGRATION_NAME,
      "authMethod": "ExternalId",
      "pollRate": 60000,
      "services": [],
      "regions": []
      ...
   }'

You will see that externalId was populated for this integration.

{
    "type": "AWSCloudWatch",
    "authMethod": "ExternalId",
    "enabled": true,
    "externalId": YOUR_EXTERNAL_ID,
    "id": THIS_INTEGRATION_ID,
    "name": "AWS",
    "pollRate": 60000,
    "regions": [],
    "roleArn": null,
    "services": []
}

Using the External ID and the SignalFx Account ID, users can now create a role in AWS Cloud Watch (similar to UI)

With the created roleArn from AWS, update the AWSCloudWatch Integration.

curl \
	--request PUT \
  --header 'X-SF-Token: YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --url https://api.signalfx.com/v2/integration
  --data \
  '{
  		"type": "AWSCloudWatch",
      "name": YOUR_INTEGRATION_NAME,
      "id": THIS_INTEGRATION_ID,
      "externalId": YOUR_EXTERNAL_ID,
      "roleArn": YOUR_ROLE_ARN,
      "authMethod": "ExternalId",
      "pollRate": 60000,
      "services": [],
      "regions": []
      ...
   }'
Suggest Edits

AWS CloudWatch Integration Model

 
Property
Type
Description

id

String

ID of the integration

name

String

Name of the integration

enabled

Boolean

Indicates whether the integration is enabled or disabled

authMethod

String

"ExternalId" or "SecurityToken"

roleArn

String

ARN linked to the external id (when using authMethod "ExternalId")

externalId

String

External ID of this integration (when using authMethod "ExternalID")

key

String

AWS Secret Access Key (when using authMethod "SecurityToken")

token

String

AWS Access Key ID (when using authMethod "SecurityToken")

pollRate

long

Rate that we poll AWS API in milliseconds. (Only 60000 and 300000 allowed)

services

List<String>

List of namespaces for SignalFx to monitor

regions

List<String>

List of regions for SignalFx to monitor

importCloudWatch

Boolean

Indicates whether SignalFx should import CloudWatch metrics

Suggest Edits

GCP Integration

 

Setting up GCP Integration

To create a GCP Integration in Signalfx, you'll need to create a new service account key for SignalFx to use on the GCP website. For detailed instructions on how to configure GCP and how to get the project service account key, see SignalFx documentation.

After retrieving the service account key for each project you want to monitor in SignalFx, create a GCP Integration object using the Create Integration call.

POST /v2/integration HTTP/1.1
Host: api.signalfx.com
X-SF-TOKEN: <adminToken>
Content-Type: application/json; charset=utf8

{
"type" : "GCP",
"name" : "YOUR_INTEGRATION_NAME_HERE",
"pollRate" : 60000,
"services" : ["LIST_OF_SERVICES_TO_MONITOR"],
"projects" : [{
"projectId": "YOUR_FIRST_PROJECT_ID",
"projectKey": "YOUR_JSON_PROJECT_KEY"
} , {
"projectId": "YOUR_SECOND_PROJECT_ID",
"projectKey": "YOUR_JSON_PROJECT_KEY"
}]
}

The expected response is:

{
    "type": "GCP",
    "name" : "YOUR_INTEGRATION_NAME_HERE",
    "pollRate" : 60000,
    "services" : [],
    "id" : INTEGRATION_ID,
    "projects" : [{
      "projectId": "YOUR_FIRST_PROJECT_ID"
    }, {
      "projectId": "YOUR_SECOND_PROJECT_ID"
    }]
}

Note: the json project key is dropped for security purposes.

Suggest Edits

GCP Integration Model

 

GCP Integration Model

Property
Type
Description

id

String

ID of the integration

name

String

Name of the integration

enabled

boolean

Whether the integration is enabled or not

pollRate

long

Rate that we poll GCP in milliseconds. (Only 60000 and 300000 allowed)

services

List of Strings

List of GCP Services for SignalFx to monitor. An API error will be thrown if the service does not map to a supported GCP service. Supported GCP services include "appengine", "bigquery", "bigtable", "cloudfunctions", "cloudiot", "cloudsql", "cloudtasks", "compute", "container", "dataflow", "datastore", "firebasedatabase", "firebasehosting", "interconnect", "loadbalancing", "logging", "ml", "monitoring", "pubsub", "router", "serviceruntime", "spanner", "storage", "vpn".

projects

List of GCPProjects

List of GCP Projects that this integration is monitoring

GCP Project

Property
Type
Description

projectId

String

ID of the GCP Project

projectKey

String

Service Account Key associated with the project ID. This property is a json string that needs to be properly escaped

Suggest Edits

SAML Integrations

 

Setting up SAML Integration requires a two step process.

First, users can make a POST request to /v2/integration with the correct type of SAML Integration.

curl \
	--request POST \
  --header 'X-SF-Token: YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --url https://api.signalfx.com/v2/integration
  --data \
  '{
    "type": SAML_TYPE,
    "name" : YOUR_INTEGRATION_NAME
  }'

This will create an empty Integration object of the specified type (PingOne, ADFS, Bitium, Okta, or OneLogin). An integration ID will be assigned by default for the object.

{
 	type: "PingOne",
  name: YOUR_INTEGRATION_NAME,
  id: INTEGRATION_ID,
  ...
}

Users can then supply the integration ID to the SAML provider. More information is available here.

After getting all the correct credentials from the different SAML Providers, complete the integration by sending an update request.

curl \
	--request PUT \
  --header 'X-SF-Token: YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --url https://api.signalfx.com/v2/integration/{INTEGRATION_ID}
  --data \
  '{
  	"type": "PingOne",
    "metadata": YOUR_METADATA_HERE,
    "certificateName": YOUR_CERTIFICATE_NAME
  }'
Suggest Edits

PingOne Integration Model

 
Property
Type
Description

id

String

ID of the integration

name

String

Name of the integration

enabled

boolean

Indicates whether the integration is enabled or disabled

metadata

String

certificateName

String

A human readable name for the certificate

metadataName

String

A human readable name for the metadata

publicKey

String

certificate.pem

issuerUrl

String

Issuer URL

metadataUrl

String

URL for the metadata

Suggest Edits

ADFS Integration Model

 
Property
Type
Description

id

String

ID of the integration

type

String

Must be "ADFS"

name

String

Name of the integration

enabled

boolean

Whether the integration is enabled or not

metadata

String

SAML metadata XML file.
FederationMetadata.xml

publicKey

String

public key certificate

issuerUrl

String

Issuer URL

metadataUrl

String

URL for the metadata file

Suggest Edits

Bitium Integration Model

 
Property
Type
Description

id

String

ID of the integration

type

String

Must be "Bitium"

name

String

Name of the Integration

enabled

boolean

Whether the integration is enabled or not

publicKey

String

certificate.pem

issueUrl

String

Issuer URL

metadataUrl

String

URL for the metadata

Suggest Edits

Okta Integration Model

 
Property
Type
Description

id

String

ID of the integration

type

String

Must be "Okta"

name

String

Name of the Integration

enabled

boolean

Whether the integration is enabled or not

publicKey

String

certificate.pem

issueUrl

String

Issuer URL

metadataUrl

String

URL for the metadata

Suggest Edits

OneLogin Integration Model

 
Property
Type
Description

id

String

ID of the integration

type

String

Must be "OneLogin"

name

String

Name of the Integration

enabled

boolean

Whether the integration is enabled or not

publicKey

String

certificate.pem

issueUrl

String

Issuer URL

metadataUrl

String

URL for the metadata

Suggest Edits

HipChat Integration Model

 
Property
Type
Description

id

String

ID of the integration

name

String

Name of the integration

enabled

boolean

Indicates whether the integration is enabled or disabled

Suggest Edits

Slack Integration Model

 
Property
Type
Description

id

String

ID of the integration

name

String

Name of the integration

enabled

boolean

Indicates whether the integration is enabled or disabled

webhookUrl

String

Suggest Edits

PagerDuty Integration Model

 
Property
Type
Description

id

String

ID of the integration

name

String

Name of the integration

enabled

boolean

Indicates whether the integration is enabled or disabled

apiKey

String

type

String

Always "PagerDuty"

Suggest Edits

VictorOps Integration Model

 
Property
Type
Description

id

String

ID of the integration

name

String

Name of the integration

enabled

boolean

Indicates whether the integration is enabled or disabled

postUrl

String

Suggest Edits

NewRelic Integration Model

 
Property
Type
Description

id

String

ID of the integration

name

String

Name of the integration

enabled

boolean

Indicates whether the integration is enabled or disabled

apiKey

String

products

List of Strings

List of PagerDuty products ("APM", "Mobile", "Servers").

Suggest Edits

Webhook Integration Model

 
Property
Type
Description

Id

String

ID of the integration

Name

String

Name of the integration

enabled

Boolean

Indicates whether the integration is enabled or disabled

Url

String

Webhook Url

Shared Secret

String

Headers

Map<String, String>

Suggest Edits

/integration

Create an integration (admins only)

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/integration
curl --request POST \
  --url https://api.signalfx.com/v2/integration
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.signalfx.com/v2/integration' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.signalfx.com/v2/integration")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.signalfx.com/v2/integration");

xhr.send(data);
import requests

url = "https://api.signalfx.com/v2/integration"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

Type
string
required

Type of integration to create. Can be one of: ADFS, AWSCloudWatch, Bitium, HipChat, NewRelic, Okta, OneLogin, PagerDuty, PingOne, Slack, Webhook, or VictorOps.

Name
string

Name of the integration to create

 

Supported Types:

  • PagerDuty
  • Slack
  • VictorOps
  • NewRelic
  • Webhook
  • SAML Integrations
  • AWS integrations
  • HipChat (enable/disable/read/delete only). HipChat connect requires creation through HipChat marketplace here.
Suggest Edits

/integration

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/integration
curl --request GET \
  --url https://api.signalfx.com/v2/integration
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.signalfx.com/v2/integration' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.signalfx.com/v2/integration")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.signalfx.com/v2/integration");

xhr.send(data);
import requests

url = "https://api.signalfx.com/v2/integration"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results

Query Params

name
string

Name of integration(s) to search for. Can be a partial name.

type
string

Types of integrations to search for. Can be one of: ADFS, AWSCloudWatch, Bitium, HipChat, NewRelic, Okta, OneLogin, PagerDuty, PingOne, Slack, or VictorOps.

offset
int32

Offset of results to return

limit
int32

Number of results to return

 
Suggest Edits

/integration/:id

Get an integration

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/integration/:id
curl --request GET \
  --url https://api.signalfx.com/v2/integration/:id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.signalfx.com/v2/integration/:id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.signalfx.com/v2/integration/:id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.signalfx.com/v2/integration/:id");

xhr.send(data);
import requests

url = "https://api.signalfx.com/v2/integration/:id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results
 

We will not return shared secrets (such as API tokens) when reading integrations as a matter of security.

Suggest Edits

/integration/:id

Update an integration (admins only)

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/integration/:id
curl --request PUT \
  --url https://api.signalfx.com/v2/integration/:id
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.signalfx.com/v2/integration/:id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.signalfx.com/v2/integration/:id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api.signalfx.com/v2/integration/:id");

xhr.send(data);
import requests

url = "https://api.signalfx.com/v2/integration/:id"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results
 
Suggest Edits

/integration/:id

Delete an integration (admins only)

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.signalfx.com/v2/integration/:id
curl --request DELETE \
  --url https://api.signalfx.com/v2/integration/:id
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.signalfx.com/v2/integration/:id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.signalfx.com/v2/integration/:id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("DELETE", "https://api.signalfx.com/v2/integration/:id");

xhr.send(data);
import requests

url = "https://api.signalfx.com/v2/integration/:id"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

Try the API to see results
 
Suggest Edits

/integration/aws/external-id

Get AWS Integration External Id

 
gethttps://api.signalfx.com/v2/integration/aws/external-id
curl --request GET \
  --url https://api.signalfx.com/v2/integration/aws/external-id
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.signalfx.com/v2/integration/aws/external-id' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.signalfx.com/v2/integration/aws/external-id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.signalfx.com/v2/integration/aws/external-id");

xhr.send(data);
import requests

url = "https://api.signalfx.com/v2/integration/aws/external-id"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	externalId: YOUR_EXTERNAL_ID,
  signalfxAccountId: YOUR_ACCOUNT_ID
}
 
Suggest Edits

Teams in SignalFx

 

Teams in SignalFx organize groups of users in order to prioritize the display of relevant content throughout the application.

Members of a team will be able to see Detectors and Dashboards that are of particular importance or relevance to them. In addition, teams can be specified as a notification target in detectors to alert all or some team members of the alert along with other notification destinations relevant to the team.

Suggest Edits

Team Model

 

Team Model

Property
Type
Description

id

String

ID of the team

name

String

Name of the team

description

String

Description for the team

members

List of [/organization/member IDs]

Organization Member IDs belonging to this team.

notificationLists

An object which defines the notification targets to use when the team is specified as a alert recipient in a detector.

NotificationLists

The notificationLists property of a team defines the destinations which will receive alerts relevant to the team (detectors for which the team is in the recipient list).

Property
Type
Description

default

List of Notifications

A default set of notification destinations to use for any undefined alert category.

critical

List of Notifications

The set of notification destinations to use for critical alerts.

warning

List of Notifications

The set of notification destinations to use for warning alerts.

major

List of Notifications

The set of notification destinations to use for major alerts.

minor

List of Notifications

The set of notification destinations to use for minor alerts.

info

List of Notifications

The set of notification destinations to use for informational alerts.

Suggest Edits

/team

Search teams by name

 

Header Auth

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

You couldn't be authenticated

{
  "count": 1,
  "results": [{
    "name": "myTeam",
    "members": ["AAAAAAAA"],
    ...
  }]
}

Query Params

name
string

A name or part of a name for charts to search for

offset
int32

Offset of results to return

limit
int32

Number of results to return

orderBy
string
 
Suggest Edits

/team

Creates a team

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/team
$ curl \
  --request POST \
  --header 'X-SF-TOKEN: YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --url https://api.signalfx.com/v2/team \
  --data '{	name: "myTeam",	members: ["ABCDEFGH"]}'
A binary file was returned

You couldn't be authenticated

{
  "name": "myTeam",
  "members": ["ABCDEFGH"],
  ...
}

Body Params

team
object
required
 
team.id
string

ID of the team

team.name
string
required

Name of the team

team.description
string

Description of the team

team.members
array of strings

Organization Member IDs belonging to this team.

team.notificationLists
object

The notification targets to use when the team is specified as a alert recipient in a detector.

 
 
Suggest Edits

/team/:id

Update a team

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/team/id
$ curl \
  --request PUT \
  --header 'X-SF-TOKEN: YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --url https://api.signalfx.com/v2/team/TEAM_ID \
  --data '{name: "newTeamName", members: ["ABCDEFGH"]}'
A binary file was returned

You couldn't be authenticated

{
  "name": "newTeamName",
  "members": ["ABCDEFGH"],
  ...
}

Path Params

id
string
required

The id of a team

Body Params

team
object
required

The updated team object

 
team.id
string

ID of the team

team.name
string
required

Name of the team

team.description
string

Description of the team

team.members
array of strings

Organization Member IDs belonging to this team.

team.notificationLists
object

The notification targets to use when the team is specified as a alert recipient in a detector.

 
 
Suggest Edits

/team/:id

Deletes a team

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.signalfx.com/v2/team/id
$ curl \
  --request DELETE \
  --header 'X-SF-TOKEN: YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --url https://api.signalfx.com/v2/team/TEAM_ID
A binary file was returned

You couldn't be authenticated

{
  "name": "myTeam",
  "members": ["ABCDEFGH"],
  ...
}

Path Params

id
string
required

The id of the team to be deleted.

 
Suggest Edits

/team/:id/members

Adds members to a team.

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/team/id/members
$ curl \
  --request PUT \
  --header 'X-SF-TOKEN: YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --url https://api.signalfx.com/v2/team/myTeam/members \
  --data '{members: ["ABCDEFGH"]}'
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

The id of the team to be updated.

Body Params

members
array of strings

Member ids to add to the team

 
Suggest Edits

/team/:id/members

Remove members from a team.

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.signalfx.com/v2/team/id/members
$ curl \
  --request DELETE \
  --header 'X-SF-TOKEN: YOUR_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --url https://api.signalfx.com/v2/team/myTeam/members \
  --data '{members: ["ABCDEFGH"]}'
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

id
string
required

The id of the team to be modified.

Body Params

members
array of strings

IDs of members to remove from the team

 
Suggest Edits

Organizations Overview

 

Data submitted to SignalFx is associated with one and only one organization. To access the data within an organization, a user must be a member of that organization. Users can belong to multiple organizations, but this is rare. Most users belong to a single SignalFx organization, and can consider it to be their "SignalFx account".

Users are invited to join an organization by an organization administrator. As members of that organization, they can submit data points and use the SignalFx API. They can also create, view and edit information within their organization, such as charts, dashboards, and detectors.

Administrator privileges are required to invite members to an organization, to remove members from an organization, and to enable and disable org access tokens for an organization (see Authentication Overview.

Suggest Edits

/organization

Get the organization object

 

Header Auth

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

{
  "creator" : "ID OF CREATOR OF ORGANIZATION OBJECT",
  "lastUpdatedBy" : "ID OF LAST UPDATER TO ORGANIZATION OBJECT",
  "created" : 1411678090144,
  "lastUpdated" : 1450134705971,
  "id" : "YOUR ORGANIZATION ID",
  "apiAccessToken" : "YOUR ORG ACCESS TOKEN",
  "organizationName" : "NAME OF ORGANIZATION",
  "accountType" : null,
  "accountStatus" : null,
  "accountKey" : null,
  "accountRenews" : false,
  "accountValidUntil" : 0,
  "dpmLimit": 0
}
A binary file was returned

You couldn't be authenticated

{
  "creator" : ID_OF_CREATOR_OF_ORGANIZATION_OBJECT,
  "lastUpdatedBy" : ID_OF_LAST_UPDATER_TO_ORGANIZATION_OBJECT,
  "created" : TIMESTAMP_OF_CREATION,
  "lastUpdated" : TIMESTAMP_OF_LAST_UPDATE,
  "id" : YOUR_ORGANIZATION_ID,
  "apiAccessToken" : ACCESS_TOKEN_FOR_ORG,
  "organizationName" : NAME_OF_ORGANIZATION,
  "accountType" : ACCOUNT_TYPE_OF_ORG,
  "accountStatus" : ACCOUNT_STATUS_OF_ORG,
  "accountKey" : ACCOUNT_KEY_OF_ORG,
  "accountRenews" : ACCOUNT_RENEWAL_STATUS_FOR_ORG,
  "accountValidUntil" : TIMESTAMP_UNTIL_WHICH_ORG_VALID_UNTIL,
  "dpmLimit": DPM_LIMIT_FOR_ORG
}
 
Suggest Edits

/organization/member

Get or search through organization members

 

Header Auth

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

{
  "results" : [ {
    "creator" : "AAAAAAAAAAA",
    "lastUpdatedBy" : "AAAAAAAAAAA",
    "created" : 1421951486399,
    "lastUpdated" : 1447415890650,
    "id" : "B79-ramAgAA",
    "organizationId" : "ByZgBHNAYAA",
    "email" : "user2@company.co",
    "fullName" : "John Doe",
    "phone" : null,
    "title" : "CTO",
    "admin" : true
  }, {
    "creator" : "AAAAAAAAAAA",
    "lastUpdatedBy" : "B3Y5ADeAgAA",
    "created" : 1417036675756,
    "lastUpdated" : 1448489001102,
    "id" : "B3Y5ADsAYAA",
    "organizationId" : "ByZgBHNAYAA",
    "email" : "user1@company.co",
    "fullName" : "Jacob Doe",
    "phone" : null,
    "title" : "Engineer",
    "admin" : false
  } ],
  "count" : 2
}
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,
    "id" : ID_OF_USER,
    "organizationId" : ID_OF_USER_ORG,
    "email" : EMAIL_OF_USER,
    "fullName" : FULL_NAME_OF_USER,
    "phone" : PHONE_NUMBER_OF_USER,
    "title" : TITLE_FOR_USER,
    "admin" : BOOLEAN_OF_USER_ADMIN_STATUS
  },
   //... 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

/organization/member

Invite a user to the organization. Requires administrator privileges in the SignalFx web UI.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/organization/member
# Requires administrator privileges in the SignalFx web UI.
$ curl \
  --request POST \
  --header "X-SF-TOKEN: ADMIN_SESSION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "email" : "newUser@company.co" }' \
  https://api.signalfx.com/v2/organization/member

{
  "creator" : "AAAAAAAAAAA",
  "lastUpdatedBy" : "AAAAAAAAAAA",
  "created" : 1421951486399,
  "lastUpdated" : 1447415890650,
  "id" : "ID OF USER",
  "organizationId" : "ID OF ORG",
  "email" : "newUser@company.co",
  "fullName" : null,
  "phone" : null,
  "title" : null,
  "admin" : false
}
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,
  "id" : ID_OF_USER,
  "organizationId" : ID_OF_USER_ORG,
  "email" : EMAIL_OF_USER,
  "fullName" : FULL_NAME_OF_USER,
  "phone" : PHONE_NUMBER_OF_USER,
  "title" : TITLE_FOR_USER,
  "admin" : BOOLEAN_OF_USER_ADMIN_STATUS
}

Body Params

email
string

Email address of the user

fullName
string

(Optional) Name of the user

title
string

(Optional) Job title of the user

phone
string

(Optional) Phone number of the user

admin
boolean

(Optional) Whether the user is an administrator or not

 

When a user is invited, they will receive a confirmation email from SignalFx which will link them to a page where they can set a password.

Suggest Edits

/organization/member/:userId

Get a user object

 

Header Auth

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

{
  "creator" : "AAAAAAAAAAA",
  "lastUpdatedBy" : "AAAAAAAAAAA",
  "created" : 1421951486399,
  "lastUpdated" : 1447415890650,
  "id" : "ID OF USER",
  "organizationId" : "ID OF ORG",
  "email" : "user@company.co",
  "fullName" : null,
  "phone" : null,
  "title" : null,
  "admin" : false
}
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,
  "id" : ID_OF_USER,
  "organizationId" : ID_OF_USER_ORG,
  "email" : EMAIL_OF_USER,
  "fullName" : FULL_NAME_OF_USER,
  "phone" : PHONE_NUMBER_OF_USER,
  "title" : TITLE_FOR_USER,
  "admin" : BOOLEAN_OF_USER_ADMIN_STATUS
}

Path Params

userId
string
required

The ID of the user

 
Suggest Edits

/organization/members

Invite multiple members to your organization. Requires administrator privileges in the SignalFx web UI.

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/organization/members
# Requires administrator privileges in the SignalFx web UI.
$ curl \
  --request POST \
  --header "X-SF-TOKEN: ADMIN_SESSION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{ "members": [ {"email" : "newUser@company.co", "admin" : false}, {"email": "anotherUser@company.co", "admin" : true} ] }' \
  https://api.signalfx.com/v2/organization/members
A binary file was returned

You couldn't be authenticated

{
  "members" : [ {
    "creator" : "AAAAAAAAAAA",
    "lastUpdatedBy" : "CZMKqt6AEAQ",
    "created" : 1453323553423,
    "lastUpdated" : 1453323553465,
    "id" : "CZMKquHAIAA",
    "organizationId" : "B9mSXOMAAAA",
    "email" : "newuser@company.co",
    "fullName" : "newuser@company.co",
    "phone" : null,
    "title" : null,
    "admin" : false
  }, {
    "creator" : "AAAAAAAAAAA",
    "lastUpdatedBy" : "AAAAAAAAAAA",
    "created" : 1453323553543,
    "lastUpdated" : 1453323553547,
    "id" : "CZMKquMAEAI",
    "organizationId" : "B9mSXOMAAAA",
    "email" : "anotheruser@company.co",
    "fullName" : "anotheruser@company.co",
    "phone" : null,
    "title" : null,
    "admin" : false
  } ]
}

Body Params

members
array

list of members to invite

 

When a user is invited, they will receive a confirmation email from SignalFx that will link them to a page where they can set a password.

Member Model

Property
Type
Description

email

String

Email address of the user

fullName

String

(Optional) Name of the user

phone

String

(Optional) Phone number of the user

title

String

(Optional) Job title of the user

admin

boolean (default false)

(Optional) Whether the user is an admin or not

Suggest Edits

/organization/member/:userId

Remove a user from an the organization. Requires administrator privileges in the SignalFx web UI.

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.signalfx.com/v2/organization/member/userId
# Requires administrator privileges in the SignalFx web UI.
$ curl \
  --request DELETE \
  --header "X-SF-TOKEN: ADMIN_SESSION_TOKEN" \
  https://api.signalfx.com/v2/organization/member/ABCDEFABCDE

{
  "creator" : "AAAAAAAAAAA",
  "lastUpdatedBy" : "AAAAAAAAAAA",
  "created" : 1421951486399,
  "lastUpdated" : 1447415890650,
  "id" : "ID OF USER",
  "organizationId" : "ID OF ORG",
  "email" : "user@company.co",
  "fullName" : null,
  "phone" : null,
  "title" : null,
  "admin" : false
}
A binary file was returned

You couldn't be authenticated

Try the API to see results

Path Params

userId
string
required

The ID of the User to remove from the organization

 
Suggest Edits

Access Token Overview

 

Access tokens allow you to manage the secret authorization tokens which accompanies data sent to SignalFx's ingest endpoint. In addition to allowing teams the ability to compartmentalize and rotate secret tokens.

Property
Type
Description

name

String (required)

A unique name of the token

description

String

The description of the token

limits

Token Limits

Token limits

notifications

Array of Notifications

See the Notifications models. Determines where notifications will be sent for an incident or alert about this token.

secret

String (read only)

The current authentication secret for this token

disabled

Boolean

Determines whether this token is disabled or not.

latestRotation

Integer (read only)

Unix timestamp of when the last secret rotation occurred for this token.

expiry

Integer (read only)

Unix timestamp of when the token will expire.

Token Limits Model

Property
Type
Description

dpmNotificationThreshold

Integer

The datapoints/min limit for this token to alert on.

Suggest Edits

/token

Search for tokens

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/token
curl \
  --request GET \
  --header "X-SF-TOKEN: ADMIN_TOKEN" \
  --header "Content-Type: application/json" \
  https://api.signalfx.com/v2/token?name=ops
A binary file was returned

You couldn't be authenticated

{
    "count": 2,
    "results": [
        {
            "created": 1494294183710,
            "creator": "AAAAAAAAAAA",
            "description": "This is the ops token",
            "lastUpdated": 1494295025117,
            "lastUpdatedBy": "CISFCxHAEAA",
            "limits": {
                "dpmNotificationThreshold": 1000
            },
            "name": "ops token",
            "secret": "AAAAAAAAAAAAAAAAAAAAAA"
        },
        {
            "created": 1493996312999,
            "creator": "AAAAAAAAAAA",
            "description": "",
            "lastUpdated": 1493996313002,
            "lastUpdatedBy": null,
            "limits": {
                "dpmNotificationThreshold": null
            },
            "name": "mmmm otterpops",
            "secret": "AAAAAAAAAAAAAAAAAAAAAA"
        }
    ]
}

Query Params

name
string

Part of the name of the tokens to search for

limit
int32

Number of results to return (max 1000)

offset
int32

Result offset for use in pagination

 
Suggest Edits

/token

Create a new token

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/token
curl \
  --request POST \
  --header "X-SF-TOKEN: ADMIN_TOKEN" \
  --header "Content-Type: application/json" \
  --data \
  '{
  	"name": "my new token",
  	"description": "my token description"
	}' \
  https://api.signalfx.com/v2/token
A binary file was returned

You couldn't be authenticated

{
    "created": 1494294183710,
    "creator": "AAAAAAAAAAA",
    "description": "my token description",
    "lastUpdated": 1494295025117,
    "lastUpdatedBy": "AAAAAAAAAAA",
    "limits": {
        "dpmNotificationThreshold": 1000000
    },
    "name": "my new token",
    "secret": "AAAAAAAAAAAAAAAAAAAAAA"
}

Body Params

body
string
required

An Ingest Token Model

 
Suggest Edits

/token/:name

Get a token

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.signalfx.com/v2/token/:name
curl \
  --request GET \
  --header "X-SF-TOKEN: ADMIN_TOKEN" \
  --header "Content-Type: application/json" \
  https://api.signalfx.com/v2/token/mytoken
A binary file was returned

You couldn't be authenticated

{
    "created": 1494294183710,
    "creator": "AAAAAAAAAAA",
    "description": "A token with a dpm limit",
    "lastUpdated": 1494295025117,
    "lastUpdatedBy": "AAAAAAAAAAA",
    "limits": {
        "dpmNotificationThreshold": 1000000
    },
    "name": "mytoken",
    "secret": "AAAAAAAAAAAAAAAAAAAAAA"
}
 
Suggest Edits

/token/:name

Update a token

 

Header Auth

 Authentication is required for this endpoint.
puthttps://api.signalfx.com/v2/token/:name
curl \
  --request POST \
  --header "X-SF-TOKEN: ADMIN_TOKEN" \
  --header "Content-Type: application/json" \
  --data \
  '{
  	"name": "my_limited_token",
  	"description": "A token with a dpm limit",
    "limits": {
    	"dpmNotificationThreshold": 1000000
    }
	}' \
  https://api.signalfx.com/v2/token/my_limited_token
A binary file was returned

You couldn't be authenticated

{
    "created": 1494294183710,
    "creator": "AAAAAAAAAAA",
    "description": "A token with a dpm limit",
    "lastUpdated": 1494295025117,
    "lastUpdatedBy": "AAAAAAAAAAA",
    "limits": {
        "dpmNotificationThreshold": 1000000
    },
    "name": "my_limited_token",
    "secret": "AAAAAAAAAAAAAAAAAAAAAA"
}

Body Params

body
string
required

An Ingest Token Model

 
Suggest Edits

/token/:name

Delete a token

 

Header Auth

 Authentication is required for this endpoint.
deletehttps://api.signalfx.com/v2/token/:name
curl \
  --request DELETE \
  --header "X-SF-TOKEN: ADMIN_TOKEN" \
  --header "Content-Type: application/json" \
  https://api.signalfx.com/v2/token/my_limited_token
A binary file was returned

You couldn't be authenticated

Try the API to see results
 
Suggest Edits

/token/:name/rotate

Generate a new token secret and deauthorize the previous secret

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.signalfx.com/v2/token/:name/rotate
# Secret rotation with a grace period of 10 minutes (600 seconds)
curl \
  --request POST \
  --header "X-SF-TOKEN: ADMIN_TOKEN" \
  --header "Content-Type: application/json" \
  https://api.signalfx.com/v2/token/mytoken/rotate?graceful=600
A binary file was returned

You couldn't be authenticated

{
    "created": 1494294183710,
    "creator": "AAAAAAAAAAA",
    "description": "A token with a dpm limit",
    "lastUpdated": 1494295025117,
    "lastUpdatedBy": "AAAAAAAAAAA",
    "limits": {
        "dpm": null
    },
    "name": "mytoken",
    "secret": "new secret for access token"
}

Query Params

graceful
int32

Seconds to wait until deauthorizing the previous secret

 
Suggest Edits

/signalflow/connect

Establish a WebSocket connection for SignalFlow streaming

 
gethttps://stream.signalfx.com/v2/signalflow/connect
#!/usr/bin/env python

import signalfx

program = """data('demo.trans.latency').mean(by='demo_customer').stream()"""

sfx = signalfx.SignalFx('YOUR ACCESS TOKEN')
flow = sfx.signalflow()
for message in flow.execute(program).stream():
    # Do something with the message; each message is a sub-type of
    # signalfx.signalflow.messages.StreamMessage.
#!/usr/bin/env python

# This is a simple and very "raw" example of using the WebSocket connection.
# We highly recommend that you use the SignalFx Python client library,
# available at https://github.com/signalfx/signalfx-python.

# The SignalFx Python client library provides easy-to-use abstractions for
# interacting with SignalFx's SignalFlow analytics service and removes the
# complexity of dealing directly with the WebSocket connection, message parsing, etc.

import json
import websocket

program = """data('demo.trans.latency').mean(by='demo_customer').stream()"""

ws = websocket.create_connection('wss://stream.signalfx.com/v2/signalflow/connect')
ws.send({'type': 'authenticate',
         'token': 'AUTH_TOKEN'})
ws.send({'type': 'execute',
         'channel': 'channel-1',
         'program': program})
while c.connected:
    msg = ws.recv()
    if msg.startswith('{'):
        msg = json.loads(msg)
        # Do something with the JSON message object
    else:
        # Decode binary data
A binary file was returned

You couldn't be authenticated

No response examples available

Headers

Connection
string
Upgrade
string
 

This endpoint allows for upgrading to a WebSocket connection for the purpose of establishing a persistent connection with SignalFx's SignalFlow service. No authentication is required on the initial request; authentication is handled as an exchange through the WebSocket connection itself.

Why and when to use the WebSocket connection

The SignalFlow WebSocket connection allows for establishing a persistent, bi-directional communication channel with SignalFx's SignalFlow service, execute and stream the outputs of multiple SignalFlow computations concurrently.

After authentication, you can execute SignalFlow computations and receive their streaming output through the WebSocket. To identify which messages come from which computation, a user-specified channel name is used and included in each message sent to the connected client.

The ability to multiplex the output of multiple SignalFlow computations through a single connection is important to limit the number of concurrent open connections. When operating within a browser, it becomes a requirement as browsers usually impose a limit of 8 concurrent open connections to a target host, which would make implementing dashboard-type applications impossible.

Finally, using a WebSocket connection allows for a much more efficient transport for data messages, which can be sent as binary through the WebSocket's binary channel using a custom data encoding that is 60-75% smaller than its JSON counterpart.

On channels

When executing a new SignalFlow computation, the client is required to provide a channel name as part of the request.

Channel names must be simple ASCII strings of no more than 16 characters in length. There is no uniqueness of channel names enforced server-side. It is up to the client to pick appropriate channel names so it can uniquely identify the messages coming from multiple concurrently executing SignalFlow computation through the same WebSocket connection. Note that channel names are only relevant, and therefore only need to be unique inside the scope of a given WebSocket connection.

Typical usage flow

The client can send requests to the server at any time. Those requests are JSON-encoded messages with a type field and other parameters depending on the type of the request (see below).

After establishing the WebSocket connection, the client is required to first authenticate itself with a valid access token within 5 seconds of establishing the connection. If the authentication is invalid, or is not provided within the allowed timeout, the connection will be closed with an appropriate status code and error message. Otherwise, the connection remains open and can accept further requests.

Once authenticated, the client can request the execution of SignalFlow computations by sending execute requests, stop a running computation, etc.

If the client disconnects, any running computation that was tied to the WebSocket connection is automatically stopped.

Authentication

An authentication request is used to authenticate the client using a valid access token. As explained above, the client must authenticate itself within 5 seconds of establishing the WebSocket connection.

If the client is using a session token (which may expire) as the access token, the client may also re-authenticate itself at any time while the connection is open to provide an updated session token, or to switch from one organization scope to another without having to re-establish a new connection. Re-authenticating does not impact running SignalFlow computations that are streaming through the WebSocket, unless the new token was invalid, in which case the connection will be closed by the server.

{
  "type": "authenticate",
  "token": "SESSION_ACCESS_TOKEN"
}

Execute a computation

A new SignalFlow computation can be started by sending an execute request. When starting a SignalFlow computation, the client is required to supply a channel name that will be used to identify the messages emitted by this computation. The name of the channel must be a simple ASCII string of no more than 16 characters.

The client must also supply the SignalFlow program to execute. Additionally, the client may specify a start time, a stop time, a desired resolution and desired maxDelay for the computation, as well as a set of disabledPublishLabels and a set of disabledDetectLabels to disable (at job start time) the output of the given publish and detect calls. For more information on all those arguments, their type and their semantics, refer to the /signalflow/execute documentation.

Here's an example of request to execute a SignalFlow computation, with its output streaming via channel channel-1:

{
  "type": "execute",
  "channel": "channel-1",
  "program": "data('demo.trans.latency').mean(by='demo_customer').stream()"
}

Here's a more complicated example showing the use of some optional arguments. The output will be streamed via channel channel-2.

{
  "type": "execute",
  "channel": "channel-2",
  "program": "data('demo.trans.latency').mean().stream()",
  "start": 1463020200000,
  "stop": 1463023800000,
  "resolution": 60000
}

Detach from a computation

To detach from computation and stop receiving its output, send a detach request specifying the channel you have assigned to it. If the channel is unknown, or has already stopped, the request is ignored.

{
  "type": "detach",
  "channel": "channel-1",
  "reason": "I don't want this anymore."
}

Stop a computation

Stops a computation, regardless of whether you are attached to it or not. Any connection attached to that computation will see an end of stream of that computation, with an abort message containing the reason you specify in the stop request.

{
  "type": "stop",
  "handle": "Ci6ryE9AAAE",
  "reason": "I don't want this anymore."
}
Suggest Edits

/signalflow/execute

Execute an analytics computation

 
posthttps://stream.signalfx.com/v2/signalflow/execute
$ curl --request POST \
       --header "Content-Type: text/plain" \
       --header "X-SF-Token: YOUR ACCESS TOKEN" \
       --data "data('cache.hits').sum().publish()" \
       "https://stream.signalfx.com/v2/signalflow/execute"
A binary file was returned

You couldn't be authenticated


event: control-message
data: {
data:   "event" : "STREAM_START",
data:   "timestampMs" : 1461351769440
data: }

event: control-message
data: {
data:   "event" : "JOB_START",
data:   "handle" : "ChkVxy0AEAA",
data:   "timestampMs" : 1461351771160
data: }

event: metadata
data: {
data:   "tsId" : "Cgql1H0AEC4",
data:   "properties" : {
data:     "jobId" : "CgqzM2WAEAA",
data:     "sf_organizationID" : "BqDQY5OAAAA",
data:     "sf_key" : [ "jobId", "sf_metric" ],
data:     "sf_metric" : "__SF_COMP_CgqzM2WAEAA_02-PUBLISH_metric",
data:     "sf_resolutionMs" : 1000,
data:     "sf_type" : "MetricTimeSeries",
data:     "sf_isPreQuantized" : true
data:   }
data: }

event: data
id: data-1461351769000
data: {
data:   "data" : [ {
data:     "tsId" : "Cgql1H0AEC4",
data:     "value" : 8.308932332308434
data:   } ],
data:   "logicalTimestampMs" : 1461351769000
data: }

...

event: control-message
data: {
data:   "event" : "END_OF_CHANNEL",
data:   "timestampMs" : 1461351775496
data: }
{
  "message" : "You must use your user session",
  "code" : 401
}

Query Params

start
date-time

Optional start timestamp in milliseconds since epoch

stop
date-time

Optional stop timestamp in milliseconds since epoch

resolution
int32

Optional desired data resolution, in milliseconds

maxDelay
int32

Optional desired maximum data delay, in milliseconds

Headers

Last-Event-ID
string

ID of the last Server-Sent Event received, for resume. See SSE specification for details

 

Executing SignalFlow computations

The /signalflow/execute endpoint allows for the execution of a SignalFlow computation, with its output being directly streamed back to the client in real-time. The stream is a text/event-stream and consists of events as defined by the Server-Sent Events (SSE) standard.

Requesting a computation is done by submitting its SignalFlow program text as the body of the request. If the stop time is in the future, or is not specified, the computation will keep streaming its output until the stop time is reached, or the connection is closed by the client, whichever occurs first. If the stop time is in the past, all the data is sent as soon as possible and the connection is closed by the server automatically.

For more information about the response format, and the specification of the various types of messages that make up the computation's streaming output, refer to the Stream messages specification.

Suggest Edits

/signalflow/preflight

Find out how many times a detector would have fired and cleared during a specified time period

 
posthttps://stream.signalfx.com/v2/signalflow/preflight
$ curl --request POST \
       --header "Content-Type: text/plain" \
       --header "X-SF-Token: YOUR ACCESS TOKEN" \
       --data "detect(data('demo.trans.latency').sum()> 4000).publish('too much latency');" \
       "https://stream.signalfx.com/v2/signalflow/preflight?start=1486396701764&stop=14863970058"
A binary file was returned

You couldn't be authenticated


event: control-message
data: {
data:   "event" : "STREAM_START",
data:   "timestampMs" : 1461351769440
data: }

event: control-message
data: {
data:   "event" : "JOB_START",
data:   "handle" : "ChkVxy0AEAA",
data:   "timestampMs" : 1461351771160
data: }

// No data fired nor cleared in a timeslice
event: data
id: data-1486396702000
data: {
data:   "data" : [ ],
data:   "logicalTimestampMs" : 1486396702000,
data:   "maxDelayMs" : 5000
data: }

event: data
id: data-1486396703000
data: {
data:   "data" : [ ],
data:   "logicalTimestampMs" : 1486396703000,
data:   "maxDelayMs" : 5000
data: }

// Metadata about an alert that fired
event: metadata
data: {
data:   "properties" : {
data:     "computationId" : "C3_qPO8AcAA",
data:     "is" : "anomalous",
data:     "sf_isPreQuantized" : true,
data:     "sf_key" : [ "is", "sf_metric", "computationId" ],
data:     "sf_metric" : "_SF_COMP_C3_qPO8AcAA_05-PUBLISH_METRIC",
data:     "sf_organizationID" : "BrppnSQAgAA",
data:     "sf_resolutionMs" : 1000,
data:     "sf_streamLabel" : "too much latency",
data:     "sf_type" : "MetricTimeSeries"
data:   },
data:   "tsId" : "AAAAAPbtD9I"
data: }

// One alert fired in this timeslice
event: data
id: data-1486396763000
data: {
data:   "data" : [ {
data:     "tsId" : "AAAAAPbtD9I",
data:     "value" : 1
data:   } ],
data:   "logicalTimestampMs" : 1486396763000,
data:   "maxDelayMs" : 5000
data: }

// Again no alerts firing
event: data
id: data-1486396763000
data: {
data:   "data" : [ {
data:     "tsId" : "AAAAAPbtD9I",
data:     "value" : 1
data:   } ],
data:   "logicalTimestampMs" : 1486396763000,
data:   "maxDelayMs" : 5000
data: }

event: data
id: data-1486396764000
data: {
data:   "data" : [ ],
data:   "logicalTimestampMs" : 1486396764000,
data:   "maxDelayMs" : 5000
data: }

....

// Metadata for an alert clearing
event: metadata
data: {
data:   "properties" : {
data:     "computationId" : "C3_qPO8AcAA",
data:     "is" : "ok",
data:     "sf_isPreQuantized" : true,
data:     "sf_key" : [ "is", "sf_metric", "computationId" ],
data:     "sf_metric" : "_SF_COMP_C3_qPO8AcAA_05-PUBLISH_METRIC",
data:     "sf_organizationID" : "BrppnSQAgAA",
data:     "sf_resolutionMs" : 1000,
data:     "sf_streamLabel" : "too much latency",
data:     "sf_type" : "MetricTimeSeries"
data:   },
data:   "tsId" : "AAAAABmd62g"
data: }

// One alert cleared.
event: data
id: data-1486396786000
data: {
data:   "data" : [ {
data:     "tsId" : "AAAAABmd62g",
data:     "value" : 1
data:   } ],
data:   "logicalTimestampMs" : 1486396786000,
data:   "maxDelayMs" : 5000
data: }

// Initial alert firing again right after it cleared.
event: data
id: data-1486396787000
data: {
data:   "data" : [ {
data:     "tsId" : "AAAAAPbtD9I",
data:     "value" : 1
data:   } ],
data:   "logicalTimestampMs" : 1486396787000,
data:   "maxDelayMs" : 5000
data: }

....

event: control-message
data: {
data:   "event" : "END_OF_CHANNEL",
data:   "timestampMs" : 1461351775496
data: }
{
  "message" : "You must use your user session",
  "code" : 401
}

Query Params

start
date-time

Start timestamp in milliseconds since epoch

stop
date-time

Stop timestamp in milliseconds since epoch

maxDelay
int64

(optional) How long to wait for late datapoints, in milliseconds (see SignalFx web UI documentation for details)

 

Executing Preflight computations

The /signalflow/preflight endpoint allows for the execution of a SignalFlow program with a detect().publish() (like a detector) on data within a specified time duration. It returns a count of the alerts that would have fired within that computation time range and streams the output back to the client in real-time. The stream is a text/event-stream and consists of events as defined by the Server-Sent Events (SSE) standard.

Requesting a preflight is done by submitting its SignalFlow program text as the body of the request. Both the start time and stop time must be specified.

The output of preflight can include up to two metric timeseries per detect() in the program text - one is the counts of the alerts that fired ('is:anomalous') and one with the counts of cleared alerts ('is:ok'). If there are no alerts, no time series are returned. If there are no cleared alerts, only one timeseries is returned for the fired events. A metadata message describing the timeseries is sent before the first datapoint of each timeseries. Each timeseries is always associated with a 'detect()' and the metadata describing it will include a property called sf_streamLabel whose value is the label associated with the corresponding publish() call.

The timeseries will contain a datapoint for each time period where an alert either fired or cleared, with the count of the number of events that entered that state in that time period, for the corresponding detect() condition.

As always, the stream will begin with a STREAM_START control message and end with an END_OF_CHANNEL control message
For more information about the response format, and the specification of the various types of messages that make up the computation's streaming output, refer to the Stream messages specification.

Suggest Edits

/signalflow/:id/feedback

Retrieve status and feedback messages for a SignalFlow computation

 
gethttps://stream.signalfx.com/v2/signalflow/id/feedback
$ curl --header "X-SF-Token: YOUR ACCESS TOKEN" \
       https://stream.signalfx.com/v2/signalflow/COMPUTATION_ID/feedback
{
  "creator" : "...",
  "id" : "...",
  "kickoff" : 1480363060464,
  "messages" : [ {
    "blockSerialNumbers" : [ ],
    "contents" : {
      "resolutionMs" : 10000
    },
    "messageCode" : "JOB_RUNNING_RESOLUTION",
    "messageLevel" : "INFO",
    "numInputTimeSeries" : 0,
    "timestampMs" : 1480362108000,
    "tsIds" : null
  }, {
    "blockSerialNumbers" : [ ],
    "contents" : {
      "lagMs" : 1000
    },
    "messageCode" : "JOB_DETECTED_LAG",
    "messageLevel" : "INFO",
    "numInputTimeSeries" : 0,
    "timestampMs" : 1480362108000,
    "tsIds" : [ "CKjtEo_AEAA" ]
  }, {
    "blockSerialNumbers" : [ 0 ],
    "contents" : {
      "dimensionCounts" : [ {
        "count" : 18,
        "dimensions" : [ "demo_datacenter", "sf_metric", "demo_customer", "demo_host" ]
      } ]
    },
    "messageCode" : "FIND_MATCHED_DIMENSIONS",
    "messageLevel" : "INFO",
    "numInputTimeSeries" : 18,
    "timestampMs" : 1480362100000,
    "tsIds" : null
  }, {
    "blockSerialNumbers" : [ 0 ],
    "messageCode" : "FETCH_NUM_TIMESERIES",
    "messageLevel" : "INFO",
    "numInputTimeSeries" : 18,
    "timestampMs" : 1480362100000,
    "tsIds" : null
  }, {
    "blockSerialNumbers" : [ 1 ],
    "messageCode" : "ID_NUM_TIMESERIES",
    "messageLevel" : "INFO",
    "numInputTimeSeries" : 18,
    "timestampMs" : 1480363110000,
    "tsIds" : null
  } ],
  "status" : "RUNNING"
}
A binary file was returned

You couldn't be authenticated

{
  "creator": "CPCcI2gAIAA",
  "id": "CvzD_j2AEAA",
  "kickoff": 1477598221447,
  "messages": [
    ...
  ],
  "status": "RUNNING"
}

Path Params

id
string
required

The computation handle

 

This endpoint can be used to retrieve status information and feedback messages for a particular SignalFlow computation, even if the computation is no longer active and running.

The feedback messages are the information messages that are sent in the output stream of a SignalFlow computation. This endpoint makes them available through a non-streaming side-channel and allows for getting information about a SignalFlow computation (like its running resolution, etc) via a direct request that is not necessarily tied to an open stream for that computation.

The format of each message is the same as what would be received from a running computation's stream and is defined in the Stream Messages Specification.

Suggest Edits

/signalflow/:id/stop

Stop a running computation

 
posthttps://stream.signalfx.com/v2/signalflow/id/stop
$ curl --request POST \
       --header "X-SF-Token: YOUR ACCESS TOKEN"
       "https://api.signalfx.com/v2/signalflow/CiX08RLAcAI/stop"
A binary file was returned

You couldn't be authenticated

{
  "message" : "You must use your user session",
  "code" : 401
}
{
  "message" : "HTTP 404 Not Found",
  "code" : 404
}
{
  "message" : "Invalid ID: 'foo'",
  "code" : 400
}

Path Params

id
string
required

The computation handle

 

This endpoints allows for stopping a running SignalFlow computation via its computation handle ID. The computation must belong to the same organization as the authenticated user's session (this is always the case for single-organization accounts).

Suggest Edits

Stream Messages Specification

Specification of the format of the stream messages from SignalFlow computations

 

When executing a SignalFlow computation, the resulting streaming response delivers the data and events generated by the computation as well as control messages and information about the computation's execution. Together, they give all the information required to utilize the output of the computation. This page describes the different kinds of messages you can expect to receive and their encoding.

SignalFx API client libraries

If you use one of the client libraries, these details are abstracted from you. This specification is provided for completeness of documentation, and for API users who choose to implement their own handling of stream messages received from a SignalFlow computation.

Structure and Encoding

Executing a SignalFlow computation returns a stream of messages as emitted by the computation. There are six different kinds of messages:

  • control messages, giving information about the stream;
  • information messages, giving information about the execution of the computation;
  • metadata messages, carrying metadata information about the time series generated by the computation;
  • data messages, carrying the actual data points for the time series generated by the computation;
  • event messages, emitted when an anomaly detector triggers or resolves;
  • error messages, carrying fatal errors encountered by the computation.

Via HTTP with Server-Sent Events

When executing a SignalFlow computation via the HTTP API, the responses are text/event-stream of Server-Sent Events (SSE). Each SSE is identified by its name (event, the type of the message) and contains a JSON data payload. As defined by the Server-Sent Events standard, events in the response are separated by an empty new line. Here's an example of the first few control messages you would usually see when executing a SignalFlow computation:

event: control-message
data: {
data:   "event" : "STREAM_START",
data:   "timestampMs" : 1461351769440
data: }

event: control-message
data: {
data:   "event" : "JOB_START",
data:   "handle" : "ChkVxy0AEAA",
data:   "timestampMs" : 1461351771160
data: }

event: control-message
data: {
data:   "event" : "JOB_PROGRESS",
data:   "timestampMs" : 1461351771168,
data:   "progress" : 10
data: }

Via the WebSocket connection

When executing a SignalFlow computation through an open, authenticated WebSocket connection to SignalFx, the stream messages are sent to the client in either JSON text or binary, depending on the type of the message and whether message compression was requested for a particular channel. Most messages are in JSON, with the exception of data messages which are always binary encoded. When compression is enabled, all messages are binary, but their compressed contents payload is whatever their uncompressed form would have been (either JSON, or a binary data payload).

All messages for a particular SignalFlow computation sent through the WebSocket are identified by a user-defined channel, and contain the type of the message as a top level property. Besides that, they have the exact same JSON structure as the Server-Sent Events data payloads described above.

{
  "type" : "control-message",
  "channel" : "channel-1",
  "event" : "STREAM_START",
  "timestampMs" : 1461351769440
}

{
  "type" : "control-message",
  "channel" : "channel-1",
  "event" : "JOB_START",
  "handle" : "ChkVxy0AEAA",
  "timestampMs" : 1461351771160
}

{
  "type" : "control-message",
  "channel" : "channel-1",
  "event" : "JOB_PROGRESS",
  "timestampMs" : 1461351771168,
  "progress" : 10
}

SignalFx provides open-source client libraries for various languages that take care of using the best connection (HTTP or WebSocket) available and of the parsing and decoding of the stream of the messages coming from your SignalFlow computations, offering a high level abstraction that makes it easier and faster to build applications using real-time SignalFlow analytics.

Binary encoding of WebSocket messages

Binary messages received from a SignalFlow WebSocket connection will follow the following format, with a 4-byte preamble followed by the 16-byte ASCII channel name.

.0                   1                   2                   3
.0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+---------------+---------------+---------------+---------------+
| Version       | Message type  | Flags         | (Reserved)    |
+---------------+---------------+-------------------------------+
|        Channel name (fixed 16 bytes, right-NUL-padded)        |
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
|                   Channel name (continued)                    |
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
|                   Channel name (continued)                    |
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -+
|                   Channel name (continued)                    |
+---------------------------------------------------------------+
|                                                               |
.                  Message payload follows...                   .
|                                                               |
+---------------------------------------------------------------+

In the preamble:

  • Version should always be 1 for the foreseeable future.
  • Flags is a bitfield. Possible flags are, from least specific bit to most specific bit:
    • Compressed (& (1 << 0))
    • JSON contents (& (1 << 1))
  • The last byte is unused at this time.

The message payload is to be interpreted according to the flags. If the compressed bit is set, the payload must first be decompressed using GZip/deflate. Once decompressed, the JSON bit indicates whether the payload should be interpreted as a UTF-8 encoded JSON message, or as a binary payload. As mentioned above, only data messages are sent with a binary payload.

Control Messages

Control messages provide contextual information about the status and the execution of the SignalFlow computation. Each control message has an event property and a timestampMs property. The event defines the type of control message ("what happened"), while timestampMs contains the millisecond-precision UNIX timestamp representing the time the event occurred.

event: control-message
data: {
data:   "event" : "...",
data:   ...
data: }
{
  "type" : "control-message",
  "channel" : "channel-1",
  "event" : "...",
  ...
}

STREAM_START

The STREAM_START control message is sent to announce that the response stream has been opened and that the computation has been kicked off.

event: control-message
data: {
data:   "event" : "STREAM_START",
data:   "timestampMs" : 1461360399704
data: }
{
  "type" : "control-message",
  "channel" : "channel-1",
  "event": "STREAM_START",
  "timestampMs" : 1461360399704
}

JOB_START

The JOB_START control message is sent when the SignalFlow computation has finished initializing and starts processing data. It contains the computation handle ID, which can be used to control the computation (keep-alive, stop, etc.).

event: control-message
data: {
data:   "event" : "JOB_START",
data:   "handle" : "ChkVxy0AEAA",
data:   "timestampMs" : 1461360399772
data: }
{
  "type" : "control-message",
  "channel" : "channel-1",
  "event" : "JOB_START",
  "handle" : "ChkVxy0AEAA",
  "timestampMs" : 1461360399772
}

JOB_PROGRESS

If the SignalFlow computation contains any moving transformation (some computation done over some period of time, such as a one-hour moving average), initialization data has to be fed into the computation to seed this data window. As a result, it may take longer for the first data batch to be emitted by the computation, especially for long data windows. In this situation, JOB_PROGRESS control messages will be sent during this seeding phase.

The JOB_PROGRESS control message contain an additional property, progress, which is a integer between 0 and 100 (inclusive) representing the progress of the seeding phase. They are usually sent every 10%.

event: control-message
data: {
data:   "event" : "JOB_PROGRESS",
data:   "timestampMs" : 1461360399784,
data:   "progress" : 10
data: }
{
  "type" : "control-message",
  "channel" : "channel-1",
  "event" : "JOB_PROGRESS",
  "timestampMs" : 1461360399784,
  "progress" : 10
}

CHANNEL_ABORT

The CHANNEL_ABORT message is sent if the computation has failed, in which case it will be the last message sent for this computation. This message contains an abortInfo object with additional fields detailing the cause error.

event: control-message
data: {
data:   "event" : "CHANNEL_ABORT",
data:   "timestampMs" : 1461360400235,
data:   "abortInfo" : {
data:     "sf_job_abortReason" : "job expired",
data:     "sf_job_abortState" : "EXPIRED"
data:   }
data: }
{
  "type" : "control-message",
  "channel" : "channel-1",
  "event" : "CHANNEL_ABORT",
  "timestampMs" : 1461360400235,
  "abortInfo" : {
    "sf_job_abortReason" : "job expired",
    "sf_job_abortState" : "EXPIRED"
  }
}

END_OF_CHANNEL

The END_OF_CHANNEL message is sent when the computation reaches the end of its execution time range (which only happens when a stop time was manually specified), in which case it will be the last message sent for this computation.

event: control-message
data: {
data:   "event" : "END_OF_CHANNEL",
data:   "timestampMs" : 1461360400235
data: }
{
  "type" : "control-message",
  "channel" : "channel-1",
  "event" : "END_OF_CHANNEL",
  "timestampMs" : 1461360400235
}

Information Messages

During the initialization, and throughout the execution of a SignalFlow computation, information is captured about decisions taken by the system, anomalous situations, and any other conditions that are worthy of being bubbled up to the user. Those messages are sent during the execution of the SignalFlow computation, in particular at the end of the very first compute iteration and at the end of the last compute iteration (if the computation had a manually specified stop time).

Here's a typical example showing four very common messages:

  • JOB_RUNNING_RESOLUTION instructs about the compute resolution of the SignalFlow computation. Data is processed and emitted at this interval, in milliseconds.
  • JOB_DETECTED_LAG reports the detected lag of the time series taking part in this computation.

Information messages are timestamped with the logical time of the computation at the time the message was emitted. The message itself also contains a timestamp that is relevant to what the message is about.

For a full reference of those messages, please see Information messages specification.

event: message
data: {
data:   "message" : {
data:     "blockSerialNumber" : 0,
data:     "timestampMs" : 1461353197000,
data:     "messageCode" : "JOB_RUNNING_RESOLUTION",
data:     "messageLevel" : "INFO",
data:     "numInputTimeSeries" : 0,
data:     "contents" : {
data:       "resolutionMs" : 1000
data:     }
data:   },
data:   "logicalTimestampMs" : 1461353198000
data: }
{
  "type" : "message",
  "channel" : "channel-1",
  "message" : {
    "blockSerialNumber" : 0,
    "timestampMs" : 1461353197000,
    "messageCode" : "JOB_RUNNING_RESOLUTION",
    "messageLevel" : "INFO",
    "numInputTimeSeries" : 0,
    "contents" : {
      "resolutionMs" : 1000
    }
  },
  "logicalTimestampMs" : 1461353198000
}
event: message
data: {
data:   "message" : {
data:     "blockSerialNumber" : 0,
data:     "timestampMs" : 1461353197000,
data:     "messageCode" : "JOB_DETECTED_LAG",
data:     "messageLevel" : "INFO",
data: