Silenced API

The /silenced API endpoints

The Silenced API provides HTTP POST and GET access to create, query, and clear (delete) a silencing entry.

/silenced (GET)

The /silenced endpoint provides HTTP GET access to silencing entry specifications.

EXAMPLES

The following example demonstrates a /silenced API query which returns a JSON Array of JSON Hashes containing all silencing entry specifications.

$ curl -s -X GET http://127.0.0.1:3000/silenced |jq .
[
  {
    "_id": "us_west1:load-balancer:check_haproxy",
    "expire": 3530,
    "expire_on_resolve": false,
    "begin": null,
    "creator": null,
    "dc": "us_west1",
    "reason": null,
    "check": "check_haproxy",
    "subscription": "load-balancer",
    "id": "load-balancer:check_haproxy",
    "timestamp": 1538599295
  },
  {
    "_id": "us_west1:all:check_ntpd",
    "expire": -1,
    "expire_on_resolve": true,
    "begin": null,
    "creator": "sysop@example.com",
    "dc": "us_west1",
    "reason": "we ran out of time",
    "check": "check_ntpd",
    "subscription": "all",
    "id": "all:check_ntpd",
    "timestamp": 1538599297
  }
]

API specification

/silenced (GET)
description Returns a list of silencing entries.
example url http://hostname:3000/silenced
response type Array
response codes
  • Success: 200 (OK)
  • Error: 500 (Internal Server Error)
output 
[
  {
    "_id": "us_west1:load-balancer:check_haproxy",
    "expire": 3530,
    "expire_on_resolve": false,
    "begin": null,
    "creator": null,
    "dc": "us_west1",
    "reason": null,
    "check": "check_haproxy",
    "subscription": "load-balancer",
    "id": "load-balancer:check_haproxy",
    "timestamp": 1538599295
  },
  {
    "_id": "us_west1:all:check_ntpd",
    "expire": -1,
    "expire_on_resolve": true,
    "begin": null,
    "creator": "sysop@example.com",
    "dc": "us_west1",
    "reason": "we ran out of time",
    "check": "check_ntpd",
    "subscription": "all",
    "id": "all:check_ntpd",
    "timestamp": 1538599297
  }
]

/silenced (POST)

The /silenced API provides HTTP POST access to create a silencing entry.

EXAMPLE

The following example demonstrates a /silenced query that creates a silencing entry with an expiration of 3600 seconds for the check check_haproxy on clients with the load-balancer subscription within the us_west1 datacenter.

$ curl -s -i -X POST \
-H 'Content-Type: application/json' \
-d '{ "dc": "us_west1", "subscription": "load-balancer", "check": "check_haproxy", "expire": 3600 }' \
http://127.0.0.1:3000/silenced

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Origin: *
Connection: close
Content-length: 0

$ curl -s -X GET http://127.0.0.1:3000/silenced | jq .
[
  {
    "_id": "us_west1:load-balancer:check_haproxy",
    "expire": 3594,
    "expire_on_resolve": false,
    "begin": null,
    "creator": null,
    "dc": "us_west1",
    "reason": null,
    "check": "check_haproxy",
    "subscription": "load-balancer",
    "id": "load-balancer:check_haproxy",
    "timestamp": 1538599295
  }
]

API specification

/silenced (POST)
description Create a silencing entry.
example URL http://hostname:3000/silenced
payload 
{
  "dc": "us_west1",
  "subscription": "load-balancer",
  "expire": 3600,
  "reason": "load-balancer maintenance window",
  "creator": "sysop@example.com"
}
payload parameters
  • dc
    • required: true
    • type: String
    • description: Specifies the name of the datacenter where the silence entry applies.
    • example: "us_west1"
  • check
    • required: true, unless subscription is specified
    • type: String
    • description: Specifies the check which the silence entry applies to.
    • example: "check_haproxy"
  • begin
    • required: false
    • type: Integer
    • description: If specified, the silence entry is only effective after this epoch timestamp. Silence a check and/or client subscriptions at a predetermined time (e.g. maintenance window).
    • example: 1512501881
  • creator
    • required: false
    • type: String
    • description: Specifies the entity responsible for this entry.
    • example: "you@yourdomain.com" or "Your Name Here"
  • expire
    • required: false
    • type: Integer
    • description: If specified, the silence entry automatically clears after this number of seconds. If begin is specified, the number of seconds until being cleared starts at that time.
    • example: 1800
  • expire_on_resolve
    • required: false
    • type: Boolean
    • description: If specified as true, the silence entry automatically clears once the condition it is silencing is resolved.
    • example: true
  • reason
    • required: false
    • type: String
    • description: If specified, this free-form string is used to provide context or rationale for the reason this silence entry was created.
    • example: "pre-arranged maintenance window"
  • subscription
    • required: true, unless check is specified
    • type: String
    • description: Specifies the subscription which the silence entry applies to.
    response codes
    • Success: 200 (OK)
    • Malformed: 400 (Bad Request)
    • Error: 500 (Internal Server Error)

    /silenced/clear (POST)

    The /silenced API provides HTTP POST access to delete a silencing entry.

    EXAMPLE

    The following example demonstrates a /silenced query that deletes a silencing entry with the id load-balancer:check_haproxy within the us_west1 datacenter.

    $ curl -s -i -X POST \
-H 'Content-Type: application/json' \
-d '{ "dc": "us_west1", "id": "load-balancer:check_haproxy" }' \
http://127.0.0.1:3000/silenced/clear

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Origin: *
Connection: close
Content-length: 0

    API specification

    /silenced/clear (POST)
    description Clear a silencing entry.
    example URL http://hostname:3000/silenced/clear
    payload 
    {
  "dc": "us_west1",
  "id": "load-balancer:ha_proxy"
}
    payload parameters
    • dc
      • required: true
      • type: String
      • description: Specifies the name of the datacenter where the silence entry applies.
      • example: "us_west1"
    • check
      • required: true, unless subscription or id is specified
      • type: String
      • description: Specifies the name of the check for which the silence entry should be cleared.
      • example: “check_haproxy”
    • subscription:
      • required: true, unless client is specified
      • type: String
      • description: Specifies the name of the subscription for which the silence entry should be cleared.
    • id:
      • required: true, unless client or is specified
      • type: String
      • description: Specifies the id (intersection of subscription and check) of the subscription for which the silence entry should be cleared.
    response codes
    • Success: 200 (OK)
    • Malformed: 400 (Bad Request)
    • Error: 500 (Internal Server Error)