solarwinds_apm 5.0.0

data/examples/sdk_examples.rb

@@ -0,0 +1,158 @@
+# Copyright (c) 2020 SolarWinds, LLC.
+# All rights reserved.
+
+###############################################################
+# SDK EXAMPLES
+###############################################################
+# The uses cases of the SDK include:
+# - tracing a piece of your own code
+# - tracing a method call of a gem that is not auto-instrumented
+#   by solarwinds_apm
+#
+# SDK documentation:
+# https://rubydoc.info/gems/solarwinds_apm/SolarWindsAPM/SDK
+
+###############################################################
+# Prerequisits
+# export SW_APM_SERVICE_KEY=<API token>:<service_name>
+# `bundle exec ruby sdk_examples.rb`
+# 5 traced requests will show up in the backend
+###############################################################
+
+require 'solarwinds_apm'
+
+unless SolarWindsAPM::SDK.solarwinds_ready?(10_000)
+  puts "aborting!!! Agent not ready after 10 seconds"
+  exit false
+end
+
+###############################################################
+### ADD A SPAN
+###############################################################
+#
+# SolarWindsAPM::SDK.trace()
+# This method adds a span to a trace that has been started either
+# by the auto-instrumentation of the gem handling incoming requests
+# or the SDK method `start_trace`.
+# If this method is called outside of the context of a started
+# trace no spans will be created.
+#
+# The argument is the name for the span
+
+SolarWindsAPM::SDK.trace('span_name') do
+  [9, 6, 12, 2, 7, 1, 9, 3, 4, 14, 5, 8].sort
+end
+
+###############################################################
+# START A TRACE, ADD A SPAN, AND LOG AN INFO EVENT
+###############################################################
+#
+# SolarWindsAPM::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
+
+SolarWindsAPM::SDK.start_trace('outer_span') do
+  SolarWindsAPM::SDK.trace('first_child_span') do
+    [9, 6, 12, 2, 7, 1, 9, 3, 4, 14, 5, 8].sort
+    SolarWindsAPM::SDK.log_info({ some: :fancy, hash: :to, send: 1 })
+  end
+end
+
+###############################################################
+# LOG AN ERROR EVENT
+###############################################################
+#
+# SolarWindsAPM::SDK.log_exception()
+# This method adds an error event to the trace, which will be
+# displayed and counted as exception on the solarwinds_apm dashboard.
+
+def do_raise
+  raise StandardError.new("oops")
+end
+
+SolarWindsAPM::SDK.start_trace('with_error') do
+  begin
+    do_raise
+  rescue => e
+    SolarWindsAPM::SDK.log_exception(e)
+  end
+end
+
+###############################################################
+# TRACE A METHOD
+###############################################################
+#
+# SolarWindsAPM::SDK.trace_method()
+# This creates a span every time the defined method is run.
+# The method can be of any (accessible) type (instance,
+# singleton, private, protected etc.).
+
+module ExampleModule
+  def self.do_sum(a, b)
+    a + b
+  end
+end
+
+SolarWindsAPM::SDK.trace_method(ExampleModule,
+                               :do_sum,
+                               config: { name: 'computation', backtrace: true },
+                               kvs: { CustomKey: "some_info" })
+
+SolarWindsAPM::SDK.start_trace('trace_a_method') do
+  ExampleModule.do_sum(1, 2)
+  ExampleModule.do_sum(3, 4)
+end
+
+###############################################################
+# SET A CUSTOM TRANSACTION NAME
+###############################################################
+#
+# SolarWindsAPM::SDK.set_transaction_name()
+#
+# this method can be called anytime after a trace has been started to add a
+# custom name for the whole transaction.
+# In case of a controller the trace is usually started in rack.
+
+class FakeController
+  def create(params)
+    # @fake = fake.new(params.permit(:type, :title))
+    # @fake.save
+    SolarWindsAPM::SDK.set_transaction_name("fake.#{params[:type]}")
+    # redirect_to @fake
+  end
+end
+
+SolarWindsAPM::SDK.start_trace('set_transaction_name') do
+  FakeController.new.create(type: 'news')
+end
+
+###############################################################
+# LOG INJECTION OF TRACE_ID
+###############################################################
+#
+# SolarWindsAPM::SDK.current_trace_info
+# This method creates an object with the current trace ID and
+# helper methods to add the ID to logs for cross-referencing.
+
+SolarWindsAPM::Config[:log_traceId] = :always
+
+SolarWindsAPM::SDK.start_trace('log_trace_id') do
+  trace = SolarWindsAPM::SDK.current_trace_info
+  SolarWindsAPM.logger.warn "Some log message #{trace.for_log}"
+end
+
+###############################################################
+# START A TRACE AND PROFILE
+###############################################################
+#
+# SolarWindsAPM::Profiling.run
+# This method adds profiling for the code executed in the block
+
+SolarWindsAPM::SDK.start_trace("#{name}_profiling") do
+  SolarWindsAPM::Profiling.run do
+    10.times do
+      [9, 6, 12, 2, 7, 1, 9, 3, 4, 14, 5, 8].sort
+      sleep 0.2
+    end
+  end
+end

