solarwinds_apm 5.1.9 → 6.0.0.preV2

data/CHANGELOG.md

@@ -1,82 +0,0 @@
-For the latest release info, see here:
-https://github.com/solarwindscloud/solarwinds-apm-ruby/releases
-
-Dates in this file are in the format MM/DD/YYYY.
-
-# solarwinds_apm 5.1.9 (05/025/2023)
-
-This release includes the following features:
-
-* Update latest liboboe library (12.3.0)
-
-Pushed to Rubygems:
-
-https://rubygems.org/gems/solarwinds_apm/versions/5.1.9
-
-# solarwinds_apm 5.1.8 (05/09/2023)
-
-This release includes the following features:
-
-* Update latest liboboe library (12.2.0)
-
-Pushed to Rubygems:
-
-https://rubygems.org/gems/solarwinds_apm/versions/5.1.8
-
-# solarwinds_apm 5.1.7 (03/14/2023)
-
-This release includes the following features:
-
-* Update latest liboboe library (12.1.0)
-
-Pushed to Rubygems:
-
-https://rubygems.org/gems/solarwinds_apm/versions/5.1.7
-
-# solarwinds_apm 5.1.6 (03/14/2023)
-
-This release includes the following features:
-
-* Update latest liboboe library (12.0.0)
-* Remove centos as testing environments and include amazonlinux as alternatives of RHEL distro
-* Include sanitize RemoteURL for kvs (p.s. RemoteHost is sanitized in library code)
-
-Pushed to Rubygems:
-
-https://rubygems.org/gems/solarwinds_apm/versions/5.1.6
-
-
-# solarwinds_apm 5.1.4 (11/23/2022)
-
-This release includes the following features:
-
-* Update to the latest redis-rb gem (> 5.x)
-* Update latest liboboe library (11.1.0)
-* Start to support solarwinds-apm-ruby arm64/aarch64 
-* Init message update for swo/nh backends
-
-Pushed to Rubygems:
-
-https://rubygems.org/gems/solarwinds_apm/versions/5.1.4
-
-
-# solarwinds_apm 5.1.0 (09/15/2022)
-
-This release includes the following features:
-
-* Using latest liboboe library (10.6.1)
-
-Pushed to Rubygems:
-
-https://rubygems.org/gems/solarwinds_apm/versions/5.1.0
-
-
-# solarwinds_apm 5.0.0 (09/15/2022)
-
-This release includes the following features:
-
-* Migrated Github repo
-
-Pushed to Rubygems:
-
-https://rubygems.org/gems/solarwinds_apm/versions/5.0.0

data/CONFIG.md

