lightstep 0.9.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 842c2598853d8cd0b169c367beb6fb16b3cc54f3
+  data.tar.gz: 19a192a4a00afb358410c6ff8953858dbb7837e5
+SHA512:
+  metadata.gz: e2c209b4d660be14a771f96676c0ab76f5c2b39a3e731b756a6cc4a2f7259a25030933aa525d08c1b76bdf47aed90133ffdbb1b75f716be4b9092f17205af693
+  data.tar.gz: d5087a55948bfdd293e4d275e290428f47857ba75909df2e3f2b6a54f1817cb1a0f04608831dcc73a8e179a635a5ea68d8ddd6cb7b2d5dbe9bc64799d6ea04c8

data/.gitignore

@@ -0,0 +1,13 @@
+.bundle/
+.yardoc
+Gemfile.lock
+_yardoc/
+coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*~
+Gemfile.lock
+lightstep-tracer*.gem
+lightstep*.gem

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 LightStep
+
+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/Makefile

@@ -0,0 +1,23 @@
+.PHONY: build test benchmark publish
+
+build:
+	gem build lightstep-tracer.gemspec
+
+test:
+	bundle exec rake spec
+	ruby example.rb
+	ruby examples/fork_children/main.rb
+
+benchmark:
+	ruby benchmark/bench.rb
+	ruby benchmark/threading/thread_test.rb
+
+bump-version:
+	ruby -e 'require "bump"; Bump::Bump.run("patch")'
+	make build	# rebuild after version increment
+	git tag `ruby scripts/version.rb`
+
+publish: build test benchmark
+	git push
+	git push --tags
+	gem push lightstep-`ruby scripts/version.rb`.gem

data/README.md

