Flapjack::Diner

Access the JSON API of a Flapjack system monitoring server.

Note that flapjack-diner releases after 1.0.0.rc1 require the JSONAPI gateway of Flapjack to connect to. All previous releases (0.x) require the older API Flapjack gateway.

Installation

Add this line to your application's Gemfile:

gem 'flapjack-diner', :github => 'flapjack/flapjack-diner'

And then execute:

$ bundle

Note, you can also install from RubyGems.org as usual.

Usage

Set the URI of the Flapjack server:

Flapjack::Diner.base_uri('127.0.0.1:5000')

Optionally, set a logger to log requests & responses:

Flapjack::Diner.logger = Logger.new('logs/flapjack_diner.log')

If you want to alter timeout periods for HTTP connection open and reading responses:

# Set HTTP connect timeout to 30 seconds
Flapjack::Diner.open_timeout(30)

# Set HTTP read timeout to 5 minutes
Flapjack::Diner.read_timeout(300)

If you want the old behaviour wrt returning hashes with keys as strings (they're now symbols by default) then:

Flapjack::Diner.return_keys_as_strings = true

Functions

Parameters for all of flapjack-diner's functions are organised into three categories:

Ids -- One or more String or Integer values
Query parameters -- Top-level hash values
Payload data -- Arrays of Hashes

While these can be passed in in any order, the convention is that they will be ordered as listed above.

If any operation fails (returning nil), Flapjack::Diner.last_error will contain an error message regarding the failure.

create_contacts

Create one or more contacts.

Flapjack::Diner.create_contacts([CONTACT, ...])

CONTACT
{
  :id => STRING,
  :first_name => STRING,
  :last_name => STRING,
  :email => STRING,
  :tags => [STRING, ...]
}

Returns an array of contact ids if creation succeeded, or false if creation failed.

contacts

Return data for one, some or all contacts.

contact = Flapjack::Diner.contacts(ID)
some_contacts = Flapjack::Diner.contacts(ID1, ID2, ...)
all_contacts = Flapjack::Diner.contacts

update_contacts

Update data for one or more contacts.

# update values for one contact
Flapjack::Diner.update_contacts(ID, :key => value, ...)

# update values for multiple contacts
Flapjack::Diner.update_contacts(ID1, ID2, ..., :key => value, ...)

Acceptable update field keys are

:first_name, :last_name, :email

as well as the linkage operations

:add_entity, :remove_entity :add_notification_rule, :remove_notification_rule

which take the id (for entity and notification rule) of the relevant resource as the value.

(NB: :add_medium and :remove_medium are not supported in Flapjack v1.x but will be in future versions.)

Returns true if updating succeeded, false if updating failed.

delete_contacts

Delete one or more contacts.

# delete one contact
Flapjack::Diner.delete_contacts(ID)

# delete multiple contacts
Flapjack::Diner.delete_contacts(ID1, ID2, ...)

Returns true if deletion succeeded or false if deletion failed.

create_contact_media

Create one or more notification media.

Flapjack::Diner.create_contact_media(CONTACT_ID, [MEDIUM, ...])

MEDIUM
{
  :type => STRING,
  :address => STRING,
  :interval => INTEGER,
  :rollup_threshold => INTEGER
}

Returns an array of media ids if creation succeeded, or false if creation failed. (Ids cannot be passed in for media records in Flapjack v1.x.)

media

Return data for one, some or all notification media. Notification media ids are formed by compounding their linked contact's ID and their type in a string (e.g. '23_sms').

medium = Flapjack::Diner.media(ID)
some_media = Flapjack::Diner.media(ID1, ID2, ...)
all_media = Flapjack::Diner.media

update_media

Update data for one or more notification media.

# update values for one medium
Flapjack::Diner.update_media(ID, :key => value, ...)

# update values for multiple media
Flapjack::Diner.update_media(ID1, ID2, ..., :key => value, ...)

Acceptable update field keys are

:address, :interval, :rollup_threshold

Returns true if updating succeeded or false if updating failed.

delete_media

Delete one or more notification media.

# delete one medium
Flapjack::Diner.delete_media(ID)

# delete multiple media
Flapjack::Diner.delete_media(ID1, ID2, ...)

Returns true if deletion succeeded or false if deletion failed.

create_contact_pagerduty_credentials

Create pagerduty credentials for a contact.

Flapjack::Diner.create_contact_pagerduty_credentials(CONTACT_ID, PAGERDUTY_CREDENTIALS)

PAGERDUTY_CREDENTIALS
{
  :service_key => STRING,
  :subdomain => STRING,
  :username => STRING,
  :password => STRING
}

Returns an array of contact ids if creation succeeded, or false if creation failed. (As contacts may only have one set of pagerduty credentials, Flapjack v1.x does not store a separate data model, thus theses objects have no separate ids.)

pagerduty_credentials

Return pagerduty credentials for a contact.

pagerduty_credentials = Flapjack::Diner.pagerduty_credentials(CONTACT_ID)
some_pagerduty_credentials = Flapjack::Diner.pagerduty_credentials(CONTACT_ID1, CONTACT_ID2, ...)
all_pagerduty_credentials = Flapjack::Diner.pagerduty_credentials

update_pagerduty_credentials

Update pagerduty credentials for one or more contacts.

# update pagerduty_credentials for one contact
Flapjack::Diner.update_pagerduty_credentials(CONTACT_ID, :key => value, ...)

# update pagerduty_credentials for multiple contacts
Flapjack::Diner.update_pagerduty_credentials(CONTACT_ID1, CONTACT_ID2, ..., :key => value, ...)

Acceptable update field keys are

:service_key, :subdomain, :username, :password

Returns true if updating succeeded or false if updating failed.

delete_pagerduty_credentials

Delete pagerduty credentials for one or more contacts

# delete pagerduty_credentials for one contact
Flapjack::Diner.delete_pagerduty_credentials(CONTACT_ID)

# delete pagerduty_credentials for multiple contacts
Flapjack::Diner.delete_pagerduty_credentials(CONTACT_ID1, CONTACT_ID2, ...)

Returns true if deletion succeeded or false if deletion failed.

create_contact_notification_rules

Create one or more notification rules.

Flapjack::Diner.create_contact_notification_rules(CONTACT_ID, [NOTIFICATION_RULE, ...])

NOTIFICATION_RULE
{
  :id => STRING,
  :entities => [STRING, ...],
  :regex_entities => [STRING, ...],
  :tags => [STRING, ...],
  :regex_tags => [STRING, ...],
  :time_restrictions => TODO,
  :unknown_media => [STRING, ...],
  :warning_media => [STRING, ...],
  :critical_media => [STRING, ...],
  :unknown_blackhole => BOOLEAN,
  :warning_blackhole => BOOLEAN,
  :critical_blackhole => BOOLEAN
}

Returns an array of notification rule ids if creation succeeded, or false if creation failed.

notification_rules

Return data for one, some or all notification rules.

notification_rule = Flapjack::Diner.notification_rules(ID)
some_notification_rules = Flapjack::Diner.notification_rules(ID1, ID2, ...)
all_notification_rules = Flapjack::Diner.notification_rules

update_notification_rules

Update data for one or more notification rules.

# update values for one notification rule
Flapjack::Diner.update_notification_rules(ID, :key => value, ...)

# update values for multiple notification rules
Flapjack::Diner.update_notification_rules(ID1, ID2, ..., :key => value, ...)

Acceptable update field keys are

:entities, :regex_entities, :tags, :regex_tags, :time_restrictions, :unknown_media, :warning_media, :critical_media, :unknown_blackhole, :warning_blackhole, and :critical_blackhole

Returns true if updating succeeded or false if updating failed.

delete_notification_rules

Delete one or more notification rules.

# delete one medium
Flapjack::Diner.delete_notification_rules(ID)

# delete multiple contacts
Flapjack::Diner.delete_notification_rules(ID1, ID2, ...)

Returns true if deletion succeeded or false if deletion failed.

create_entities

Create one or more entities.

Flapjack::Diner.create_entities([ENTITY, ...])

ENTITY
{
  :id => STRING,
  :name => STRING,
  :tags => [STRING, ...]
}

Returns an array of entity ids if creation succeeded, or false if creation failed.

entities

Return data for one, some or all entities.

entity = Flapjack::Diner.entities(ID)
some_entities = Flapjack::Diner.entities(ID1, ID2, ...)
all_entities = Flapjack::Diner.entities

entities_matching

Returns an array of entities matching a given regular expression

entities = Flapjack::Diner.entities_matching(/^db-app-01/)

update_entities

Update data for one or more entities.

# update values for one entity
Flapjack::Diner.update_entities(ID, :key => value, ...)

# update values for multiple entities
Flapjack::Diner.update_entities(ID1, ID2, ..., :key => value, ...)

There are no valid update field keys yet.

The linkage operations

:add_contact and :remove_contact :add_tag and :remove_tag

take the id (for contact) or the name (for tag) of the relevant resource as the value.

Returns true if updating succeeded or false if updating failed.

create_scheduled_maintenances_entities

Create one or more scheduled maintenance periods (duration seconds in length) on all checks for the provided entities.

Flapjack::Diner.create_scheduled_maintenances_entities(ENTITY_ID(S), [SCHEDULED_MAINTENANCE, ...])

SCHEDULED_MAINTENANCE
{
  :start_time => DATETIME,
  :duration => INTEGER,
  :summary => STRING
}

Returns true if creation succeeded or false if creation failed.

delete_scheduled_maintenances_entities

Delete scheduled maintenance periods starting at a specific time for checks across one or more entities.

Flapjack::Diner.delete_scheduled_maintenances_entities(ENTITY_ID(S), :start_time => DATETIME)

Returns true if deletion succeeded or false if deletion failed. Raises an exception if the :start_time parameter is not supplied.

create_unscheduled_maintenances_entities

Acknowledges any failing checks on the passed entities and sets up unscheduled maintenance (duration seconds long) on them.

Flapjack::Diner.create_unscheduled_maintenances_entities(ENTITY_ID(S), [SCHEDULED_MAINTENANCE, ...])

UNSCHEDULED_MAINTENANCE
{
  :duration => INTEGER,
  :summary => STRING
}

Returns true if creation succeeded or false if creation failed.

update_unscheduled_maintenances_entities

Finalises currently existing unscheduled maintenance periods for all acknowledged checks in the provided entities. The periods end at the time provided in the :end_time parameter.

Flapjack::Diner.update_unscheduled_maintenances_entities(ENTITY_ID(S), :end_time => DATETIME)

Returns true if the finalisation succeeded or false if deletion failed.

create_test_notifications_entities

Instructs Flapjack to issue test notifications on all checks for the passed entities. These notifications will be sent to contacts configured to receive notifications for those checks.

Flapjack::Diner.create_test_notifications_entities(ENTITY_ID(S), [TEST_NOTIFICATION, ...])

TEST_NOTIFICATION
{
  :summary => STRING
}

Returns true if creation succeeded or false if creation failed.

create_checks

Create one or more checks.

Flapjack::Diner.create_checks([CHECK, ...])

CHECK
{
  :entity_id => STRING,
  :name      => STRING,
  :tags      => [STRING, ...]
}

Returns an array of check ids if creation succeeded, or false if creation failed. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)

