SignalFx Developers Guide

Developer Home

Product Docs

SignalFx

Incidents and Alerts API

Incidents

An incident is the combination of the alert event and clear event for a detector rule.

Detectors monitor metric time series; in the context of a detector, these are known as a signal. When a condition defined in a detector rule matches the signal, the detector does the following:

  • Triggers an alert that you can view in a number of places throughout SignalFx
  • Generates an event that you can view in the web UI. SignalFx also stores the event.
  • Sends one or more notifications, so that users learn about the alert even if they're not looking at the web UI.

When the signal no longer matches the condition in the detector rule, the detector generates a clear event and sends out a second notification. Together, the alert and clear event for a detector rule constitute an incident.

Alert muting rules

Alert muting rules (known as muting rules in the web UI) stop a detector from sending notifications, based on properties you specify in the rule. When you mute a notification, the detector still triggers alerts and generates events, and you can see these in their respective locations in the web UI. However, the detector doesn't send notifications to recipients who would normally receive them.

Use alert muting rules to mute certain notifications when you want to schedule server downtime or test new code or configurations. You can set alert muting rules to last for a specific time period or to last indefinitely.

In some cases, SignalFx may send notifications during an alert muting period. To learn more, see the section Considerations for alert muting in the API concepts guide.

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

Retrieve Alert Muting Rules Query

Retrieves alerting muting rules based on search criteria

get /alertmuting

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

Retrieves alerting muting rules based on the query you specify in the query query parameter. This endpoint retrieves alert 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 alert muting rules.

query
string

Query that specifies the muting rules you want to retrieve.

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successfully retrieved alert muting rules, or no rules matched the search criteria

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

Number of objects that match the search criteria, in the form of a JSON integer. 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 objects that match the search criteria
results
Array of objects (AlertMutingRule)

Results of an alert muting rule query, in the form of a JSON array of objects. Each element is an alert muting rule object.

Response samples

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

Create Single Alert Muting Rule

Creates a new alert muting rule

post /alertmuting

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

Creates a new alert muting rule, based on the specifications in the request body. 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.

NOTE: In some cases, SignalFx may send notifications during an alert muting period. To learn more, see the section Considerations for alert muting in the API concepts guide.

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 alerting muting rule.

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

description
string

Description of the rule. read/write

filters
Array of objects

List of alert muting filters for this rule, in the form of a JSON array of alert muting filter objects. Each object is a set of conditions for an alert muting rule. Each object property (name-value pair) specifies a dimension or custom property to match to alert events. read/write

startTime
integer <int64> (StartTime)

Starting time of an alert muting rule, in Unix time format UTC. If not specified, defaults to the current time. read/write.

stopTime
integer <int64> (StopTime)
Default: 0

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

Responses

200

Successful request.

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 alerting muting rule 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 user ID of the alert muting rule creator, in the form of a JSON string. This property is read-only; it's always set by the system.

description
string

Description of the rule. read/write

filters
Array of objects

List of alert muting filters for this rule, in the form of a JSON array of alert muting filter objects. Each object is a set of conditions for an alert muting rule. Each object property (name-value pair) specifies a dimension or custom property to match to alert events. read/write

id
string (Alerting muting rule ID)

SignalFx-assigned ID of an alert muting rule, in the form of a JSON string. This property is read-only; it's always set by the system.

lastUpdated
integer <int64> (Alert muting rule last updated time)

The last time the alert muting rule was last updated, in Unix time UTC-relative. This property is read-only; it's always set by the system.

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

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

startTime
integer <int64> (StartTime)

Starting time of an alert muting rule, in Unix time format UTC. If not specified, defaults to the current time. read/write.

stopTime
integer <int64> (StopTime)
Default: 0

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

Request samples

application/json
Copy
Expand all Collapse all
{
  • "description": "string",
  • "filters":
    [
    ],
  • "startTime": 0,
  • "stopTime": 0
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1556825430000,
  • "creator": "AAXYAAAAAZ3",
  • "description": "string",
  • "filters":
    [
    ],
  • "id": "string",
  • "lastUpdated": 1557689430000,
  • "lastUpdatedBy": "string",
  • "startTime": 0,
  • "stopTime": 0
}

