SignalFx Developers Guide

Developer Home

Product Docs

SignalFx

Detectors API

Detectors define rules for identifying conditions of interest to the customer, and the notifications to send when the conditions occur or stop occurring.

Create Single Detector

Creates a detector

post /detector

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{REALM}.signalfx.com/v2/detector

Creates a new v2 detector object. Detectors define rules for identifying conditions of interest to the customer, and the notifications to send when the conditions occur or stop occurring. For more information on detectors including the types of notifications available, see Detectors, Events, and Alerts.

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is 'application/json'

X-SF-Token
required
string

A valid organization access token

Request Body schema: application/json
authorizedWriters
object (Organizations and teams with write permission for an object)

If your organization has the "write permissions" feature enabled, you can use this object to specify the user and team IDs that have write access to the object you're specifying.

customProperties
string (Custom properties)

User-defined JSON object containing metadata

description
string (Detector description)

Description of the detector. It appears in the Detector window displayed from the web UI Actions menu

maxDelay
integer (Late-arriving datapoint delay time)

The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the detector analysis. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).

timezone
string (Time zone for SignalFlow calendar window transformations)
Default: "UTC"

Specifies which time zone SignalFlow should use as the basis of calendar window transformation methods. For example, if you set "timezone": "Europe/Paris" and then use the transformation sum(cycle="week", cycle_start="Monday") in your detector's SignalFlow program, the calendar window starts on Monday, Paris time.
For a list of supported time zones, see Timezones and SignalFlow calendar window transformations

name
string (Detector name (displayed)) non-empty

The displayed name of the detector in the dashboard

programText
string (SignalFlow program for the detector)

The SignalFlow program that populates the detector. The program must include one or more detect functions and each detect function must be modified by a publish stream method with a label that's unique across the program. If you wish to support custom notification messages that include input data you must use variables to assign the detect conditions . If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n"). See the Detectors Overview for more information.

rules
Array of object (Alert Rule Definitions)

An array of rules that define aspects of an alert. These include the alert's severity and the specification of how notifications are sent when the alert is triggered. Each rule is connected to a specific detect function in the programText property by the value of the label in its publish method. The connection is to a set of one or more notification directives and an severity indicator. A single condition can be used in multiple rules if different severity indicators are desired for different notification methods.

To see the properties for a rule, expand the definition of the rules array. What you see is the "rules" object that specifies a single rule.

tags
Array of string (Keyword filters)

A an array of keywords that filters detectors by one of their fields. Use tags to indicate the state of a detector or its data source (for example, you can label a detector with a "prod" tag to indicate that it monitors a production environment).

teams
Array of string (Team IDs for this detector)

IDs of teams associated with this detector. Teams associated with a detector can see the detector and its active alerts on the team's landing page in the web UI. The list of teams associated with a detector is independent of notification settings. Teams specified in this field don''t automatically get notified of new alerts, and teams that choose to get alerts do not have to display the detector on their team landing page in the web application.

visualizationOptions
Array of object (Detector appearance options)

Options that control the appearance of a detector in the SignalFx web UI. Each element in the array is a 'VisualizationObject'.

Responses

200

Successful creation

Response Schema: application/json
created
integer <int32> (Creation time)

The time the detector was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.

creator
string (Creator user ID)

User ID of the initial creator

customProperties
string (Custom properties)

User-defined JSON object containing metadata

description
string (Detector description)

Description of the detector. It appears in the Detector window displayed from the web UI Actions menu

id
string (Detector system ID)

System-defined identifier for the detector

labelResolution
object (Alert resolution time)

Indicates how often data is analyzed to determine if an alert should be triggered. This is different from the data display resolution used to populate the detector visualization. The data display resolution is automatically set to the coarsest resolution of all of the publish statements associated with the detector, since they are all displayed together in the same visualization.
In the object, the label name of each publish statement in the detector is the property key, and the time is the value. For example, to refer to the label resolution of the publish statement with the label DetectorStatement, specify results[index].labelResolution.DetectorStatement.

lastUpdated
integer (Detector last updated time)

The last time the detector was updated, in milliseconds UTC relative to the Unix epoch.

lastUpdatedBy
string (Detector last updated ID)

The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.

locked
boolean (Detector lock state)

