SoarStatus

This gem provides a functional and detailed status aggregator that allows decoupling of status providers in the SOAR architecture. Functional and detailed status endpoints can then source the information from this single gem.

Installation

Add this line to your application's Gemfile:

gem 'soar_status'

And then execute:

  bundle

Or install it yourself as:

  gem install soar_status

Testing

Behavioural driven testing can be performed by testing as follows:

  bundle exec rspec -cfd spec/*

Usage

Registering release information

Simply register your release information as follow on startup:

SoarStatus::Status.release_commit_hash = '123abc'
SoarStatus::Status.release_version = '1.2.3'

Registering environment and configuration information

Simply register your environment and configuration information on startup. Note that any secrets contained in here will also be exposed and must only be used in non-production modes.

SoarStatus::Status.configuration = @my_configuration
SoarStatus::Status.environment = @my_environment

Creating a function status provider

Create/Enhance a class that can provide a functional status of the service. This is done in two parts:

• The instance must be registered with SoarStatus. This can be done in the initializer as shown below or later by simply passing in a reference to the object.
• It must provide a method called "functional_status" that will be called (via IOC) by SoarStatus in order to retrieve the functional status.

class ClassThatHasFunctionalStatus
  def initialize
    SoarStatus::Status.register_functional_status_provider(self)
  end

  def functional_status
    "100"
  end
end

Creating a detailed status provider

Create/Enhance a class that can provide a detailed status of the service. This is done in two parts:

• The instance must be registered with SoarStatus. This can be done in the initializer as shown below or later by simply passing in a reference to the object.
• It must provide a method called "detailed_status" that will be called (via IOC) by SoarStatus in order to retrieve the detailed status.

class ClassThatHasDetailedStatus
  def initialize
    SoarStatus::Status.register_detailed_status_provider('class_1',self)
  end

  def detailed_status
    { 'stuff' => 'from_class1'}
  end
end

Accessing the functional and detailed statuses

All the information can be provided via endpoints in your service.

class Status
  def serve(request)
    [200, SoarStatus::Status.functional_status.to_json]
  end
end

class StatusDetail
  def serve(request)
    [200, SoarStatus::Status.detailed_status.to_json]
  end
end

Detailed example

require 'soar_status'

class ClassThatHasFunctionalStatus
  def initialize
    SoarStatus::Status.register_functional_status_provider(self)
    @status = "100"
  end

  def functional_status
    @status
  end

  def set_functional_status(status)
    @status = status
  end
end

class ClassThatHasDetailedStatus1
  def initialize
    SoarStatus::Status.register_detailed_status_provider('class_1',self)
  end

  def detailed_status
    { 'stuff' => 'from_class1'}
  end
end

class ClassThatHasDetailedStatus2
  def initialize
    SoarStatus::Status.register_detailed_status_provider('class_2',self)
  end

  def detailed_status
    { 'stuff' => 'from_class2'}
  end
end

class Main
  def test_sanity
    @test_configuration = { 'some' => 'configuration' }
    @test_environment = { 'some' => 'environment' }

    #registration of release information
    SoarStatus::Status.release_commit_hash = '123abc'
    SoarStatus::Status.release_version = '1.2.3'

    #registration of configuration and environment detail
    SoarStatus::Status.configuration = @test_configuration
    SoarStatus::Status.environment = @test_environment

    #registration of functional and detailed status providers
    functional_status_provider = ClassThatHasFunctionalStatus.new
    detailed_status_provider1 = ClassThatHasDetailedStatus1.new
    detailed_status_provider2 = ClassThatHasDetailedStatus2.new

    #retrieval of functional status
    puts "Functional Status: #{SoarStatus::Status.functional_status}"

    #retrieval of detailed status
    puts "Detailed status: #{SoarStatus::Status.detailed_status}"
  end
end

main = Main.new
main.test_sanity

Contributing

Bug reports and feature requests are welcome by email to barney dot de dot villiers at hetzner dot co dot za. This gem is sponsored by Hetzner (Pty) Ltd (http://hetzner.co.za)

License

The gem is available as open source under the terms of the MIT License.