Delete Single Alert Muting Rule

Deletes an alert muting rule specified in the {id} path parameter

delete /alertmuting/{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/alertmuting/{id}

Deletes an alert muting rule, specified by the rule ID in the {id} path parameter. Unlike the detector APIs that create v2 detectors, you can use the alert 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 alerting muting rule.

path Parameters
id
required
string

The SignalFx-assigned ID of an alerting muting rule

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful deletion of an alert muting rule that starts in the future.

400

Bad request, for example, you tried to delete an alert muting rule that starts in the past

404

An alert muting rule for the ID you specified doesn't exist.

Retrieve Alert Muting Rule ID

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

get /alertmuting/{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/alertmuting/{id}

Retrieves an alert 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 an alerting muting rule

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful retrieval of the specified alert muting rule

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 alerting muting rule 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 user ID of the alert muting rule creator, in the form of a JSON string. This property is read-only; it's always set by the system.

description
string

Description of the rule. read/write

filters
Array of objects

List of alert muting filters for this rule, in the form of a JSON array of alert muting filter objects. Each object is a set of conditions for an alert muting rule. Each object property (name-value pair) specifies a dimension or custom property to match to alert events. read/write

id
string (Alerting muting rule ID)

SignalFx-assigned ID of an alert muting rule, in the form of a JSON string. This property is read-only; it's always set by the system.

lastUpdated
integer <int64> (Alert muting rule last updated time)

The last time the alert muting rule was last updated, in Unix time UTC-relative. This property is read-only; it's always set by the system.

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

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

startTime
integer <int64> (StartTime)

Starting time of an alert muting rule, in Unix time format UTC. If not specified, defaults to the current time. read/write.

stopTime
integer <int64> (StopTime)
Default: 0

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

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1556825430000,
  • "creator": "AAXYAAAAAZ3",
  • "description": "string",
  • "filters":
    [
    ],
  • "id": "string",
  • "lastUpdated": 1557689430000,
  • "lastUpdatedBy": "string",
  • "startTime": 0,
  • "stopTime": 0
}

Update Single Alert Muting Rule

Updates an alert muting rule

put /alertmuting/{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/alertmuting/{id}

Updates the alert muting rule specified in the {id} path parameter, using the values specified in the request body. 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.

NOTE: In some cases, SignalFx may send notifications during an alert muting period. To learn more, see the section Considerations for alert muting in the API concepts guide.

path Parameters
id
required
string

The SignalFx-assigned ID of an alerting muting rule

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

Alert muting rule properties that overwrite existing properties.

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

description
string

Description of the rule. read/write

filters
Array of objects

List of alert muting filters for this rule, in the form of a JSON array of alert muting filter objects. Each object is a set of conditions for an alert muting rule. Each object property (name-value pair) specifies a dimension or custom property to match to alert events. read/write

startTime
integer <int64> (StartTime)

Starting time of an alert muting rule, in Unix time format UTC. If not specified, defaults to the current time. read/write.

stopTime
integer <int64> (StopTime)
Default: 0

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

Responses

200

Successfully updated the alert muting rule

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 alerting muting rule 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 user ID of the alert muting rule creator, in the form of a JSON string. This property is read-only; it's always set by the system.

description
string

Description of the rule. read/write

filters
Array of objects

List of alert muting filters for this rule, in the form of a JSON array of alert muting filter objects. Each object is a set of conditions for an alert muting rule. Each object property (name-value pair) specifies a dimension or custom property to match to alert events. read/write

id
string (Alerting muting rule ID)

SignalFx-assigned ID of an alert muting rule, in the form of a JSON string. This property is read-only; it's always set by the system.

lastUpdated
integer <int64> (Alert muting rule last updated time)

The last time the alert muting rule was last updated, in Unix time UTC-relative. This property is read-only; it's always set by the system.

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

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

startTime
integer <int64> (StartTime)

Starting time of an alert muting rule, in Unix time format UTC. If not specified, defaults to the current time. read/write.

stopTime
integer <int64> (StopTime)
Default: 0

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

Request samples

application/json
Copy
Expand all Collapse all
{
  • "description": "string",
  • "filters":
    [
    ],
  • "startTime": 0,
  • "stopTime": 0
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1556825430000,
  • "creator": "AAXYAAAAAZ3",
  • "description": "string",
  • "filters":
    [
    ],
  • "id": "string",
  • "lastUpdated": 1557689430000,
  • "lastUpdatedBy": "string",
  • "startTime": 0,
  • "stopTime": 0
}

Unmute Single Alert Muting Rule

Ends the active muting period for an alert muting rule

put /alertmuting/{id}/unmute

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/alertmuting/{id}/unmute

Ends the muting period that's currently active for an alert muting rule and updates the stop time to the current server time. The detector resumes sending notifications that this rule muted. In the web UI, resuming notifications this way is known as cancelling a muting rule.

This operation works with alert muting rules for detectors you create using the web UI as well as detectors you create using the API (v2 detectors).

NOTE: In some cases, SignalFx may send notifications during an alert muting period. To learn more, see the section Considerations for alert muting in the API concepts guide.

path Parameters
id
required
string

The SignalFx-assigned ID of an alerting muting rule

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successfully unmuted an alert

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 alerting muting rule 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 user ID of the alert muting rule creator, in the form of a JSON string. This property is read-only; it's always set by the system.

description
string

Description of the rule. read/write

filters
Array of objects

List of alert muting filters for this rule, in the form of a JSON array of alert muting filter objects. Each object is a set of conditions for an alert muting rule. Each object property (name-value pair) specifies a dimension or custom property to match to alert events. read/write

id
string (Alerting muting rule ID)

SignalFx-assigned ID of an alert muting rule, in the form of a JSON string. This property is read-only; it's always set by the system.

lastUpdated
integer <int64> (Alert muting rule last updated time)

The last time the alert muting rule was last updated, in Unix time UTC-relative. This property is read-only; it's always set by the system.

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

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

startTime
integer <int64> (StartTime)

Starting time of an alert muting rule, in Unix time format UTC. If not specified, defaults to the current time. read/write.

stopTime
integer <int64> (StopTime)
Default: 0

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

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created": 1556825430000,
  • "creator": "AAXYAAAAAZ3",
  • "description": "string",
  • "filters":
    [
    ],
  • "id": "string",
  • "lastUpdated": 1557689430000,
  • "lastUpdatedBy": "string",
  • "startTime": 0,
  • "stopTime": 0
}

Retrieve Incidents

Retrieves information for all incidents

get /incident

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

Retrieves the information for all incidents in an organization. This endpoint retrieves incidents created by detectors you add in the web UI and detectors you add using the API (v2 detectors)

query Parameters
includeResolved
boolean
Default: false

Controls which incidents to retrieve, based on their status. If the value is true, the API returns incidents for which the status is "resolved"; otherwise, the API only returns active incidents.

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.

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful operation

Response Headers
Content-Type
string

Format of the response body. Always application/json.

Response Schema: application/json
Array
active
boolean (Active)

Flag that indicates if the incident is still ongoing ("active"), in the form of a JSON boolean. This property is read-only.

anomalyState
string (AnomalyState)
Enum:"ANOMALOUS" "MANUALLY_RESOLVED" "OK" "STOPPED"

Describes the current anomaly state of an event or incident, in the form of a JSON string that describes the current signal status compared to its expected state. This property is read only. The possible values are:

  • ANOMALOUS: For this event or incident, the detector detected an anomaly, triggered an alert, generated an alert event, and sent a notification. anomaly and issued events in this incident.
  • MANUALLY_RESOLVED: User resolved the incident in the web UI or by calling PUT /incident/{id}/clear.
  • OK: The detector detected that the anomaly had cleared and issued a clear event for the incident.
  • STOPPED: User updated the detector and restarted the detector job
detectLabel
string (DetectLabel)

The label of the SignalFlow program that generated an event or the events in an incident, in the form of a JSON string. The program is specified in the detector that's the source of the event or events. This property is read-only.

detectorId
string (DetectorId)

The SignalFx-assigned ID of the detector that generated an event or the events in an incident, in the form of a JSON string. This property is read-only.

events
Array of objects (IncidentEvent)

A array that contains the event objects for this incident

incidentId
string (IncidentId)

The SignalFx-assigned ID of an incident, in the form of a JSON string. This property is read-only.

severity
string <Capitalized> (Severity)
Enum:"Critical" "Major" "Minor" "Warning" "Info"

The severity of an event or an incident, in the form of an enumerated JSON string. You set this value in the detector that triggered the events in this incident. For the /incident endpoint, this property is read-only.

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Retrieve Incident ID

Retrieves the incident specified in the {id} path parameter

get /incident/{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/incident/{id}

Retrieves an incident, based on the SignalFx-assigned incident ID specified in the {id} path parameter. This endpoint retrieves an incident created by a detector you add using the web UI or a detector you add using the API (a v2 detector).

path Parameters
id
required
string

SignalFx-assigned ID of an incident

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successful retrieval

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

Format of the response body. Always application/json.

Response Schema: application/json
active
boolean (Active)

Flag that indicates if the incident is still ongoing ("active"), in the form of a JSON boolean. This property is read-only.

anomalyState
string (AnomalyState)
Enum:"ANOMALOUS" "MANUALLY_RESOLVED" "OK" "STOPPED"

Describes the current anomaly state of an event or incident, in the form of a JSON string that describes the current signal status compared to its expected state. This property is read only. The possible values are:

  • ANOMALOUS: For this event or incident, the detector detected an anomaly, triggered an alert, generated an alert event, and sent a notification. anomaly and issued events in this incident.
  • MANUALLY_RESOLVED: User resolved the incident in the web UI or by calling PUT /incident/{id}/clear.
  • OK: The detector detected that the anomaly had cleared and issued a clear event for the incident.
  • STOPPED: User updated the detector and restarted the detector job
detectLabel
string (DetectLabel)

The label of the SignalFlow program that generated an event or the events in an incident, in the form of a JSON string. The program is specified in the detector that's the source of the event or events. This property is read-only.

detectorId
string (DetectorId)

The SignalFx-assigned ID of the detector that generated an event or the events in an incident, in the form of a JSON string. This property is read-only.

events
Array of objects (IncidentEvent)

A array that contains the event objects for this incident

incidentId
string (IncidentId)

The SignalFx-assigned ID of an incident, in the form of a JSON string. This property is read-only.

severity
string <Capitalized> (Severity)
Enum:"Critical" "Major" "Minor" "Warning" "Info"

The severity of an event or an incident, in the form of an enumerated JSON string. You set this value in the detector that triggered the events in this incident. For the /incident endpoint, this property is read-only.

Response samples

application/json
Copy
Expand all Collapse all
{
  • "active": true,
  • "anomalyState": "ANOMALOUS",
  • "detectLabel": "string",
  • "detectorId": "string",
  • "events":
    [
    ],
  • "incidentId": "string",
  • "severity": "Critical"
}

Clear Single Incident

Clears the incident specified by the `{id}`path parameter

put /incident/{id}/clear

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/incident/{id}/clear

Manually clears the incident identified by the SignalFx-assigned incident ID specified in the {id} path parameter.

This API can be used with incidents created by a detector you add using the web UI or a detector you add using the API (a v2 detector).

This operation doesn't return a response body.

path Parameters
id
required
string

The id of an existing incident that you want to clear

header Parameters
X-SF-TOKEN
required
string

Authentication token.

Responses

200

Successfully cleared the event

© Copyright 2019 SignalFx.

Third-party license information