checks

Return basic identity data for one, some or all checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)

check = Flapjack::Diner.checks(ID)
some_checks = Flapjack::Diner.checks(ID1, ID2, ...)
all_checks = Flapjack::Diner.checks

checks_matching

Returns an array of checks matching a given regular expression

entities = Flapjack::Diner.checks_matching(/^PING/)

update_checks

Update data for one or more checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)

# update values for one checks
Flapjack::Diner.update_checks(ID, :key => value, ...)

# update values for multiple checks
Flapjack::Diner.update_checks(ID1, ID2, ..., :key => value, ...)

Acceptable update field keys are

:enabled

as well as the linkage operations

:add_tag and :remove_tag

which take the name of the tag as the value.

Returns true if updating succeeded or false if updating failed.

create_scheduled_maintenances_checks

Create one or more scheduled maintenance periods (duration seconds in length) on one or more checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)

Flapjack::Diner.create_scheduled_maintenances_checks(CHECK_ID(S), [SCHEDULED_MAINTENANCE, ...])

SCHEDULED_MAINTENANCE
{
  :start_time => DATETIME,
  :duration => INTEGER,
  :summary => STRING
}

Returns true if creation succeeded or false if creation failed.

delete_scheduled_maintenances_checks

Delete scheduled maintenance periods starting at a specific time for one or more checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)

Flapjack::Diner.delete_scheduled_maintenances_checks(CHECK_ID(S), :start_time => DATETIME)

Returns true if deletion succeeded or false if deletion failed. Raises an exception if the :start_time parameter is not supplied.

create_unscheduled_maintenances_checks

Acknowledges any failing checks from those passed and sets up unscheduled maintenance (duration seconds long) on them. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)

Flapjack::Diner.create_unscheduled_maintenances_checks(CHECK_ID(S), [SCHEDULED_MAINTENANCE, ...])

UNSCHEDULED_MAINTENANCE
{
  :duration => INTEGER,
  :summary => STRING
}

Returns true if creation succeeded or false if creation failed.

update_unscheduled_maintenances_checks

Finalises currently existing unscheduled maintenance periods for acknowledged checks. The periods end at the time provided in the :end_time parameter. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)

Flapjack::Diner.update_unscheduled_maintenances_checks(CHECK_ID(S), :end_time => DATETIME)

Returns true if the finalisation succeeded or false if deletion failed.

create_test_notifications_checks

Instructs Flapjack to issue test notifications on the passed checks. These notifications will be sent to contacts configured to receive notifications for those checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)

Flapjack::Diner.create_test_notifications_checks(CHECK_ID(S), [TEST_NOTIFICATION, ...])

TEST_NOTIFICATION
{
  :summary => STRING
}

Returns true if creation succeeded or false if creation failed.

status_report_entities

Return a report on status data for checks in one, some or all entities.