Detector modification state. If true, the detector can't be modified in anyway; otherwise, anyone can edit it.

maxDelay
integer (Late-arriving datapoint delay time)

The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the detector analysis. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).

name
string (Detector name (displayed)) non-empty

The displayed name of the detector in the dashboard

overMTSLimit
boolean (OverMTSLimit)

If true one, or more statements in the detector matched too many time series and the matched set was forcefully limited. In this case, the detector is most likely looking at incomplete data or an incomplete aggregation. If this flag is set to true, you can use a series of partition_filter functions to split the data set into manageable pieces then use the union function to rejoin the results in a subsequent computation. Note that the union function still observes the time series limit; some type of aggregation on the partial streams must limit the data set prior to recombining the streams for this approach to work.

programText
string (SignalFlow program for the detector)

The SignalFlow program that populates the detector. The program must include one or more detect functions and each detect function must be modified by a publish stream method with a label that's unique across the program. If you wish to support custom notification messages that include input data you must use variables to assign the detect conditions . If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n"). See the Detectors Overview for more information.

rules
Array of object (Alert Rule Definitions)

An array of rules that define aspects of an alert. These include the alert's severity and the specification of how notifications are sent when the alert is triggered. Each rule is connected to a specific detect function in the programText property by the value of the label in its publish method. The connection is to a set of one or more notification directives and an severity indicator. A single condition can be used in multiple rules if different severity indicators are desired for different notification methods.

To see the properties for a rule, expand the definition of the rules array. What you see is the "rules" object that specifies a single rule.

tags
Array of string (Keyword filters)

A an array of keywords that filters detectors by one of their fields. Use tags to indicate the state of a detector or its data source (for example, you can label a detector with a "prod" tag to indicate that it monitors a production environment).

teams
Array of string (Team IDs for this detector)

IDs of teams associated with this detector. Teams associated with a detector can see the detector and its active alerts on the team's landing page in the web UI. The list of teams associated with a detector is independent of notification settings. Teams specified in this field don''t automatically get notified of new alerts, and teams that choose to get alerts do not have to display the detector on their team landing page in the web application.

visualizationOptions
Array of object (Detector appearance options)

Options that control the appearance of a detector in the SignalFx web UI. Each element in the array is a 'VisualizationObject'.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "authorizedWriters":
    {
    },
  • "customProperties": "string",
  • "description": "string",
  • "maxDelay": 60000,
  • "timezone": "UTC",
  • "name": "string",
  • "programText": "string",
  • "rules":
    [
    ],
  • "tags":
    [
    ],
  • "teams":
    [
    ],
  • "visualizationOptions":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1533676829319,
  • "creator": ""AAAAAAAAAA" if the system created the detector",
  • "customProperties": "string",
  • "description": "string",
  • "id": "string",
  • "labelResolution":
    {
    },
  • "lastUpdated": 1533676829319,
  • "lastUpdatedBy": "string",
  • "locked": true,
  • "maxDelay": 60000,
  • "name": "string",
  • "overMTSLimit": true,
  • "programText": "string",
  • "rules":
    [
    ],
  • "tags":
    [
    ],
  • "teams":
    [
    ],
  • "visualizationOptions":
    [
    ]
}

Retrieve Detectors Using Query

Retrieves detectors based on search criteria

get /detector

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{REALM}.signalfx.com/v2/detector

Retrieve the specification of one or more detectors. If you don't specify any query parameters, the API returns up to the first 50 detector specifications that you have access to.

query Parameters
id
string

ID of an existing detector.

limit
integer
Default: 50
Example: 100

Maximum number of definitions to return.

name
string

Search criteria that the API tries to match to the name property of the defined detectors. The match can be full or partial. If the string is empty, it's ignored and the API uses the other criteria in the query. For example, a value of "per" matches detectors for which the name contains "dropped per day", "95th percentile", or "personal disk usage".

offset
integer >= 0
Default: 0

The starting index value of the returned objects; this assumes all of the possible returns are put in a 0-based indexed list in the appropriate sort order and identified by their order in the list. If the offset value is greater than the number of possible results, no objects are returned in the response.

tags
string

Search criteria that the API applies to the tags array property of the defined detectors. The string must be an exact match. You can specify multiple tags parameters in the same request.