data/ext/oboe_metal/README.md

@@ -0,0 +1,69 @@
+# Debug the c-code with gdb
+
+inspired by: https://dev.to/wataash/how-to-create-and-debug-ruby-gem-with-c-native-extension-3l8b
+
+
+## install ruby with sources
+
+rbenv is your friend ;) -k means keep sources
+
+```
+rbenv install -k 2.7.5
+rbenv shell 2.7.5
+
+# check that ruby is debuggable
+type ruby           # => ruby is /home/wsh/.rbenv/shims/ruby
+rbenv which ruby    # => /home/wsh/.rbenv/versions/2.6.3/bin/ruby
+```
+
+
+##
+## add debug info when compiling solarwinds_apm
+add this line to extconf.rb to turn off optimization
+
+```
+CONFIG["optflags"] = "-O0"
+```
+
+
+##
+## start ruby app with gdb
+
+This will run ruby and load the app with a breakpoint in the Reporter::startThread
+c-function.
+
+`bundle exec gdb -q -ex 'set breakpoint pending on' -ex 'b Reporter::startThread' -ex run --args ruby -e 'require "./app"'`
+
+If there is a bug in the ruby code or a ruby byebug binding that halts the 
+script, the debugger will hang without showing any output. 
+So, make sure `bundle exec ruby app.rb` runs.
+
+use the gdb navigation commands to step through the code. If it says:
+
+```
+(gdb) n
+Single stepping until exit from function _ZN8Reporter11startThreadEv@plt,
+which has no line number information.
+```
+
+type `c` and it may end up stopping in the right location.
+
+##
+## make ruby .gdbinit macros available
+
+These macros are pretty elaborate. They are checked in the ruby github 
+repo: https://github.com/ruby/ruby/blob/master/.gdbinit
+The code is nicely formatted and colorized in github and easiest to read there.
+
+installation in the user's home dir:
+```
+wget https://github.com/ruby/ruby/blob/master/.gdbinit
+```
+##
+## examples
+
+Some inspiring examples here:
+
+https://jvns.ca/blog/2016/06/12/a-weird-system-call-process-vm-readv/
+
+https://medium.com/@zanker/finding-a-ruby-bug-with-gdb-56d6b321bc86

