symian 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a2b94c03a7439d507a21cbd1f3b5591796993816
+  data.tar.gz: 8964d9303d4ff851ff3c969b1077150516a29b25
+SHA512:
+  metadata.gz: ebe39ffb3dbd463beaacf6e309161ee2e05cf42c2d70ba47ac29b48c937776b01208426dd6962f399f708471c2257b5dc2fde85003e080337369c7e9271f77a3
+  data.tar.gz: 90fc7bb7efad95ac893e545834a87ddbcee467c0564d63fca4510fa108caedbed6d07eb8e4a482332b37a73f18bb21da2b295a4def88166f022dd3e6c5a17cf8

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in sisfc.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Mauro Tortonesi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,63 @@
+# SYMIAN
+
+Symian is a tool, based on what-if scenario analysis and discrete-event
+simulation, for the modeling of a hierarchical and multi-level incident
+management structures. The simulative approach allows to extract important
+metrics and statistics in complex and dynamic systems, which would otherwise be
+impossible to obtain by means of the analytical approach. Symian allows to test
+corrective actions on the architecture itself of support groups before
+executing them in practice.
+
+
+## References
+
+Symian (more precisely an earlier version of it) was used in the following
+research papers:
+
+1. C. Bartolini, C.Stefanelli, M. Tortonesi, "SYMIAN: Analysis and Performance
+   Improvement of the IT Incident Management Process", IEEE Transactions on
+   Network and Service Management, IEEE Communications Society Press, ISSN
+   1932-4537, Vol. 7, No. 3, pp. 132-144, September 2010.
+2. C. Bartolini, C. Stefanelli, M. Tortonesi, "SYMIAN: a Simulation Tool for
+   the Optimization of the IT Incident Management Process", in Proceedings of
+   19th IFIP/IEEE International Workshop on Distributed Systems: Operations and
+   Management (DSOM 2008), pp. 83-94, ISBN: 978-3-540-85999-4, 25-26 September
+   2008, Pythagorion, Samos Island, Greece.
+3. C. Bartolini, C. Stefanelli, M. Tortonesi, "Business-impact analysis and
+   simulation of critical incidents in IT service management", in Proceedings
+   of the 11th IFIP/IEEE International Symposium on Integrated Network Management
+   (IM 2009) - Main track, pp. 9-16, ISBN: 978-1-4244-3486-2, 1-5 June 2009, New
+   York, NY, USA.
+4. C. Bartolini, C. Stefanelli, M. Tortonesi, "Modeling IT Support
+   Organizations from Transactional Logs", in Proceedings of the 12th IEEE/IFIP
+   Network Operations and Management Symposium (NOMS 2010) - Main track, pp.
+   256-263, ISBN: 978-1-4244-5367-2, 19-23 April 2010, Osaka, Japan.
+5. C. Bartolini, C. Stefanelli, M. Tortonesi, D. Targa, "A Web-based What-If
+   Scenario Analysis Tool for Performance Improvement of IT Support
+   Organizations" (short paper), in Proceedings of 7th International Conference on
+   Network and Service Management (CNSM 2011), 24-28 October 2011, Paris, France.
+6. C. Bartolini, C. Stefanelli, M. Tortonesi, "Modeling IT Support
+   Organizations Using Multiple-Priority Queues", in Proceedings of the 13th
+   IEEE/IFIP Network Operations and Management Symposium (NOMS 2012) - Main track,
+   16-20 April 2012, Maui, Hawaii, USA.
+7. C. Bartolini, C. Stefanelli, M. Tortonesi, D. Targa, "A Cloud-based Solution
+   for the Performance Improvement of IT Support Organizations", in Proceedings
+   of the 13th IEEE/IFIP Network Operations and Management Symposium (NOMS 2012) -
+   Mini-conference track, 16-20 April 2012, Maui, Hawaii, USA.
+8. C. Bartolini, C. Stefanelli, M. Tortonesi, "Potential Benefits and
+   Challenges of Closed-Loop Optimization Processes for IT Support
+   Organizations", in Proceedings of the 7th IFIP/IEEE International Workshop on
+   Business-driven IT Management (BDIM 2012), 20 April 2012, Maui, Hawaii, USA.
+9. C. Bartolini, C. Stefanelli, M. Tortonesi, "Synthetic Incident Generation in
+   the Reenactment of IT Support Organization Behavior", in Proceedings of the
+   13th IFIP/IEEE Integrated Network Management Symposium (IM 2013) - Technical
+   (main) track, 27-31 May 2013, Ghent, Belgium.
+
+Please, consider citing some of these papers if you find Symian useful for your
+research.
+
+
+## NOTE
+
+I am still in the process of cleaning up the Symian code. As soon as I am done,
+I will commit it here and upload updated installation and usage information.

