Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Consumer of the Flapjack API
Ruby

README.md

Flapjack::Diner

Travis CI Status

Access the JSON API of a Flapjack system monitoring server.

Please note that the following documentation refers to the v2.0.0-alpha.3 pre-release of this gem. You may instead be looking for documentation for the latest stable version.

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

Options for all of flapjack-diner's functions are organised as either:

  • Ids &emdash; One or more String or Integer values; or
  • Parameters &emdash; One or more 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), the Flapjack::Diner.last_error method will return an error message regarding the failure.

 

 Checks

 Contacts

 Media

 Acceptors

 Rejectors

 Tags

 Maintenance periods

 Events

 Miscellaneous


 

Checks ^

 

create_checks

Create one or more checks.

Flapjack::Diner.create_checks(CHECK, ...)
CHECK
{
  :id      => STRING,
  :name    => STRING,
  :enabled => BOOLEAN,
  :tags    => [TAG_NAME, ...]
}

Returns false if creation failed, or the created object(s) if it succeeded.

^

 

checks

Return data for one, some or all checks.

check = Flapjack::Diner.checks(CHECK_ID)
some_checks = Flapjack::Diner.checks(CHECK_ID, CHECK_ID, ...)
first_page_of_checks = Flapjack::Diner.checks

^

 

update_checks

Update data for one or more checks.

# update values for one check
Flapjack::Diner.update_checks(CHECK_ID, KEY => VALUE, ...)

# update values for multiple checks
Flapjack::Diner.update_checks({CHECK_ID, KEY => VALUE, ...}, {CHECK_ID, KEY => VALUE, ...})

Acceptable update field keys are

:enabled, :name and :tags

Returns true if updating succeeded or false if updating failed.

^

 

delete_checks

Delete one or more checks.

# delete one check
Flapjack::Diner.delete_checks(CHECK_ID)

# delete multiple check
Flapjack::Diner.delete_checks(CHECK_ID, CHECK_ID, ...)

Returns true if deletion succeeded or false if deletion failed.

^


 

Contacts ^

 

create_contacts

Create one or more contacts.

Flapjack::Diner.create_contacts(CONTACT, ...)
CONTACT
{
  :id => STRING,
  :name => STRING,
  :timezone => STRING,
  :tags => [TAG_NAME, ...]
}

Returns false if creation failed, or the created object(s) if it succeeded.

^

 

contacts

Return data for one, some or all contacts.

contact = Flapjack::Diner.contacts(CONTACT_ID)
some_contacts = Flapjack::Diner.contacts(CONTACT_ID, CONTACT_ID, ...)
first_page_of_contacts = Flapjack::Diner.contacts

^

 

update_contacts

Update data for one or more contacts.

# update values for one contact
Flapjack::Diner.update_contacts(CONTACT_ID, KEY => VALUE, ...)

# update values for multiple contacts
Flapjack::Diner.update_contacts({CONTACT_ID, KEY => VALUE, ...}, {CONTACT_ID, KEY => VALUE, ...})

Acceptable update field keys are

:name, :timezone and :tags

Returns true if updating succeeded, false if updating failed.

^

 

delete_contacts

Delete one or more contacts.

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

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

Returns true if deletion succeeded or false if deletion failed.

^


 

Media ^

 

create_media

Create one or more notification media.

Flapjack::Diner.create_media(MEDIUM, MEDIUM, ...)
# MEDIUM
{
  :id => UUID,
  :transport => STRING,               # required
  :address => STRING,                 # required (context depends on transport)
  :interval => INTEGER,               # required (if transport != 'pagerduty')
  :rollup_threshold => INTEGER,       # required (if transport != 'pagerduty')
  :pagerduty_subdomain => STRING,     # required (if transport == 'pagerduty')
  :pagerduty_token => STRING,         # required (if transport == 'pagerduty')
  :pagerduty_ack_duration => INTEGER, # required (if transport == 'pagerduty')
  :contact => CONTACT_ID,             # required
  :acceptors => [ACCEPTOR_ID, ACCEPTOR_ID, ...],
  :rejectors => [REJECTOR_ID, REJECTOR_ID, ...]
}

