API Documentation | Maintenance
Schedule a maintenance window for your account, check, rule set or host.
A number containing an integer between 0 and 5 inclusive
A tag is just a string, with or without a colon, such as 'foo', 'bar', 'datacenter:london', or 'os:linux'. The part of the string before the colon is considered the category the tag is in; Tag strings without a colon will place the string in the 'uncategorized' category. Circonus will lowercase the contents of the string before storing it.
Fetching Maintenance Windows
Fetching details for a maintenance window is as simple as performing a GET on the maintenance cid:
From this we can see some important things:
- The maintenance started at 1383694418 (2013-11-05T23:33:38Z) and ended five minutes later at 1383694718 (2013-11-05T23:38:38Z)
- The host
www2.internal.example.comwas in maintenance
- Since all five severity levels are listed, any alert caused by a rule set based on the given host will be ignored
Creating Maintenance Windows
Creating a new maintenance window is as simple as making a HTTP POST request
/maintenance and passing JSON representing the new maintenance
This puts the entire account into maintenance for the next five minutes for all severities (since start defaults to the current time, and stop defaults to five minutes from the start time, and severities defaults to all five severities)
As is usual, the POST request returns the full JSON in the response (including the new maintenance window's cid)
You can always be more explicit about the start and stop times, specify a particular host (or check, or rule set), and you can add tags:
When creating a maintenance window you can't start or stop the maintenance window in the past (though you can specify a time in the past, it'll just set the start time or stop time to the current time). And obviously you can't create a maintenance window that stops before it starts.
Updating Maintenance Windows
Before we demonstrate how to update a maintenance window, it's important to cover a few basic rules:
- You can't change what the maintenance window refers to (the "item" or the "type")
- Once a maintenance window has started you can't change its start time
- Once a maintenance window has stopped you can't change its stop time
And obviously you can't break any of the rules specified when creating the maintenance window above.
Maintenance windows can be updated simply by using the PUT HTTP method with new field values:
As is normal with Circonus the PUT method returns the full JSON of the updated maintenance window in response.
Listing Maintenance Windows
It's only possible to use the API to list maintenance windows that have not yet stopped (you can still use the API to extract details on past maintenance windows if you know the maintenance window's cid as demonstrated above)
You can list all not yet stopped maintenance windows for your account simply
by requesting the
/maintenance path with a simple GET request.
By applying filters you can restrict which maintenance windows are returned. For example, you can list only those maintenance windows that will be active at a particular time:
Removing Maintenance Windows
If the maintenance window hasn't yet started then you can simply delete it by sending a HTTP DELETE request to the cid:
If the maintenance window has already started then it's a matter of historical record and you can't delete it. If it hasn't stopped yet you can stop it right away by just updating it to stop at the current time: