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.

NOTE: The Detectors API can only retrieve, update, and delete detectors you create using the POST /detector API operation. (these are v2 detectors). You can't use the detectors API to work with detectors you create in the web UI (v1 detectors). To learn more about v1 and v2 detectors, see the topic Detectors, Events, and Alerts in the Developers Guide.

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

Retrieves the properties of one or more v2 detectors. If you don't specify any query parameters, the API returns up to the first 50 detector objects that you have access to.

NOTE: Detectors you create in the web UI are v1 detectors. You can't use this operation to retrieve them.

query Parameters
id
string

SignalFx-assigned ID of an existing v2 detector

limit
integer
Default: 50
Example: 100

Number of results to return from the list of detectors that match your search criteria.
Together, the offset and limit properties provide paged access to the query results. You can repeatedly download small slices of a large query result, which helps you avoid bandwidth and performance problems.

name
string

Search criteria that the API tries to match to the name property of existing v2 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

Index, in the list of detectors that match your search criteria, at which you want to start downloading results.

Together, the offset and limit properties provide paged access to the query results. You can repeatedly download small slices of a large query result, which helps you avoid bandwidth and performance problems.

tags
string

Search criteria that the API applies to the elements of the tags array property of v2 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 request payload. Must be "application/json".

X-SF-TOKEN
required
string

Authentication token

Responses

200

Successful detector retrieval

Response Headers
Content-Type
string

Format of the response payload

Response Schema: application/json
count
integer <int64> (Count of matched **v2** detectors)

Number of v2 detectors that match the search criteria. This property is read-only; it's always set by the system.

Note: Count is not the same as the number of v2 detectors returned in the response body:

  • sizeOf(results): Size of the array returned in the response body.
  • count: Number of objects that match the search criteria
results
Array of objects (Detector Properties Object)

Results of a search for v2 detectors, in the form of a JSON array of objects. Each element is a v2 detector object.

Response samples

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

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 the topic Detectors, Events, and Alerts in the Developers Guide.

header Parameters
Content-Type
required
string

Format of the request payload. Must be "application/json".

X-SF-TOKEN
required
string

Authentication token

Request Body schema: application/json

A JSON object that contains the values for the new detector

authorizedWriters
object (Organizations and teams with write permission for an object)

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

customProperties
string (Custom properties)

User metadata, in the form of properties in a JSON object. The name and value of each property are strings.

description
string (Detector description)
Default: ""

Detailed description of the detector. SignalFx displays the value in the Detector pane accessed from the Actions menu in the web UI.

labelResolution
object (Alert resolution time)

Key-value pairs that indicate how often data is analyzed to determine if an alert should be triggered, in the form of a JSON object containing properties. Each key is the label name of a call to publish() in the SignalFlow for the detector, and each value is the resolution time for that publish() block.

For example, to retrieve the label resolution of the call to publish("DetectorStatement") from this object, use labelResolution.DetectorStatement.

Label resolution 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 SignalFlow publish() calls associated with the detector, since they are all displayed together in the same visualization.

maxDelay
integer (Late-arriving datapoint delay time) <= 900000

The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the v2 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
required
string (Detector name (displayed)) non-empty

Displayed name of the v2 detector in the web UI. When you retrieve events or incidents, this property contains the name of the associated v2 detector.

packageSpecifications
string (SignalFlow internal field)
Default: ""

For SignalFx internal use only.

programText
required
string (SignalFlow program for the detector)

Specifies the SignalFlow program that defines the v2 detector. This program must include one or more calls to the SignalFlow detect() function. The program must also call publish() on each detect stream, using a label that's unique to the program.

Because the value of this property is a string, you have to surround it with double quotes ". Inside the string, escape double quotes with the backslash character, for example, "detect(when(jvm.cpu.load > 15)).publish("load warning")".

If you want to use custom notification messages that include input data, assign your detect conditions to variables.

To use multiple lines in your program, terminate each line with a semicolon ; or newline character \n.

To learn more about SignalFlow programs for detectors, see the topic Detectors, Events, and Alerts in the Developers Guide.

rules
Array of objects (Alert Rule Definitions)

An array of rules that define aspects of an alert. These include the alert's severity and directives that control how notifications are sent when the alert is triggered. Each rule is connected to a specific detect() function in the SignalFlow program (the programText property) by the value of the label in its publish() method. The rule connects to one or more notification directives and an severity indicator.

To apply different severities to each notification method you use for a single condition, create multiple rules for the condition. In each rule, specify a notification method and severity.