Returns false if creation failed, or the created object(s) if it succeeded.

^

 

media

Return data for one, some or all notification media.

medium = Flapjack::Diner.media(MEDIUM_ID)
some_media = Flapjack::Diner.media(MEDIUM_ID, MEDIUM_ID, ...)
first_page_of_media = Flapjack::Diner.media

^

 

update_media

Update data for one or more notification media.

# update values for one medium
Flapjack::Diner.update_media(MEDIUM_ID, KEY => VALUE, ...)

# update values for multiple media
Flapjack::Diner.update_media({MEDIUM_ID, KEY => VALUE, ...}, {MEDIUM_ID, KEY => VALUE, ...})

Acceptable update field keys are

:address, :interval, :rollup_threshold, :pagerduty_subdomain, :pagerduty_token, :pagerduty_ack_duration, :acceptors and :rejectors

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(MEDIUM_ID)

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

Returns true if deletion succeeded or false if deletion failed.

^


 

Acceptors ^

 

create_acceptors

Create one or more notification acceptors.

Flapjack::Diner.create_acceptors(ACCEPTOR, ...)

FIXME time_restrictions data structure isn't handled yet

# ACCEPTOR
{
  :id              => UUID_STRING,
  :name            => STRING,
  :all             => BOOLEAN,          # apply to all checks, ignore tag linkages
  :conditions_list => STRING,           # which conditions the acceptor will match;
                                        # all if empty, or comma-separated subset
                                        # of 'critical,warning,unknown'
  :contact         => CONTACT_ID,       # required
  :media           => [MEDIUM_ID, ...]
  :tags            => [TAG_NAME, ...]
}

Returns false if creation failed, or the created object(s) if it succeeded.

^

 

acceptors

Return data for one, some or all notification acceptors.

acceptor = Flapjack::Diner.acceptors(ACCEPTOR_ID)
some_acceptors = Flapjack::Diner.acceptors(ACCEPTOR_ID, ACCEPTOR_ID, ...)
first_page_of_acceptors = Flapjack::Diner.acceptors

^

 

update_acceptors

Update data for one or more notification acceptors.

# update values for one acceptor
Flapjack::Diner.update_acceptors(:id => ACCEPTOR_ID, KEY => VALUE, ...)

# update values for multiple acceptors
Flapjack::Diner.update_acceptors({:id => ACCEPTOR_ID, KEY => VALUE, ...}, {:id => ACCEPTOR_ID, KEY => VALUE, ...})

Acceptable update field keys are

:conditions_list, :is_blackhole, :media and :tags

Returns true if updating succeeded or false if updating failed.

^

 

delete_acceptors

Delete one or more notification acceptors.

# delete one acceptor
Flapjack::Diner.delete_acceptors(ACCEPTOR_ID)

# delete multiple acceptors
Flapjack::Diner.delete_acceptors(ACCEPTOR_ID, ACCEPTOR_ID, ...)

Returns true if deletion succeeded or false if deletion failed.

^


 

Rules ^

 

create_rejectors

Create one or more notification rejectors.

Flapjack::Diner.create_rejectors(REJECTOR, ...)

FIXME time_restrictions data structure isn't handled yet

# REJECTOR
{
  :id              => UUID_STRING,
  :name            => STRING,
  :all             => BOOLEAN,          # apply to all checks, ignore tag linkages
  :conditions_list => STRING,           # which conditions the rejector will match;
                                        # all if empty, or comma-separated subset
                                        # of 'critical,warning,unknown'
  :contact         => CONTACT_ID,       # required
  :media           => [MEDIUM_ID, ...]
  :tags            => [TAG_NAME, ...]
}

Returns false if creation failed, or the created object(s) if it succeeded.

^

 

rejectors

Return data for one, some or all notification rejectors.