data/ext/oboe_metal/extconf.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+
+require 'mkmf'
+require 'rbconfig'
+require 'open-uri'
+require 'no_proxy_fix'
+
+CONFIG['warnflags'] = CONFIG['warnflags'].gsub(/-Wdeclaration-after-statement/, '')
+                        .gsub(/-Wimplicit-function-declaration/, '')
+                        .gsub(/-Wimplicit-int/, '')
+                        .gsub(/-Wno-tautological-compare/, '')
+                        .gsub(/-Wno-self-assign/, '')
+                        .gsub(/-Wno-parentheses-equality/, '')
+                        .gsub(/-Wno-constant-logical-operand/, '')
+                        .gsub(/-Wno-cast-function-type/, '')
+init_mkmf(CONFIG)
+
+ext_dir = File.expand_path(File.dirname(__FILE__))
+
+# Set the mkmf lib paths so we have no issues linking to
+# the SolarWindsAPM libs.
+ao_lib_dir = File.join(ext_dir, 'lib')
+ao_include = File.join(ext_dir, 'src')
+
+# Download the appropriate liboboe from S3(via rake for testing) or files.appoptics.com (production)
+version = File.read(File.join(ao_include, 'VERSION')).strip
+if ENV['OBOE_FROM_S3'].to_s.downcase == 'true'
+  ao_path = File.join('https://rc-files-t2.s3-us-west-2.amazonaws.com/c-lib/', version)
+  puts 'Fetching c-lib from S3'
+else
+  ao_path = File.join('https://files.appoptics.com/c-lib', version)
+end
+
+ao_arch = 'x86_64'
+if File.exist?('/etc/alpine-release')
+  version = File.read('/etc/alpine-release').strip
+
+  ao_arch =
+    if Gem::Version.new(version) < Gem::Version.new('3.9')
+      'alpine-libressl-x86_64'
+    else # openssl
+      'alpine-x86_64'
+    end
+end
+
+ao_clib = "liboboe-1.0-#{ao_arch}.so.0.0.0"
+ao_item = File.join(ao_path, ao_clib)
+ao_checksum_file = File.join(ao_lib_dir, "#{ao_clib}.sha256")
+clib = File.join(ao_lib_dir, ao_clib)
+
+retries = 3
+success = false
+while retries > 0
+  begin
+    download = URI.open(ao_item, 'rb')
+    IO.copy_stream(download, clib)
+
+    clib_checksum = Digest::SHA256.file(clib).hexdigest
+    download.close
+    checksum =  File.read(ao_checksum_file).strip
+
+    # unfortunately these messages only show if the install command is run
+    # with the `--verbose` flag
+    if clib_checksum != checksum
+      $stderr.puts '== ERROR ================================================================='
+      $stderr.puts 'Checksum Verification failed for the c-extension of the solarwinds_apm gem'
+      $stderr.puts 'Installation cannot continue'
+      $stderr.puts "\nChecksum packaged with gem:   #{checksum}"
+      $stderr.puts "Checksum calculated from lib: #{clib_checksum}"
+      $stderr.puts 'Contact technicalsupport@solarwinds.com if the problem persists'
+      $stderr.puts '=========================================================================='
+      exit 1
+    else
+      success = true
+      retries = 0
+    end
+  rescue => e
+    File.write(clib, '')
+    retries -= 1
+    if retries == 0
+      $stderr.puts '== ERROR =========================================================='
+      $stderr.puts 'Download of the c-extension for the solarwinds_apm gem failed.'
+      $stderr.puts 'solarwinds_apm will not instrument the code. No tracing will occur.'
+      $stderr.puts 'Contact technicalsupport@solarwinds.com if the problem persists.'
+      $stderr.puts "error: #{ao_item}\n#{e.message}"
+      $stderr.puts '==================================================================='
+      create_makefile('oboe_noop', 'noop')
+    end
+    sleep 0.5
+  end
+end
+
+if success
+  # Create relative symlinks for the SolarWindsAPM library
+  Dir.chdir(ao_lib_dir) do
+    File.symlink(ao_clib, 'liboboe.so')
+    File.symlink(ao_clib, 'liboboe-1.0.so.0')
+  end
+
+  dir_config('oboe', 'src', 'lib')
+
+  # create Makefile
+  if have_library('oboe', 'oboe_config_get_revision', 'oboe.h')
+    $libs = append_library($libs, 'oboe')
+    $libs = append_library($libs, 'stdc++')
+
+    $CFLAGS << " #{ENV['CFLAGS']}"
+    # $CPPFLAGS << " #{ENV['CPPFLAGS']} -std=c++11"
+    # TODO for debugging: -pg -gdwarf-2, remove for production
+    # -pg does not work on alpine https://www.openwall.com/lists/musl/2014/11/05/2
+    $CPPFLAGS << " #{ENV['CPPFLAGS']} -std=c++11  -gdwarf-2 -I$$ORIGIN/../ext/oboe_metal/include -I$$ORIGIN/../ext/oboe_metal/src"
+    # $CPPFLAGS << " #{ENV['CPPFLAGS']} -std=c++11 -I$$ORIGIN/../ext/oboe_metal/include"
+    $LIBS << " #{ENV['LIBS']}"
+
+    # use "z,defs" to see what happens during linking
+    # $LDFLAGS << " #{ENV['LDFLAGS']} '-Wl,-rpath=$$ORIGIN/../ext/oboe_metal/lib,-z,defs'  -lrt"
+    $LDFLAGS << " #{ENV['LDFLAGS']} '-Wl,-rpath=$$ORIGIN/../ext/oboe_metal/lib' -lrt"
+    $CXXFLAGS += " -std=c++11 "
+
+    # ____ include debug info, comment out when not debugging
+    # ____ -pg -> profiling info for gprof
+    CONFIG["debugflags"] = "-ggdb3 "
+    CONFIG["optflags"] = "-O0"
+
+    create_makefile('libsolarwinds_apm', 'src')
+  else
+    $stderr.puts   '== ERROR ========================================================='
+    if have_library('oboe')
+      $stderr.puts "The c-library either needs to be updated or doesn't match the OS."
+      $stderr.puts 'No tracing will occur.'
+    else
+      $stderr.puts 'Could not find a matching c-library. No tracing will occur.'
+    end
+    $stderr.puts   'Contact technicalsupport@solarwinds.com if the problem persists.'
+    $stderr.puts   '=================================================================='
+    create_makefile('oboe_noop', 'noop')
+  end
+end

