zipkin-tracer 0.36.2 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 795d59f52ecde287fa4afd8e391285c4bfcd5e60bc8eef827b31c53b14525b4f
-  data.tar.gz: f21cb46bf09dda5b55e660d7c47a2a70e281a3b21089e033b1ad9828e8802ec8
+  metadata.gz: f71b9baf08a3f387fc409c40a8997d29da5a8dd48e9d4fa9609b02c2b4f2ea03
+  data.tar.gz: a481c2dc583679f1bbbe4341ac896ad4594a7b7920562344b95ed23f6f266a1f
 SHA512:
-  metadata.gz: b63fc26c0ac9cd3c64cd1fcbe3079657ae9fea506213aeed3885cb4a334908aaa18b61086699282c629afb712923e56a4b3ee45e06d3dd4051011b62d528d37b
-  data.tar.gz: 7b6c764aeee41e2b124c5494a180f31decd6f4f302195f9a3a8f273aff5775cd3fd76a474e97484bc081e54fd522953fbbe7333eb04db3df33f2f5c0fa558592
+  metadata.gz: 9bf32473266105e4b8dc1d19d3042937c451962aa8f58deac3f606d04205bc7f0fa8ad856169bd02d216193f22e085d8e7b48a317f99182ec0adf7dedab96509
+  data.tar.gz: cc75da694fe165499b0f84c10d795d1e3e8f4c8fac6814531662c103e80330f668c298b7c76f16c8d94385f6550ff6afb489770cacfa6923d79dab826152c5b8

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+# 0.37.0
+* Add an `async` option to the HTTP and SQS senders.
+* Allow the `logger` option to be provided.
+* Add the TraceWrapper utility class.
+
 # 0.36.2
 * Cleanup the gemspec. No code changes.
 

data/README.md

@@ -8,27 +8,34 @@ Rack and Faraday integration middlewares for Zipkin tracing.
 
 ### Sending traces on incoming requests
 
-Options can be provided via Rails.config for a Rails 3+ app, or can be passed as a hash argument to the Rack plugin.
+Options can be provided as a hash via `Rails.config.zipkin_tracer` for Rails apps or directly to the Rack middleware:
 
 ```ruby
 require 'zipkin-tracer'
-use ZipkinTracer::RackHandler, config # config is optional
+use ZipkinTracer::RackHandler, config
 ```
 
-where `Rails.config.zipkin_tracer` or `config` is a hash that can contain the following keys:
+### Configuration options
 
+#### Common
 * `:service_name` **REQUIRED** - the name of the service being traced. There are two ways to configure this value. Either write the service name in the config file or set the "DOMAIN" environment variable (e.g. 'test-service.example.com' or 'test-service'). The environment variable takes precedence over the config file value.
 * `:sample_rate` (default: 0.1) - the ratio of requests to sample, from 0 to 1