header Parameters
Content-Type
required
string

Format of the response payload.

X-SF-Token
required
string

A valid organization access token

Responses

200

Detector specification or specifications retrieved by the request

Response Headers
Access-Control-Allow-Credentials
boolean
Default: true

If true, the response can be exposed to users even if they've authenticated with a front end client using cookies

Access-Control-Allow-Origin
string
Default: "URL of the agent making the request"

Specifies the URIs that can access the results of the request

Access-Control-Expose-Headers
string

A header that can be exposed to front end clients. The headers may contain multiple instances of this header.

Connection
string
Default: "keep-alive"

Specifies how connections should be handled for a series of API calls

Content-Encoding
string
Default: "gzip"

Specifies the content encoding of the response payload, as a standard HTTP content-encoding token

Content-Type
string
Default: "application/json"

Specifies the format of the response payload. Must be set to "application/json".

Date
string
Example: "Mon, 01 Jan 2018 10:19:25 GMT"

'Timestamp of the response, formatted as ddd, dd mmm yyyy hh:mm:ss. The time is GMT+0'

Transfer-Encoding
string
Default: "chunked"

The form of encoding used to safely transfer the response to the user agent.

Vary
string
Default: "Accept-Encoding, User-Agent"

Indicates that the response payload may be encoded or compressed differently depending on the source of the request. Primarily used to inform caching agents whether content is static or may vary depending on the request settings.

X-Content-Type-Options
string
Default: "nosniff"

Indicates that front-end clients shouldn't attempt to determine the payload format and adjust the content-type to match their expectations.

Response Schema: application/json
count
any (Count of matched objects)

Number of objects that match the search query. If you use paging, count is either the value of the limit request parameter or the number of objects still undelivered after the request reached the offset request parameter.
Note: If you use paging, count is not the number of objects returned in the response.

results
Array of object (Detector Properties Object)

An array of detector definitions that match the request criteria. Each definition is defined as a ResultsObject.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "count": null,
  • "results":
    [
    ]
}

Retrieve Detector Using ID

Retrieves the detector specified in the {id} path parameter

get /detector/{id}

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{REALM}.signalfx.com/v2/detector/{id}

Retrieves the specification of the detector with the identifier specified in {id}.

path Parameters
id
required
string

The detector ID for the detector to retrieve.

header Parameters
Content-Type
string

Format of the request payload. The only allowed value is 'application/json'.

X-SF-Token
required
string

Access token for an organization that has access to this detector.

Responses

200

Successful Get Detector by ID request

Response Headers
Access-Control-Allow-Credentials
boolean
Default: true

If true, the response can be exposed to users even if they've authenticated with a front end client using cookies

Access-Control-Allow-Origin
string
Default: "URL of the agent making the request"

Specifies the URIs that can access the results of the request

Access-Control-Expose-Headers
string

A header that can be exposed to front end clients. The headers may contain multiple instances of this header.

Connection
string
Default: "keep-alive"

Specifies how connections should be handled for a series of API calls

Content-Encoding
string
Default: "gzip"

Specifies the content encoding of the response payload, as a standard HTTP content-encoding token

Content-Type
string
Default: "application/json"

Specifies the format of the response payload. Must be set to "application/json; charset=utf8".

Date
string
Example: "Mon, 01 Jan 2018 10:19:25 GMT"

'Timestamp of the response, formatted as ddd, dd mmm yyyy hh:mm:ss. The time is GMT+0'

Transfer-Encoding
string
Default: "chunked"

The form of encoding used to safely transfer the response to the user agent.

Vary
string
Default: "Accept-Encoding, User-Agent"

Indicates that the response payload may be encoded or compressed differently depending on the source of the request. Primarily used to inform caching agents whether content is static or may vary depending on the request settings.

X-Content-Type-Options
string
Default: "nosniff"

Indicates that front-end clients shouldn't attempt to determine the payload format and adjust the content-type to match their expectations.

Response Schema: application/json
created
integer <int32> (Creation time)

The time the detector was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.

creator
string (Creator user ID)

User ID of the initial creator

customProperties
string (Custom properties)

User-defined JSON object containing metadata

description
string (Detector description)

