SignalFx Developers Guide

Developer Home

Product Docs

SignalFx
Documentation Powered by ReDoc

Incidents and Alerts API

This API provides two endpoints:

  • /incident: Operations that retrieve incident information or clear an incident
  • /alertmuting: Operations that create, retrieve, update, or delete notification muting rules

Incidents

An incident is the combination of an alert event and a clear event. SignalFx generates alert events when an incoming stream of data triggers a rule you've defined for a detector. When the condition that triggered the alert is no longer true, SignalFx triggers a clear event. Use the /incident endpoint to retrieve information for these events.

Notification muting

Notification muting controls the optional notifications for a detector rule. If you've defined a notification service for a detector rule, SignalFx sends you a notification for an alert event and a clear event. Notification muting controls these notifications.

To learn more about notification muting, see the section Mute notifications in the product documentation.

NOTE: Although the Detectors API only works with detectors you create in the API (v2 detectors, the /incident and /alertmuting endpoints work with all alerts, events, incidents, and notifications, regardless of which detector version created them. This means that you can use the endpoints to work with incidents and muting rules for detectors you create in the web UI.

Retrieve Muting Rules Query

Retrieves muting rules based on search criteria

Retrieves muting rules based on the query you specify in the query query parameter. This endpoint retrieves muting rules regardless of the version of the detector associated with the rule.

query Parameters
include
string

Specifies the type of muting rules you want to retrieve. The allowed values are:

  • Past
  • Future
  • Ongoing
  • Open
  • All
limit
integer <int32>

The number of results to return from the result set.

offset
integer <int32>

The result object in the result set at which the API should start returning results to you. If omitted, the API starts at the first result in the set.

orderBy
string

The metadata property on which the API should sort the results. You don't have to include this property in the query, but the name must be a property of muting rules.

query
string

Query that specifies the muting rules you want to retrieve.

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

Response Headers
Content-Type
string
Default: "application/json"

Format of the response body. Always application/json.

Response Schema: application/json
count
integer <int64> (Count of matched muting rules)

Number of muting rules that match the search criteria. This property is read-only.

NOTE: Count is not the same as the number of objects returned in the response body:

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

Query results, in the form of a JSON array of objects. Each element is a muting rule.

Response samples

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

Create Single Muting Rule

Creates a new muting rule

Creates a new muting rule, based on the specifications in the request body. Unlike the detector APIs, you can use the muting APIs with detectors you create in the web UI as well as detectors you create with the API.

NOTE: In some cases, SignalFx may send notifications during a muting period. To learn more, see the section Mute notifications in the product documentation.

When you create a muting rule, you can resolve all of the alerts for the muting rule you created by setting the optional resolveMatchingActiveAlerts query parameter to true. The flag's default value is false.

query Parameters
resolveMatchingActiveAlerts
boolean
Example: resolveMatchingActiveAlerts=true

Optional resolve alerts flag. If you set the flag to true, SignalFx resolves the alerts that match the muting rule you created. If you leave out the parameter or set it to false, SignalFx takes no action.

header Parameters
Content-Type
required
string

Format of the request body. Always application/json.

X-SF-TOKEN
required
string

Authentication token.

Request Body schema: application/json

Contains the specification of a new muting rule.

NOTE: You can't create properties that are marked read-only

description
string

Description of the rule. read/write

Array of objects (AlertMutingFilter)

List of muting filters for this rule, in the form of a JSON array. Each array element specifies a single filter.

A muting filter JSON specifies the following:

  • property: The dimension or custom property to compare to propertyValue
  • propertyValue: A number, string, or array
  • NOT: A flag that controls the comparison.

A filter mutes an alert based on the following:

  • NOT = false: value of property EQ propertyValue
  • NOT = true: value of property NE propertyValue

If propertyValue is an array, then the filter mutes an alert based on the following:

  • NOT = false: value of property matches any element of propertyValue
  • NOT = true: value of property matches none of the elements of propertyValue
sendAlertsOnceMutingPeriodHasEnded
boolean (SendAlertsOnceMutingPeriodHasEnded)
Default: true

Controls notifications after the muting period ends. To learn more, see the section Mute notifications in the product documentation.

startTime
integer <int64> (StartTime) >= 0

Starting time of a muting rule, in Unix time. If not specified, defaults to the current time. read/write.

stopTime
integer <int64> (StopTime) >= 0
Default: 0

Stop time of a muting rule, in Unix time. If set to 0, detectors that match this rule are muted indefinitely. The default value is 0. read/write

Responses

Response Headers
Content-Type
string
Default: "application/json"

Format of the response body. Always application/json.

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

The time the muting rule was created, in Unix time.

This property is read-only; it's always set by the system.

creator
string (Creator user ID)

SignalFx user ID of the muting rule creator. This property is read-only; it's always set by the system.

description
string

Description of the rule. read/write

Array of objects (AlertMutingFilter)

List of muting filters for this rule, in the form of a JSON array. Each array element specifies a single filter.

A muting filter JSON specifies the following:

  • property: The dimension or custom property to compare to propertyValue
  • propertyValue: A number, string, or array
  • NOT: A flag that controls the comparison.

A filter mutes an alert based on the following:

  • NOT = false: value of property EQ propertyValue
  • NOT = true: value of property NE propertyValue

If propertyValue is an array, then the filter mutes an alert based on the following:

  • NOT = false: value of property matches any element of propertyValue
  • NOT = true: value of property matches none of the elements of propertyValue
id
string (Muting rule ID)

SignalFx-assigned ID of a muting rule. This property is read-only; it's always set by the system.

lastUpdated
integer <int64> (Muting rule last updated time)

The last time the muting rule was last updated, in Unix time.

This property is read-only; it's always set by the system.

lastUpdatedBy
string (SignalFx ID of user who last updated the muting rule)

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

sendAlertsOnceMutingPeriodHasEnded
boolean (SendAlertsOnceMutingPeriodHasEnded)
Default: true

Controls notifications after the muting period ends. To learn more, see the section Mute notifications in the product documentation.

startTime
integer <int64> (StartTime) >= 0

Starting time of a muting rule, in Unix time. If not specified, defaults to the current time. read/write.

stopTime
integer <int64> (StopTime) >= 0
Default: 0

Stop time of a muting rule, in Unix time. If set to 0, detectors that match this rule are muted indefinitely. The default value is 0. read/write

Request samples

Content type
application/json
{
  • "description": "string",
  • "filters":
    [
    ],
  • "sendAlertsOnceMutingPeriodHasEnded": true,
  • "startTime": 0,
  • "stopTime": 0
}

Response samples

Content type
application/json
{
  • "created": 1556825430000,
  • "creator": "AAXYAAAAAZ3",
  • "description": "string",
  • "filters":
    [
    ],
  • "id": "string",
  • "lastUpdated": 1557689430000,
  • "lastUpdatedBy": "string",
  • "sendAlertsOnceMutingPeriodHasEnded": true,
  • "startTime": 0,
  • "stopTime": 0
}

Delete Single Muting Rule

Deletes a muting rule specified in the {id} path parameter

Deletes a muting rule, specified by the rule ID in the {id} path parameter. Unlike the detector APIs that create v2 detectors, you can use the muting APIs with detectors you create using the web UI as well as detectors you create using the API (v2 detectors).

This operation doesn't return a response body.

NOTE: You can't delete an active muting rule.

path Parameters
id
required
string

The SignalFx-assigned ID of a muting rule

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

Retrieve Muting Rule ID

Retrieves the muting rule specified in the {id} path parameter

Retrieves a muting rule, based on the rule ID specified in the {id} path parameter. Unlike the detector APIs, you can use the alert muting APIs with detectors you create in the web UI as well as detectors you create with the API.

path Parameters
id
required
string

SignalFx-assigned ID of a muting rule

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

Response Headers
Content-Type
string
Default: "application/json"

Format of the response body. Always application/json.

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

The time the muting rule was created, in Unix time.

This property is read-only; it's always set by the system.

creator
string (Creator user ID)

SignalFx user ID of the muting rule creator. This property is read-only; it's always set by the system.

description
string

Description of the rule. read/write

Array of objects (AlertMutingFilter)