rejector = Flapjack::Diner.rejectors(REJECTOR_ID)
some_rejectors = Flapjack::Diner.rejectors(REJECTOR_ID, REJECTOR_ID, ...)
first_page_of_rejectors = Flapjack::Diner.rejectors

^

 

update_rejectors

Update data for one or more notification rejectors.

# update values for one rejector
Flapjack::Diner.update_rejectors(:id => REJECTOR_ID, KEY => VALUE, ...)

# update values for multiple rejectors
Flapjack::Diner.update_rejectors({:id => REJECTOR_ID, KEY => VALUE, ...}, {:id => REJECTOR_ID, KEY => VALUE, ...})

Acceptable update field keys are

:conditions_list, :is_blackhole, :media and :tags

Returns true if updating succeeded or false if updating failed.

^

 

delete_rejectors

Delete one or more notification rejectors.

# delete one rejector
Flapjack::Diner.delete_rejectors(REJECTOR_ID)

# delete multiple rejectors
Flapjack::Diner.delete_rejectors(REJECTOR_ID, REJECTOR_ID, ...)

Returns true if deletion succeeded or false if deletion failed.

^


 

Tags ^

 

create_tags

Create one or more tags.

Flapjack::Diner.create_tags(TAG, ...)
# TAG
{
  :name      => STRING,         # required
  :checks    => [CHECK_ID, ...],
  :contacts  => [CONTACT_ID, ...],
  :acceptors => [ACCEPTOR_ID, ...],
  :rejectors => [REJECTOR_ID, ...]
}

Returns false if creation failed, or the created object(s) if it succeeded.

^

 

tags

Return data for one, some or all tags.

tag = Flapjack::Diner.tags(TAG_NAME)
some_tags = Flapjack::Diner.tags(TAG_NAME, TAG_NAME, ...)
first_page_of_tags = Flapjack::Diner.tags

^

 

update_tags

Update data for one or more tags.

# update values for one tag
Flapjack::Diner.update_tags(:id => TAG_NAME, KEY => VALUE, ...)

# update values for multiple tags
Flapjack::Diner.update_tags({:id => TAG_NAME, KEY => VALUE, ...}, {:id => TAG_NAME, KEY => VALUE, ...})

Acceptable update field keys are

:checks, :contacts, :acceptors and :rejectors

Returns true if updating succeeded or false if updating failed.

^

 

delete_tags

Delete one or more tags.

# delete one tag
Flapjack::Diner.delete_tags(TAG_NAME)

# delete multiple tags
Flapjack::Diner.delete_tags(TAG_NAME, TAG_NAME, ...)

Returns true if deletion succeeded or false if deletion failed.

^


 

Maintenance periods ^

 

create_scheduled_maintenances

Create one or more scheduled maintenance periods (duration seconds in length) on one or more checks.

Flapjack::Diner.create_scheduled_maintenances(SCHEDULED_MAINTENANCE, ...)
SCHEDULED_MAINTENANCE
{
  :id => UUID,
  :start_time => DATETIME, # required
  :end_time => DATETIME,   # required
  :summary => STRING,
  :check => CHECK_ID,      # one (and only one) of :check or :tag must be provided
  :tag => TAG_NAME         # :tag will create scheduled maintenance periods for all checks that this tag is associated with
}

Returns false if creation failed, or the created object(s) if it succeeded.

^

 

scheduled_maintenances

Return data for one, some or all scheduled maintenance periods.

scheduled_maintenance = Flapjack::Diner.scheduled_maintenances(SCHEDULED_MAINTENANCE_ID)
some_scheduled_maintenances = Flapjack::Diner.scheduled_maintenances(SCHEDULED_MAINTENANCE_ID, SCHEDULED_MAINTENANCE_ID, ...)
first_page_of_scheduled_maintenances = Flapjack::Diner.scheduled_maintenances

^

 

update_scheduled_maintenances

Update data for one or more scheduled maintenance periods.