tags
Array of strings (Keyword filters)

Array of keywords that filters detectors by one of their properties. 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).

NOTE: You can have no more than 50 tags per detector.

teams
Array of strings (Team IDs for this detector)

SignalFx IDs of teams associated with this v2 detector. The 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.

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 the topic Supported SignalFlow time zones in the Developers Guide.

visualizationOptions
Array of objects (Detector appearance options)

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

Responses

200

Successful creation of a detector

Response Headers
Content-Type
string

Format of the response payload

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

The time the v2 detector was created, in Unix time UTC-relative. This property is read-only; it's always set by the system.

creator
string (Creator user ID)

SignalFx ID of the user who created the v2 detector. This property is read-only; it's always set by the system.

customProperties
string (Custom properties)

Metadata for a v2 detector, in the form of a JSON object.

description
string (v2 detector description)

Description of a v2 detector. The value appears in the Detector window displayed in the web UI Actions menu.

id
string (Detector system ID)

SignalFx-assigned identifier of a v2 detector. When you retrieve events or incidents for a detector, this ID is for the detector that generated the event or incident. This property is read-only; it's always set by the system.

labelResolution
object (Alert resolution time)

Key-value pairs that indicate how often data is analyzed to determine if an alert should be triggered, in the form of a JSON object containing properties. Each key is the label name of a call to publish() in the SignalFlow for the detector, and each value is the resolution time for that publish() block.

For example, to retrieve the label resolution of the call to publish("DetectorStatement") from this object, use labelResolution.DetectorStatement.

Label resolution 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 SignalFlow publish() calls associated with the detector, since they are all displayed together in the same visualization.

lastUpdated
integer <int64> (Detector last updated time)

The last time the v2 detector was updated, in Unix time UTC-relative.

lastUpdatedBy
string (Detector last updated ID)

The SignalFx-assigned ID of the last user who updated the v2 detector. If the system made the last update, the value is "AAAAAAAAAA". This property is read-only; it's always set by the system.

locked
boolean (Detector lock state)

Detector lock state. If true, nobody can modify the detector in any way; otherwise, anyone can modify it.

maxDelay
integer (Late-arriving datapoint delay time) <= 900000

The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the v2 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

Displayed name of the v2 detector in the web UI. When you retrieve events or incidents, this property contains the name of the associated v2 detector.

overMTSLimit
boolean (OverMTSLimit)

If true, one or more statements in a v2 detector matched too many MTS, and the system forcibly limited the detector. This usually occurs when the detector is is looking at incomplete data or an incomplete aggregation. When this flag is true, use partition_filter() functions to split your data set into smaller pieces, then use the union() function to rejoin the results in a subsequent computation. Note that the union() function still observes the MTS limit, so an aggregation of the partial streams must first limit the data set prior to recombining the streams. This property is read-only; it's always set by the system.

packageSpecifications
string (SignalFlow internal field)
Default: ""

For SignalFx internal use only.

programText
string (SignalFlow program for the detector)

Specifies the SignalFlow program that defines the v2 detector. This program must include one or more calls to the SignalFlow detect() function. The program must also call publish() on each detect stream, using a label that's unique to the program.

Because the value of this property is a string, you have to surround it with double quotes ". Inside the string, escape double quotes with the backslash character, for example, "detect(when(jvm.cpu.load > 15)).publish("load warning")".

If you want to use custom notification messages that include input data, assign your detect conditions to variables.

To use multiple lines in your program, terminate each line with a semicolon ; or newline character \n.

To learn more about SignalFlow programs for detectors, see the topic Detectors, Events, and Alerts in the Developers Guide.

rules
Array of objects (Alert Rule Definitions)

An array of rules that define aspects of an alert. These include the alert's severity and directives that control how notifications are sent when the alert is triggered. Each rule is connected to a specific detect() function in the SignalFlow program (the programText property) by the value of the label in its publish() method. The rule connects to one or more notification directives and an severity indicator.

To apply different severities to each notification method you use for a single condition, create multiple rules for the condition. In each rule, specify a notification method and severity.

tags
Array of strings (Keyword filters)

Array of keywords that filters detectors by one of their properties. 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).

NOTE: You can have no more than 50 tags per detector.

teams
Array of strings (Team IDs for this detector)

SignalFx IDs of teams associated with this v2 detector. The 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.

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 the topic Supported SignalFlow time zones in the Developers Guide.

