appoptics_apm_mnfst 4.5.2

data/Rakefile

@@ -0,0 +1,230 @@
+#!/usr/bin/env rake
+
+require 'rubygems'
+require 'fileutils'
+require 'open-uri'
+require 'bundler/setup'
+require 'rake/testtask'
+require 'appoptics_apm/test'
+
+Rake::TestTask.new do |t|
+  t.verbose = false
+  t.warning = false
+  t.ruby_opts = []
+  t.libs << 'test'
+
+  # Since we support so many libraries and frameworks, tests
+  # runs are segmented into gemfiles that have different
+  # sets and versions of gems (libraries and frameworks).
+  #
+  # Here we detect the Gemfile the tests are being run against
+  # and load the appropriate tests.
+  #
+  case AppOpticsAPM::Test.gemfile
+  when /delayed_job/
+    require 'delayed/tasks'
+    t.test_files = FileList['test/queues/delayed_job*_test.rb']
+  when /rails/
+    # Pre-load rails to get the major version number
+    require 'rails'
+
+    if Rails::VERSION::MAJOR == 5
+      t.test_files = FileList["test/frameworks/rails#{Rails::VERSION::MAJOR}x_test.rb"] +
+                     FileList["test/frameworks/rails#{Rails::VERSION::MAJOR}x_api_test.rb"]
+    else
+      t.test_files = FileList["test/frameworks/rails#{Rails::VERSION::MAJOR}x_test.rb"]
+    end
+
+  when /frameworks/
+    t.test_files = FileList['test/frameworks/sinatra*_test.rb'] +
+                   FileList['test/frameworks/padrino*_test.rb'] +
+                   FileList['test/frameworks/grape*_test.rb']
+  when /libraries/
+    t.test_files = FileList['test/support/*_test.rb'] +
+                   FileList['test/reporter/*_test.rb'] +
+                   FileList['test/instrumentation/*_test.rb'] +
+                   FileList['test/profiling/*_test.rb'] -
+                   ['test/instrumentation/twitter-cassandra_test.rb']
+  when /instrumentation_mocked/
+    # WebMock is interfering with other tests, so these have to run separately
+    t.test_files = FileList['test/mocked/*_test.rb']
+  when /noop/
+    t.test_files = FileList['test/noop/*_test.rb']
+  when /unit/
+    t.test_files = FileList['test/unit/*_test.rb'] +
+                   FileList['test/unit/*/*_test.rb']
+  end
+
+  if defined?(JRUBY_VERSION)
+    t.ruby_opts << ['-J-javaagent:/usr/local/tracelytics/tracelyticsagent.jar']
+  end
+end
+
+desc "Run all test suites defined by travis"
+task "docker_tests" do
+  Dir.chdir('test/run_tests')
+  exec('docker-compose run --service-ports ruby_appoptics /code/ruby-appoptics/test/run_tests/ruby_setup.sh test')
+end
+
+desc "Start docker container for testing and debugging"
+task "docker" do
+  Dir.chdir('test/run_tests')
+  exec('docker-compose run --service-ports ruby_appoptics /code/ruby-appoptics/test/run_tests/ruby_setup.sh bash')
+end
+
+desc "Fetch extension dependency files"
+task :fetch_ext_deps do
+  swig_version = %x{swig -version} rescue ''
+  swig_version = swig_version.scan(/swig version 3.0.\d*/i)
+  if swig_version.empty?
+    $stderr.puts '== ERROR ================================================================='
+    $stderr.puts "Could not find required swig version 3.0.*, found #{swig_version.inspect}"
+    $stderr.puts 'Please install swig "~ 3.0.8" and try again.'
+    $stderr.puts '=========================================================================='
+    raise
+  end
+
+  # The c-lib version is different from the gem version
+  oboe_version = ENV['OBOE_VERSION'] || 'latest'
+  oboe_s3_dir = "https://s3-us-west-2.amazonaws.com/rc-files-t2/c-lib/#{oboe_version}"
+  ext_src_dir = File.expand_path('ext/oboe_metal/src')
+
+  # VERSION is used by extconf.rb to download the correct liboboe when installing the gem
+  remote_file = File.join(oboe_s3_dir, 'VERSION')
+  local_file = File.join(ext_src_dir, 'VERSION')
+  puts "fetching #{remote_file} to #{local_file}"
+  open(remote_file, 'rb') do |rf|
+    content = rf.read
+    File.open(local_file, 'wb') { |f| f.puts content }
+    puts "!!!!!!! C-Lib VERSION: #{content.strip} !!!!!!!!"
+  end
+
+  # oboe and bson header files
+  FileUtils.mkdir_p(File.join(ext_src_dir, 'bson'))
+  %w(oboe.h oboe.hpp oboe_debug.h oboe.i bson/bson.h bson/platform_hacks.h).each do |filename|
+    remote_file = File.join(oboe_s3_dir, 'include', filename)
+    local_file = File.join(ext_src_dir, filename)
+
+    puts "fetching #{remote_file} to #{local_file}"
+    open(remote_file, 'rb') do |rf|
+      content = rf.read
+      File.open(local_file, 'wb') { |f| f.puts content }
+    end
+  end
+
+  FileUtils.cd(ext_src_dir) do
+    system('swig -c++ -ruby -module oboe_metal oboe.i')
+    FileUtils.rm('oboe.i')
+  end
+end
+
+desc "Build the gem's c extension"
+task :compile do
+  if !defined?(JRUBY_VERSION)
+    puts "== Building the c extension against Ruby #{RUBY_VERSION}"
+
+    pwd      = Dir.pwd
+    ext_dir  = File.expand_path('ext/oboe_metal')
+    final_so = File.expand_path('lib/oboe_metal.so')
+    so_file  = File.expand_path('ext/oboe_metal/oboe_metal.so')
+
+    Dir.chdir ext_dir
+    ENV['APPOPTICS_FROM_S3'] = 'true'
+    cmd = [Gem.ruby, 'extconf.rb']
+    sh cmd.join(' ')
+    sh '/usr/bin/env make'
+
+    File.delete(final_so) if File.exist?(final_so)
+
+    if File.exist?(so_file)
+      FileUtils.mv(so_file, final_so)
+      Dir.chdir(pwd)
+      puts "== Extension built and moved to #{final_so}"
+    else
+      Dir.chdir(pwd)
+      puts '!! Extension failed to build (see above). Have the required binary and header files been fetched?'
+      puts '!! Try the tasks in this order: clean > fetch_ext_deps > compile.'
+    end
+  else
+    puts '== Nothing to do under JRuby.'
+  end
+end
+
+desc 'Clean up extension build files'
+task :clean do
+  if !defined?(JRUBY_VERSION)
+    pwd     = Dir.pwd
+    ext_dir = File.expand_path('ext/oboe_metal')
+    symlinks = [
+      File.expand_path('lib/oboe_metal.so'),
+      File.expand_path('ext/oboe_metal/lib/liboboe.so'),
+      File.expand_path('ext/oboe_metal/lib/liboboe-1.0.so.0')
+    ]
+
+    symlinks.each do |symlink|
+      FileUtils.rm_f symlink
+    end
+    Dir.chdir ext_dir
+    sh '/usr/bin/env make clean' if File.exist? 'Makefile'
+
+    Dir.chdir pwd
+  else
+    puts '== Nothing to do under JRuby.'
+  end
+end
+
+desc 'Remove all built files and extensions'
+task :distclean do
+  if !defined?(JRUBY_VERSION)
+    pwd     = Dir.pwd
+    ext_dir = File.expand_path('ext/oboe_metal')
+    mkmf_log = File.expand_path('ext/oboe_metal/mkmf.log')
+    symlinks = [
+      File.expand_path('lib/oboe_metal.so'),
+      File.expand_path('ext/oboe_metal/lib/liboboe.so'),
+      File.expand_path('ext/oboe_metal/lib/liboboe-1.0.so.0')
+    ]
+
+    if File.exist? mkmf_log
+      symlinks.each do |symlink|
+        FileUtils.rm_f symlink
+      end
+      Dir.chdir ext_dir
+      sh '/usr/bin/env make distclean' if File.exist? 'Makefile'
+
+      Dir.chdir pwd
+    else
+      puts 'Nothing to distclean. (nothing built yet?)'
+    end
+  else
+    puts '== Nothing to do under JRuby.'
+  end
+end
+
+desc "Rebuild the gem's c extension"
+task :recompile => [:distclean, :compile]
+
+task :environment do
+  ENV['APPOPTICS_GEM_VERBOSE'] = 'true'
+
+  Bundler.require(:default, :development)
+  AppOpticsAPM::Config[:tracing_mode] = :always
+  AppOpticsAPM::Test.load_extras
+
+  if AppOpticsAPM::Test.gemfile?(:delayed_job)
+    require 'delayed/tasks'
+  end
+end
+
+task :console => :environment do
+  ARGV.clear
+  if AppOpticsAPM::Test.gemfile?(:delayed_job)
+    require './test/servers/delayed_job'
+  end
+  Pry.start
+end
+
+# Used when testing Resque locally
+task 'resque:setup' => :environment do
+  require 'resque/tasks'
+end