data/Rakefile

@@ -0,0 +1,9 @@
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = Dir.glob('test/**/*_test.rb').sort
+  t.verbose = true
+end

data/bin/symian

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+
+begin
+  require 'symian'
+rescue LoadError
+  require 'rubygems'
+  require 'symian'
+end
+
+if File.exists?(ARGV[0])
+  begin
+    configuration = Symian::Configuration.load_from_file(ARGV[0])
+    kpis = Symian::Simulation.new(configuration,
+                                  Symian::PerformanceAnalyzer.new(configuration)).run
+    puts kpis.inspect
+    costs = Symian::CostAnalyzer.new(configuration).evaluate(kpis)
+    puts costs
+  rescue Exception => e
+    puts e.inspect
+    puts e.backtrace
+  end
+else
+  puts 'Usage: symian configuration_file'
+end

data/lib/symian.rb

@@ -0,0 +1,5 @@
+require 'active_support/time'
+
+require 'symian/configuration'
+require 'symian/simulation'
+require 'symian/cost_analyzer'

data/lib/symian/configuration.rb

@@ -0,0 +1,97 @@
+require 'symian/support/dsl_helper'
+
+require 'ice_nine'
+require 'ice_nine/core_ext/object'
+
+
+module Symian
+
+  module Configurable
+    dsl_accessor :start_time,
+                 :duration,
+                 :warmup_duration,
+                 :incident_generation,
+                 :transition_matrix,
+                 :cost_analysis,
+                 :support_groups
+  end
+
+  class Configuration
+    include Configurable
+
+    attr_accessor :filename
+
+    def initialize(filename)
+      @filename = filename
+    end
+
+    def end_time
+      @start_time + @duration
+    end
+
+    def validate
+      # @start_time      = @start_time.to_i
+      # @duration        = @duration.to_i
+      # @warmup_duration = @warmup_duration.to_i
+
+      if @incident_generation[:type] == :file
+        @incident_generation[:source][:path].gsub!('<pwd>', File.expand_path(File.dirname(@filename)))
+      end
+
+      # freeze everything!
+      @start_time.deep_freeze
+      @duration.deep_freeze
+      @warmup_duration.deep_freeze
+      @incident_generation.deep_freeze
+      @transition_matrix.deep_freeze
+      @cost_analysis.deep_freeze
+      @support_groups.deep_freeze
+    end
+
+    def reallocate_ops_and_clone(operators)
+      raise 'Wrong allocation' unless operators.size == @support_groups.size
+
+      new_conf = Configuration.new(@filename)
+      new_conf.start_time          @start_time
+      new_conf.duration            @duration
+      new_conf.warmup_duration     @warmup_duration
+      new_conf.incident_generation @incident_generation
+      new_conf.transition_matrix   @transition_matrix
+      new_conf.cost_analysis       @cost_analysis
+
+      new_sgs = {}
+      @support_groups.zip(operators) do |(sg_name,sg_conf),num_ops|
+        new_sgs[sg_name] = {
+          work_time: sg_conf[:work_time], # this is already frozen
+          operators: {
+            number: num_ops,
+            workshift: sg_conf[:operators][:workshift], # this is already frozen
+          },
+        }
+      end
+      new_sgs.deep_freeze
+
+      new_conf.support_groups(new_sgs)
+
+      new_conf
+    end
+
+    def self.load_from_file(filename)
+      # allow filename, string, and IO objects as input
+      raise ArgumentError, "File #{filename} does not exist!" unless File.exists?(filename)
+
+      # create configuration object
+      conf = Configuration.new(filename)
+
+      # take the file content and pass it to instance_eval
+      conf.instance_eval(File.new(filename, 'r').read)
+
+      # validate and finalize configuration
+      conf.validate
+
+      # return new object
+      conf
+    end
+
+  end
+end

data/lib/symian/cost_analyzer.rb

