README

   1 = LWES - Light Weight Event System API for Ruby
   2
   3 * http://www.lwes.org
   4 * http://sourceforge.net/projects/lwes
   5
   6 == DESCRIPTION:
   7
   8 The LWES Light-Weight Event System is a framework for allowing the exchange of
   9 information from many machines to many machines in a controlled, platform
  10 neutral, language neutral way.  The exchange of information is done in a
  11 connectless fashion using multicast or unicast UDP, and using self describing
  12 data so that any platform or language can translate it to it's local dialect.
  13
  14 Instead of blindly using SWIG-generated bindings and exposing users to the
  15 underlying C APIs, we've wrapped the underlying C library bindings in an
  16 easy-to-use Ruby library.  Currently we only support emitting events but
  17 may support listening and journaling capabilities as time allows.
  18
  19 == FEATURES:
  20
  21 * easy-to-use, "Ruby-ish" API, no manual memory management
  22 * optional ESF (event specification format) validation support
  23
  24 == SUPPORT:
  25
  26 See the SourceForge project.
  27
  28 == DEVELOPMENT:
  29
  30 Our SVN repository is here:
  31
  32   https://lwes.svn.sourceforge.net/svnroot/lwes/lwes-ruby
  33
  34 == INSTALL:
  35
  36 This library is easy to install, if you have the LWES library already
  37 installed you can use that, otherwise the RubyGems installer will
  38 automatically download and install a private copy only for use with your
  39 gem.
  40
  41   gem install lwes
  42
  43 == SYNOPSIS:
  44
  45   require 'lwes'
  46
  47   # create an Emitter which may be used for the lifetime of your process
  48   emitter = LWES::Emitter.new(:address => '224.1.1.11',
  49                               :port => 12345,
  50                               :heartbeat => 30, # nil to disable
  51                               :ttl => 1) # nil for default TTL(3)
  52
  53   # parse your ESF file at startup, the example below assumes you
  54   # have "Event1" and "Event2" defined in your ESF file:
  55   type_db = LWES::TypeDB.new("my_events.esf")
  56
  57   # create classes to use, by default and to encourage DRY-ness,
  58   # we map each event in the ESF file to a class
  59   # Optionally, you may specify :parent => module/namespace
  60   type_db.create_classes! :parent => MyApp
  61
  62   # inside your application, you may now do this to slowly build up
  63   # fields for the event
  64   my_event = MyApp::Event1.new
  65   my_event.started = Time.now.to_i
  66   my_event.remote_addr = "192.168.0.1"
  67   # ...do a lot of stuff here in between...
  68   my_event.field1 = value1
  69   my_event.field2 = value2
  70   my_event.field3 = value3
  71   my_event.finished = Time.now.to_i
  72   emitter << my_event
  73
  74   # Alternatively, if you know ahead of time all the fields you want to
  75   # set for an event, you can emit an event in one step:
  76
  77   emitter.emit MyApp::Event2, :field1 => value1, :field2 => value2 # ...
  78
  79
  80 == NON-ESF USERS:
  81
  82 For prototyping and development, it may be easier to not use an ESF
  83 file.  In those cases, you may skip the TypeDB steps entirely and
  84 just use an emitter to send Hash objects:
  85
  86   emitter = LWES::Emitter.new(:address => '224.1.1.11',
  87                               :port => 12345,
  88                               :heartbeat => 30, # nil to disable
  89                               :ttl => 1) # nil for default TTL(3)
  90
  91   # Since we can't reliably map certain Ruby types to LWES types, you'll
  92   # have to specify them explicitly for IP addresses and all Integer
  93   # types.
  94   event = {
  95     :time_sec => [ :int32, Time.now.to_i ],
  96     :time_usec => [ :int32, Time.now.tv_usec ],
  97     :remote_addr => [ :ip_addr, "192.168.0.1" ],
  98   }
  99
 100   # Strings and Boolean values are easily mapped, however:
 101   event[:field1] = "String value"
 102   event[:boolean1] = true
 103   event[:boolean2] = false
 104
 105   # finally, we just emit the hash with any given name
 106   emitter.emit "Event3", event