Description of the detector. It appears in the Detector window displayed from the web UI Actions menu

id
string (Detector system ID)

System-defined identifier for the detector

labelResolution
object (Alert resolution time)

Indicates how often data is analyzed to determine if an alert should be triggered. This is different from the data display resolution used to populate the detector visualization. The data display resolution is automatically set to the coarsest resolution of all of the publish statements associated with the detector, since they are all displayed together in the same visualization.
In the object, the label name of each publish statement in the detector is the property key, and the time is the value. For example, to refer to the label resolution of the publish statement with the label DetectorStatement, specify results[index].labelResolution.DetectorStatement.

lastUpdated
integer (Detector last updated time)

The last time the detector was updated, in milliseconds UTC relative to the Unix epoch.

lastUpdatedBy
string (Detector last updated ID)

The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.

locked
boolean (Detector lock state)

Detector modification state. If true, the detector can't be modified in anyway; otherwise, anyone can edit it.

maxDelay
integer (Late-arriving datapoint delay time)

The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the detector analysis. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).

name
string (Detector name (displayed)) non-empty

The displayed name of the detector in the dashboard

overMTSLimit
boolean (OverMTSLimit)

If true one, or more statements in the detector matched too many time series and the matched set was forcefully limited. In this case, the detector is most likely looking at incomplete data or an incomplete aggregation. If this flag is set to true, you can use a series of partition_filter functions to split the data set into manageable pieces then use the union function to rejoin the results in a subsequent computation. Note that the union function still observes the time series limit; some type of aggregation on the partial streams must limit the data set prior to recombining the streams for this approach to work.

programText
string (SignalFlow program for the detector)

The SignalFlow program that populates the detector. The program must include one or more detect functions and each detect function must be modified by a publish stream method with a label that's unique across the program. If you wish to support custom notification messages that include input data you must use variables to assign the detect conditions . If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n"). See the Detectors Overview for more information.

rules
Array of object (Alert Rule Definitions)

An array of rules that define aspects of an alert. These include the alert's severity and the specification of how notifications are sent when the alert is triggered. Each rule is connected to a specific detect function in the programText property by the value of the label in its publish method. The connection is to a set of one or more notification directives and an severity indicator. A single condition can be used in multiple rules if different severity indicators are desired for different notification methods.

To see the properties for a rule, expand the definition of the rules array. What you see is the "rules" object that specifies a single rule.

tags
Array of string (Keyword filters)

A an array of keywords that filters detectors by one of their fields. Use tags to indicate the state of a detector or its data source (for example, you can label a detector with a "prod" tag to indicate that it monitors a production environment).

teams
Array of string (Team IDs for this detector)

IDs of teams associated with this detector. Teams associated with a detector can see the detector and its active alerts on the team's landing page in the web UI. The list of teams associated with a detector is independent of notification settings. Teams specified in this field don''t automatically get notified of new alerts, and teams that choose to get alerts do not have to display the detector on their team landing page in the web application.

visualizationOptions
Array of object (Detector appearance options)

Options that control the appearance of a detector in the SignalFx web UI. Each element in the array is a 'VisualizationObject'.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1533676829319,
  • "creator": ""AAAAAAAAAA" if the system created the detector",
  • "customProperties": "string",
  • "description": "string",
  • "id": "string",
  • "labelResolution":
    {
    },
  • "lastUpdated": 1533676829319,
  • "lastUpdatedBy": "string",
  • "locked": true,
  • "maxDelay": 60000,
  • "name": "string",
  • "overMTSLimit": true,
  • "programText": "string",
  • "rules":
    [
    ],
  • "tags":
    [
    ],
  • "teams":
    [
    ],
  • "visualizationOptions":
    [
    ]
}

Update Single Detector

Updates properties for the detector specified in the {id} path parameter

put /detector/{id}

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{REALM}.signalfx.com/v2/detector/{id}

Updates an existing v2 detector specification identified by its ID.

path Parameters
id
required
string

The detector ID for the detector to retrieve.

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is 'application/json'

X-SF-Token
required
string

A valid organization access token

Request Body schema: application/json
customProperties
string (Custom properties)

User-defined JSON object containing metadata

description
string (Detector description)

Description of the detector. It appears in the Detector window displayed from the web UI Actions menu