@@ -0,0 +1,37 @@
+require 'symian/configuration'
+
+module Symian
+  class CostAnalyzer
+    def initialize(configuration)
+      @configuration = configuration
+      unless @configuration.cost_analysis[:operations]
+        raise ArgumentError, 'No operations cost configuration provided!'
+      end
+    end
+
+    def evaluate(kpis)
+      # evaluate operation costs
+      operations_cost = @configuration.support_groups.inject(0.0) do |sum,(sg_name,sg_conf)|
+        sg_costs = @configuration.cost_analysis[:operations].find{|sg| sg[:sg_name] == sg_name }
+        unless sg_costs
+          raise "Cannot find salaries for support group #{sg_name}!"
+        end
+        # ugly hack
+        sum += sg_conf[:operators][:number] * sg_costs[:operator_salary]
+      end
+      # need to consider daily costs (salaries are annual)
+      operations_cost /= 365.0
+
+      # evaluate contracting costs (SLO violations)
+      contracting_func = @configuration.cost_analysis[:contracting]
+      contracting_cost = (contracting_func.nil? ? 0.0 : (contracting_func.call(kpis) or 0.0))
+
+      # evaluate drift costs
+      drift_func = @configuration.cost_analysis[:drift]
+      drift_cost = (drift_func.nil? ? 0.0 : (drift_func.call(kpis) or 0.0))
+
+      # return result
+      { :operations => operations_cost, :contracting => contracting_cost, :drift => drift_cost }
+    end
+  end
+end

data/lib/symian/event.rb

@@ -0,0 +1,53 @@
+require 'symian/support/yaml_io'
+
+module Symian
+
+  class Event
+
+    ET_INCIDENT_ARRIVAL                =  0
+    ET_INCIDENT_ASSIGNMENT             =  1
+    ET_INCIDENT_RESCHEDULING           =  2
+    ET_INCIDENT_ESCALATION             =  3
+    ET_OPERATOR_RETURNING              = 10
+    ET_OPERATOR_LEAVING                = 11
+    ET_OPERATOR_ACTIVITY_STARTS        = 12
+    ET_OPERATOR_ACTIVITY_FINISHES      = 13
+    ET_SUPPORT_GROUP_QUEUE_SIZE_CHANGE = 20
+    ET_END_OF_SIMULATION               = 90
+
+
+    # let the comparable mixin provide the < and > operators for us
+    include Comparable
+
+
+    # setup readable/accessible attributes
+    ATTRIBUTES = [ :type, :data, :time, :destination ]
+
+    attr_reader *ATTRIBUTES # should this be attr_accessor instead?
+
+
+    # setup attributes saved in traces
+    include YAMLSerializable
+
+    TRACED_ATTRIBUTES = ATTRIBUTES
+
+
+    def initialize(type, data, time, destination)
+      @type        = type
+      @data        = data
+      @time        = time
+      @destination = destination
+    end
+
+    def <=> (event)
+      @time <=> event.time
+    end
+
+    def to_s
+      "Event type: #{@type}, data: #{@data}, time: #{@time}, #{@destination}"
+    end
+
+  end
+
+end
+

data/lib/symian/generator.rb

@@ -0,0 +1,89 @@
+require 'erv'
+
+require 'symian/configuration'
+require 'symian/incident'
+
+
+module Symian
+  class IncidentGenerator
+
+    def initialize(simulation, options={})
+      @simulation = simulation
+
+      @arrival_times = Sequence.create(options)
+      raise ArgumentError unless @arrival_times
+
+      # NOTE: so far we support only sequential integer iids
+      @next_iid = 0
+    end
+
+
+    def generate
+      # get next incident arrival time
+      next_arrival = @arrival_times.next
+
+      # handle case where arrival times is limited source
+      return nil unless next_arrival
+
+      # increase @next_iid
+      @next_iid += 1
+
+      # generate and return incident
+      i = Incident.new(@next_iid, next_arrival,
+                       :category => 'normal', # not supported at the moment
+                       :priority => 0)        # not supported at the moment
+
+      @simulation.new_event(Event::ET_INCIDENT_ARRIVAL, i, next_arrival, nil)
+    end
+  end
+
+
+  class Sequence
+    def self.create(args)
+      case args[:type]
+      when :file
+        FileInputSequence.new(args[:source])
+      when :sequential_random_variable
+        ERV::SequentialRandomVariable.new(args[:source])
+      # TODO: also support CSV files and arrays as input source
+      end
+    end
+  end
+
+
+  class FileInputSequence
+    def initialize(args)
+      @file = File.open(args[:path], 'r')
+
+      # throw away the first line (containing the CSV headers)
+      @file.gets
+
+      @curr_val = args[:first_value]
+    end
+
+    # returns nil when EOF occurs
+    def next
+      displacement = @file.gets.try(:chomp).try(:to_f)
+      return nil unless displacement
+
+      ret = @curr_val
+      @curr_val += displacement
+      ret
+    end
+
+    private
+      # After object destruction, make sure that the input file is closed or
+      # the input command process is killed.
+      def setup_finalizer
+        ObjectSpace.define_finalizer(self, self.class.close_io(@file))
+      end
+
+      # Need to make this a class method, or the deallocation won't take place. See:
+      # http://www.mikeperham.com/2010/02/24/the-trouble-with-ruby-finalizers/
+      def self.close_io(file)
+        Proc.new do
+          file.close
+        end
+      end
+  end
+end

