NAM Server REST API - Alerts blackout

Applies to NAM 2019 Service Pack 1

Use the alerts blackout API commands to configure periods during which alert triggering is suppressed.

Tip

Alerts blackouts can be useful for avoiding skewed statistics that may occur when monitoring continues during scheduled downtime and for preventing alert fatigue (exposing people to so many alerts that they ignore or are slower to respond to important alerts).

  • Alerts blackout does not affect maintenance alerts. They continue to be triggered regardless of your alerts blackout configuration.
  • Access is limited to users with one of the following roles:
    • Internal-API-User
    • Public-API-User
    • Administrator
  • Configuration is per NAM Server
  • Times are in the NAM Server's time zone

GET alerts blackout configuration

A GET request of the form:

GET https://nam-server-address:port/public/api/blackoutAlerts/v1/configuration

returns the alerts blackout configuration for that NAM Server.

Example reponse:

{
    "enabled": false,
    "periods": [
        {
            "periodStartDate": "Thu Jun 11 09:00:00 CEST 2020",
            "periodEndDate": "Thu Jun 11 10:00:00 CEST 2020"
        }
    ]
}
Field Description
enabled Boolean.
  • true = Alerts blackouts are enabled on this NAM Server. Alerts will not be triggered during the specified periods (using the specified NAM Server's time zone).
  • false = Alerts blackouts are disabled on this NAM Server.
periods Contains all blackout periods defined for this NAM Server. If enabled is true, alerts will not be triggered during the specified periods.
  • periodStartDate shows the start of one alerts blackout period.
  • periodEndDate shows the end of one alerts blackout period.
Note that the dates displayed in the response to a GET request are formatted for readability and include the NAM Server's time zone. The format for specifying start and end times in POST and PUT requests is in yyyy-mm-dd hh:mm format without the time zone. See POST alerts blackout configuration and PUT alerts blackout configuration for details.

POST alerts blackout configuration

A POST request of the form:

POST https://nam-server-address:port/public/api/blackoutAlerts/v1/configuration

with a payload of the form:

{
  "enabled": true,
  "periods": [
    {
      "periodStartDate": "yyyy-mm-dd hh:mm",
      "periodEndDate": "yyyy-mm-dd hh:mm"
    },
    {
      "periodStartDate": "yyyy-mm-dd hh:mm",
      "periodEndDate": "yyyy-mm-dd hh:mm"
    }
  ]
}

sets the alerts blackout state and periods for the specified NAM Server based on the contents of the payload. It overwrites any existing alerts blackout configuration on this NAM Server.

Field Description
enabled Boolean.
  • true = Enables alerts blackouts on this NAM Server. Alerts will not be triggered during the specified periods (using the specified NAM Server's time zone).
  • false = Disables alerts blackouts on this NAM Server.
periods Specifies all blackout periods for this NAM Server. If enabled is true, alerts will not be triggered during the specified periods.
  • periodStartDate specifies (in yyyy-mm-dd hh:mm format) the start of one alerts blackout period. Must be earlier than periodEndDate.
  • periodEndDate specifies (in yyyy-mm-dd hh:mm format) the end of one alerts blackout period. Must be a future time and must be later than periodStartDate.
Note that the dates displayed in a response to a GET request are formatted for readability and include the NAM Server's time zone, but the format for specifying start and end times in POST and PUT requests is as above, in yyyy-mm-dd hh:mm format with no time zone specified. The NAM Server's time zone is assumed.

Example payload:

{
  "enabled": true,
  "periods": [
    {
      "periodStartDate": "2020-06-11 09:00",
      "periodEndDate": "2020-06-11 10:00"
    },
    {
      "periodStartDate": "2020-06-11 11:00",
      "periodEndDate": "2020-06-11 12:00"
    }
  ]
}

This example deletes any existing alerts blackout configuration on the specified NAM Server and replaces it with a configuration that enables alerts blackout with two blackout periods (times during which alerts will not be triggered from this NAM Server).

Specify each period with a start and end date and time.

  • periodStartDate specifies (in yyyy-mm-dd hh:mm format) the start of one alerts blackout period. Must be earlier than periodEndDate.
  • periodEndDate specifies (in yyyy-mm-dd hh:mm format) the end of one alerts blackout period. Must be a future time and must be later than periodStartDate.

Specify start and end times as above, in yyyy-mm-dd hh:mm format with no time zone specified. The NAM Server's time zone is assumed.

PUT alerts blackout configuration

A PUT request of the form:

PUT https://nam-server-address:port/public/api/blackoutAlerts/v1/configuration

appends the alerts blackout configuration with the periods specified in the request payload.

Example payload:

[
  {
    "periodStartDate": "2020-06-11 13:00",
    "periodEndDate": "2020-06-11 14:00"
  }
]

Specify a period with a start and end date and time.

  • periodStartDate specifies (in yyyy-mm-dd hh:mm format) the start of one alerts blackout period. Must be earlier than periodEndDate.
  • periodEndDate specifies (in yyyy-mm-dd hh:mm format) the end of one alerts blackout period. Must be a future time and must be later than periodStartDate.

This example adds one alerts blackout period to the existing alerts blackout configuration on the specified NAM Server.

Note that the dates displayed in a response to a GET request are formatted for readability and include the NAM Server's time zone, but the format for specifying start and end times in POST and PUT requests is as above, in yyyy-mm-dd hh:mm format with no time zone specified. The NAM Server's time zone is assumed.

If you issued the previous POST example followed by this PUT example, the resulting alerts blackout configuration change would be as follows:

DELETE alerts blackout configuration

A DELETE request of the form:

DELETE https://nam-server-address:port/public/api/blackoutAlerts/v1/configuration

deletes the entire alerts blackout configuration from the specified NAM Server.

HEAD alerts blackout configuration

A HEAD request of the form:

HEAD https://nam-server-address:port/public/api/blackoutAlerts/v1/configuration

returns the timestamp and date of last modification. This is used, for example, for synchronization in farm configurations or to notify the NAM Console that there have been changes on the NAM Server. For alerts blackout configuration, this head is used for synchronization.