maxDelay
integer (Late-arriving datapoint delay time)

The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the detector analysis. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).

name
string (Detector name (displayed)) non-empty

The displayed name of the detector in the dashboard

programText
string (SignalFlow program for the detector)

The SignalFlow program that populates the detector. The program must include one or more detect functions and each detect function must be modified by a publish stream method with a label that's unique across the program. If you wish to support custom notification messages that include input data you must use variables to assign the detect conditions . If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n"). See the Detectors Overview for more information.

rules
Array of object (Alert Rule Definitions)

An array of rules that define aspects of an alert. These include the alert's severity and the specification of how notifications are sent when the alert is triggered. Each rule is connected to a specific detect function in the programText property by the value of the label in its publish method. The connection is to a set of one or more notification directives and an severity indicator. A single condition can be used in multiple rules if different severity indicators are desired for different notification methods.

To see the properties for a rule, expand the definition of the rules array. What you see is the "rules" object that specifies a single rule.

tags
Array of string (Keyword filters)

A an array of keywords that filters detectors by one of their fields. Use tags to indicate the state of a detector or its data source (for example, you can label a detector with a "prod" tag to indicate that it monitors a production environment).

teams
Array of string (Team IDs for this detector)

IDs of teams associated with this detector. Teams associated with a detector can see the detector and its active alerts on the team's landing page in the web UI. The list of teams associated with a detector is independent of notification settings. Teams specified in this field don''t automatically get notified of new alerts, and teams that choose to get alerts do not have to display the detector on their team landing page in the web application.

visualizationOptions
Array of object (Detector appearance options)

Options that control the appearance of a detector in the SignalFx web UI. Each element in the array is a 'VisualizationObject'.

Responses

200

Valid Update Detector request

Response Headers
Access-Control-Allow-Credentials
boolean
Default: true

If true, the response can be exposed to users even if they've authenticated with a front end client using cookies

Access-Control-Allow-Origin
string
Default: "URL of the agent making the request"

Specifies the URIs that can access the results of the request

Access-Control-Expose-Headers
string

A header that can be exposed to front end clients. The headers may contain multiple instances of this header.

Connection
string
Default: "keep-alive"

Specifies how connections should be handled for a series of API calls

Content-Encoding
string
Default: "gzip"

Specifies the content encoding of the response payload, as a standard HTTP content-encoding token

Content-Type
string
Default: "application/json"

Specifies the format of the response payload. Must be set to "application/json; charset=utf8".

Date
string
Example: "Mon, 01 Jan 2018 10:19:25 GMT"

'Timestamp of the response, formatted as ddd, dd mmm yyyy hh:mm:ss. The time is GMT+0'

Transfer-Encoding
string
Default: "chunked"

The form of encoding used to safely transfer the response to the user agent.

Vary
string
Default: "Accept-Encoding, User-Agent"

Indicates that the response payload may be encoded or compressed differently depending on the source of the request. Primarily used to inform caching agents whether content is static or may vary depending on the request settings.

X-Content-Type-Options
string
Default: "nosniff"

Indicates that front-end clients shouldn't attempt to determine the payload format and adjust the content-type to match their expectations.

Response Schema: application/json
created
integer <int32> (Creation time)

The time the detector was created in UTC milliseconds; this corresponds to the receipt of the first request to send an invitation to this email address. This value is always set by the system.

creator
string (Creator user ID)

User ID of the initial creator

customProperties
string (Custom properties)

User-defined JSON object containing metadata

description
string (Detector description)

Description of the detector. It appears in the Detector window displayed from the web UI Actions menu

id
string (Detector system ID)

System-defined identifier for the detector

labelResolution
object (Alert resolution time)

Indicates how often data is analyzed to determine if an alert should be triggered. This is different from the data display resolution used to populate the detector visualization. The data display resolution is automatically set to the coarsest resolution of all of the publish statements associated with the detector, since they are all displayed together in the same visualization.
In the object, the label name of each publish statement in the detector is the property key, and the time is the value. For example, to refer to the label resolution of the publish statement with the label DetectorStatement, specify results[index].labelResolution.DetectorStatement.

lastUpdated
integer (Detector last updated time)