@@ -1,31 +0,0 @@
-# SolarWindsAPM Gem Configuration
-
-## Environment Variables
-
-The following environment variables are detected by the solarwinds_apm gem and affect how the gem functions.
-
-### General
-
-Name | Description | Default
----- | ----------- | -------
-`SW_APM_SERVICE_KEY` | API token + service name combination, mandatory for metrics and traces to show in the dashboard |
-`SW_APM_GEM_VERBOSE` | sets the verbose flag (`SolarWindsAPM::Config[:verbose]`) early in the gem loading process which may output valuable information | `false`
-`SW_APM_NO_LIBRARIES_WARNING` | tells the solarwinds_apm gem to __not__ output the _missing SolarWindsAPM libraries_ message on stack initialization | `false`
-
-# Related to Tests
-
-Name | Description | Default
----- | ----------- | -------
-`SW_APM_GEM_TEST` | puts the gem in test mode to avoid restarting certain background services used in testing.   `false`
-`DBTYPE` | For tests on Ruby on Rails, specifies the database type to test against.  `postgres`, `mysql` and `mysql2` are valid options. | `postgres`
-`MONGO_SERVER` | specifies the Mongo server to test against. | `127.0.0.1:27017`
-`RABBITMQ_SERVER` | specifies the RabbitMQ server to test against. | `127.0.0.1`
-`RABBITMQ_PORT` | port for the RabbitMQ connection. | `5672`
-`RABBITMQ_USERNAME` | username for the RabbitMQ connection | `guest`
-`RABBITMQ_PASSWORD` | password for the RabbitMQ connection | `guest`
-
-## SolarWindsAPM::Config
-
-`SolarWindsAPM::Config` is a nested hash used by the solarwinds_apm gem to store preferences and switches.
-
-See [this Rails generator template file](https://github.com/librato/ruby-solarwinds/blob/master/lib/rails/generators/solarwinds_apm/templates/sw_apm_initializer.rb) for documentation on all of the supported values.

data/Gemfile

@@ -1,15 +0,0 @@
-source 'https://rubygems.org'
-
-# this Gemfile is very minimal
-# use rake commands or gemfiles in the gemfiles directory for testing
-
-gem 'rake', '>= 0.9.0'
-
-group :development, :test do
-  gem 'byebug', '>= 8.0.0'
-  gem 'irb', '>= 1.0.0' # if RUBY_VERSION >= '2.6.0'
-  gem 'memory_profiler'
-  gem 'package_cloud'
-end
-
-gemspec

data/README.md

@@ -1,385 +0,0 @@
-# Welcome to the SolarWindsAPM Ruby Gem
-
-The solarwinds_apm gem provides [SolarWindsAPM](https://cloud.solarwinds.com/) performance instrumentation for Ruby.
-
-It has the ability to report performance metrics on an array of libraries, databases and frameworks such as Rails,
-Rack, ActiveRecord, Mongo, Memcache, Resque 
-[and more](https://documentation.solarwinds.com/en/success_center/observability/default.htm#cshid=config-ruby-agent).
-
-It requires an [Solarwinds] account to view metrics.  Get yours, 
-[it's free](https://cloud.solarwinds.com).
-
-[![Gem Version](https://badge.fury.io/rb/solarwinds_apm.svg)](https://badge.fury.io/rb/solarwinds_apm)
-
-[![Run All Tests](https://github.com/solarwindscloud/solarwinds-apm-ruby/actions/workflows/test_on_4_linux.yml/badge.svg)](https://github.com/solarwindscloud/solarwinds-apm-ruby/actions/workflows/test_on_4_linux.yml)
-
-[![C++ Tests](https://github.com/solarwindscloud/solarwinds-apm-ruby/actions/workflows/run_cpluplus_tests.yml/badge.svg)](https://github.com/solarwindscloud/solarwinds-apm-ruby/actions/workflows/run_cpluplus_tests.yml)
-
-[comment]: <> ([![Maintainability]&#40;https://api.codeclimate.com/v1/badges/ac7f36241a23a3a82fc5/maintainability&#41;]&#40;https://codeclimate.com/github/appoptics/appoptics-apm-ruby/maintainability&#41;)
-
-# Documentation
-
-* [SolarWindsAPM Knowledge Base](https://documentation.solarwinds.com/en/success_center/observability/default.htm#cshid=config-ruby-agent)
-
-# Installation
-
-_Before installing the gem below, make sure that you have the 
-[dependencies](https://documentation.solarwinds.com/en/success_center/observability/default.htm#cshid=config-ruby-install) installed on your host first._
-
-The solarwinds_apm gem is [available on Rubygems](https://rubygems.org/gems/solarwinds_apm) and can be installed with:
-
-```bash
-gem install solarwinds_apm
-```
-
-or added to **the end** of your Gemfile and running `bundle install`:
-
-```ruby
-gem 'solarwinds_apm'
-```
-
-# Running
-
-Make sure to set `SW_APM_SERVICE_KEY` in the environment from where the app or service is run, e.g:
-```
-export SW_APM_SERVICE_KEY=795fb4947d15275d208c49cfd2412d4a5bf38742045b47236c94c4fe5f5b17c7:<your_app_name>
-```
-
-## Rails
-
-No special steps are needed to instrument Ruby on Rails.  Once part of the bundle, the solarwinds-apm gem will automatically 
-detect Rails and instrument on stack initialization.
-
-### The Install Generator
-
-The solarwinds_apm gem provides a Rails generator used to seed an initializer where you can configure and control 
-`tracing_mode` and [other options](https://documentation.solarwinds.com/en/success_center/observability/default.htm#cshid=config-ruby-config-file).
-
-To run the install generator run:
-
-```bash
-bundle exec rails generate solarwinds_apm:install
-```
-
-After the prompts, this will create an initializer: `config/initializers/solarwinds_apm.rb`.
-
-## Sinatra
-
-You can instrument your Sinatra application by adding the following code to your `config.ru` Rackup file:
-
-```ruby
-# If you're not using Bundler.require.  Make sure this is done
-# after the Sinatra require directive.
-require 'solarwinds_apm'
-```
-
-Make sure that the solarwinds_apm gem is loaded _after_ Sinatra either by listing `gem 'solarwinds_apm'` after Sinatra in 
-your Gemfile or calling the `require 'solarwinds_gem'` directive after Sinatra is loaded.
-
-With this, the solarwinds_apm gem will automatically detect Sinatra on boot and instrument key components.
-
-## Padrino
-
-As long as the solarwinds_apm gem is in your `Gemfile` (inserted after the `gem 'padrino'` directive) and you are calling 
-`Bundler.require`, the solarwinds_apm gem will automatically instrument Padrino applications.
-
-If you need to set `SolarWindsAPM::Config` values on stack boot, you can do so by adding the following
-to your `config/boot.rb` file:
-
-```ruby
-Padrino.before_load do
-  # Verbose output of instrumentation initialization
-  SolarWindsAPM
-end
-```
-
-## Grape
-
-You can instrument your Grape application by adding the following code to your `config.ru` Rackup file:
-
-```ruby
-    # If you're not using Bundler.require.  Make sure this is done
-    # after the Grape require directive.
-    require 'solarwinds_apm'
-
-    ...
-
-    class App < Grape::API
-      use SolarWindsAPM::Rack
-    end
-```
-
-Make sure that the solarwinds gem is loaded _after_ Grape either by listing `gem 'solarwinds_apm'` after Grape in your 
-Gemfile or calling the `require 'solarwinds_apm'` directive after Grape is loaded.
-
-You must explicitly tell your Grape application to use SolarWindsAPM::Rack for tracing to occur.
-
-
-# SDK for Custom Tracing 
-
-The solarwinds_apm gem has the ability to instrument any arbitrary Ruby application or script.
-
-```ruby
-require 'rubygems'
-require 'bundler'
-
-Bundler.require
-
-require 'solarwinds_apm'
-```
-
-You can add even more visibility into any part of your application or scripts by adding custom instrumentation.  
-
-## SolarWindsAPM::SDK.trace
-You can instrument any arbitrary block of code using `SolarWindsAPM::SDK.trace`.  
-
-```ruby
-# layer_name will show up in the SolarWinds dashboard
-layer_name = 'subsystemX'
-
-# report_kvs are a set of information Key/Value pairs that are sent to
-# SolarWinds dashboard along with the performance metrics. These KV
-# pairs are used to report request, environment and/or client specific
-# information.
-
-report_kvs = {}
-report_kvs[:mykey] = @client.id
-
-SolarWindsAPM::SDK.trace(layer_name, kvs: report_kvs) do
-  # the block of code to be traced
-end
-```
-
-`SolarWindsAPM::SDK.trace` is used within the context of a request.  It will follow the upstream state of the request 
-being traced.  i.e. the block of code will only be traced when the parent request is being traced.
-
-This tracing state of a request can also be queried by using `SolarWindsAPM.tracing?`.
-
-## SolarWindsAPM::SDK.start_trace
-
-If you need to instrument code outside the context of a request (such as a cron job, background job or an arbitrary 
-ruby script), use `SolarWindsAPM::SDK.start_trace` instead which will initiate a new trace based on configuration and 
-probability (based on the sample rate).
-
-
-
-### Example
-
-```ruby
-require 'rubygems'
-require 'bundler'
-
-Bundler.require
-
-# Make sure solarwinds_apm is at the bottom of your Gemfile.
-# This is likely redundant but just in case.
-require 'solarwinds_apm'
- 
-
-# Tracing mode can be :enabled or :disabled
-SolarWindsAPM::Config[:tracing_mode] = :enabled
- 
-#
-# Update April 9, 2015 - this is done automagically now
-# and doesn't have to be called manually
-#
-# Load library instrumentation to auto-capture stuff we know about...
-# e.g. ActiveRecord, Dalli, Redis, memcache, mongo
-# TraceView::Ruby.load
- 
-# Some KVs to report to the dashboard
-report_kvs = {}
-report_kvs[:command_line_params] = ARGV.to_s
-report_kvs[:user_id] = `whoami`
- 
-SolarWindsAPM::SDK.start_trace('my_background_job', kvs: report_kvs) do
-  #
-  # Initialization code
-  #
-  
-  tasks = get_all_tasks
-  
-  tasks.each do |t|
-    # Optional: Here we embed another 'trace' to separate actual 
-    # work for each task.  In the traces dashboard this will show 
-    # up as a large 'my_background_job' parent layer with many 
-    # child 'task' layers.
-    SolarWindsAPM::SDK.trace('task', kvs: { :task_id => t.id }) do
-      t.perform
-    end
-  end
-  
-  #
-  # cleanup code
-  #
-end
- 
-
-# Note that we use 'start_trace' in the outer block and 'trace' for
-# any sub-blocks of code we wish to instrument.  The arguments for
-# both methods vary slightly. 
-``` 
-
-Find more details in the [RubyDoc page](https://www.rubydoc.info/gems/solarwinds_apm/SolarWindsAPM/SDK) on how to use the Tracing SDK in an independent Ruby script.
-
-# Support
-
-If you run into a problem, find a bug, or would like to request an enhancement, feel free to contact our tech support 
-[technicalsupport@solarwinds.com](technicalsupport@solarwinds.com).  
-
-# Contributing
-
-You are obviously a person of great sense and intelligence.  We happily appreciate all contributions to the solarwinds_apm 
-gem whether it is documentation, a bug fix, new instrumentation for a library or framework or anything else we haven't 
-thought of.
-
-We welcome you to send us PRs.  We also humbly request that any new instrumentation submissions have corresponding tests 
-that accompany them.  This way we don't break any of your additions when we (and others) make changes after the fact.
-
-
-## Layout of the Gem
-
-The solarwinds_apm gem uses a standard gem layout.  Here are the notable directories.
-
-    lib/solarwinds_apm/inst               # Auto load directory for various instrumented libraries
-    lib/solarwinds_apm/frameworks         # Framework instrumentation directory
-    lib/solarwinds_apm/frameworks/rails   # Files specific to Rails instrumentation
-    lib/rails                             # A Rails required directory for the Rails install generator
-    lib/api                               # The SolarWindsAPM Tracing API: layers, logging, tracing
-    ext/oboe_metal                        # The Ruby c extension that links against the system liboboe library
-
-## Building the Gem
-
-The solarwinds_apm gem is built with the standard `gem build` command passing in the gemspec:
-
-```bash
-gem build solarwinds_apm.gemspec
-```
-
-## Writing Custom Instrumentation
-
-Custom instrumentation for a library, database or other service can be authored fairly easily.  Generally, 
-instrumentation of a library is done by wrapping select operations of that library and timing their execution using the 
-SolarWindsAPM Tracing SDK which then reports the metrics to the users' SolarWinds dashboard.
-
-Here, I'll use a stripped down version of the Dalli instrumentation (`lib/solarwinds_apm/inst/dalli.rb`) as a quick example 
-of how to instrument a client library (the dalli gem).
-
-The Dalli gem nicely routes all memcache operations through a single `perform` operation.  Wrapping this method allows 
-us to capture all Dalli operations called by an application.
-
-First, we define a module (SolarWindsAPM::Inst::Dalli) and our own custom `perform_with_sw_apm` method that we will 
-use as a wrapper around Dalli's `perform` method.  We also declare an `included` method which automatically gets called 
-when this module is included by another.  
-See [`Module#included` Ruby reference documentation](https://devdocs.io/ruby~2.5/module#method-i-included).
-
-```ruby
-module SolarWindsAPM
-  module Inst
-    module Dalli
-      include SolarWindsAPM::API::Memcache
- 
-      def self.included(cls)
-        cls.class_eval do
-          if ::Dalli::Client.private_method_defined? :perform
-            alias perform_without_sw_apm perform
-            alias perform perform_with_sw_apm
-          end
-        end
-      end
- 
-      def perform_with_sw_apm(*all_args, &blk)
-        op, key, *args = *all_args
- 
-        if SolarWindsAPM.tracing?
-          opts = {}
-          opts[:KVOp] = op
-          opts[:KVKey] = key
- 
-          SolarWindsAPM::SDK.trace('memcache', kvs: opts) do
-            result = perform_without_sw_apm(*all_args, &blk)
-            if op == :get and key.class == String
-                SolarWindsAPM::API.log_info('memcache', { :KVHit => memcache_hit?(result) })
-            end
-            result
-          end
-        else
-          perform_without_sw_apm(*all_args, &blk)
-        end
-      end
-       
-    end
-  end
-end
-```
-
-Second, we tail onto the end of the instrumentation file a simple `::Dalli::Client.module_eval` call to tell the Dalli 
-module to include our newly defined instrumentation module.  Doing this will invoke our previously defined `included` method.
-
-```ruby
-if defined?(Dalli) and SolarWindsAPM::Config[:dalli][:enabled]
-  ::Dalli::Client.module_eval do
-    include SolarWindsAPM::Inst::Dalli
-  end
-end
-```
-
-Third, in our wrapper method, we capture the arguments passed in, collect the operation and key information into a local 
-hash and then invoke the `SolarWindsAPM::SDK.trace` method to time the execution of the original operation.
-
-The `SolarWindsAPM::SDK.trace` method calls Dalli's native operation and reports the timing metrics and your custom 
-`report_kvs` up to SolarWinds servers to be shown on the user's dashboard.
-
-Some other tips and guidelines:
-
-* You can point your Gemfile directly at your cloned solarwinds_apm gem source by using 
-`gem 'solarwinds_apm', :path => '/path/to/ruby-solarwinds'`
-
-* If instrumenting a library, database or service, place your new instrumentation file into the `lib/solarwinds_apm/inst/` 
-directory.  From there, the solarwinds_apm gem will detect it and automatically load the instrumentation file.
-
-* If instrumenting a new framework, place your instrumentation file in `lib/solarwinds_apm/frameworks`.  Refer to the Rails 
-instrumentation for on ideas on how to load the solarwinds_apm gem correctly in your framework.
-
-* Review other existing instrumentation similar to the one you wish to author.  `lib/solarwinds_apm/inst/` is a great place 
-to start.
-
-* Depending on the configured `:sample_rate`, not all requests will be traced.  Use `SolarWindsAPM.tracing?` to determine 
-of this is a request that is being traced.
-
-* Performance is paramount.  Make sure that your wrapped methods don't slow down users applications.
-
-* Include tests with your instrumentation.  See `test/instrumentation/` for some examples of existing instrumentation 
-tests.
-
-## Compiling the C extension
-
-The solarwinds_apm gem utilizes a C extension to interface with a core library bundled in with the gem which handles 
-reporting the trace and performance data back to SolarWinds servers.
-
-C extensions are usually built on `gem install` but when working out of a local git repository, it's required that you 
-manually build this C extension for the gem to function.
-
-To make this simpler, we've included a few rake tasks to automate this process:
-
-```bash
-rake clean                             # make sure no old stuff is around
-rake fetch_oboe_file["stg"]     # download c-files from staging
-rake compile                           # Build the gem's c extension
-```
-
-To see the code related to the C extension, take a look at `ext/oboe_metal/extconf.rb` for details.
-
-You can read more about Ruby gems with C extensions in the 
-[Rubygems Guides](http://guides.rubygems.org/gems-with-extensions/).
-
-## Running the Tests
-
-See the README in the test directory.
-
-# License
-
-Copyright (c) 2018 SolarWinds, LLC
-
-Released under the [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0)
-

data/bin/solarwinds_apm_config

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

data/examples/prepend.rb

@@ -1,13 +0,0 @@
-require 'solarwinds_apm'
-
-module Measurements
-  def request(*args, &block)
-    req = args.first
-    SolarWindsAPM::SDK.summary_metric("request_size", req.to_hash.to_s.size)
-    resp = super
-    SolarWindsAPM::SDK.summary_metric("response_size", resp.to_hash.to_s.size)
-    return resp
-  end
-end
-
-Net::HTTP.send(:prepend, :Measurements)