visualizationOptions
Array of objects (Detector appearance options)

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

Request samples

application/json
Copy
Expand all Collapse all
{
  • "authorizedWriters":
    {
    },
  • "customProperties": "string",
  • "description": "",
  • "labelResolution":
    {
    },
  • "maxDelay": 60000,
  • "name": "string",
  • "packageSpecifications": "",
  • "programText": "data(\"jvm.cpu.load\").percentile(pct=94).publish(label=\"A\", enable=False); detect(when(A > 15)).publish(\"load warning\")",
  • "rules":
    [
    ],
  • "tags":
    [
    ],
  • "teams":
    [
    ],
  • "timezone": "UTC",
  • "visualizationOptions":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1556825430000,
  • "creator": "AAXYAAAAAZ3",
  • "customProperties": "string",
  • "description": "string",
  • "id": "string",
  • "labelResolution":
    {
    },
  • "lastUpdated": 1557689430000,
  • "lastUpdatedBy": "string",
  • "locked": true,
  • "maxDelay": 60000,
  • "name": "string",
  • "overMTSLimit": true,
  • "packageSpecifications": "",
  • "programText": "data(\"jvm.cpu.load\").percentile(pct=94).publish(label=\"A\", enable=False); detect(when(A > 15)).publish(\"load warning\")",
  • "rules":
    [
    ],
  • "tags":
    [
    ],
  • "teams":
    [
    ],
  • "timezone": "UTC",
  • "visualizationOptions":
    [
    ]
}

Validate Detector Definition

Validates a v2 detector

post /detector/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/detector/validate

Does a "dry run" of a v2 detector request payload to see if it's valid, but doesn't actually create a detector. This operation doesn't return a response body.

*Note: This operation can only validate v2 detectors.

header Parameters
Content-Type
required
string

Format of the request payload. Must be "application/json".

X-SF-TOKEN
required
string

Authentication token

Request Body schema: application/json

v2 detector definition

customProperties
string (Custom properties)

Metadata for a v2 detector, in the form of a JSON object.

description
string (v2 detector description)

Description of a v2 detector. The value appears in the Detector window displayed in the web UI Actions menu.

maxDelay
integer (Late-arriving datapoint delay time) <= 900000

The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the v2 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

Displayed name of the v2 detector in the web UI. When you retrieve events or incidents, this property contains the name of the associated v2 detector.

programText
string (SignalFlow program for the detector)

Specifies the SignalFlow program that defines the v2 detector. This program must include one or more calls to the SignalFlow detect() function. The program must also call publish() on each detect stream, using a label that's unique to the program.

Because the value of this property is a string, you have to surround it with double quotes ". Inside the string, escape double quotes with the backslash character, for example, "detect(when(jvm.cpu.load > 15)).publish("load warning")".

If you want to use custom notification messages that include input data, assign your detect conditions to variables.

To use multiple lines in your program, terminate each line with a semicolon ; or newline character \n.

To learn more about SignalFlow programs for detectors, see the topic Detectors, Events, and Alerts in the Developers Guide.

rules
Array of objects (Alert Rule Definitions)

An array of rules that define aspects of an alert. These include the alert's severity and directives that control how notifications are sent when the alert is triggered. Each rule is connected to a specific detect() function in the SignalFlow program (the programText property) by the value of the label in its publish() method. The rule connects to one or more notification directives and an severity indicator.

To apply different severities to each notification method you use for a single condition, create multiple rules for the condition. In each rule, specify a notification method and severity.

tags
Array of strings (Keyword filters)

Array of keywords that filters detectors by one of their properties. 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).

NOTE: You can have no more than 50 tags per detector.

teams
Array of strings (Team IDs for this detector)

SignalFx IDs of teams associated with this v2 detector. The 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.

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 the topic Supported SignalFlow time zones in the Developers Guide.

visualizationOptions
Array of objects (Detector appearance options)

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

Responses

204

Valid detector

Request samples

application/json
Copy
Expand all Collapse all
{
  • "customProperties": "string",
  • "description": "string",
  • "maxDelay": 60000,
  • "name": "string",
  • "programText": "data(\"jvm.cpu.load\").percentile(pct=94).publish(label=\"A\", enable=False); detect(when(A > 15)).publish(\"load warning\")",
  • "rules":
    [
    ],
  • "tags":
    [
    ],
  • "teams":
    [
    ],
  • "timezone": "UTC",
  • "visualizationOptions":
    [
    ]
}

Retrieve Detector ID

