Module: OML4R

Defined in:
lib/oml4r.rb,
lib/oml4r/version.rb,
lib/oml4r/benchmark.rb

Overview

Copyright © 2009 - 2014 National ICT Australia Limited (NICTA). This software may be used and distributed solely under the terms of the MIT license (License). You should find a copy of the License in LICENSE.TXT or at opensource.org/licenses/MIT. By downloading or using this software you accept the terms and the liability disclaimer in the License.

Defined Under Namespace

Classes: ArgumentMismatchException, Benchmark, Channel, ExperimentMetadata, Logger, MPBase, MissingArgumentException, OML4RException

Constant Summary collapse

DEF_SERVER_PORT = 
3003
DEF_PROTOCOL = 
4
VERSION = 
"2.10.3"
VERSION_STRING = 
"OML4R Client V#{VERSION}"
"Copyright 2009-2014, NICTA"
@@logger = 
Logger.new(STDERR)

Class Method Summary collapse

Class Method Details

.close ⇒ Object

Close the OML collection. This will block until all outstanding data have been sent out.



509
510
511
 
# File 'lib/oml4r.rb', line 509

def self.close()
  Channel.close_all
end

.create_channel(name, url) ⇒ Object 



502
503
504
 
# File 'lib/oml4r.rb', line 502

def self.create_channel(name, url)
  Channel.create(name, url)
end

.generate_guid ⇒ BigNum

Generate a random GUID



516
517
518
 
# File 'lib/oml4r.rb', line 516

def self.generate_guid()
  SecureRandom.random_number(2**64)
end

.init(argv, opts = {}, &block) ⇒ Object

The Init method of OML4R Ruby applications should call this method to initialise the OML4R module This method will parse the command line argument of the calling application to extract the OML specific parameters, it will also do the parsing for the remaining application-specific parameters. It will then connect to the OML server (if requested on the command line), and send the initial instruction to setup the database and the tables for each MPs.

param argv = the Array of command line arguments from the calling Ruby application param opts opts [String] :domain opts [String] :nodeID opts [String] :appName opts [Integer] :protocol opts [Proc] :afterParse param block = a block which defines the additional application-specific arguments



327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
 
# File 'lib/oml4r.rb', line 327