data/ext/oboe_metal/extconf_local.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2016 SolarWinds, LLC.
+# All rights reserved.
+
+require 'mkmf'
+require 'rbconfig'
+require 'open-uri'
+require 'no_proxy_fix'
+
+CONFIG['warnflags'] = CONFIG['warnflags'].gsub(/-Wdeclaration-after-statement/, '')
+                        .gsub(/-Wimplicit-function-declaration/, '')
+                        .gsub(/-Wimplicit-int/, '')
+                        .gsub(/-Wno-tautological-compare/, '')
+                        .gsub(/-Wno-self-assign/, '')
+                        .gsub(/-Wno-parentheses-equality/, '')
+                        .gsub(/-Wno-constant-logical-operand/, '')
+                        .gsub(/-Wno-cast-function-type/, '')
+init_mkmf(CONFIG)
+
+ext_dir = File.expand_path(File.dirname(__FILE__))
+
+# Set the mkmf lib paths so we have no issues linking to
+# the SolarWindsAPM libs.
+ao_lib_dir = File.join(ext_dir, 'lib')
+ao_path = '../../../oboe/factory-output'
+ao_clib = "liboboe-1.0-x86_64.so.0.0.0"
+ao_item = File.join(ao_path, ao_clib)
+clib = File.join(ao_lib_dir, ao_clib)
+
+FileUtils.cp(ao_item, clib)
+
+# Create relative symlinks for the SolarWindsAPM library
+Dir.chdir(ao_lib_dir) do
+  File.symlink(ao_clib, 'liboboe.so')
+  File.symlink(ao_clib, 'liboboe-1.0.so.0')
+end
+
+dir_config('oboe', 'src', 'lib')
+
+if have_library('oboe', 'oboe_config_get_revision', 'oboe.h')
+  $libs = append_library($libs, 'oboe')
+  $libs = append_library($libs, 'stdc++')
+
+  $CFLAGS << " #{ENV['CFLAGS']}"
+  # $CPPFLAGS << " #{ENV['CPPFLAGS']} -std=c++11"
+  # TODO for debugging: -pg -gdwarf-2, remove for production
+  # -pg does not work on alpine https://www.openwall.com/lists/musl/2014/11/05/2
+  $CPPFLAGS << " #{ENV['CPPFLAGS']} -std=c++11  -gdwarf-2 -I$$ORIGIN/../ext/oboe_metal/include -I$$ORIGIN/../ext/oboe_metal/src"
+  # $CPPFLAGS << " #{ENV['CPPFLAGS']} -std=c++11 -I$$ORIGIN/../ext/oboe_metal/include"
+  $LIBS << " #{ENV['LIBS']}"
+
+  # use "z,defs" to see what happens during linking
+  # $LDFLAGS << " #{ENV['LDFLAGS']} '-Wl,-rpath=$$ORIGIN/../ext/oboe_metal/lib,-z,defs'  -lrt"
+  $LDFLAGS << " #{ENV['LDFLAGS']} '-Wl,-rpath=$$ORIGIN/../ext/oboe_metal/lib' -lrt"
+  $CXXFLAGS += " -std=c++11 "
+
+  # ____ include debug info, comment out when not debugging
+  # ____ -pg -> profiling info for gprof
+  CONFIG["debugflags"] = "-ggdb3 "
+  CONFIG["optflags"] = "-O0"
+
+  create_makefile('libsolarwinds_apm', 'src')
+else
+  $stderr.puts   '== ERROR ========================================================='
+  if have_library('oboe')
+    $stderr.puts "The c-library either needs to be updated or doesn't match the OS."
+    $stderr.puts 'No tracing will occur.'
+  else
+    $stderr.puts 'Could not find a matching c-library. No tracing will occur.'
+  end
+  $stderr.puts   'Contact technicalsupport@solarwinds.com if the problem persists.'
+  $stderr.puts   '=================================================================='
+  create_makefile('oboe_noop', 'noop')
+end

data/ext/oboe_metal/lib/liboboe-1.0-alpine-x86_64.so.0.0.0.sha256

@@ -0,0 +1 @@
+32deed8447ef3b97ed92efe062c2c2c609458978ce8760b29e343cc60c3f93e6

data/ext/oboe_metal/lib/liboboe-1.0-x86_64.so.0.0.0.sha256

@@ -0,0 +1 @@
+34b3413d417ff9c6c9b19b77cf335294a8cd04132d224651aba2706bdd6dff2f

data/ext/oboe_metal/noop/noop.c

@@ -0,0 +1,8 @@
+#include <ruby.h>
+
+/* ruby calls this to load the extension */
+void Init_oboe_noop(void) {
+  /* assume we haven't yet defined Hola */
+//  VALUE klass = rb_define_class("OboeNoop", rb_cObject);
+  rb_define_class("OboeNoop", rb_cObject);
+}

data/ext/oboe_metal/src/README.md

@@ -0,0 +1,6 @@
+
+oboe_api.hpp and oboe_api.cpp are copied here from the oboe repo during install
+
+it is best to edit these file in the oboe codebase and use the OBOE_WIP=true env
+var to include the local development version while the changes aren't deployed to s3.
+

data/ext/oboe_metal/src/VERSION

@@ -0,0 +1,2 @@
+10.3.3
+