report = Flapjack::Diner.status_report_entities(ENTITY_ID)
report_some = Flapjack::Diner.status_report_entities(ENTITY_ID1, ENTITY_ID2, ...)
report_all = Flapjack::Diner.status_report_entities

scheduled_maintenance_report_entities

Return a report on scheduled maintenance periods for checks in one, some or all entities.

report = Flapjack::Diner.scheduled_maintenance_report_entities(ENTITY_ID)
report_some = Flapjack::Diner.scheduled_maintenance_report_entities(ENTITY_ID1, ENTITY_ID2, ...)
report_all = Flapjack::Diner.scheduled_maintenance_report_entities

unscheduled_maintenance_report_entities

Return a report on unscheduled maintenance periods for checks in one, some or all entities.

report = Flapjack::Diner.unscheduled_maintenance_report_entities(ENTITY_ID)
report_some = Flapjack::Diner.unscheduled_maintenance_report_entities(ENTITY_ID1, ENTITY_ID2, ...)
report_all = Flapjack::Diner.unscheduled_maintenance_report_entities

downtime_report_entities

Return a report on downtime data for checks in one, some or all entities.

report = Flapjack::Diner.downtime_report_entities(ENTITY_ID)
report_some = Flapjack::Diner.downtime_report_entities(ENTITY_ID1, ENTITY_ID2, ...)
report_all = Flapjack::Diner.downtime_report_entities

outage_report_entities

Return a report on outage data for checks in one, some or all entities.

report = Flapjack::Diner.outage_report_entities(ENTITY_ID)
report_some = Flapjack::Diner.outage_report_entities(ENTITY_ID1, ENTITY_ID2, ...)
report_all = Flapjack::Diner.outage_report_entities

status_report_checks

Return a report on status data for one, some or all checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)

report = Flapjack::Diner.status_report_checks(CHECK_ID)
report_some = Flapjack::Diner.status_report_checks(CHECK_ID1, CHECK_ID2, ...)
report_all = Flapjack::Diner.status_report_checks

scheduled_maintenance_report_checks

Return a report on scheduled maintenance periods for one, some or all checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)

report = Flapjack::Diner.scheduled_maintenance_report_checks(CHECK_ID)
report_some = Flapjack::Diner.scheduled_maintenance_report_checks(CHECK_ID1, CHECK_ID2, ...)
report_all = Flapjack::Diner.scheduled_maintenance_report_checks

unscheduled_maintenance_report_checks

Return a report on unscheduled maintenance periods for one, some or all checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)

report = Flapjack::Diner.unscheduled_maintenance_report_checks(CHECK_ID)
report_some = Flapjack::Diner.unscheduled_maintenance_report_checks(CHECK_ID1, CHECK_ID2, ...)
report_all = Flapjack::Diner.unscheduled_maintenance_report_checks

downtime_report_checks

Return a report on downtime data for one, some or all checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)

report = Flapjack::Diner.downtime_report_checks(CHECK_ID)
report_some = Flapjack::Diner.downtime_report_checks(CHECK_ID1, CHECK_ID2, ...)
report_all = Flapjack::Diner.downtime_report_checks

outage_report_checks

Return a report on outage data for one, some or all checks. (Check ids are composed by joining together the check's entity's name, the character ':' and the check's name.)

report = Flapjack::Diner.outage_report_checks(CHECK_ID)
report_some = Flapjack::Diner.outage_report_checks(CHECK_ID1, CHECK_ID2, ...)
report_all = Flapjack::Diner.outage_report_checks

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Added some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

Flapjack::Diner

Installation

Usage

Functions

Contacts

Media

Pagerduty credentials

Notification rules

Entities

Checks

Reports

create_contacts

contacts

update_contacts

delete_contacts

create_contact_media

media

update_media

delete_media

create_contact_pagerduty_credentials

pagerduty_credentials

update_pagerduty_credentials

delete_pagerduty_credentials

create_contact_notification_rules

notification_rules

update_notification_rules

delete_notification_rules

create_entities

entities

entities_matching

update_entities

create_scheduled_maintenances_entities

delete_scheduled_maintenances_entities

create_unscheduled_maintenances_entities

update_unscheduled_maintenances_entities

create_test_notifications_entities

create_checks

checks

checks_matching

update_checks

create_scheduled_maintenances_checks

delete_scheduled_maintenances_checks

create_unscheduled_maintenances_checks

update_unscheduled_maintenances_checks

create_test_notifications_checks

status_report_entities

scheduled_maintenance_report_entities

unscheduled_maintenance_report_entities

downtime_report_entities

outage_report_entities

status_report_checks

scheduled_maintenance_report_checks

unscheduled_maintenance_report_checks

downtime_report_checks

outage_report_checks

Contributing