def self.init(argv, opts = {}, &block)
  OML4R.logger.info "OML4R Client #{VERSION} [OMSPv#{opts[:protocol] || DEF_PROTOCOL}; Ruby #{RUBY_VERSION}] #{COPYRIGHT}"
  if d = (ENV['OML_EXP_ID'] || opts[:expID])
    # NOTE: It is still too early to complain about that. We need to be sure
    # of the nomenclature before making user-visible changes.
    OML4R.logger.warn "opts[:expID] and ENV['OML_EXP_ID'] are getting deprecated; please use opts[:domain] or ENV['OML_DOMAIN']  instead"
    opts[:domain] ||= d
  end
  opts[:domain] = ENV['OML_DOMAIN'] || opts[:domain]

  # TODO: Same as above; here, though, :id might actually be the way to go; or
  # perhaps instId?
  #if opts[:id]
  #  raise 'OML4R: :id is not a valid option. Do you mean :nodeID?'
  #end
  opts[:nodeID]  = ENV['OML_NAME'] || opts[:nodeID]  ||  opts[:id] || ENV['OML_ID']
  #
  # XXX: Same again; also, this is the responsibility of the developer, not the user
  #if opts[:app]
  #  raise 'OML4R: :app is not a valid option. Do you mean :appName?'
  #end
  opts[:appName] ||= opts[:app]
  @@appName = opts[:appName]
  opts[:protocol] ||= DEF_PROTOCOL

  if  ENV['OML_URL'] || opts[:omlURL] || opts[:url]
    raise MissingArgumentException.new 'neither OML_URL, :omlURL nor :url are valid. Do you mean OML_COLLECT or :omlCollect?'
  end
  if ENV['OML_SERVER'] || opts[:omlServer]
      OML4R.logger.warn "opts[:omlServer] and ENV['OML_SERVER'] are getting deprecated; please use opts[:collect] or ENV['OML_COLLECT'] instead"
  end
  opts[:omlCollectUri] = ENV['OML_COLLECT'] || ENV['OML_SERVER'] || opts[:collect] || opts[:omlServer]
  noop = opts[:noop] || false
  omlConfigFile = nil

  if argv
    # Create a new Parser for the command line
    op = OptionParser.new
    # Include the definition of application's specific arguments
    yield(op) if block
    # Include the definition of OML specific arguments
    op.on("--oml-id id", "Name to identify this app instance [#{opts[:nodeID] || 'undefined'}]") { |name| opts[:nodeID] = name }
    op.on("--oml-domain domain", "Name of experimental domain [#{opts[:domain] || 'undefined'}] *EXPERIMENTAL*") { |name| opts[:domain] = name }
    op.on("--oml-collect uri", "URI of server to send measurements to") { |u|  opts[:omlCollectUri] = u }
    op.on("--oml-protocol p", "Protocol number [#{OML4R::DEF_PROTOCOL}]") { |l| opts[:protocol] = l.to_i }
    op.on("--oml-log-level l", "Log level used (info: 0 .. debug: 1)") { |l| OML4R.logger.level = 1 - l.to_i }
    op.on("--oml-noop", "Do not collect measurements") { noop = true }
    op.on("--oml-config file", "File holding OML configuration parameters") { |f| omlConfigFile = f }
    op.on("--oml-exp-id domain", "Obsolescent equivalent to --oml-domain domain") { |name|
      opts[:domain] = name
      OML4R.logger.warn "Option --oml-exp-id is getting deprecated; please use '--oml-domain #{domain}' instead"
    }
    op.on("--oml-file localPath", "Obsolescent equivalent to --oml-collect file:localPath") { |name|
      opts[:omlCollectUri] = "file:#{name}"
      OML4R.logger.warn "Option --oml-file is getting deprecated; please use '--oml-collect #{opts[:omlCollectUri]}' instead"
    }
    op.on("--oml-server uri", "Obsolescent equivalent to --oml-collect uri") {|u|
      opts[:omlCollectUri] = "#{u}"
      OML4R.logger.warn "Option --oml-server is getting deprecated; please use '--oml-collect #{opts[:omlCollectUri]}' instead"
    }
    op.on_tail("--oml-help", "Show this message") { $stderr.puts op; exit }
    # XXX: This should be set by the application writer, not the command line
    #op.on("--oml-appid APPID", "Application ID for OML [#{appName || 'undefined'}] *EXPERIMENTAL*") { |name| appID = name }

    # Now parse the command line
    rest = op.parse(argv)
    if opts[:afterParse]
      # give the app a chance to fix missing parameters
      opts[:afterParse].call(opts)
    end
   OML4R.logger.debug "ARGV: #{argv.inspect}"
   return if noop
   # Parameters in OML config file takes precedence
   unless omlConfigFile.nil? 
     f = File.open(omlConfigFile, 'r')
     f.each_line do |l|
       d = l[/.*experiment=["']([^"']*)/,1]
       opts[:domain] = d if d
       d = l[/.*domain=["']([^"']*)/,1]
       opts[:domain] = d if d
       i = l[/.*id=["']([^"']*)/,1]
       opts[:nodeID] = i if i
       u = l[/.*url=["']([^"']*)/,1]
       opts[:omlCollectUri] = u if u
     end
     f.close
   end
  end
 
 unless opts[:nodeID]
    begin
      # Create a default nodeID by concatinating the local hostname with the process ID
      hostname = nil
      begin
        #hostname = Socket.gethostbyname(Socket.gethostname)[0]
        hostname = Socket.gethostname
      rescue Exception
        begin
          hostname = (`hostname`).chop
        rescue Exception; end
      end
      if hostname
        opts[:nodeID] = "#{hostname}-#{Process.pid}"
      end
    end
    unless opts[:nodeID]
      raise MissingArgumentException.new 'OML4R: Missing values for parameter :nodeID (--oml-id)'
    end
  end

  unless opts[:domain] && opts[:appName]
    raise MissingArgumentException.new 'OML4R: Missing values for parameters :domain (--oml-domain) or :appName (in code)!'
  end

  # Set a default collection URI if nothing has been specified
  opts[:omlCollectUri] ||= "file:#{opts[:appName]}_#{opts[:nodeID]}_#{opts[:domain]}_#{Time.now.strftime("%Y-%m-%dt%H.%M.%S%z")}"
  opts[:omlCollectUri] = qualify_uri(opts[:omlCollectUri])
  OML4R.logger.info "Collection URI is #{opts[:omlCollectUri]}"

  create_channel(:default, opts[:omlCollectUri]) if opts[:omlCollectUri]

  # Handle the defined Measurement Points
  startTime = Time.now
  Channel.init_all(opts[:domain], opts[:nodeID], opts[:appName], startTime, opts[:protocol])
  rest || []
end

.logger ⇒ Object 



778
779
780
 
# File 'lib/oml4r.rb', line 778

def self.logger
  @@logger
end

.logger=(logger) ⇒ Object

Overwrite the default logger



40
41
42
 
# File 'lib/oml4r.rb', line 40

def self.logger=(logger)
  @@logger = logger
end

.qualify_uri(uri) ⇒ String

Parse an underspecified URI into a fully-qualified one URIs are resolved as follows; the default is [tcp:]host.

hostname		-> tcp:hostname:3003
hostname:3004	-> tcp:hostname:3004
tcp:hostname	-> tcp:hostname:3003
tcp:hostname:3004	-> tcp:hostname:3004
file:/P/A/T/H	-> file:/P/A/T/H

Raises:



468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
 
# File 'lib/oml4r.rb', line 468

def self.qualify_uri(uri)
  curi = uri.split(':')

  # Defaults
  scheme = 'tcp'
  port = DEF_SERVER_PORT

  if curi.length == 1
    host = curi[0]

  elsif curi.length == 2
    if curi[0] == 'tcp'
      scheme, host = curi

    elsif  curi[0] == 'file'
      scheme, host = curi
      port = nil

    else
      host, port = curi
    end

  elsif curi.length >= 3
    if curi.length > 3
      OML4R.logger.warn "Parsing URI '#{uri}' as a triplet, ignoring later components"
    end
    scheme, host, port = curi

  else
    raise OML4RException.new "OML4R: Unable to parse URI '#{url}"
  end
  "#{scheme}:#{host}#{":#{port}" if port}"
end