Retrieves a specified detector

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 properties of the v2 detector that has the SignalFx-assigned ID specified in the {id} path parameter.

NOTE: Detectors you create in the web UI are v1 detectors. You can't use this operation to retrieve them.

path Parameters
id
required
string

SignalFx-assigned detector ID for a v2 detector

header Parameters
X-SF-TOKEN
required
string

Authentication token

Responses

200

Successful retrieval

Response Headers
Content-Type
string

Format of the response payload

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

The time the v2 detector was created, in Unix time UTC-relative. This property is read-only; it's always set by the system.

creator
string (Creator user ID)

SignalFx ID of the user who created the v2 detector. This property is read-only; it's always set by the system.

customProperties
string (Custom properties)

Metadata for a v2 detector, in the form of a JSON object.

description
string (v2 detector description)

Description of a v2 detector. The value appears in the Detector window displayed in the web UI Actions menu.

id
string (Detector system ID)

SignalFx-assigned identifier of a v2 detector. When you retrieve events or incidents for a detector, this ID is for the detector that generated the event or incident. This property is read-only; it's always set by the system.

labelResolution
object (Alert resolution time)

Key-value pairs that indicate how often data is analyzed to determine if an alert should be triggered, in the form of a JSON object containing properties. Each key is the label name of a call to publish() in the SignalFlow for the detector, and each value is the resolution time for that publish() block.

For example, to retrieve the label resolution of the call to publish("DetectorStatement") from this object, use labelResolution.DetectorStatement.

Label resolution 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 SignalFlow publish() calls associated with the detector, since they are all displayed together in the same visualization.

lastUpdated
integer <int64> (Detector last updated time)

The last time the v2 detector was updated, in Unix time UTC-relative.

lastUpdatedBy
string (Detector last updated ID)

The SignalFx-assigned ID of the last user who updated the v2 detector. If the system made the last update, the value is "AAAAAAAAAA". This property is read-only; it's always set by the system.

locked
boolean (Detector lock state)

Detector lock state. If true, nobody can modify the detector in any way; otherwise, anyone can modify it.

maxDelay
integer (Late-arriving datapoint delay time) <= 900000

The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the v2 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

Displayed name of the v2 detector in the web UI. When you retrieve events or incidents, this property contains the name of the associated v2 detector.

overMTSLimit
boolean (OverMTSLimit)

If true, one or more statements in a v2 detector matched too many MTS, and the system forcibly limited the detector. This usually occurs when the detector is is looking at incomplete data or an incomplete aggregation. When this flag is true, use partition_filter() functions to split your data set into smaller pieces, then use the union() function to rejoin the results in a subsequent computation. Note that the union() function still observes the MTS limit, so an aggregation of the partial streams must first limit the data set prior to recombining the streams. This property is read-only; it's always set by the system.

programText
string (SignalFlow program for the detector)

Specifies the SignalFlow program that defines the v2 detector. This program must include one or more calls to the SignalFlow detect() function. The program must also call publish() on each detect stream, using a label that's unique to the program.

Because the value of this property is a string, you have to surround it with double quotes ". Inside the string, escape double quotes with the backslash character, for example, "detect(when(jvm.cpu.load > 15)).publish("load warning")".

If you want to use custom notification messages that include input data, assign your detect conditions to variables.

To use multiple lines in your program, terminate each line with a semicolon ; or newline character \n.

To learn more about SignalFlow programs for detectors, see the topic Detectors, Events, and Alerts in the Developers Guide.

rules
Array of objects (Alert Rule Definitions)

An array of rules that define aspects of an alert. These include the alert's severity and directives that control how notifications are sent when the alert is triggered. Each rule is connected to a specific detect() function in the SignalFlow program (the programText property) by the value of the label in its publish() method. The rule connects to one or more notification directives and an severity indicator.

To apply different severities to each notification method you use for a single condition, create multiple rules for the condition. In each rule, specify a notification method and severity.

tags
Array of strings (Keyword filters)

Array of keywords that filters detectors by one of their properties. 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).

NOTE: You can have no more than 50 tags per detector.

teams
Array of strings (Team IDs for this detector)

SignalFx IDs of teams associated with this v2 detector. The 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.

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 the topic Supported SignalFlow time zones in the Developers Guide.

visualizationOptions
Array of objects (Detector appearance options)

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

400

Bad request. Messages may be:

  • "Unable to convert old detector model. This endpoint can only return detectors which were created programmatically" This message indicates that the detector ID you specified in the path parameter of your request is a v1 detector. The API can only retrieve v2 detectors.
