SignalFx Developers Guide

Developer Home

Product Docs

SignalFx

Detectors API

IMPORTANT: The Detectors API supports the original SignalFx Microservices APM product released in 2019 that is now known as Microservice APM Previous Generation (µAPM PG). The developer interface for the current µAPM product, released on March 31, 2020, is not available.

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 and update 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 created 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

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: You can't use this operation to retrieve detectors you created in the web UI (v1 detectors).

query Parameters
id
string

SignalFx-assigned ID of an existing v2 detector

limit
integer <int32>
Default: 50
Example: limit=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 <int32> >= 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 body. Always "application/json".

X-SF-TOKEN
required
string

Authentication token

Responses

Response Schema: application/json
count
integer <int32> (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
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

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

Create Single Detector

Creates a 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

Request body format. Always "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

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.

maxDelay
integer <int32> (Late-arriving datapoint delay time) [ 0 .. 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.
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.

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)
Deprecated

DEPRECATED: Use the Teams API /v2/team/{teamId}/detector/{detectorId} endpoint to manage links between an existing team and an existing detector. Use the POST method to create a link and the DELETE method to delete a link.
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 API topics section Supported SignalFlow time zones.

object (Detector appearance options)

Options that control the appearance of a v2 detector in the SignalFx web UI

Responses

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

The time the v2 detector was created, in Unix time.
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.

object (Alert resolution times)

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 labelResolutions.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

lastUpdatedBy
string (Detector last updated ID)

The SignalFx-assigned ID of the user who last 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 <int32> (Late-arriving datapoint delay time) [ 0 .. 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. 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.
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.

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)
Deprecated

DEPRECATED: Use the Teams API /v2/team/{teamId}/detector/{detectorId} endpoint to manage links between an existing team and an existing detector. Use the POST method to create a link and the DELETE method to delete a link.
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 API topics section Supported SignalFlow time zones.

object (Detector appearance options)

Options that control the appearance of a v2 detector in the SignalFx web UI

Request samples

Content type
application/json
{
  • "authorizedWriters":
    {
    },
  • "customProperties": "string",
  • "description": "",
  • "maxDelay": 60000,
  • "name": "string",
  • "packageSpecifications": "",
  • "programText": "data('jvm.cpu.load').percentile(pct=94).publish(label='A'); detect(when(A > 15)).publish('load warning');"