The last time the detector was updated, in milliseconds UTC relative to the Unix epoch.

lastUpdatedBy
string (Detector last updated ID)

The user ID of the last person who updated the object. If the last update was by the system, the value is "AAAAAAAAAA" This value is always set by the system.

locked
boolean (Detector lock state)

Detector modification state. If true, the detector can't be modified in anyway; otherwise, anyone can edit it.

maxDelay
integer (Late-arriving datapoint delay time)

The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the detector analysis. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).

name
string (Detector name (displayed)) non-empty

The displayed name of the detector in the dashboard

overMTSLimit
boolean (OverMTSLimit)

If true one, or more statements in the detector matched too many time series and the matched set was forcefully limited. In this case, the detector is most likely looking at incomplete data or an incomplete aggregation. If this flag is set to true, you can use a series of partition_filter functions to split the data set into manageable pieces then use the union function to rejoin the results in a subsequent computation. Note that the union function still observes the time series limit; some type of aggregation on the partial streams must limit the data set prior to recombining the streams for this approach to work.

programText
string (SignalFlow program for the detector)

The SignalFlow program that populates the detector. The program must include one or more detect functions and each detect function must be modified by a publish stream method with a label that's unique across the program. If you wish to support custom notification messages that include input data you must use variables to assign the detect conditions . If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n"). See the Detectors Overview for more information.

rules
Array of object (Alert Rule Definitions)

An array of rules that define aspects of an alert. These include the alert's severity and the specification of how notifications are sent when the alert is triggered. Each rule is connected to a specific detect function in the programText property by the value of the label in its publish method. The connection is to a set of one or more notification directives and an severity indicator. A single condition can be used in multiple rules if different severity indicators are desired for different notification methods.

To see the properties for a rule, expand the definition of the rules array. What you see is the "rules" object that specifies a single rule.

tags
Array of string (Keyword filters)

A an array of keywords that filters detectors by one of their fields. Use tags to indicate the state of a detector or its data source (for example, you can label a detector with a "prod" tag to indicate that it monitors a production environment).

teams
Array of string (Team IDs for this detector)

IDs of teams associated with this detector. Teams associated with a detector can see the detector and its active alerts on the team's landing page in the web UI. The list of teams associated with a detector is independent of notification settings. Teams specified in this field don''t automatically get notified of new alerts, and teams that choose to get alerts do not have to display the detector on their team landing page in the web application.

visualizationOptions
Array of object (Detector appearance options)

Options that control the appearance of a detector in the SignalFx web UI. Each element in the array is a 'VisualizationObject'.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "customProperties": "string",
  • "description": "string",
  • "maxDelay": 60000,
  • "name": "string",
  • "programText": "string",
  • "rules":
    [
    ],
  • "tags":
    [
    ],
  • "teams":
    [
    ],
  • "visualizationOptions":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1533676829319,
  • "creator": ""AAAAAAAAAA" if the system created the detector",
  • "customProperties": "string",
  • "description": "string",
  • "id": "string",
  • "labelResolution":
    {
    },
  • "lastUpdated": 1533676829319,
  • "lastUpdatedBy": "string",
  • "locked": true,
  • "maxDelay": 60000,
  • "name": "string",
  • "overMTSLimit": true,
  • "programText": "string",
  • "rules":
    [
    ],
  • "tags":
    [
    ],
  • "teams":
    [
    ],
  • "visualizationOptions":
    [
    ]
}

Enable Single Detector

Restarts the jobs for the detector specified by the {id} path parameter

put /detector/{id}/enable

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{REALM}.signalfx.com/v2/detector/{id}/enable

Restarts one or more previously disabled jobs associated with a detector, allowing them to resume triggering or clearing alerts. This is different from unmuting an alert, which enables notifications for jobs that are already processing data. If a disabled detector is also muted it remains muted when you enable it, and you must turn on notifications separately.

path Parameters
id
required
string

The detector ID for the detector to enable.

query Parameters
id
required
string

ID of an existing detector

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is 'application/json'

X-SF-Token
required
string

A valid organization access token

Request Body schema: application/json
Array
string

Label of an existing SignalFlow publish statement in the definition of a detector.

Responses

200

Successful Enable Detector request

Response Headers
Access-Control-Allow-Credentials
boolean
Default: true

