ddtrace 0.3.1

data/ddtrace.gemspec

@@ -0,0 +1,41 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ddtrace/version'
+
+Gem::Specification.new do |spec|
+  spec.name                  = "ddtrace"
+  spec.version               = "#{Datadog::VERSION::STRING}#{ENV['VERSION_SUFFIX']}"
+  spec.required_ruby_version = '>= 2.1.0'
+  spec.authors               = ["Datadog, Inc."]
+  spec.email                 = ["dev@datadoghq.com"]
+
+  spec.summary     = "Datadog tracing code for your Ruby applications"
+  spec.description = <<-EOS
+ddtrace is Datadog’s tracing client for Ruby. It is used to trace requests
+as they flow across web servers, databases and microservices so that developers
+have great visiblity into bottlenecks and troublesome requests.
+EOS
+
+  spec.homepage = "https://github.com/DataDog/dd-trace-rb"
+  spec.license  = "BSD-3-Clause"
+
+  if spec.respond_to?(:metadata)
+    spec.metadata['allowed_push_host'] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "msgpack"
+
+  spec.add_development_dependency "bundler", "~> 1.12"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rubocop", "~> 0.43"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "appraisal", "~> 2.1"
+end

data/docker-compose.yml

@@ -0,0 +1,33 @@
+# remember to use this compose file __ONLY__ for development/testing purposes
+postgres:
+    image: postgres:9.6
+    environment:
+        - POSTGRES_PASSWORD=$TEST_POSTGRES_PASSWORD
+        - POSTGRES_USER=$TEST_POSTGRES_USER
+        - POSTGRES_DB=$TEST_POSTGRES_DB
+    ports:
+        - "127.0.0.1:${TEST_POSTGRES_PORT}:5432"
+
+mysql:
+    image: mysql:5.6
+    environment:
+        - MYSQL_ROOT_PASSWORD=$TEST_MYSQL_ROOT_PASSWORD
+        - MYSQL_PASSWORD=$TEST_MYSQL_PASSWORD
+        - MYSQL_USER=$TEST_MYSQL_USER
+    ports:
+        - "127.0.0.1:${TEST_MYSQL_PORT}:3306"
+
+elasticsearch:
+    # Note: ES 5.0 dies with error:
+    # max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]
+    # see https://github.com/docker-library/elasticsearch/issues/98 for details
+    # For now, just rely on a 2.X server.
+    image: elasticsearch:2.4
+    ports:
+        - "127.0.0.1:${TEST_ELASTICSEARCH_REST_PORT}:9200"
+        - "127.0.0.1:${TEST_ELASTICSEARCH_NATIVE_PORT}:9300"
+
+redis:
+    image: redis:3.0
+    ports:
+        - "127.0.0.1:${TEST_REDIS_PORT}:6379"

data/docs/GettingStarted