-* `:json_api_host` - hostname with protocol of a zipkin api instance (e.g. `https://zipkin.example.com`) to use the HTTP sender
-* `:zookeeper` - the address of the zookeeper server to use by the Kafka sender
-* `:sqs_queue_name` - the name of the Amazon SQS queue to use the SQS sender
-* `:sqs_region` - the AWS region for the Amazon SQS queue
-* `:log_tracing` - Set to true to log all traces. Only used if traces are not sent to the API or Kafka.
-* `:annotate_plugin` - plugin function which receives the Rack env, the response status, headers, and body to record annotations
-* `:filter_plugin` - plugin function which receives the Rack env and will skip tracing if it returns false
-* `:whitelist_plugin` - plugin function which receives the Rack env and will force sampling if it returns true
 * `:sampled_as_boolean` - When set to true (default but deprecrated), it uses true/false for the `X-B3-Sampled` header. When set to false uses 1/0 which is preferred.
 * `:trace_id_128bit` - When set to true, high 8-bytes will be prepended to trace_id. The upper 4-bytes are epoch seconds and the lower 4-bytes are random. This makes it convertible to Amazon X-Ray trace ID format v1. (See http://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-request-tracing.html)
+* `:async` - By default senders will flush traces asynchronously. Set to `false` to make that process synchronous. Only supported by the HTTP and SQS senders.
+* `:logger` - The default logger for Rails apps is `Rails.logger`, else it is `STDOUT`. Use this option to pass a custom logger.
+
+#### Sender specific
+* `:json_api_host` - Hostname with protocol of a zipkin api instance (e.g. `https://zipkin.example.com`) to use the HTTP sender
+* `:zookeeper` - The address of the zookeeper server to use by the Kafka sender
+* `:sqs_queue_name` - The name of the Amazon SQS queue to use the SQS sender
+* `:sqs_region` - The AWS region for the Amazon SQS queue (optional)
+* `:log_tracing` - Set to true to log all traces. Only used if traces are not sent to the API or Kafka.
+
+#### Plugins
+* `:annotate_plugin` - Receives the Rack env, the response status, headers, and body to record annotations
+* `:filter_plugin` - Receives the Rack env and will skip tracing if it returns false
+* `:whitelist_plugin` - Receives the Rack env and will force sampling if it returns true
 
 ### Sending traces on outgoing requests with Faraday
 
@@ -210,6 +217,29 @@ For example:
 lambda { |env| KNOWN_DEVICES.include?(env['HTTP_X_DEVICE_ID']) }
 ```
 
+## Utility classes
+
+### TraceWrapper
+
+This class provides a `.wrap_in_custom_span` method which expects a configuration hash, a span name and a block.
+You may also pass a span kind and an Application object using respectively `span_kind:` and `app:` keyword arguments.
+
+The block you pass will be executed in the context of a custom span.
+This is useful when your application doesn't use the rack handler but still needs to generate complete traces, for instance background jobs or lambdas calling remote services.
+
+The following code will create a trace starting with a span of the (default) `SERVER` kind named "custom span" and then a span of the `CLIENT` kind will be added by the Faraday middleware. Afterwards the configured sender will call `flush!`.
+
+```ruby
+TraceWrapper.wrap_in_custom_span(config, "custom span") do |span|
+  conn = Faraday.new(url: remote_service_url) do |builder|
+    builder.use ZipkinTracer::FaradayHandler, config[:service_name]
+    builder.adapter Faraday.default_adapter
+  end
+  conn.get("/")
+end
+```
+
+
 ## Development
 
 This project uses Rspec. Make sure your PRs contain proper tests.

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "zipkin-tracer"
+
+# 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(__FILE__)

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/lib/zipkin-tracer/config.rb

@@ -5,10 +5,9 @@ require 'zipkin-tracer/rack/zipkin-tracer'
 module ZipkinTracer
   # Configuration of this gem. It reads the configuration and provides default values
   class Config
-    attr_reader :service_name, :sample_rate,
+    attr_reader :service_name, :sample_rate, :sampled_as_boolean, :trace_id_128bit, :async, :logger,
       :json_api_host, :zookeeper, :kafka_producer, :kafka_topic, :sqs_queue_name, :sqs_region, :log_tracing,
-      :annotate_plugin, :filter_plugin, :whitelist_plugin,
-      :logger, :sampled_as_boolean, :trace_id_128bit
+      :annotate_plugin, :filter_plugin, :whitelist_plugin
 
     def initialize(app, config_hash)
       config = config_hash || Application.config(app)
@@ -25,14 +24,16 @@ module ZipkinTracer
       @sqs_queue_name    = config[:sqs_queue_name]
       @sqs_region        = config[:sqs_region]
       # Percentage of traces which by default this service traces (as float, 1.0 means 100%)
-      @sample_rate       = config[:sample_rate]       || DEFAULTS[:sample_rate]
+      @sample_rate       = config[:sample_rate] || DEFAULTS[:sample_rate]
       # A block of code which can be called to do extra annotations of traces
       @annotate_plugin   = config[:annotate_plugin]   # call for trace annotation
       # A block of code which can be called to skip traces. Skip tracing if returns false
       @filter_plugin     = config[:filter_plugin]
       # A block of code which can be called to force sampling. Forces sampling if returns true
       @whitelist_plugin  = config[:whitelist_plugin]
-      @logger            = Application.logger
+      # be strict about checking `false` to ensure misconfigurations don't lead to accidental synchronous configurations
+      @async             = config[:async] != false
+      @logger            = config[:logger] || Application.logger
       # Was the logger in fact setup by the client?
       @log_tracing       = config[:log_tracing]
       # When set to false, it uses 1/0 in the 'X-B3-Sampled' header, else uses true/false

data/lib/zipkin-tracer/trace_wrapper.rb

@@ -0,0 +1,22 @@
+module ZipkinTracer
+  class TraceWrapper
+    def self.wrap_in_custom_span(config, span_name, span_kind: Trace::Span::Kind::SERVER, app: nil)
+      raise ArgumentError, "you must provide a block" unless block_given?
+
+      zipkin_config = ZipkinTracer::Config.new(app, config).freeze
+      tracer = ZipkinTracer::TracerFactory.new.tracer(zipkin_config)
+      trace_id = ZipkinTracer::TraceGenerator.new.next_trace_id
+
+      ZipkinTracer::TraceContainer.with_trace_id(trace_id) do
+        if trace_id.sampled?
+          tracer.with_new_span(trace_id, span_name) do |span|
+            span.kind = span_kind
+            yield(span)
+          end
+        else
+          yield(ZipkinTracer::NullSpan.new)
+        end
+      end
+    end
+  end
+end

data/lib/zipkin-tracer/tracer_factory.rb

@@ -18,7 +18,12 @@ module ZipkinTracer
           Trace::ZipkinKafkaSender.new(options)
         when :sqs
           require 'zipkin-tracer/zipkin_sqs_sender'
-          options = { logger: config.logger, queue_name: config.sqs_queue_name , region: config.sqs_region }
+          options = {
+            async: config.async,
+            logger: config.logger,
+            queue_name: config.sqs_queue_name,
+            region: config.sqs_region
+          }
           Trace::ZipkinSqsSender.new(options)
         when :logger
           require 'zipkin-tracer/zipkin_logger_sender'

data/lib/zipkin-tracer/version.rb

@@ -1,3 +1,3 @@
 module ZipkinTracer
-  VERSION = '0.36.2'.freeze
+  VERSION = '0.37.0'.freeze
 end

data/lib/zipkin-tracer/zipkin_http_sender.rb

@@ -4,7 +4,7 @@ require 'zipkin-tracer/zipkin_sender_base'
 require 'zipkin-tracer/hostname_resolver'
 
 module Trace
-  class AsyncHttpApiClient
+  class HttpApiClient
     include SuckerPunch::Job
     SPANS_PATH = '/api/v2/spans'
 
@@ -32,13 +32,18 @@ module Trace
     IP_FORMAT = :string
 
     def initialize(options)
-      SuckerPunch.logger = options[:logger]
       @json_api_host = options[:json_api_host]
+      @async = options[:async] != false
+      SuckerPunch.logger = options[:logger]
       super(options)
     end
 
     def flush!
-      AsyncHttpApiClient.perform_async(@json_api_host, spans.dup)
+      if @async
+        HttpApiClient.perform_async(@json_api_host, spans.dup)
+      else
+        HttpApiClient.new.perform(@json_api_host, spans)
+      end
     end
   end
 end

data/lib/zipkin-tracer/zipkin_sqs_sender.rb

@@ -5,7 +5,7 @@ require "zipkin-tracer/zipkin_sender_base"
 require "zipkin-tracer/hostname_resolver"
 
 module Trace
-  class AsyncSqsClient
+  class SqsClient
     include SuckerPunch::Job
 
     def perform(sqs_options, queue_name, spans)
@@ -13,9 +13,10 @@ module Trace
         ::ZipkinTracer::HostnameResolver.new.spans_with_ips(spans, ZipkinSqsSender::IP_FORMAT).map(&:to_h)
       sqs = Aws::SQS::Client.new(**sqs_options)
       queue_url = sqs.get_queue_url(queue_name: queue_name).queue_url
-      sqs.send_message(queue_url: queue_url, message_body: JSON.generate(spans_with_ips))
+      body = JSON.generate(spans_with_ips)
+      sqs.send_message(queue_url: queue_url, message_body: body)
     rescue Aws::SQS::Errors::NonExistentQueue
-      error_message = "A queue named '#{@queue_name}' does not exist."
+      error_message = "The queue '#{queue_name}' does not exist."
       SuckerPunch.logger.error(error_message)
     rescue => e
       SuckerPunch.logger.error(e)
@@ -28,12 +29,17 @@ module Trace
     def initialize(options)
       @sqs_options = options[:region] ? { region: options[:region] } : {}
       @queue_name = options[:queue_name]
+      @async = options[:async] != false
       SuckerPunch.logger = options[:logger]
       super(options)
     end
 
     def flush!
-      AsyncSqsClient.perform_async(@sqs_options, @queue_name, spans.dup)
+      if @async
+        SqsClient.perform_async(@sqs_options, @queue_name, spans.dup)
+      else
+        SqsClient.new.perform(@sqs_options, @queue_name, spans)
+      end
     end
   end
 end

data/lib/zipkin-tracer.rb

@@ -4,11 +4,12 @@ require 'zipkin-tracer/sidekiq/middleware'
 require 'zipkin-tracer/trace_client'
 require 'zipkin-tracer/trace_container'
 require 'zipkin-tracer/trace_generator'
+require 'zipkin-tracer/trace_wrapper'
 
 begin
   require 'faraday'
   require 'zipkin-tracer/faraday/zipkin-tracer'
-rescue LoadError #Faraday is not available, we do not load our code.
+rescue LoadError # Faraday is not available, we do not load our code.
 end
 
 begin

data/zipkin-tracer.gemspec

@@ -31,6 +31,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency 'aws-sdk-sqs', '~> 1.0'
   s.add_development_dependency 'excon', '~> 0.53'
   s.add_development_dependency 'rspec', '~> 3.8'
+  s.add_development_dependency 'rspec-json_expectations', '~> 2.2'
   s.add_development_dependency 'rack-test', '~> 1.1'
   s.add_development_dependency 'rake', '~> 10.0'
   s.add_development_dependency 'timecop', '~> 0.8'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zipkin-tracer
 version: !ruby/object:Gem::Version
-  version: 0.36.2
+  version: 0.37.0
 platform: ruby
 authors:
 - Franklin Hu
@@ -14,7 +14,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-04-24 00:00:00.000000000 Z
+date: 2019-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -100,6 +100,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: rspec-json_expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: rack-test
   requirement: !ruby/object:Gem::Requirement
@@ -193,6 +207,8 @@ files:
 - README.md
 - RELEASE.md
 - Rakefile
+- bin/console
+- bin/setup
 - lib/zipkin-tracer.rb
 - lib/zipkin-tracer/application.rb
 - lib/zipkin-tracer/config.rb
@@ -206,6 +222,7 @@ files:
 - lib/zipkin-tracer/trace_client.rb
 - lib/zipkin-tracer/trace_container.rb
 - lib/zipkin-tracer/trace_generator.rb
+- lib/zipkin-tracer/trace_wrapper.rb
 - lib/zipkin-tracer/tracer_factory.rb
 - lib/zipkin-tracer/version.rb
 - lib/zipkin-tracer/zipkin_http_sender.rb