data/appoptics_apm.gemspec

@@ -0,0 +1,61 @@
+$:.push File.expand_path("../lib", __FILE__)
+require "appoptics_apm/version"
+
+Gem::Specification.new do |s|
+  s.name = %q{appoptics_apm_mnfst}
+  s.version = AppOpticsAPM::Version::STRING
+  s.date = Time.now.strftime('%Y-%m-%d')
+
+  s.license = "Librato Open License, Version 1.0"
+
+  s.authors = ["Maia Engeli", "Peter Giacomo Lombardo", "Spiros Eliopoulos"]
+  s.email = %q{support@appoptics.com}
+  s.homepage = %q{https://www.appoptics.com/}
+  s.summary = %q{AppOptics APM performance instrumentation gem for Ruby}
+  s.description = <<-EOF
+Automatic tracing and metrics for Ruby applications. Get started at appoptics.com. @AppOptics
+  EOF
+
+  s.metadata = {
+      'changelog_uri'     => 'https://github.com/appoptics/appoptics-apm-ruby/releases',
+      'documentation_uri' => 'https://docs.appoptics.com/kb/apm_tracing/ruby/',
+      'homepage_uri'      => 'https://www.appoptics.com/',
+      'source_code_uri'   => 'https://github.com/appoptics/appoptics-apm-ruby',
+  }
+
+  s.extra_rdoc_files = ['LICENSE']
+  s.files = `git ls-files`.split("\n").reject { |f| f.match(%r{^(test|gemfiles)/}) }
+  s.files += ['ext/oboe_metal/src/oboe.h',
+              'ext/oboe_metal/src/oboe.hpp',
+              'ext/oboe_metal/src/oboe_debug.h',
+              'ext/oboe_metal/src/oboe_wrap.cxx',
+              'ext/oboe_metal/src/bson/bson.h',
+              'ext/oboe_metal/src/bson/platform_hacks.h',
+              'ext/oboe_metal/src/VERSION']
+
+  # TODO this is commented out util we can actually provide gems for different platforms
+  # it will create a gem that goes into noop on Darwin and other unsupported platforms
+  # s.platform   = defined?(JRUBY_VERSION) ? 'java' : Gem::Platform::CURRENT
+
+  s.extensions = ['ext/oboe_metal/extconf.rb'] unless defined?(JRUBY_VERSION)
+
+  s.add_runtime_dependency('json', '>= 0')
+  s.add_runtime_dependency('no_proxy_fix', '~> 0.1.2', '>= 0.1.2')
+
+  # Development dependencies used in gem development & testing
+  s.add_development_dependency('rake', '>= 0.9.0')
+  s.add_development_dependency('simplecov', '>= 0.16.0') if ENV["SIMPLECOV_COVERAGE"]
+  s.add_development_dependency('simplecov-console', '>= 0.4.0') if ENV["SIMPLECOV_COVERAGE"]
+
+  unless defined?(JRUBY_VERSION)
+    s.add_development_dependency('byebug', '>= 8.0.0')
+    s.add_development_dependency('pry', '>= 0.10.0')
+    s.add_development_dependency('pry-byebug', '>= 3.0.0')
+    s.add_development_dependency('minitest-hooks', '>= 1.5.0')
+  else
+    s.add_development_dependency('pry', '>= 0.10.0')
+  end
+
+  s.required_ruby_version = '>= 2.0.0'
+  s.executables   = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
+end

data/bin/appoptics_apm_config

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+
+##
+# execute this with `bundle exec appoptics_apm_config`
+# copies the configuration template file into the current  directory
+#
+
+puts "Copying the configuration template file to appoptics_apm_config_tmp.rb"
+puts "Edit and save as appoptics_apm_config.rb"
+
+target_file = File.join(Dir.pwd, 'appoptics_apm_config_tmp.rb')
+temp_orig = File.join(File.dirname(File.dirname(__FILE__)),
+                 'lib/rails/generators/appoptics_apm/templates/appoptics_apm_initializer.rb')
+
+FileUtils.copy(temp_orig, target_file)

data/build_gem.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# builds the appoptics_apm gem for MRI.
+
+# we currently only build for MRI, no JRuby
+echo -e "\n=== building for MRI ===\n"
+rm -f Gemfile.lock
+bundle install
+bundle exec rake distclean
+bundle exec rake fetch_ext_deps
+gem build appoptics_apm.gemspec
+
+echo -e "\n=== built gems ===\n"
+ls -la appoptics_apm*.gem
+
+echo -e "\n=== publish to rubygems via: gem push <gem> ===\n"

data/build_gem_upload_to_packagecloud.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+# build the gem,
+# oboe/c-lib version can be given as optional parameter
+if [ "$1" != "" ]; then
+  OBOE_VERSION=$1 ./build_gem.sh
+else
+  ./build_gem.sh
+fi
+
+# save current rbenv setting and switch to 2.4.1 for the package_cloud commands
+current_ruby=`rbenv global`
+rbenv global 2.4.1
+
+# prerequisite: package_cloud token needs to be in ~/.packagecloud
+gem=`ls -dt1 appoptics_apm-[^pre]*.gem | head -1`
+package_cloud push solarwinds/appoptics-apm-ruby $gem
+
+# restore ruby version
+rbenv global $current_ruby

data/examples/SDK/01_basic_tracing.rb

@@ -0,0 +1,67 @@
+
+###############################################################
+# BASIC TRACING EXAMPLES
+###############################################################
+
+# set APPOPTICS_SERVICE_KEY and run with
+# `bundle exec ruby 01_basic_tracing.rb`
+
+require 'appoptics_apm'
+unless AppopticsAPM::SDK.appoptics_ready(10_000)
+  puts "aborting!!! Agent not ready after 10 seconds"
+  exit false
+end
+
+
+###############################################################
+# Starting a trace and adding a span
+###############################################################
+
+# USE CASE:
+# You may want to either trace a piece of your own code or a
+# call to a method from a gem that isn't auto-instrumented by
+# appoptics_apm
+
+# The first example will not create a span, because no trace has
+# been started, but the second and third ones will.
+
+# The string argument is the name for the span
+
+##
+# AppOpticsAPM::SDK.trace()
+# most of the time this is the method you need.  It adds a span
+# to a trace that has probably been started by rack.
+
+# Example 1
+def do_work
+  42
+end
+
+AppOpticsAPM::SDK.trace('simple_span') do
+  do_work
+end
+
+##
+# AppOpticsAPM::SDK.start_trace()
+# This method starts a trace.  It is handy for background jobs,
+# workers, or scripts, that are not part of a rack application
+
+# Example 2
+AppOpticsAPM::SDK.start_trace('outer_span') do
+
+  AppOpticsAPM::SDK.trace('simple_span') do
+    do_work
+  end
+
+end
+
+# Example 3
+def do_traced_work
+  AppOpticsAPM::SDK.trace('simple_span_2') do
+    do_work
+  end
+end
+
+AppOpticsAPM::SDK.start_trace('outer_span_2') do
+  do_traced_work
+end

data/examples/carrying_context.rb

@@ -0,0 +1,220 @@
+###############################################################
+# A brief overview of AppOpticsAPM tracing context
+###############################################################
+#
+# Tracing context is the state held when AppOpticsAPM is instrumenting a
+# transaction, block, request etc..  This context is advanced as
+# new blocks are instrumented and this chain of context is used
+# by AppOpticsAPM to later reassemble performance data to be displayed
+# in the AppOptics dashboard.
+#
+# Tracing context is non-existent until established by calling
+# `AppOpticsAPM::API.start_trace` or `AppOpticsAPM::API.log_start`.  Those methods
+# are part of the high-level and low-level API respectively.
+#
+# After a tracing context is established, that context can be
+# continued by calling `AppOpticsAPM::API.trace` or `AppOpticsAPM::API.log_entry`.
+# These methods will advance an existing context but not start
+# new one.
+#
+# For example, when a web request comes into a stack, a tracing
+# context is established using `AppOpticsAPM::API.log_start` as the request
+# enters through the rack middleware via `AppOpticsAPM::Rack`.
+#
+# That tracing context is then continued using `AppOpticsAPM::API.trace` or
+# `AppOpticsAPM::API.log_entry` for each subsequent layer such as Rails,
+# ActiveRecord, Redis, Memcache, ActionView, Mongo (etc...) until
+# finally request processing is complete and the tracing context
+# is cleared (AppOpticsAPM::Context.clear)
+#
+
+###############################################################
+# Carrying Context
+###############################################################
+#
+# The tracing context exists in the form of an X-Trace string and
+# can be retrieved using 'AppOpticsAPM::Context.toString'
+#
+# xtrace = AppOpticsAPM::Context.toString
+#
+# => "1B4EDAB9E028CA3C81BCD57CC4644B4C4AE239C7B713F0BCB9FAD6D562"
+#
+# Tracing context can also be picked up from a pre-existing
+# X-Trace string:
+#
+# xtrace = "1B4EDAB9E028CA3C81BCD57CC4644B4C4AE239C7B713F0BCB9FAD6D562"
+#
+# AppOpticsAPM::Context.fromString(xtrace)
+#
+# With these two methods, context can be passed across threads,
+# processes (via fork) and in requests (such as external HTTP
+# requests where the X-Trace is inserted in request headers).
+#
+#
+
+###############################################################
+# Two Options for Spawned Tracing
+###############################################################
+#
+# When your application needs to instrument code that forks,
+# spawns a thread or does something in-parallel, you have the
+# option to either link those child traces to the parent or
+# trace them as individuals (but with identifying information).
+#
+# Linking parent and child has it's benefits as in the
+# AppOptics dashboard, you will see how a process may spawn
+# a task in parallel and in a single view see the performance
+# of both.
+#
+# The limitation of this is that this is only useful if your
+# parent process spawns only a limited number of child traces.
+#
+# If your parent process is spawning many child tasks (e.g.
+# twenty, hundreds, thousands or more) it's best to trace those
+# child tasks as individuals and pass in identifier Key-Values
+# (such as task ID, job ID etc..)
+#
+# In the examples below, I show implementations of both linked
+# asynchronous traces and separated independent traces.
+
+###############################################################
+# Thread - with separated traces
+###############################################################
+
+AppOpticsAPM::API.log_start('parent')
+
+# Get the work to be done
+job = get_work
+
+Thread.new do
+  # This is a new thread so there is no pre-existing context so
+  # we'll call `AppOpticsAPM::API.log_start` to start a new trace context.
+  AppOpticsAPM::API.log_start('worker_thread', :job_id => job.id)
+
+  # Do the work
+  do_the_work(job)
+
+  AppOpticsAPM::API.log_end('worker_thread')
+end
+
+AppOpticsAPM::API.log_end('parent')
+
+###############################################################
+#
+# This will generate two independent traces with the following
+# topology.
+#
+# 'parent'
+# ------------------------------------------------------------
+#
+# 'worker_thread'
+# ------------------------------------------------------------
+#
+
+###############################################################
+# Thread - with linked asynchronous traces
+###############################################################
+
+# Since the following example spawns a thread without waiting
+# for it to return, we carry over the context and we mark the
+# trace generated in that thread to be asynchronous using
+# the `Async` flag.
+
+AppOpticsAPM::API.log_start('parent')
+
+# Save the context to be imported in spawned thread
+tracing_context = AppOpticsAPM::Context.toString
+
+# Get the work to be done
+job = get_work
+
+Thread.new do
+  # Restore context
+  AppOpticsAPM::Context.fromString(tracing_context)
+
+  AppOpticsAPM::API.log_entry('worker_thread')
+
+  # Do the work
+  do_the_work(job)
+
+  AppOpticsAPM::API.log_exit('worker_thread', :Async => 1)
+end
+
+AppOpticsAPM::API.log_end('parent')
+
+###############################################################
+#
+# This will generate a single trace with an asynchronous
+# branch like the following
+#
+# 'parent'
+# ------------------------------------------------------------
+#     \
+#      \
+#       ------------------------------------------------------
+#        'worker_thread'
+#
+
+###############################################################
+# Process via fork - with separated traces
+###############################################################
+
+AppOpticsAPM::API.start_trace('parent_process') do
+  # Get some work to process
+  job = get_job
+
+  # fork process to handle work
+  fork do
+    # Since fork does a complete process copy, the tracing_context still exists
+    # so we have to clear it and start again.
+    AppOpticsAPM::Context.clear
+
+    AppOpticsAPM::API.start_trace('worker_process', nil, :job_id => job.id) do
+      do_work(job)
+    end
+  end
+
+end
+
+###############################################################
+#
+# This will generate two independent traces:
+#
+# 'parent_process'
+# ------------------------------------------------------------
+#
+# 'worker_process'
+# ------------------------------------------------------------
+#
+###############################################################
+# Process via fork - with linked asynchronous traces
+###############################################################
+
+AppOpticsAPM::API.start_trace('parent_process') do
+  # Get some work to process
+  job = get_job
+
+  # fork process to handle work
+  fork do
+    # Since fork does a complete process copy, the tracing_context still exists
+    # although we'll have to mark these traces as asynchronous to denote
+    # that it has split off from the main program flow
+
+    AppOpticsAPM::API.trace('worker_process', :Async => 1) do
+      do_work(job)
+    end
+  end
+end
+
+###############################################################
+#
+# This will generate a single trace with an asynchronous
+# branch like the following
+#
+# 'parent_process'
+# ------------------------------------------------------------
+#     \
+#      \
+#       ------------------------------------------------------
+#        'worker_process'
+#