# update values for one scheduled maintenance period
Flapjack::Diner.update_scheduled_maintenances(:id => SCHEDULED_MAINTENANCE_ID, KEY => VALUE, ...)

# update values for multiple scheduled maintenance periods
Flapjack::Diner.update_scheduled_maintenances({:id => SCHEDULED_MAINTENANCE_ID, KEY => VALUE, ...}, {:id => SCHEDULED_MAINTENANCE_ID, KEY => VALUE, ...})

Acceptable update field keys are

:start_time, :end_time and :summary

Returns true if updating succeeded or false if updating failed.

FIXME we may make it a configuration setting as to whether times in the past may be edited

^

 

delete_scheduled_maintenances

Delete one or more scheduled maintenance periods.

Flapjack::Diner.delete_scheduled_maintenances(SCHEDULED_MAINTENANCE_ID)
Flapjack::Diner.delete_scheduled_maintenances(SCHEDULED_MAINTENANCE_ID, SCHEDULED_MAINTENANCE_ID, ...)

Returns true if deletion succeeded or false if deletion failed.

FIXME we may make it a configuration setting as to whether scheduled maintenance periods that have already started (or finished) may be deleted

^

 

unscheduled_maintenances

Return data for one, some or all unscheduled maintenance periods.

unscheduled_maintenance = Flapjack::Diner.unscheduled_maintenances(UNSCHEDULED_MAINTENANCE_ID)
some_unscheduled_maintenances = Flapjack::Diner.unscheduled_maintenances(UNSCHEDULED_MAINTENANCE_ID, UNSCHEDULED_MAINTENANCE_ID, ...)
first_page_of_unscheduled_maintenances = Flapjack::Diner.unscheduled_maintenances

^

 

update_unscheduled_maintenances

Update data for one or more unscheduled maintenance periods.

Flapjack::Diner.update_unscheduled_maintenances(:id => UNSCHEDULED_MAINTENANCE_ID, KEY => VALUE)

Flapjack::Diner.update_unscheduled_maintenances({:id => UNSCHEDULED_MAINTENANCE_ID, KEY => VALUE},
  {:id => UNSCHEDULED_MAINTENANCE_ID, KEY => VALUE}, ...)

Acceptable update field keys are

:start_time, :end_time and :summary

Returns true if updating succeeded or false if updating failed.

FIXME we may make it a configuration setting as to whether times in the past may be edited

^

 

delete_unscheduled_maintenances

Delete one or more unscheduled maintenance periods.

Flapjack::Diner.delete_unscheduled_maintenances(UNSCHEDULED_MAINTENANCE_ID)
Flapjack::Diner.delete_unscheduled_maintenances(UNSCHEDULED_MAINTENANCE_ID, UNSCHEDULED_MAINTENANCE_ID, ...)

Returns true if deletion succeeded or false if deletion failed.

FIXME we may make it a configuration setting as to whether unscheduled maintenance periods may be deleted

^


 

Events ^

 

create_acknowledgements

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

Flapjack::Diner.create_acknowledgements(ACKNOWLEDGEMENT, ...)
# ACKNOWLEDGEMENT
{
  :summary => STRING,
  :duration => INTEGER,
  :check => CHECK_ID,   # one (and only one) of :check or :tag must be provided
  :tag => TAG_NAME      # :tag will acknowledge all failing checks that this tag is associated with
}

Returns false if creation failed, or the created object(s) if it succeeded.

^

 

create_test_notifications

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

Flapjack::Diner.create_test_notifications(TEST_NOTIFICATION, ...)
# TEST_NOTIFICATION
{
  :summary => STRING,
  :check => CHECK_ID, # one (and only one) of :check or :tag must be provided
  :tag => TAG_NAME    # :tag will send test notifications for all checks that this tag is associated with
}

Returns false if creation failed, or the created object(s) if it succeeded.

^


 

Miscellaneous ^

 

states

Return data for one, some or all check states.