data/lib/symian/incident.rb

@@ -0,0 +1,135 @@
+require 'symian/support/yaml_io'
+
+
+module Symian
+  class Incident
+    include YAMLSerializable
+
+    # priorities are not currently used
+    MIN_PRIORITY = 0
+    MAX_PRIORITY = 9
+
+    REQUIRED_ATTRIBUTES = [
+      :iid,                     # incident ID
+      :arrival_time,            # time of incident arrival at the IT support organization
+    ]
+
+    OTHER_ATTRIBUTES = [
+      :category,                # incident category
+    # :severity,                # incident severity - not implemented yet
+    # :state,                   # incident state - not implemented yet
+      :priority,                # incident priority - not currently used
+      :visited_support_groups,  # number of visited SGs
+    # :needed_work_time,        # needed work time before incident escalation
+    #                           #   - initialized at the arrival in a support group
+    #                           #   - decreased as operator works on the incident
+    #                           #   - when it reaches 0, the incident is escalated
+      :start_work_time,         # time when the first operator starts working on the incident
+                                #   - set in Operator#assign
+    # :total_work_time,         # total work time on the incident
+    #                           #   - initialized to 0 in the constructor
+    # :total_queue_time,        # total time spent waiting for an operator
+    #                           #   - initialized to 0 in the constructor
+    # :total_suspension_time,   # total suspension time
+    #                           #   - initialized to 0 in the constructor
+      :closure_time,            # time at which the incident was closed
+    ]
+
+    attr_accessor *(REQUIRED_ATTRIBUTES + OTHER_ATTRIBUTES)
+
+
+    # setup attributes saved in traces
+    include YAMLSerializable
+
+    TRACED_ATTRIBUTES = REQUIRED_ATTRIBUTES + OTHER_ATTRIBUTES + [ :tracking_information ]
+
+
+    def initialize(iid, arrival_time, opts={})
+      @iid = iid
+      @arrival_time = arrival_time
+
+      # set correspondent instance variables for optional arguments
+      opts.each do |k, v|
+        # ignore invalid attributes
+        instance_variable_set("@#{k}", v) if OTHER_ATTRIBUTES.include?(k)
+      end
+
+      @tracking_information ||= []
+      @visited_support_groups ||= 0
+    end
+
+
+    # the format of track_info is:
+    # { :type => one of [ :queue, :work, :suspend ]
+    #   :at => begin time
+    #   :duration => duration
+    #   :sg => support_group_name
+    #   :operator => operator_id (if applicable)
+    # }
+    def add_tracking_information(track_info)
+      @tracking_information << track_info
+    end
+
+    def with_tracking_information(type=:all)
+      selected_ti = if type == :all
+        @tracking_information
+      else
+        @tracking_information.select{|el| el.type == type }
+      end
+
+      selected_ti.each do |ti|
+        yield ti
+      end
+    end
+
+    def total_work_time
+      calculate_time(:work)
+    end
+
+    def total_queue_time
+      calculate_time(:queue)
+    end
+
+    def total_suspend_time
+      calculate_time(:suspend)
+    end
+
+    def total_time_at_last_sg
+      calculate_time_at_last_support_group(:all)
+    end
+
+    def queue_time_at_last_sg
+      calculate_time_at_last_support_group(:queue)
+    end
+
+    def closed?
+      !@closure_time.nil?
+    end
+
+    def ttr
+      # if incident isn't closed yet, just return nil without raising an exception.
+      @closure_time.nil? ? nil : (@closure_time - @arrival_time).to_int
+    end
+
+
+    private
+
+      def calculate_time(type)
+        return 0 unless @tracking_information
+        @tracking_information.inject(0){|sum,x| sum += ((type == :all || type == x[:type]) ? x[:duration].to_i : 0) }
+      end
+
+      def calculate_time_at_last_support_group(*types)
+        time = 0
+        last_sg = nil
+        @tracking_information.reverse_each do |ti|
+          last_sg ||= ti[:sg]
+          break unless ti[:sg] == last_sg
+          time += ti[:duration].to_i if (types.include?(:all) || types.include?(ti[:type]))
+        end
+        time
+      end
+
+  end
+
+end