If true, the response can be exposed to users even if they've authenticated with a front end client using cookies

Access-Control-Allow-Origin
string
Default: "URL of the agent making the request"

Specifies the URIs that can access the results of the request

Access-Control-Expose-Headers
string

A header that can be exposed to front end clients. The headers may contain multiple instances of this header.

Connection
string
Default: "keep-alive"

Specifies how connections should be handled for a series of API calls

Content-Encoding
string
Default: "gzip"

Specifies the content encoding of the response payload, as a standard HTTP content-encoding token

Content-Type
string
Default: "application/json"

Specifies the format of the response payload. Must be set to "application/json".

Date
string
Example: "Mon, 01 Jan 2018 10:19:25 GMT"

'Timestamp of the response, formatted as ddd, dd mmm yyyy hh:mm:ss. The time is GMT+0'

Transfer-Encoding
string
Default: "chunked"

The form of encoding used to safely transfer the response to the user agent.

Vary
string
Default: "Accept-Encoding, User-Agent"

Indicates that the response payload may be encoded or compressed differently depending on the source of the request. Primarily used to inform caching agents whether content is static or may vary depending on the request settings.

X-Content-Type-Options
string
Default: "nosniff"

Indicates that front-end clients shouldn't attempt to determine the payload format and adjust the content-type to match their expectations.

Request samples

application/json
Copy
Expand all Collapse all
[
  • "string"
]

Disable Single Detector

Stops jobs for the detector specified in the {id} path parameter

put /detector/{id}/disable

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{REALM}.signalfx.com/v2/detector/{id}/disable

Stops one or more previously running jobs associated with a detector, preventing them from triggering or clearing alerts. This is different from muting an alert, which prevents notifications but leaves jobs running and displays their state in the web UI. Muting an alert retains pull notifications while turning off push notifications, while disabling the detector prevents both push and pull notifications. Disabling a detector removes your ability to view the current detector state. This request is idempotent, so making it for a detector that is already disabled results in a successful call and the detector remains disabled. You can make the request without first checking the current state of the detector. Disabling a detector prevents future state changes until after the detector is re-enabled and the conditions for a state change occur. In particular, disabling a detector does not clear any active alerts but instead keeps them until after you enable the detector and clear the condition.

path Parameters
id
required
string

The detector ID for the detector to disable.

query Parameters
id
required
string

ID of an existing detector

header Parameters
Content-Type
required
string

Format of the request payload. The only allowed value is 'application/json'

X-SF-Token
required
string

A valid organization access token

Request Body schema: application/json
Array
string

Label of an existing SignalFlow publish statement in the definition of a detector.

Responses

200

Successful Enable Detector request

Response Headers
Access-Control-Allow-Credentials
boolean
Default: true

If true, the response can be exposed to users even if they've authenticated with a front end client using cookies

Access-Control-Allow-Origin
string
Default: "URL of the agent making the request"

Specifies the URIs that can access the results of the request

Access-Control-Expose-Headers
string

A header that can be exposed to front end clients. The headers may contain multiple instances of this header.

Connection
string
Default: "keep-alive"

Specifies how connections should be handled for a series of API calls

Content-Encoding
string
Default: "gzip"

Specifies the content encoding of the response payload, as a standard HTTP content-encoding token

Content-Type
string
Default: "application/json"

Specifies the format of the response payload. Must be set to "application/json".

Date
string
Example: "Mon, 01 Jan 2018 10:19:25 GMT"

'Timestamp of the response, formatted as ddd, dd mmm yyyy hh:mm:ss. The time is GMT+0'

Transfer-Encoding
string
Default: "chunked"

The form of encoding used to safely transfer the response to the user agent.

Vary
string
Default: "Accept-Encoding, User-Agent"

Indicates that the response payload may be encoded or compressed differently depending on the source of the request. Primarily used to inform caching agents whether content is static or may vary depending on the request settings.

X-Content-Type-Options
string
Default: "nosniff"

Indicates that front-end clients shouldn't attempt to determine the payload format and adjust the content-type to match their expectations.

Request samples

application/json
Copy
Expand all Collapse all
[
  • "string"
]

Retrieve Events for Single Detector