Response Schema: application/json
string

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1556825430000,
  • "creator": "AAXYAAAAAZ3",
  • "customProperties": "string",
  • "description": "string",
  • "id": "string",
  • "labelResolution":
    {
    },
  • "lastUpdated": 1557689430000,
  • "lastUpdatedBy": "string",
  • "locked": true,
  • "maxDelay": 60000,
  • "name": "string",
  • "overMTSLimit": true,
  • "programText": "data(\"jvm.cpu.load\").percentile(pct=94).publish(label=\"A\", enable=False); detect(when(A > 15)).publish(\"load warning\")",
  • "rules":
    [
    ],
  • "tags":
    [
    ],
  • "teams":
    [
    ],
  • "timezone": "UTC",
  • "visualizationOptions":
    [
    ]
}

Update Single Detector

Updates properties for a v2 detector

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 the properties of the v2 detector with the SignalFx-assigned ID specified in the {id} path parameter.

NOTE: Detectors you create in the web UI are v1 detectors. You can't use this operation to update them. The PUT /detector/{id} operation has overwrite semantics:

  • For read-write properties, if the value is already specified, a new value in the request body overwrites it.
  • For read-write properties, if the value is already specified, and you don't specify a value for it, SignalFx removes the property from the detector.

Properties that are read-write are annotated in the request body property descriptions. Because of these semantics, you have to explicitly preserve existing values as follows:

  1. Send a GET /detector/{id} request to retrieve the existing detector values.
  2. Update any read-write properties in the result body with the new values you want to use.
  3. Use the result body as the request body in the PUT /detector/{id} operation to update the detector.
path Parameters
id
required
string

SignalFx-assigned ID of a v2 detector you want to update

header Parameters
Content-Type
required
string

Format of the request payload. Must be "application/json".

X-SF-TOKEN
required
string

Authentication token

NOTE: If you're updating the authorizedWriters property, and your user ID isn't in authorizedWriters already, then you need to use a session token (User API access token) associated with a SignalFx administrator.

Request Body schema: application/json

Properties you want to use to update an existing v2 detector, in the form of a JSON object.

authorizedWriters
object (Organizations and teams with write permission for an object)

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

customProperties
string (Custom properties)

Metadata for a v2 detector, in the form of a JSON object.

description
string (v2 detector description)

Description of a v2 detector. The value appears in the Detector window displayed in the web UI Actions menu.

maxDelay
integer (Late-arriving datapoint delay time) <= 900000

The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the v2 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

Displayed name of the v2 detector in the web UI. When you retrieve events or incidents, this property contains the name of the associated v2 detector.

packageSpecifications
string (SignalFlow internal field)
Default: ""

For SignalFx internal use only.

programText
string (SignalFlow program for the detector)

Specifies the SignalFlow program that defines the v2 detector. This program must include one or more calls to the SignalFlow detect() function. The program must also call publish() on each detect stream, using a label that's unique to the program.

Because the value of this property is a string, you have to surround it with double quotes ". Inside the string, escape double quotes with the backslash character, for example, "detect(when(jvm.cpu.load > 15)).publish("load warning")".

If you want to use custom notification messages that include input data, assign your detect conditions to variables.

To use multiple lines in your program, terminate each line with a semicolon ; or newline character \n.

To learn more about SignalFlow programs for detectors, see the topic Detectors, Events, and Alerts in the Developers Guide.

rules
Array of objects (Alert Rule Definitions)

An array of rules that define aspects of an alert. These include the alert's severity and directives that control how notifications are sent when the alert is triggered. Each rule is connected to a specific detect() function in the SignalFlow program (the programText property) by the value of the label in its publish() method. The rule connects to one or more notification directives and an severity indicator.

To apply different severities to each notification method you use for a single condition, create multiple rules for the condition. In each rule, specify a notification method and severity.

tags
Array of strings (Keyword filters)

Array of keywords that filters detectors by one of their properties. 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).

NOTE: You can have no more than 50 tags per detector.

teams
Array of strings (Team IDs for this detector)

SignalFx IDs of teams associated with this v2 detector. The 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.

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 the topic Supported SignalFlow time zones in the Developers Guide.

visualizationOptions
Array of objects (Detector appearance options)

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

Responses

200

SignalFx updated the detector.

Response Headers
Content-Type
string

Format of the response payload

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

The time the v2 detector was created, in Unix time UTC-relative. This property is read-only; it's always set by the system.