states = Flapjack::Diner.states(STATE_ID)
some_states = Flapjack::Diner.states(STATE_ID, STATE_ID, ...)
first_page_of_states = Flapjack::Diner.states

^

 

metrics

Return global metric data for the flapjack instance (i.e. all components backed by the shared data store).

metrics = Flapjack::Diner.metrics

^

 

statistics

Return data for one, some or all flapjack processor instances.

statistics = Flapjack::Diner.statistics(STATISTICS_ID)
some_statistics = Flapjack::Diner.statistics(STATISTICS_ID, STATISTICS_ID, ...)
first_page_of_statistics = Flapjack::Diner.statistics

^


 

Common options for all GET requests

Option Type Description
:fields String or Array of Strings Limit the fields of :included records
:filter Hash Resources must match query terms
:include String or Array of Strings Full resources to return with the response
:sort String or Array of Strings How the resources should be sorted
:page Integer, > 0 Page number
:per_page Integer, > 0 Number of resources per page

 

Associated data allowed for the include parameter

Method Association Assoc. Type
.checks 'alerting_media' ['medium', ...]
.checks 'contacts' ['contact', ...]
.checks 'current_scheduled_maintenances' ['scheduled_maintenance', ...]
.checks 'current_state' 'state'
.checks 'current_unscheduled_maintenance' 'unscheduled_maintenance'
.checks 'latest_notifications' ['state', ...]
.checks 'tags' ['tag', ...]
.contacts 'acceptors' ['acceptor', ...]
.contacts 'checks' ['check', ...]
.contacts 'media' ['medium', ...]
.contacts 'rejectors' ['rejector', ...]
.contacts 'tags' ['tag', ...]
.media 'acceptors' ['acceptor', ...]
.media 'alerting_checks' ['check', ...]
.media 'contact' 'contact'
.media 'rejectors' ['rejector', ...]
.acceptors 'contact' 'contact'
.acceptors 'media' ['medium', ...]
.acceptors 'tags' ['tag', ...]
.rejectors 'contact' 'contact'
.rejectors 'media' ['medium', ...]
.rejectors 'tags' ['tag', ...]
.scheduled_maintenances 'check' 'check'
.states 'check' 'check'
.tags 'acceptors' ['acceptor', ...]
.tags 'checks' ['check', ...]
.tags 'contacts' ['contact', ...]
.tags 'rejectors' ['acceptor', ...]
.unscheduled_maintenances 'check' 'check'

NB: these may be chained, as long as they follow the allowed paths above; e.g.

Flapjack::Diner.contacts(CONTACT_ID, :include => 'media.alerting_checks')

The above will include both the contact's media and any alerting checks in extra data accessible via the Flapjack::Diner.context method; specifically, from the value held for:included key in the resulting Hash.


 

Retrieving object relationships

The following operations are supported: they will all return data in the format

{:type => LINKED_TYPE, :id => UUID}

(for singular resources), or

[{:type => LINKED_TYPE, :id => UUID}, {:type => LINKED_TYPE, :id => UUID}, ...]

for multiple resources.

check_link_alerting_media(check_id, opts = {})
check_link_contacts(check_id, opts = {})
check_link_current_scheduled_maintenances(check_id, opts = {})
check_link_current_state(check_id, opts = {})
check_link_current_unscheduled_maintenance(check_id, opts = {})
check_link_latest_notifications(check_id, opts = {})
check_link_scheduled_maintenances(check_id, opts = {})
check_link_states(check_id, opts = {})
check_link_tags(check_id, opts = {})
check_link_unscheduled_maintenances(check_id, opts = {})

contact_link_acceptors(contact_id, opts = {})
contact_link_checks(contact_id, opts = {})
contact_link_media(contact_id, opts = {})
contact_link_rejectors(contact_id, opts = {})
contact_link_tags(contact_id, opts = {})

medium_link_acceptors(medium_id, opts = {})
medium_link_alerting_checks(medium_id, opts = {})
medium_link_contact(medium_id, opts = {})
medium_link_rejectors(medium_id, opts = {})