@@ -0,0 +1,56 @@
+# lightstep-tracer-ruby
+
+[![Gem Version](https://badge.fury.io/rb/lightstep-tracer.svg)](https://badge.fury.io/rb/lightstep-tracer) [![Circle CI](https://circleci.com/gh/lightstep/lightstep-tracer-ruby.svg?style=shield)](https://circleci.com/gh/lightstep/lightstep-tracer-ruby) [![MIT license](http://img.shields.io/badge/license-MIT-blue.svg)](http://opensource.org/licenses/MIT) [![Code Climate](https://codeclimate.com/github/lightstep/lightstep-tracer-ruby/badges/gpa.svg)](https://codeclimate.com/github/lightstep/lightstep-tracer-ruby)
+
+The LightStep distributed tracing library for Ruby.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'lightstep'
+
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install lightstep
+
+
+## Getting started
+
+    require 'lightstep'
+
+    # Initialize the singleton tracer
+    LightStep.configure(component_name: 'lightstep/ruby/example', access_token: 'your_access_token')
+
+    # Create a basic span and attach a log to the span
+    span = LightStep.start_span('my_span')
+    span.log(event: 'hello world', count: 42)
+
+    # Create a child span (and add some artificial delays to illustrate the timing)
+    sleep(0.1)
+    child = LightStep.start_span('my_child', child_of: span)
+    sleep(0.2)
+    child.finish
+    sleep(0.1)
+    span.finish
+
+## Thread Safety
+
+The LightStep Tracer is threadsafe. For increased performance, you can add the
+`concurrent-ruby-ext` gem to your Gemfile. This will enable C extensions for
+concurrent operations.
+
+**The LightStep Tracer is not inherently Fork-safe**. When forking, you should
+`disable` the Tracer before forking, then `enable` it in the child Process
+and parent Process after forking. See the `fork_children` example for more.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `make test` to run the tests.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).

data/Rakefile

@@ -0,0 +1,6 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/benchmark/bench.rb

@@ -0,0 +1,60 @@
+require 'benchmark'
+require 'securerandom'
+
+require 'bundler/setup'
+require 'lightstep'
+
+rng = Random.new
+
+# Run a quick profile on logging lots of spans
+tracer = LightStep::Tracer.new(
+  component_name: 'lightstep/ruby/spec',
+  transport: LightStep::Transport::Nil.new
+)
+
+Benchmark.bm(32) do |x|
+  x.report('Random.bytes.unpack') do
+    for i in 1..10_000; rng.bytes(8).unpack('H*')[0]; end
+  end
+  x.report('Random.bytes.each_byte.map') do
+    for i in 1..10_000; rng.bytes(8).each_byte.map { |b| b.to_s(16) }.join; end
+  end
+  x.report('SecureRandom.hex') do
+    for i in 1..10_000; SecureRandom.hex(8); end
+  end
+
+  x.report('start_span(100)') do
+    for i in 0..100; tracer.start_span('my_span').finish; end
+  end
+  x.report('start_span(1000)') do
+    for i in 0..1000; tracer.start_span('my_span').finish; end
+  end
+  x.report('start_span(10000)') do
+    for i in 0..10_000; tracer.start_span('my_span').finish; end
+  end
+
+  x.report('log_event(100)') do
+    span = tracer.start_span('my_span')
+    for i in 0..100; span.log(event: 'event', i: i); end
+    span.finish
+  end
+  x.report('log_event(1000)') do
+    span = tracer.start_span('my_span')
+    for i in 0..1000; span.log(event: 'event', i: i); end
+    span.finish
+  end
+  x.report('log_event(10000)') do
+    span = tracer.start_span('my_span')
+    for i in 0..10_000; span.log(event: 'event', i: i); end
+    span.finish
+  end
+
+  x.report('inject(10000)') do
+    span = tracer.start_span('my_span')
+    for i in 0..10_000
+      carrier = {}
+      tracer.inject(span, LightStep::Tracer::FORMAT_TEXT_MAP, carrier)
+     end
+    span.finish
+  end
+end

data/benchmark/threading/thread_test.rb

@@ -0,0 +1,53 @@
+require 'bundler/setup'
+require 'lightstep'
+
+LightStep.configure(component_name: 'lightstep/ruby/example', access_token: '{your_access_token}')
+
+puts 'Starting...'
+
+mutex = Mutex.new
+done = false
+span_count = 0
+percent_done = 0
+total_time = 0
+
+watchThread = Thread.new do
+  loop do
+    sleep(0.5)
+    mutex.lock
+    time_per_span = (1e6 * (total_time.to_f / span_count.to_f)).round(2)
+    puts "#{span_count} spans #{percent_done}% done #{total_time.round(2)} seconds (#{time_per_span} us/span)"
+    is_done = done
+    mutex.unlock
+    Thread.exit if is_done
+  end
+end
+
+thread = Thread.new do
+  count = 0
+  total_time = 0
+  for j in 1..1000
+    start = Time.now
+    for i in 1..100
+      span = LightStep.start_span('my_span')
+      span.log(event: 'hello world', count: i)
+      span.finish
+      count += 1
+    end
+    delta = Time.now - start
+
+    mutex.lock
+    percent_done = (100.0 * (count / 100_000.0)).ceil
+    span_count = count
+    total_time += delta
+    mutex.unlock
+  end
+end
+
+thread.join
+mutex.lock
+done = true
+mutex.unlock
+watchThread.join
+
+puts 'Done!'

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'lightstep'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/circle.yml

@@ -0,0 +1,7 @@
+general:
+  branches:
+    only:
+      - master
+machine:
+  ruby:
+    version: 2.2.3

data/example.rb

@@ -0,0 +1,34 @@
+require 'bundler/setup'
+require 'simplecov'
+SimpleCov.command_name 'example.rb'
+SimpleCov.start
+require 'lightstep'
+
+access_token = '{your_access_token}'
+
+LightStep.configure(component_name: 'lightstep/ruby/example', access_token: access_token)
+
+puts 'Starting operation...'
+span = LightStep.start_span('my_span')
+thread1 = Thread.new do
+  for i in 1..10
+    sleep(0.15)
+    puts "Logging event #{i}..."
+    span.log(event: 'hello world', count: i)
+  end
+end
+thread2 = Thread.new do
+  current = 1
+  for i in 1..16
+    child = LightStep.start_span('my_child', child_of: span)
+    sleep(0.1)
+    current *= 2
+    child.log(event: "2^#{i}", result: current)
+    child.finish
+  end
+end
+[thread1, thread2].each(&:join)
+span.finish
+
+puts 'Done!'
+puts "https://app.lightstep.com/#{access_token}/trace?span_guid=#{span.guid}&at_micros=#{span.start_micros}"

data/examples/fork_children/main.rb

@@ -0,0 +1,54 @@
+# A simple, manual test ensuring that tracer instances still report after a
+# Process.fork. Currently this requires the tracer instance to be explicitly
+# disabled before the fork and reenabled afterward.
+
+require 'bundler/setup'
+require 'lightstep'
+
+LightStep.configure(
+  component_name: 'lightstep/ruby/examples/fork_children',
+  access_token: '{your_access_token}'
+)
+
+puts 'Starting...'
+(1..20).each do |k|
+  puts "Explicit reset iteration #{k}..."
+
+  # NOTE: the tracer is disabled and reenabled on either side of the fork
+  LightStep.disable
+  pid = Process.fork do
+    LightStep.enable
+    10.times do
+      span = LightStep.start_span("my_forked_span-#{Process.pid}")
+      sleep(0.0025 * rand(k))
+      span.finish
+    end
+  end
+
+  # Also renable the parent process' tracer
+  LightStep.enable
+
+  10.times do
+    span = LightStep.start_span("my_process_span-#{Process.pid}")
+    sleep(0.0025 * rand(k))
+    span.finish
+  end
+
+  # Make sure redundant enable calls don't cause problems
+  10.times do
+    LightStep.disable
+    LightStep.enable
+    LightStep.disable
+    LightStep.disable
+    LightStep.enable
+    LightStep.enable
+    span = LightStep.start_span("my_toggle_span-#{Process.pid}")
+    sleep(0.0025 * rand(k))
+    span.finish
+  end
+
+  puts "Parent, pid #{Process.pid}, waiting on child pid #{pid}"
+  Process.wait
+end
+
+puts 'Done!'

data/examples/rack/hello.rb

@@ -0,0 +1,22 @@
+require 'bundler/setup'
+require 'lightstep'
+
+require 'rack'
+require 'rack/server'
+
+LightStep.configure(
+  component_name: 'lightstep/ruby/examples/rack',
+  access_token: '{your_access_token}'
+)
+
+class HelloWorldApp
+  def self.call(env)
+    span = LightStep.start_span('request')
+    span.log event: 'env', env: env
+    resp = [200, {}, ["Hello World. You said: #{env['QUERY_STRING']}"]]
+    span.finish
+    resp
+  end
+end
+
+Rack::Server.start app: HelloWorldApp

data/lib/lightstep.rb

@@ -0,0 +1,35 @@
+require 'forwardable'
+
+# LightStep Tracer
+module LightStep
+  extend SingleForwardable
+
+  # Base class for all LightStep errors
+  class Error < StandardError; end
+
+  # Returns the singleton instance of the Tracer.
+  def self.instance
+    LightStep::GlobalTracer.instance
+  end
+
+  def_delegator :instance, :configure
+  def_delegator :instance, :start_span
+  def_delegator :instance, :disable
+  def_delegator :instance, :enable
+  def_delegator :instance, :flush
+
+  # Convert a time to microseconds
+  def self.micros(time)
+    (time.to_f * 1E6).floor
+  end
+
+  # Returns a random guid. Note: this intentionally does not use SecureRandom,
+  # which is slower and cryptographically secure randomness is not required here.
+  def self.guid
+    @_rng ||= Random.new
+    @_rng.bytes(8).unpack('H*')[0]
+  end
+end
+
+require 'lightstep/tracer'
+require 'lightstep/global_tracer'

data/lib/lightstep/global_tracer.rb

@@ -0,0 +1,27 @@
+require 'singleton'
+
+module LightStep
+  # GlobalTracer is a singleton version of the LightStep::Tracer.
+  #
+  # You should access it via `LightStep.instance`.
+  class GlobalTracer < Tracer
+    private
+    def initialize
+    end
+
+    public
+    include Singleton
+
+    # Configure the GlobalTracer
+    # See {LightStep::Tracer#initialize}
+    def configure(opts = nil)
+      raise ConfigurationError, 'Already configured' if configured
+      self.configured = true
+      super
+    end
+
+    private
+
+    attr_accessor :configured
+  end
+end

data/lib/lightstep/span.rb

@@ -0,0 +1,148 @@
+require 'concurrent'
+
+module LightStep
+  # Span represents an OpenTracer Span
+  #
+  # See http://www.opentracing.io for more information.
+  class Span
+    # Internal use only
+    # @private
+    attr_reader :guid, :trace_guid, :start_micros, :end_micros, :baggage, :tags
+
+    # Creates a new {Span}
+    #
+    # @param tracer [Tracer] the tracer that created this span
+    # @param operation_name [String] the operation name of this span
+    # @param child_of_guid [String] the guid of the span this span is a child of
+    # @param trace_guid [String] the guid of this span's trace
+    # @param start_micros [Numeric] start time of the span in microseconds
+    # @return [Span] a new Span
+    def initialize(
+      tracer:,
+      operation_name:,
+      child_of_guid: nil,
+      trace_guid:,
+      start_micros:,
+      tags: nil,
+      max_log_records:
+    )
+      @tags = Concurrent::Hash.new(tags)
+      @baggage = Concurrent::Hash.new
+      @log_records = Concurrent::Array.new
+      @dropped_logs = Concurrent::AtomicFixnum.new
+      @max_log_records = max_log_records
+
+      @tracer = tracer
+      @guid = LightStep.guid
+      self.operation_name = operation_name
+      self.start_micros = start_micros
+      self.trace_guid = trace_guid
+      set_tag(:parent_span_guid, child_of_guid) if !child_of_guid.nil?
+    end
+
+    # Set a tag value on this span
+    # @param key [String] the key of the tag
+    # @param value [String, Numeric, Boolean] the value of the tag. If it's not
+    # a String, Numeric, or Boolean it will be encoded with to_s
+    def set_tag(key, value)
+      case value
+      when String, Fixnum, TrueClass, FalseClass
+        tags[key] = value
+      else
+        tags[key] = value.to_s
+      end
+      self
+    end
+
+    # TODO(ngauthier@gmail.com) baggage keys have a restricted format according
+    # to the spec: http://opentracing.io/documentation/pages/spec#baggage-vs-span-tags
+
+    # Set a baggage item on the span
+    # @param key [String] the key of the baggage item
+    # @param value [String] the value of the baggage item
+    def set_baggage_item(key, value)
+      baggage[key] = value
+      self
+    end
+
+    # Get a baggage item
+    # @param key [String] the key of the baggage item
+    # @return Value of the baggage item
+    def get_baggage_item(key)
+      baggage[key]
+    end
+
+    # Add a log entry to this span
+    # @param event [String] event name for the log
+    # @param timestamp [Time] time of the log
+    # @param fields [Hash] Additional information to log
+    def log(event: nil, timestamp: Time.now, **fields)
+      return unless tracer.enabled?
+
+      record = {
+        runtime_guid: tracer.guid,
+        timestamp_micros: LightStep.micros(timestamp)
+      }
+      record[:stable_name] = event.to_s if !event.nil?
+
+      begin
+        record[:payload_json] = JSON.generate(fields, max_nesting: 8)
+      rescue
+        # TODO: failure to encode a payload as JSON should be recorded in the
+        # internal library logs, with catioun not flooding the internal logs.
+      end
+
+      log_records.push(record)
+      if log_records.size > @max_log_records
+        log_records.shift
+        dropped_logs.increment
+      end
+    end
+
+    # Finish the {Span}
+    # @param end_time [Time] custom end time, if not now
+    def finish(end_time: Time.now)
+      if end_micros.nil?
+        self.end_micros = LightStep.micros(end_time)
+      end
+      tracer.finish_span(self)
+      self
+    end
+
+    # Hash representation of a span
+    def to_h
+      {
+        runtime_guid: tracer.guid,
+        span_guid: guid,
+        trace_guid: trace_guid,
+        span_name: operation_name,
+        attributes: tags.map {|key, value|
+          {Key: key.to_s, Value: value}
+        },
+        oldest_micros: start_micros,
+        youngest_micros: end_micros,
+        error_flag: false,
+        dropped_logs: dropped_logs_count,
+        log_records: log_records
+      }
+    end
+
+    # Internal use only
+    # @private
+    def dropped_logs_count
+      dropped_logs.value
+    end
+
+    # Internal use only
+    # @private
+    def logs_count
+      log_records.size
+    end
+
+    private
+
+    attr_reader :tracer, :dropped_logs, :log_records
+    attr_writer :guid, :trace_guid, :start_micros, :end_micros
+    attr_accessor :operation_name
+  end
+end

data/lib/lightstep/tracer.rb

@@ -0,0 +1,309 @@
+require 'json'
+require 'concurrent'
+
+require 'lightstep/span'
+require 'lightstep/transport/http_json'
+require 'lightstep/transport/nil'
+require 'lightstep/transport/callback'
+
+module LightStep
+  class Tracer
+    FORMAT_TEXT_MAP = 1
+    FORMAT_BINARY = 2
+
+    CARRIER_TRACER_STATE_PREFIX = 'ot-tracer-'.freeze
+    CARRIER_BAGGAGE_PREFIX = 'ot-baggage-'.freeze
+
+    DEFAULT_MAX_LOG_RECORDS = 1000
+    MIN_MAX_LOG_RECORDS = 1
+    DEFAULT_MAX_SPAN_RECORDS = 1000
+    MIN_MAX_SPAN_RECORDS = 1
+    DEFAULT_MIN_REPORTING_PERIOD_SECS = 1.5
+    DEFAULT_MAX_REPORTING_PERIOD_SECS = 30.0
+
+    class Error < LightStep::Error; end
+    class ConfigurationError < LightStep::Tracer::Error; end
+
+    attr_reader :access_token, :guid
+
+    # Initialize a new tracer. Either an access_token or a transport must be
+    # provided. A component_name is always required.
+    # @param component_name [String] Component name to use for the tracer
+    # @param access_token [String] The project access token when pushing to LightStep
+    # @param transport [LightStep::Transport] How the data should be transported
+    # @return LightStep::Tracer
+    # @raise LightStep::ConfigurationError if the group name or access token is not a valid string.
+    def initialize(component_name:, access_token: nil, transport: nil)
+      configure(component_name: component_name, access_token: access_token, transport: transport)
+    end
+
+    def max_log_records
+      @max_log_records ||= DEFAULT_MAX_LOG_RECORDS
+    end
+
+    def max_log_records=(max)
+      @max_log_records = [MIN_MAX_LOG_RECORDS, max].max
+    end
+
+    def max_span_records
+      @max_span_records ||= DEFAULT_MAX_SPAN_RECORDS
+    end
+
+    def max_span_records=(max)
+      @max_span_records = [MIN_MAX_SPAN_RECORDS, max].max
+    end
+
+    def min_flush_period_micros
+      @min_flush_period_micros ||= DEFAULT_MIN_REPORTING_PERIOD_SECS * 1E6
+    end
+
+    def min_reporting_period_secs=(secs)
+      @min_flush_period_micros = [DEFAULT_MIN_REPORTING_PERIOD_SECS, secs].max * 1E6
+    end
+
+    def max_flush_period_micros
+      @max_flush_period_micros ||= DEFAULT_MAX_REPORTING_PERIOD_SECS * 1E6
+    end
+
+    def max_reporting_period_secs=(secs)
+      @max_flush_period_micros = [DEFAULT_MAX_REPORTING_PERIOD_SECS, secs].min * 1E6
+    end
+
+    # TODO(ngauthier@gmail.com) inherit SpanContext from references
+
+    # Starts a new span.
+    # @param operation_name [String] the operation name for the Span
+    # @param child_of [Span] Span to inherit from
+    # @param start_time [Time] When the Span started, if not now
+    # @param tags [Hash] tags for the span
+    # @return [Span]
+    def start_span(operation_name, child_of: nil, start_time: nil, tags: nil)
+      child_of_guid = nil
+      trace_guid = nil
+      if Span === child_of
+        child_of_guid = child_of.guid
+        trace_guid = child_of.trace_guid
+      else
+        trace_guid = LightStep.guid
+      end
+
+      Span.new(
+        tracer: self,
+        operation_name: operation_name,
+        child_of_guid: child_of_guid,
+        trace_guid: trace_guid,
+        start_micros: start_time.nil? ? LightStep.micros(Time.now) : LightStep.micros(start_time),
+        tags: tags,
+        max_log_records: max_log_records
+      )
+    end
+
+    # Inject a span into the given carrier
+    # @param span [Span]
+    # @param format [LightStep::Tracer::FORMAT_TEXT_MAP, LightStep::Tracer::FORMAT_BINARY]
+    # @param carrier [Hash-like]
+    def inject(span, format, carrier)
+      case format
+      when LightStep::Tracer::FORMAT_TEXT_MAP
+        inject_to_text_map(span, carrier)
+      when LightStep::Tracer::FORMAT_BINARY
+        warn 'Binary inject format not yet implemented'
+      else
+        warn 'Unknown inject format'
+      end
+    end
+
+    # Extract a span from a carrier
+    # @param operation_name [String]
+    # @param format [LightStep::Tracer::FORMAT_TEXT_MAP, LightStep::Tracer::FORMAT_BINARY]
+    # @param carrier [Hash-like]
+    # @return [Span]
+    def extract(operation_name, format, carrier)
+      case format
+      when LightStep::Tracer::FORMAT_TEXT_MAP
+        extract_from_text_map(operation_name, carrier)
+      when LightStep::Tracer::FORMAT_BINARY
+        warn 'Binary join format not yet implemented'
+        nil
+      else
+        warn 'Unknown join format'
+        nil
+      end
+    end
+
+    # @return true if the tracer is enabled
+    def enabled?
+      @enabled ||= true
+    end
+
+    # Enables the tracer
+    def enable
+      @enabled = true
+    end
+
+    # Disables the tracer
+    # @param discard [Boolean] whether to discard queued data
+    def disable(discard: true)
+      @enabled = false
+      @transport.clear if discard
+      @transport.flush
+    end
+
+    # Flush to the Transport
+    def flush
+      _flush_worker
+    end
+
+    # Internal use only.
+    # @private
+    def finish_span(span)
+      return unless enabled?
+      @span_records.push(span.to_h)
+      if @span_records.size > max_span_records
+        @span_records.shift
+        @dropped_spans.increment
+        @dropped_span_logs.increment(span.logs_count + span.dropped_logs_count)
+      end
+      flush_if_needed
+    end
+
+    protected
+
+    def access_token=(token)
+      if !access_token.nil?
+        raise ConfigurationError, "access token cannot be changed"
+      end
+      @access_token = token
+    end
+
+    def configure(component_name:, access_token: nil, transport: nil)
+      raise ConfigurationError, "component_name must be a string" unless String === component_name
+      raise ConfigurationError, "component_name cannot be blank"  if component_name.empty?
+
+      @span_records = Concurrent::Array.new
+      @dropped_spans = Concurrent::AtomicFixnum.new
+      @dropped_span_logs = Concurrent::AtomicFixnum.new
+
+      start_time = LightStep.micros(Time.now)
+      @guid = LightStep.guid
+      @report_start_time = start_time
+      @last_flush_micros = start_time
+
+      @runtime = {
+        guid: guid,
+        start_micros: start_time,
+        group_name: component_name,
+        attrs: [
+          {Key: "lightstep.tracer_platform",         Value: "ruby"},
+          {Key: "lightstep.tracer_version",          Value: LightStep::VERSION},
+          {Key: "lightstep.tracer_platform_version", Value: RUBY_VERSION}
+        ]
+      }.freeze
+
+      if !transport.nil?
+        if !(LightStep::Transport::Base === transport)
+          raise ConfigurationError, "transport is not a LightStep transport class: #{transport}"
+        end
+        @transport = transport
+      else
+        if access_token.nil?
+          raise ConfigurationError, "you must provide an access token or a transport"
+        end
+        @transport = Transport::HTTPJSON.new(access_token: access_token)
+      end
+
+      # At exit, flush this objects data to the transport and close the transport
+      # (which in turn will send the flushed data over the network).
+      at_exit do
+        flush
+        @transport.close
+      end
+    end
+
+    def flush_if_needed
+      return unless enabled?
+
+      delta = LightStep.micros(Time.now) - @last_flush_micros
+      return if delta < min_flush_period_micros
+
+      if delta > max_flush_period_micros || @span_records.size >= max_span_records / 2
+        flush
+      end
+    end
+
+    private
+
+    def inject_to_text_map(span, carrier)
+      carrier[CARRIER_TRACER_STATE_PREFIX + 'spanid'] = span.guid
+      carrier[CARRIER_TRACER_STATE_PREFIX + 'traceid'] = span.trace_guid unless span.trace_guid.nil?
+      carrier[CARRIER_TRACER_STATE_PREFIX + 'sampled'] = 'true'
+
+      span.baggage.each do |key, value|
+        carrier[CARRIER_BAGGAGE_PREFIX + key] = value
+      end
+    end
+
+    def extract_from_text_map(operation_name, carrier)
+      span = Span.new(
+        tracer: self,
+        operation_name: operation_name,
+        start_micros: LightStep.micros(Time.now),
+        child_of_guid: carrier[CARRIER_TRACER_STATE_PREFIX + 'spanid'],
+        trace_guid: carrier[CARRIER_TRACER_STATE_PREFIX + 'traceid'],
+        max_log_records: max_log_records
+      )
+
+      carrier.each do |key, value|
+        next unless key.start_with?(CARRIER_BAGGAGE_PREFIX)
+        plain_key = key.to_s[CARRIER_BAGGAGE_PREFIX.length..key.to_s.length]
+        span.set_baggage_item(plain_key, value)
+      end
+      span
+    end
+
+    def _flush_worker
+      return unless enabled?
+      # The thrift configuration has not yet been set: allow logs and spans
+      # to be buffered in this case, but flushes won't yet be possible.
+      return if @runtime.nil?
+      return if @span_records.empty?
+
+      now = LightStep.micros(Time.now)
+
+      span_records = @span_records.slice!(0, @span_records.length)
+      dropped_spans = 0
+      @dropped_spans.update{|old| dropped_spans = old; 0 }
+
+      old_dropped_span_logs = 0
+      @dropped_span_logs.update{|old| old_dropped_span_logs = old; 0 }
+      dropped_logs = old_dropped_span_logs
+      dropped_logs = span_records.reduce(dropped_logs) do |memo, span|
+        memo += span.delete :dropped_logs
+      end
+
+      report_request = {
+        runtime: @runtime,
+        oldest_micros: @report_start_time,
+        youngest_micros: now,
+        span_records: span_records,
+        counters: [
+            {Name: "dropped_logs",  Value: dropped_logs},
+            {Name: "dropped_spans", Value: dropped_spans},
+        ]
+      }
+
+      @last_flush_micros = now
+      @report_start_time = now
+
+      begin
+        @transport.report(report_request)
+      rescue LightStep::Transport::HTTPJSON::QueueFullError
+        # If the queue is full, add the previous dropped logs to the logs
+        # that were going to get reported, as well as the previous dropped
+        # spans and spans that would have been recorded
+        @dropped_spans.increment(dropped_spans + span_records.length)
+        @dropped_span_logs.increment(old_dropped_span_logs)
+      end
+    end
+  end
+end

data/lib/lightstep/transport/base.rb

@@ -0,0 +1,22 @@
+module LightStep
+  module Transport
+    # Base Transport type
+    class Base
+      def initialize
+      end
+
+      def report(_report)
+        nil
+      end
+
+      def close
+      end
+
+      def clear
+      end
+
+      def flush
+      end
+    end
+  end
+end

data/lib/lightstep/transport/callback.rb

@@ -0,0 +1,25 @@
+require 'lightstep/transport/base'
+
+module LightStep
+  module Transport
+    class Callback < Base
+      def initialize(callback:)
+        @callback = callback
+      end
+
+      def report(report)
+        @callback.call(report)
+        nil
+      end
+
+      def close
+      end
+
+      def clear
+      end
+
+      def flush
+      end
+    end
+  end
+end

data/lib/lightstep/transport/http_json.rb

@@ -0,0 +1,111 @@
+require 'net/http'
+require 'lightstep/transport/base'
+
+module LightStep
+  module Transport
+    # HTTPJSON is a transport that sends reports via HTTP in JSON format.
+    # It is thread-safe, however it is *not* fork-safe. When forking, all items
+    # in the queue will be copied and sent in duplicate.
+    #
+    # When forking, you should first `disable` the tracer, then `enable` it from
+    # within the fork (and in the parent post-fork). See
+    # `examples/fork_children/main.rb` for an example.
+    class HTTPJSON < Base
+      LIGHTSTEP_HOST = "collector.lightstep.com"
+      LIGHTSTEP_PORT = 443
+      QUEUE_SIZE = 16
+
+      ENCRYPTION_TLS = 'tls'
+      ENCRYPTION_NONE = 'none'
+
+      class QueueFullError < LightStep::Error; end
+
+      # Initialize the transport
+      # @param host [String] host of the domain to the endpoind to push data
+      # @param port [Numeric] port on which to connect
+      # @param verbose [Numeric] verbosity level. Right now 0-3 are supported
+      # @param secure [Boolean]
+      # @param access_token [String] access token for LightStep server
+      # @return [HTTPJSON]
+      def initialize(host: LIGHTSTEP_HOST, port: LIGHTSTEP_PORT, verbose: 0, encryption: ENCRYPTION_TLS, access_token:)
+        @host = host
+        @port = port
+        @verbose = verbose
+        @encryption = encryption
+
+        raise ConfigurationError, "access_token must be a string" unless String === access_token
+        raise ConfigurationError, "access_token cannot be blank"  if access_token.empty?
+        @access_token = access_token
+
+        start_queue
+      end
+
+      # Queue a report for sending
+      def report(report)
+        p report if @verbose >= 3
+        # TODO(ngauthier@gmail.com): the queue could be full here if we're
+        # lagging, which would cause this to block!
+        @queue.push({
+          host: @host,
+          port: @port,
+          encryption: @encryption,
+          access_token: @access_token,
+          content: report,
+          verbose: @verbose
+        }, true)
+        nil
+      rescue ThreadError
+        raise QueueFullError
+      end
+
+      # Flush the current queue
+      def flush
+        close
+        start_queue
+      end
+
+      # Clear the current queue, deleting pending items
+      def clear
+        @queue.clear
+      end
+
+      # Close the transport. No further data can be sent!
+      def close
+        @queue.close
+        @thread.join
+      end
+
+      private
+
+      def start_queue
+        @queue = SizedQueue.new(QUEUE_SIZE)
+        @thread = start_thread(@queue)
+      end
+
+      # TODO(ngauthier@gmail.com) abort on exception?
+      def start_thread(queue)
+        Thread.new do
+          while item = queue.pop
+            post_report(item)
+          end
+        end
+      end
+
+      def post_report(params)
+        https = Net::HTTP.new(params[:host], params[:port])
+        https.use_ssl = params[:encryption] == ENCRYPTION_TLS
+        req = Net::HTTP::Post.new('/api/v0/reports')
+        req['LightStep-Access-Token'] = params[:access_token]
+        req['Content-Type'] = 'application/json'
+        req['Connection'] = 'keep-alive'
+        req.body = params[:content].to_json
+        res = https.request(req)
+
+        puts res.to_s if params[:verbose] >= 3
+
+        # TODO(ngauthier@gmail.com): log unknown commands
+        # TODO(ngauthier@gmail.com): log errors from server
+      end
+    end
+  end
+end

data/lib/lightstep/transport/nil.rb

@@ -0,0 +1,9 @@
+require 'lightstep/transport/base'
+
+module LightStep
+  module Transport
+    # Empty transport, primarily for unit testing purposes
+    class Nil < Base
+    end
+  end
+end

data/lib/lightstep/version.rb

@@ -0,0 +1,3 @@
+module LightStep
+  VERSION = '0.9.2'.freeze
+end

data/lightstep-tracer.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'lightstep/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lightstep'
+  spec.version       = LightStep::VERSION
+  spec.authors       = ['bcronin']
+  spec.email         = ['support@lightstep.com']
+
+  spec.summary       = 'LightStep OpenTracing Ruby bindings'
+  spec.homepage      = 'https://github.com/lightstep/lightstep-tracer-ruby'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'concurrent-ruby', '~> 1.0.0'
+  spec.add_development_dependency 'rake', '~> 11.3.0'
+  spec.add_development_dependency 'rack', '~> 2.0.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'bump', '~> 0.5'
+  spec.add_development_dependency 'simplecov', '~> 0.12.0'
+end

data/scripts/version.rb

@@ -0,0 +1,5 @@
+lib = File.expand_path('../../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'lightstep/version'
+
+print LightStep::VERSION

metadata

@@ -0,0 +1,154 @@
+--- !ruby/object:Gem::Specification
+name: lightstep
+version: !ruby/object:Gem::Version
+  version: 0.9.2
+platform: ruby
+authors:
+- bcronin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-11-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 11.3.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 11.3.0
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: bump
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+description: 
+email:
+- support@lightstep.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- LICENSE.txt
+- Makefile
+- README.md
+- Rakefile
+- benchmark/bench.rb
+- benchmark/threading/thread_test.rb
+- bin/console
+- bin/setup
+- circle.yml
+- example.rb
+- examples/fork_children/main.rb
+- examples/rack/hello.rb
+- lib/lightstep.rb
+- lib/lightstep/global_tracer.rb
+- lib/lightstep/span.rb
+- lib/lightstep/tracer.rb
+- lib/lightstep/transport/base.rb
+- lib/lightstep/transport/callback.rb
+- lib/lightstep/transport/http_json.rb
+- lib/lightstep/transport/nil.rb
+- lib/lightstep/version.rb
+- lightstep-tracer.gemspec
+- scripts/version.rb
+homepage: https://github.com/lightstep/lightstep-tracer-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: LightStep OpenTracing Ruby bindings
+test_files: []