@@ -0,0 +1,352 @@
+= \Datadog Trace Client
+
+_ddtrace_ is Datadog’s tracing client for Ruby. It is used to trace requests as they flow across web servers,
+databases and microservices so that developers have great visiblity into bottlenecks and troublesome requests.
+
+== Installation
+
+Install the tracer with the +gem+ command, but point to Datadog's gems repository:
+
+    $ gem install ddtrace --source http://gems.datadoghq.com/trace/
+
+On the other hand, if you're using +Bundler+, just update your +Gemfile+ as follows:
+
+    source 'https://rubygems.org'
+
+    # tracing gem
+    gem 'ddtrace', :source => 'http://gems.datadoghq.com/trace/'
+
+== Quickstart (Auto Instrumentation)
+
+If you are on a {supported integration}[#label-Integrations], you should be able to generate traffic and view
+metrics in your {dashboard}[https://app.datadoghq.com/trace].
+
+== Quickstart (Manual Instrumentation)
+
+If you aren't using a supported framework instrumentation, you may want to to manually instrument your code.
+Adding tracing to your code is very simple. As an example, let’s imagine we have a web server and we want
+to trace requests to the home page:
+
+    require 'ddtrace'
+    require 'sinatra'
+    require 'activerecord'
+
+    # a generic tracer that you can use across your application
+    tracer = Datadog.tracer
+
+    get '/' do
+      tracer.trace('web.request') do |span|
+        # set some span metadata
+        span.service = 'my-web-site'
+        span.resource = '/'
+        span.set_tag('http.method', request.request_method)
+
+        # trace the activerecord call
+        tracer.trace('posts.fetch') do
+          @posts = Posts.order(created_at: :desc).limit(10)
+        end
+
+        # trace the template rendering
+        tracer.trace('template.render') do
+          erb :index
+        end
+      end
+    end
+
+== Glossary
+
+[Service] The name of a set of processes that do the same job. Some examples are +datadog-web-app+ or +datadog-metrics-db+.
+
+[Resource] A particular query to a service. For a web application, some examples might be a URL stem like +/user/home+ or a
+           handler function like +web.user.home+. For a SQL database, a resource would be the SQL of the query itself like
+           <tt>select * from users where id = ?</tt>.
+           You can track thousands (not millions or billions) of unique resources per services, so prefer resources like
+           +/user/home+ rather than <tt>/user/home?id=123456789</tt>.
+
+[Span] A span tracks a unit of work in a service, like querying a database or rendering a template. Spans are associated
+       with a service and optionally a resource. Spans have names, start times, durations and optional tags.
+
+== Integrations
+
+=== Ruby on \Rails
+
+The \Rails integration will trace requests, database calls, templates rendering and cache read/write/delete
+operations. The integration makes use of the Active Support Instrumentation, listening to the Notification API
+so that any operation instrumented by the API is traced.
+
+The supported versions are:
+
+* \Rails 3.2 (MRI interpreter, JRuby is experimental)
+* \Rails 4.2 (MRI interpreter, JRuby is experimental)
+* \Rails 5.0 (MRI interpreter)
+
+The currently supported web server are:
+* Puma 2.16+ and 3.6+
+* Unicorn 4.8+ and 5.1+
+* Passenger 5.0 (experimental)
+
+==== Installation
+
+Add the tracer gem to your +Gemfile+:
+
+    gem 'ddtrace', :source => 'http://gems.datadoghq.com/trace/'
+
+Now you can set your service name, simply creating an initializer file in your +config/+ folder:
+
+    # config/initializers/datadog-tracer.rb
+
+    Rails.configuration.datadog_trace = {
+      default_service: 'my-rails-app',
+    }
+
+If you're using \Rails 3 or higher, the auto-instrumentation will be automatically activated and no more configuration
+is required. Your application will be listed as +my-rails-app+ in your {dashboard}[https://app.datadoghq.com/trace].
+
+==== Custom Instrumentation
+
+If you need to instrument custom code within your controllers, you can simply:
+
+    class CustomController < ApplicationController
+      def index
+        # using auto instrumentation, these calls are already traced
+        @values = SomeModel.all
+        @counter = Rails.cache.fetch('custom_cache_key')
+
+        # use the global tracer to instrument your code
+        tracer = Datadog.tracer
+        tracer.trace('custom.service') do
+          data = Something::fetch_data()
+          @objects = Something::parse_data(data)
+        end
+      end
+    end
+
+With the auto instrumentation turned on, the result trace will include your span correctly nested under the
++rails.request+ span.
+
+==== Tracer Configuration
+
+All tracing settings are namespaced under the +Rails.configuration.datadog_tracer+ hash. To change the default behavior
+of the Datadog tracer, you can override the following defaults:
+
+    # config/initializers/datadog-tracer.rb
+
+    Rails.configuration.datadog_trace = {
+      enabled: true,
+      auto_instrument: true,
+      auto_instrument_redis: true,
+      default_service: 'rails-app',
+      default_cache_service: 'rails-cache',
+      template_base_path: 'views/',
+      tracer: Datadog.tracer,
+      debug: false,
+      trace_agent_hostname: 'localhost',
+      trace_agent_port: 7777
+    }
+
+The available settings are:
+
+* +enabled+: defines if the +tracer+ is enabled or not. If set to +false+, the code is still instrumented
+  but no spans are sent to the local trace agent.
+* +auto_instrument+: if set to false the code will not be instrumented, while the +tracer+ may be active for
+  your internal usage. This could be useful if you want to use the \Rails integration, but you want to trace
+  only particular functions or views
+* +auto_instrument_redis+: if set to false \Redis calls will not be traced as such. Calls to cache will
+  still be instrumented but you will not have the detail of low-level \Redis calls.
+* +default_service+: set the service name used when tracing application requests. Defaults to +rails-app+
+* +default_database_service+: set the database service name used when tracing database activity. Defaults to the
+  current adapter name, so if you're using PostgreSQL it will be +postgres+.
+* +default_cache_service+: set the cache service name used when tracing cache activity. Defaults to +rails-cache+
+* +template_base_path+: used when the template name is parsed in the auto instrumented code. If you don't store
+  your templates in the +views/+ folder, you may need to change this value
+* +tracer+: is the global tracer used by the tracing application. Usually you don't need to change that value
+  unless you're already using a different initialized +tracer+ somewhere else
+* +debug+: set to true to enable debug logging.
+* +trace_agent_hostname+: set the hostname of the trace agent.
+* +trace_agent_port+: set the port the trace agent is listening on.
+
+=== Redis
+
+The \Redis integration will trace simple calls as well as pipelines.
+
+    require 'redis'
+    require 'ddtrace'
+
+    Datadog::Monkey.patch_module(:redis) # you need to explicitly patch it
+
+    # now do your Redis stuff, eg:
+    redis = Redis.new
+    redis.set 'foo', 'bar' # traced!
+
+The \patch_module allows you to enable tracing on a per-library basis.
+If you want to enable tracing for all supported integrations, you can simply
+use \patch_all eg:
+
+    require 'redis'
+    require 'ddtrace'
+
+    Datadog::Monkey.patch_all # enables all available integrations
+
+    # now do your Redis stuff, eg:
+    redis = Redis.new
+    redis.set 'foo', 'bar' # traced!
+
+=== Elastic Search
+
+The \Elasticsearch integration will trace any call to \perform_request
+in the \Client object:
+
+    require 'elasticsearch/transport'
+    require 'ddtrace'
+
+    Datadog::Monkey.patch_module(:elasticsearch) # you need to explicitly patch it
+
+    # now do your Elastic Search stuff, eg:
+    client = Elasticsearch::Client.new url: 'http://127.0.0.1:9200'
+    response = client.perform_request 'GET', '_cluster/health'
+
+The \patch_module allows you to enable tracing on a per-library basis.
+If you want to enable tracing for all supported integrations, you can simply
+use \patch_all eg:
+
+    require 'elasticsearch/transport'
+    require 'ddtrace'
+
+    Datadog::Monkey.patch_all # enables all available integrations
+
+    # now do your Elastic Search stuff, eg:
+    client = Elasticsearch::Client.new url: 'http://127.0.0.1:9200'
+    response = client.perform_request 'GET', '_cluster/health'
+
+== Monkey Patching
+
+=== Patching methods
+
+Integrations such as \Redis or \Elasticsearch use monkey patching.
+
+The available methods are:
+
+* +autopatch_modules+: returns a \Hash of all modules available for monkey patching,
+  the key is the name of the module and the value \true or \false. If it is \true,
+  a call to \patch_all will enable the module, if it is \false, it will do nothing.
+* +patch_all+: patches all modules which are supported. Make sure all the necessary
+  calls to \require have been done before this is alled, else monkey patching will
+  not work.
+* +patch_module+: patches a single module, regardless of its settings in the
+  \autopatch_modules list.
+* +patch+: patches some modules, you should pass a hash like the one returned
+  by \autopatch_modules
+* +get_patched_modules+: returns the list of patched modules, a module has been
+  correctly patched only if it is in this hash, with a value set to \true.
+
+Example:
+
+    require 'ddtrace'
+
+    puts Datadog::Monkey.autopatch_modules                   # lists all modules available for monkey patching
+    Datadog::Monkey.patch_module(:redis)                     # patch only one module
+    Datadog::Monkey.patch(elasticsearch: false, redis: true) # patch redis, but not elasticsearch
+    Datadog::Monkey.patch_all                                # patch all the available modules
+    puts Datadog::Monkey.get_patched_modules                 # tells wether modules are patched or not
+
+It is safe to call \patch_all, \patch_module or \patch several times.
+Make sure the library you want to patch is imported before you call \patch_module.
+In doubt, check with \get_patched_modules.
+Once a module is patched, it is not possible to unpatch it.
+
+=== Patch Info (PIN)
+
+The Patch Info, AKA \Pin object, gives you control on the integration.
+
+It has one class method:
+
+* +get_from+: returns the Pin object which has been pinned onto some random
+  object. It is safe to call \get_from on any object, but it might return \nil.
+
+Some instance methods:
+
+* +enabled?+: wether tracing is enabled for this object
+* +onto+: applies the patch information to some random object. It is the companion
+  function of \get_from.
+
+Accessors:
+
+* +service+: service, you should typically set some meaningful value for this.
+* +app+: application name
+* +tags+: optional tags
+* +app_type+: application type
+* +name+: span name
+* +tracer+: the tracer object used for tracing
+
+By default, a traced integration such as \Redis or \Elasticsearch carries a \Pin object. Eg:
+
+    require 'redis'
+    require 'ddtrace'
+
+    Datadog::Monkey.patch_all
+
+    redis = Redis.new
+    pin = Datadog::Pin.get_from(redis)
+    pin.service = 'my-redis-cache'
+    puts redis.get 'my-key' # this will be traced as belonging to 'my-redis-cache' service
+    pin.tracer = nil
+    puts pin.enabled?       # false
+    puts redis.get 'my-key' # this won't be traced, tracing has been disabled now
+
+You can use this object to instrument your own code:
+
+    require 'ddtrace'
+    require 'ddtrace/ext/app_types'
+
+    class MyWebSite
+      def initialize
+        pin = Datadog::Pin.new('my-web-site', app_type: Datadog::Ext::AppTypes::WEB)
+        Datadog::Pin.onto(self)
+      end
+
+      def serve(something)
+        pin = Datadog::Pin.get_from(self)
+        pin.tracer.trace('serve') do |span|
+          span.resource = something
+          span.service = pin.service
+          # serve something here
+        end
+      end
+    end
+
+== Debug Mode
+
+If you need to check locally what traces and spans are sent after each traced block, you can enable
+a global debug mode for all tracers so that every time a trace is ready to be sent, the content will be
+printed in the +STDOUT+. To enable the debug logging, add this code anywhere before using the tracer
+for the first time:
+
+    require 'ddtrace'
+    require 'sinatra'
+    require 'activerecord'
+
+    # enable debug mode
+    Datadog::Tracer.debug_logging = true
+
+    # use the tracer as usual
+    tracer = Datadog.tracer
+
+    get '/' do
+      tracer.trace('web.request') do |span|
+        # ...
+      end
+    end
+
+Remember that the debug mode may affect your application performance and so it must not be used
+in a production environment.
+
+== Supported Versions
+
+The \Datadog Trace Client has been tested with the following Ruby versions:
+
+* Ruby MRI 2.1
+* Ruby MRI 2.2
+* Ruby MRI 2.3
+* JRuby 9.1.5 (experimental)
+
+Other versions aren't yet officially supported.

data/gemfiles/contrib.gemfile

@@ -0,0 +1,9 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "elasticsearch-transport"
+gem "redis"
+gem "hiredis"
+
+gemspec :path => "../"

data/gemfiles/rails3_mysql2.gemfile

@@ -0,0 +1,11 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "test-unit"
+gem "rails", "3.2.22.5"
+gem "mysql2", "0.3.21", :platform => :ruby
+gem "activerecord-mysql-adapter", :platform => :ruby
+gem "activerecord-jdbcmysql-adapter", :platform => :jruby
+
+gemspec :path => "../"