creator
string (Creator user ID)

SignalFx ID of the user who created the v2 detector. This property is read-only; it's always set by the system.

customProperties
string (Custom properties)

Metadata for a v2 detector, in the form of a JSON object.

description
string (v2 detector description)

Description of a v2 detector. The value appears in the Detector window displayed in the web UI Actions menu.

id
string (Detector system ID)

SignalFx-assigned identifier of a v2 detector. When you retrieve events or incidents for a detector, this ID is for the detector that generated the event or incident. This property is read-only; it's always set by the system.

labelResolution
object (Alert resolution time)

Key-value pairs that indicate how often data is analyzed to determine if an alert should be triggered, in the form of a JSON object containing properties. Each key is the label name of a call to publish() in the SignalFlow for the detector, and each value is the resolution time for that publish() block.

For example, to retrieve the label resolution of the call to publish("DetectorStatement") from this object, use labelResolution.DetectorStatement.

Label resolution 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 SignalFlow publish() calls associated with the detector, since they are all displayed together in the same visualization.

lastUpdated
integer <int64> (Detector last updated time)

The last time the v2 detector was updated, in Unix time UTC-relative.

lastUpdatedBy
string (Detector last updated ID)

The SignalFx-assigned ID of the last user who updated the v2 detector. If the system made the last update, the value is "AAAAAAAAAA". This property is read-only; it's always set by the system.

locked
boolean (Detector lock state)

Detector lock state. If true, nobody can modify the detector in any way; otherwise, anyone can modify it.

maxDelay
integer (Late-arriving datapoint delay time) <= 900000

The number of milliseconds to wait for late datapoints before rejecting them for inclusion in the v2 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

Displayed name of the v2 detector in the web UI. When you retrieve events or incidents, this property contains the name of the associated v2 detector.

overMTSLimit
boolean (OverMTSLimit)

If true, one or more statements in a v2 detector matched too many MTS, and the system forcibly limited the detector. This usually occurs when the detector is is looking at incomplete data or an incomplete aggregation. When this flag is true, use partition_filter() functions to split your data set into smaller pieces, then use the union() function to rejoin the results in a subsequent computation. Note that the union() function still observes the MTS limit, so an aggregation of the partial streams must first limit the data set prior to recombining the streams. This property is read-only; it's always set by the system.

programText
string (SignalFlow program for the detector)

Specifies the SignalFlow program that defines the v2 detector. This program must include one or more calls to the SignalFlow detect() function. The program must also call publish() on each detect stream, using a label that's unique to the program.

Because the value of this property is a string, you have to surround it with double quotes ". Inside the string, escape double quotes with the backslash character, for example, "detect(when(jvm.cpu.load > 15)).publish("load warning")".

If you want to use custom notification messages that include input data, assign your detect conditions to variables.

To use multiple lines in your program, terminate each line with a semicolon ; or newline character \n.

To learn more about SignalFlow programs for detectors, see the topic Detectors, Events, and Alerts in the Developers Guide.

rules
Array of objects (Alert Rule Definitions)

An array of rules that define aspects of an alert. These include the alert's severity and directives that control how notifications are sent when the alert is triggered. Each rule is connected to a specific detect() function in the SignalFlow program (the programText property) by the value of the label in its publish() method. The rule connects to one or more notification directives and an severity indicator.

To apply different severities to each notification method you use for a single condition, create multiple rules for the condition. In each rule, specify a notification method and severity.

tags
Array of strings (Keyword filters)

Array of keywords that filters detectors by one of their properties. 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).

NOTE: You can have no more than 50 tags per detector.

teams
Array of strings (Team IDs for this detector)

SignalFx IDs of teams associated with this v2 detector. The 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.

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 the topic Supported SignalFlow time zones in the Developers Guide.

visualizationOptions
Array of objects (Detector appearance options)

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

Request samples

application/json
Copy
Expand all Collapse all
{
  • "authorizedWriters":
    {
    },
  • "customProperties": "string",
  • "description": "string",
  • "maxDelay": 60000,
  • "name": "string",
  • "packageSpecifications": "",
  • "programText": "data(\"jvm.cpu.load\").percentile(pct=94).publish(label=\"A\", enable=False); detect(when(A > 15)).publish(\"load warning\")",
  • "rules":
    [
    ],
  • "tags":
    [
    ],
  • "teams":
    [
    ],
  • "timezone": "UTC",
  • "visualizationOptions":
    [