Gets the events generated by a detector specified in the {id} path parameter

get /detector/{id}/events

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{REALM}.signalfx.com/v2/detector/{id}/events

Gets the events generated a detector specified by its ID in the id path parameter.
Note: This API only supports v2 detectors, which are detectors that you created with the v2 API or v2 web UI.

path Parameters
id
required
string

The SignalFx-assigned detector ID for the detector that generated the events you want to retrieve.

query Parameters
from
integer <int64>

The starting timestamp, inclusive, of the time range of events you want to retrieve, in Unix epoch time format (milliseconds since 1970-01-01, UTC+0)

to
integer <int64>

The ending timestamp, inclusive, for the time range of events you want to retrieve, in Unix epoch time format (milliseconds since 1970-01-01, UTC+0)

offset
integer <int32>

The object in the result set at which the API should start returning results to you. Each object contains event data for an event generated by the specified detector.

limit
integer <int32>

The number of results to return from the result set.

header Parameters
X-SF-Token
required
string

An access token (referred to as a User ID access token in the web UI) for a user that has authorization to retrieve events.

Responses

200

Successful retrieval of events for the specified detector.

Retrieve Incidents For Single Detector

Gets the active incidents for a detector specified in the {id} path parameter

get /detector/{id}/incidents

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{REALM}.signalfx.com/v2/detector/{id}/incidents

Gets the active incidents for a detector specified by ID in the id path parameter. An incident is a collection of events generated by a detector, such as alerting and clearing events.
Note: This API only supports v2 detectors, which are detectors that you created with the v2 API or v2 web UI.

path Parameters
id
required
string

The SignalFx-assigned detector ID for the detector that generated the incidents you want to retrieve.

query Parameters
offset
integer <int32>

The object in the result set at which the API should start returning results to you. Each object contains active incidents generated by the specified detector.

limit
integer <int32>

The number of results to return from the result set.

header Parameters
X-SF-Token
required
string

An access token (referred to as a User ID access token in the web UI) for a user that has authorization to retrieve incidents.

Responses

200

Successful retrieval of incidents for the specified detector.

Validate Detector Definition

Validates a detector

post /validate

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://api.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://api.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://api.{REALM}.signalfx.com/v2/validate

Does a "dry run" of the request payload to see if it's valid, but doesn't actually create a detector

Request Body schema: application/json
customProperties
string (Custom properties)

User-defined JSON object containing metadata

description
string (Detector description)

Description of the detector. It appears in the Detector window displayed from the web UI Actions menu

maxDelay
integer (Late-arriving datapoint delay time)

The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the detector analysis. The default is to detect and apply a sensible value automatically (this option can also be explicitly chosen by setting the property to 0).

name
string (Detector name (displayed)) non-empty

The displayed name of the detector in the dashboard

programText
string (SignalFlow program for the detector)

The SignalFlow program that populates the detector. The program must include one or more detect functions and each detect function must be modified by a publish stream method with a label that's unique across the program. If you wish to support custom notification messages that include input data you must use variables to assign the detect conditions . If more than one line of SignalFlow is included, each line should be separated by either semicolons (";") or new line characters ("\n"). See the Detectors Overview for more information.

rules
Array of object (Alert Rule Definitions)

An array of rules that define aspects of an alert. These include the alert's severity and the specification of how notifications are sent when the alert is triggered. Each rule is connected to a specific detect function in the programText property by the value of the label in its publish method. The connection is to a set of one or more notification directives and an severity indicator. A single condition can be used in multiple rules if different severity indicators are desired for different notification methods.

To see the properties for a rule, expand the definition of the rules array. What you see is the "rules" object that specifies a single rule.

tags
Array of string (Keyword filters)

A an array of keywords that filters detectors by one of their fields. Use tags to indicate the state of a detector or its data source (for example, you can label a detector with a "prod" tag to indicate that it monitors a production environment).

teams
Array of string (Team IDs for this detector)

IDs of teams associated with this detector. Teams associated with a detector can see the detector and its active alerts on the team's landing page in the web UI. The list of teams associated with a detector is independent of notification settings. Teams specified in this field don''t automatically get notified of new alerts, and teams that choose to get alerts do not have to display the detector on their team landing page in the web application.

visualizationOptions