acceptor_link_contact(acceptor_id, opts = {})
acceptor_link_media(acceptor_id, opts = {})
acceptor_link_tags(acceptor_id, opts = {})

rejector_link_contact(rejector_id, opts = {})
rejector_link_media(rejector_id, opts = {})
rejector_link_tags(rejector_id, opts = {})

state_link_check(state_id, opts = {})

tag_link_acceptors(tag_name, opts = {})
tag_link_checks(tag_name, opts = {})
tag_link_contacts(tag_name, opts = {})
tag_link_rejectors(tag_name, opts = {})
tag_link_scheduled_maintenances(tag_name, opts = {})
tag_link_states(tag_name, opts = {})
tag_link_unscheduled_maintenances(tag_name, opts = {})

All returned results are paginated, and the common options for GET requests apply here too.

 

Manipulating object relationships

The following operations are supported; please note that some associations (e.g. associating an acceptor with a contact) must be made on object creation, via the secondary resource's create method, and cannot be altered later.

create_check_link_tags(check_id, *tags_names)
update_check_link_tags(check_id, *tags_names)
delete_check_link_tags(check_id, *tags_names)

create_contact_link_tags(contact_id, *tags_names)
update_contact_link_tags(contact_id, *tags_names)
delete_contact_link_tags(contact_id, *tags_names)

create_medium_link_acceptors(medium_id, *acceptors_ids)
update_medium_link_acceptors(medium_id, *acceptors_ids)
delete_medium_link_acceptors(medium_id, *acceptors_ids)

create_medium_link_rejectors(medium_id, *rejectors_ids)
update_medium_link_rejectors(medium_id, *rejectors_ids)
delete_medium_link_rejectors(medium_id, *rejectors_ids)

create_acceptor_link_media(acceptor_id, *media_ids)
update_acceptor_link_media(acceptor_id, *media_ids)
delete_acceptor_link_media(acceptor_id, *media_ids)

create_acceptor_link_tags(acceptor_id, *tags_names)
update_acceptor_link_tags(acceptor_id, *tags_names)
delete_acceptor_link_tags(acceptor_id, *tags_names)

create_rejector_link_media(rejector_id, *media_ids)
update_rejector_link_media(rejector_id, *media_ids)
delete_rejector_link_media(rejector_id, *media_ids)

create_rejector_link_tags(rejector_id, *tags_names)
update_rejector_link_tags(rejector_id, *tags_names)
delete_rejector_link_tags(rejector_id, *tags_names)

create_tag_link_checks(tag_name, *checks_ids)
update_tag_link_checks(tag_name, *checks_ids)
delete_tag_link_checks(tag_name, *checks_ids)

create_tag_link_contacts(tag_name, *contacts_ids)
update_tag_link_contacts(tag_name, *contacts_ids)
delete_tag_link_contacts(tag_name, *contacts_ids)

create_tag_link_acceptors(tag_name, *acceptors_ids)
update_tag_link_acceptors(tag_name, *acceptors_ids)
delete_tag_link_acceptors(tag_name, *acceptors_ids)

create_tag_link_rejectors(tag_name, *rejectors_ids)
update_tag_link_rejectors(tag_name, *rejectors_ids)
delete_tag_link_rejectors(tag_name, *rejectors_ids)

 

create_{resource}_link_{related}

Creates new links between the resource represented by the first argument and the related resources represented by the rest of the arguments. At least one related resource identifier must be provided. If the related resource is already linked, it is skipped.

 

update_{resource}_link_{related}

Replace all current links between the resource represented by the first argument with the related resources represented by the rest of the arguments. If there are no further arguments, removes all current links of that type for the resource, otherwise removes any not present in the passed related resources and adds any that are passed but not already present.

 

delete_{resource}_link_{related}

Remove the link between the resource represented by the first argument, and the related resources represented by the rest of the arguments. If there is no link for a related resource, deletion is skipped for that linkage.


Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Added some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request
Something went wrong with that request. Please try again.