elastic-apm 1.1.0 → 2.0.0

data/docs/context.asciidoc

@@ -5,13 +5,14 @@
 [float]
 ==== Adding custom context
 
-You can add your own custom, nested JSON-compatible data to the current transaction using `ElasticAPM.add_custom_context(hash)` eg.:
+You can add your own custom, nested JSON-compatible data to the current
+transaction using `ElasticAPM.set_custom_context(hash)` eg.:
 
 [source,ruby]
 ----
 class ThingsController < ApplicationController
   before_action do
-    ElasticAPM.add_custom_context(company: current_user.company)
+    ElasticAPM.set_custom_context(company: current_user.company)
   end
 
   # ...
@@ -21,13 +22,16 @@ end
 [float]
 ==== Adding tags
 
-Tags are special in that they are indexed in your Elasticsearch database and therefore searchable.
+Tags are special in that they are indexed in your Elasticsearch database and
+therefore searchable.
 
 [source,ruby]
 ----
 ElasticAPM.set_tag(:company_name, 'Acme, Inc.')
 ----
 
+Note that `.`, `*` and `"` in keys are converted to `_`.
+
 [float]
 ==== Providing info about the user
 

data/docs/custom-instrumentation.asciidoc

@@ -1,19 +1,22 @@
 [[custom-instrumentation]]
 === Custom instrumentation
 
-When <<introduction,installed>> and <<configuration,properly configured>> ElasticAPM will automatically wrap your app's request/responses in
-transactions and report its errors.
+When <<introduction,installed>> and <<configuration,properly configured>>
+ElasticAPM will automatically wrap your app's request/responses in transactions
+and report its errors.
 It also wraps each background job if you use Sidekiq or DelayedJob.
 
-But it is possible to create your own transactions as well as provide spans for any
-automatic or custom transaction.
+But it is possible to create your own transactions as well as provide spans for
+any automatic or custom transaction.
 
-See <<api-transaction,`ElasticAPM.transaction`>> and <<api-agent-span,`ElasticAPM.span`>>.
+See <<api-agent-start_transaction,`ElasticAPM.start_transaction`>> and
+<<api-agent-start_span,`ElasticAPM.start_span`>>.
 
 [float]
 ==== Helpers
 
-ElasticAPM includes some nifty helpers if you just want to instrument a regular method.
+ElasticAPM includes some nifty helpers if you just want to instrument a regular
+method.
 
 [source,ruby]
 ----
@@ -35,14 +38,14 @@ end
 [float]
 ==== Custom span example
 
-If you are already inside a Transaction (most likely) and you want to intrument
+If you are already inside a Transaction (most likely) and you want to instrument
 some work inside it, add a custom span:
 
 [source,ruby]
 ----
 class ThingsController < ApplicationController
   def index
-    @result_of_work = ElasticAPM.span "Heavy work" do
+    @result_of_work = ElasticAPM.with_span "Heavy work" do
       do_the_heavy_work
     end
   end
@@ -52,40 +55,26 @@ end
 [float]
 ==== Custom transaction example
 
-If you are **not** inside a Transaction already (eg. outside of your common web application)
-start and manage your own transactions like so:
+If you are **not** inside a Transaction already (eg. outside of your common web
+application) start and manage your own transactions like so:
 
 [source,ruby]
 ----
 class Something
   def do_work
-    transaction = ElasticAPM.transaction 'Something#do_work'
+    transaction = ElasticAPM.start_transaction 'Something#do_work'
 
     begin
       Sequel[:users] # many third party libs will be automatically instrumented
-      transaction.submit('success') if transaction
     rescue Exception => e
       ElasticAPM.report(e)
-      transaction.submit('error') if transaction
       raise
     ensure
-      transaction.release
+      ElasticAPM.end_transaction('result')
     end
   end
 end
 ----
 
-**Note:** If the agent isn't started beforehand this will do nothing. See <<api-agent-start,ElasticAPM.start>>.
-
-[[spies]]
-=== Spies
-
-[float]
-====  Automatic integrations with third-party libraries
-
-ElasticAPM has built-in integrations for some popular libraries.
-Use `config.disabled_spies` to disable specific integrations.
-
-For a list of available spies, see
-https://github.com/elastic/apm-agent-ruby/blob/1.x/lib/elastic_apm/config.rb#L174-L188[config.rb].
-
+**Note:** If the agent isn't started beforehand this will do nothing.
+See <<api-agent-start,ElasticAPM.start>>.

data/docs/index.asciidoc

@@ -2,7 +2,8 @@
 include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 
 ifdef::env-github[]
-NOTE: For the best reading experience, please view this documentation at https://www.elastic.co/guide/en/apm/agent/ruby[elastic.co]
+NOTE: For the best reading experience, please view this documentation at
+https://www.elastic.co/guide/en/apm/agent/ruby[elastic.co]
 endif::[]
 
 = APM Ruby Agent Reference
@@ -10,18 +11,23 @@ endif::[]
 [[introduction]]
 == Introduction
 
-The Elastic APM Ruby Agent sends performance metrics and error logs to an Elastic APM Server.
+The Elastic APM Ruby Agent sends performance metrics and error logs to an
+Elastic APM Server.
 
-It has built-in support for <<getting-started-rails,Ruby on Rails>> and other <<getting-started-rack,Rack-compatible>> applications.
+It has built-in support for <<getting-started-rails,Ruby on Rails>> and other
+<<getting-started-rack,Rack-compatible>> applications.
 
-This agent is one of several components you need to get started collecting APM data. See also:
+This agent is one of several components you need to get started collecting APM
+data. See also:
 
  * {apm-server-ref}[APM Server]
 
 [[framework-support]]
-The Elastic APM Ruby Agent officially supports <<getting-started-rails,Ruby on Rails>> versions 4.x on onwards.
+The Elastic APM Ruby Agent officially supports Ruby on Rails versions 4.x on
+onwards, see <<getting-started-rails,Getting started with Ruby on Rails>>.
 
-For Sinatra and other Rack compatible frameworks, see <<getting-started-rack,Getting started with Rack>>.
+For Sinatra and other Rack compatible frameworks, see
+<<getting-started-rack,Getting started with Rack>>.
 
 include::./getting-started-rails.asciidoc[]
 include::./getting-started-rack.asciidoc[]
@@ -31,7 +37,7 @@ include::./configuration.asciidoc[]
 == Advanced Topics
 include::./context.asciidoc[]
 include::./custom-instrumentation.asciidoc[]
-include::./troubleshooting.asciidoc[]
 
+include::./supported-technologies.asciidoc[]
 include::./api.asciidoc[]
 

data/docs/supported-technologies.asciidoc

@@ -0,0 +1,65 @@
+[[supported-technologies]]
+== Supported technologies
+
+The Elastic APM Ruby Agent has built-in support for many frameworks and
+libraries.
+
+Generally we want to support all the most popular libraries, so if your favorite
+is missing feel free so request it in an issue or better yet supply a pull
+request.
+
+[float]
+[[supported-technologies-ruby]]
+=== Ruby
+
+We follow Ruby's own maintenance policy and officially support all currently
+maintained versions per
+https://www.ruby-lang.org/en/downloads/branches/[Ruby Maintenance Branches].
+
+[float]
+[[supported-technologies-web]]
+=== Web Frameworks and Libraries
+
+We have automatic support for Ruby on Rails and all Rack compatible web
+frameworks.
+
+We test against all supported minor versions of Rails and Sinatra.
+
+[float]
+[[supported-technologies-rails]]
+==== Ruby on Rails
+
+We currently support all versions of Rails since 4.2.
+This follows Rails' own https://rubyonrails.org/security/[Security policy].
+
+See <<getting-started-rails>>.
+
+[float]
+[[supported-technologies-sinatra]]
+==== Sinatra
+
+We currently support all versions of Sinatra since 1.0.
+
+See <<getting-started-rack>>.
+
+[float]
+[[supported-technologies-databases]]
+=== Databases
+
+We automatically instrument database actions using:
+
+- ActiveRecord
+- Elasticsearch
+- Mongo
+- Redis
+- Sequel
+
+[float]
+[[supported-technologies-http]]
+=== External HTTP requests
+
+We automatically instrument and add support for distributed tracing to external
+requests using these libraries:
+
+- `net/http`
+- Http.rb

data/elastic-apm.gemspec

@@ -12,13 +12,14 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/elastic/apm-agent-ruby'
   spec.metadata     = { 'source_code_uri' => 'https://github.com/elastic/apm-agent-ruby' }
   spec.license       = 'Apache-2.0'
-  spec.required_ruby_version = ">= 2.2.0"
+  spec.required_ruby_version = ">= 2.3.0"
 
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
 
-  spec.add_dependency('concurrent-ruby', '~> 1.0.0')
+  spec.add_dependency('concurrent-ruby', '~> 1.0')
+  spec.add_dependency('http', '>= 3.0')
 
   spec.require_paths = ['lib']
 end

data/lib/elastic_apm.rb

@@ -1,16 +1,15 @@
 # frozen_string_literal: true
 
 require 'elastic_apm/version'
-require 'elastic_apm/log'
-require 'elastic_apm/util/dig'
+require 'elastic_apm/internal_error'
+require 'elastic_apm/logging'
+require 'elastic_apm/deprecations'
 
 # Core
 require 'elastic_apm/agent'
 require 'elastic_apm/config'
 require 'elastic_apm/context'
 require 'elastic_apm/instrumenter'
-require 'elastic_apm/internal_error'
-require 'elastic_apm/span_helpers'
 require 'elastic_apm/util'
 
 require 'elastic_apm/middleware'
@@ -18,142 +17,294 @@ require 'elastic_apm/middleware'
 require 'elastic_apm/railtie' if defined?(::Rails::Railtie)
 
 # ElasticAPM
-module ElasticAPM
-  ### Life cycle
-
-  # Starts the ElasticAPM Agent
-  #
-  # @param config [Config] An instance of Config
-  # @return [Agent] The resulting [Agent]
-  def self.start(config = {})
-    Agent.start config
-  end
+module ElasticAPM # rubocop:disable Metrics/ModuleLength
+  class << self
+    extend ElasticAPM::Deprecations
 
-  # Stops the ElasticAPM Agent
-  def self.stop
-    Agent.stop
-  end
+    ### Life cycle
 
-  # @return [Boolean] Whether there's an [Agent] running
-  def self.running?
-    Agent.running?
-  end
+    # Starts the ElasticAPM Agent
+    #
+    # @param config [Config] An instance of Config
+    # @return [Agent] The resulting [Agent]
+    def start(config = {})
+      Agent.start config
+    end
 
-  # @return [Agent] Currently running [Agent] if any
-  def self.agent
-    Agent.instance
-  end
+    # Stops the ElasticAPM Agent
+    def stop
+      Agent.stop
+    end
 
-  ### Metrics
+    # @return [Boolean] Whether there's an [Agent] running
+    def running?
+      Agent.running?
+    end
 
-  # Returns the currently active transaction (if any)
-  #
-  # @return [Transaction] if any
-  def self.current_transaction
-    agent && agent.current_transaction
-  end
+    # @return [Agent] Currently running [Agent] if any
+    def agent
+      Agent.instance
+    end
 
-  # Start a new transaction or return the currently running
-  #
-  # @param name [String] A description of the transaction, eg
-  # `ExamplesController#index`
-  # @param type [String] The kind of the transaction, eg `app.request.get` or
-  # `db.mysql2.query`
-  # @param context [Context] An optional [Context]
-  # @yield [Transaction] Optional block encapsulating transaction
-  # @return [Transaction] Unless block given
-  def self.transaction(name = nil, type = nil, context: nil, &block)
-    return (block_given? ? yield : nil) unless agent
-
-    agent.transaction(name, type, context: context, &block)
-  end
+    ### Metrics
+
+    # Returns the currently active transaction (if any)
+    #
+    # @return [Transaction] or `nil`
+    def current_transaction
+      agent&.current_transaction
+    end
+
+    # Returns the currently active span (if any)
+    #
+    # @return [Span] or `nil`
+    def current_span
+      agent&.current_span
+    end
+
+    # Start a new transaction or return the currently running
+    #
+    # @param name [String] A description of the transaction, eg
+    # `ExamplesController#index`
+    # @param type [String] The kind of the transaction, eg `app.request.get` or
+    # `db.mysql2.query`
+    # @param context [Context] An optional [Context]
+    # @yield [Transaction] Optional block encapsulating transaction
+    # @return [Transaction] Unless block given
+    # @deprecated See `with_transaction` or `start_transaction`
+    def transaction(name = nil, type = nil, context: nil, &block)
+      return (block_given? ? yield : nil) unless agent
+
+      if block_given?
+        with_transaction(name, type, context: context, &block)
+      else
+        start_transaction(name, type, context: context)
+      end
+    end
+
+    deprecate :transaction, :with_transaction
+
+    # Start a new transaction
+    #
+    # @param name [String] A description of the transaction, eg
+    # `ExamplesController#index`
+    # @param type [String] The kind of the transaction, eg `app.request.get` or
+    # `db.mysql2.query`
+    # @param context [Context] An optional [Context]
+    # @return [Transaction]
+    def start_transaction(
+      name = nil,
+      type = nil,
+      context: nil,
+      traceparent: nil
+    )
+      agent&.start_transaction(
+        name,
+        type,
+        context: context,
+        traceparent: traceparent
+      )
+    end
+
+    # Ends the current transaction with `result`
+    #
+    # @param result [String] The result of the transaction
+    # @return [Transaction]
+    def end_transaction(result = nil)
+      agent&.end_transaction(result)
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    # Wrap a block in a Transaction, ending it after the block
+    #
+    # @param name [String] A description of the transaction, eg
+    # `ExamplesController#index`
+    # @param type [String] The kind of the transaction, eg `app.request.get` or
+    # `db.mysql2.query`
+    # @param context [Context] An optional [Context]
+    # @yield [Transaction]
+    # @return result of block
+    def with_transaction(name = nil, type = nil, context: nil, traceparent: nil)
+      unless block_given?
+        raise ArgumentError,
+          'expected a block. Do you want `start_transaction\' instead?'
+      end
+
+      return yield(nil) unless agent
 
-  # Starts a new span under the current Transaction
-  #
-  # @param name [String] A description of the span, eq `SELECT FROM "users"`
-  # @param type [String] The kind of span, eq `db.mysql2.query`
-  # @param context [Span::Context] Context information about the span
-  # @yield [Span] Optional block encapsulating span
-  # @return [Span] Unless block given
-  def self.span(name, type = nil, context: nil, include_stacktrace: true,
-    &block)
-    return (block_given? ? yield : nil) unless agent
-
-    agent.span(
+      begin
+        transaction =
+          start_transaction(
+            name,
+            type,
+            context: context,
+            traceparent: traceparent
+          )
+        yield transaction
+      ensure
+        end_transaction
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    # rubocop:disable Metrics/MethodLength
+    # Start a new span
+    #
+    # @param name [String] A description of the span, eq `SELECT FROM "users"`
+    # @param type [String] The kind of span, eq `db.mysql2.query`
+    # @param context [Span::Context] Context information about the span
+    # @yield [Span] Optional block encapsulating span
+    # @return [Span] Unless block given
+    # @deprecated See `with_span` or `start_span`
+    def span(name, type = nil, context: nil, include_stacktrace: true, &block)
+      return (block_given? ? yield : nil) unless agent
+
+      if block_given?
+        with_span(
+          name,
+          type,
+          context:
+          context,
+          include_stacktrace: include_stacktrace,
+          &block
+        )
+      else
+        start_span(
+          name,
+          type,
+          context: context,
+          include_stacktrace: include_stacktrace
+        )
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    deprecate :span, :with_span
+
+    # Start a new span
+    #
+    # @param name [String] A description of the span, eq `SELECT FROM "users"`
+    # @param type [String] The kind of span, eq `db.mysql2.query`
+    # @param context [Span::Context] Context information about the span
+    # @param include_stacktrace [Boolean] Whether or not to capture a stacktrace
+    # @return [Span]
+    def start_span(name, type = nil, context: nil, include_stacktrace: true)
+      agent&.start_span(
+        name,
+        type,
+        context: context,
+        backtrace: include_stacktrace ? caller : nil
+      )
+    end
+
+    # Ends the current span
+    #
+    # @return [Span]
+    def end_span
+      agent&.end_span
+    end
+
+    # rubocop:disable Metrics/MethodLength
+    # Wrap a block in a Span, ending it after the block
+    #
+    # @param name [String] A description of the span, eq `SELECT FROM "users"`
+    # @param type [String] The kind of span, eq `db.mysql2.query`
+    # @param context [Span::Context] Context information about the span
+    # @param include_stacktrace [Boolean] Whether or not to capture a stacktrace
+    # @yield [Span]
+    # @return Result of block
+    def with_span(
       name,
-      type,
-      context: context,
-      backtrace: include_stacktrace ? caller : nil,
-      &block
+      type = nil,
+      context: nil,
+      include_stacktrace: true
     )
-  end
+      unless block_given?
+        raise ArgumentError,
+          'expected a block. Do you want `start_span\' instead?'
+      end
 
-  # Build a [Context] from a Rack `env`. The context may include information
-  # about the request, response, current user and more
-  #
-  # @param rack_env [Rack::Env] A Rack env
-  # @return [Context] The built context
-  def self.build_context(rack_env)
-    agent && agent.build_context(rack_env)
-  end
+      return yield nil unless agent
+
+      begin
+        span =
+          start_span(
+            name, type, context: context, include_stacktrace: include_stacktrace
+          )
+        yield span
+      ensure
+        end_span
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
 
-  ### Errors
+    # Build a [Context] from a Rack `env`. The context may include information
+    # about the request, response, current user and more
+    #
+    # @param rack_env [Rack::Env] A Rack env
+    # @return [Context] The built context
+    def build_context(rack_env)
+      agent&.build_context(rack_env)
+    end
 
-  # Report and exception to APM
-  #
-  # @param exception [Exception] The exception
-  # @param handled [Boolean] Whether the exception was rescued
-  # @return [Error] The generated [Error]
-  def self.report(exception, handled: true)
-    agent && agent.report(exception, handled: handled)
-  end
+    ### Errors
 
-  # Report a custom string error message to APM
-  #
-  # @param message [String] The message
-  # @return [Error] The generated [Error]
-  def self.report_message(message, **attrs)
-    agent && agent.report_message(message, backtrace: caller, **attrs)
-  end
+    # Report and exception to APM
+    #
+    # @param exception [Exception] The exception
+    # @param handled [Boolean] Whether the exception was rescued
+    # @return [Error] The generated [Error]
+    def report(exception, handled: true)
+      agent&.report(exception, handled: handled)
+    end
 
-  ### Context
+    # Report a custom string error message to APM
+    #
+    # @param message [String] The message
+    # @return [Error] The generated [Error]
+    def report_message(message, **attrs)
+      agent&.report_message(message, backtrace: caller, **attrs)
+    end
 
-  # Set a _tag_ value for the current transaction
-  #
-  # @param key [String,Symbol] A key
-  # @param value [Object] A value (will be converted to string)
-  # @return [Object] The given value
-  def self.set_tag(key, value)
-    agent && agent.set_tag(key, value)
-  end
+    ### Context
 
-  # Provide further context for the current transaction
-  #
-  # @param custom [Hash] A hash with custom information. Can be nested.
-  # @return [Hash] The current custom context
-  def self.set_custom_context(custom)
-    agent && agent.set_custom_context(custom)
-  end
+    # Set a _tag_ value for the current transaction
+    #
+    # @param key [String,Symbol] A key
+    # @param value [Object] A value (will be converted to string)
+    # @return [Object] The given value
+    def set_tag(key, value)
+      agent&.set_tag(key, value)
+    end
 
-  # Provide a user to the current transaction
-  #
-  # @param user [Object] An object representing a user
-  # @return [Object] Given user
-  def self.set_user(user)
-    agent && agent.set_user(user)
-  end
+    # Provide further context for the current transaction
+    #
+    # @param custom [Hash] A hash with custom information. Can be nested.
+    # @return [Hash] The current custom context
+    def set_custom_context(custom)
+      agent&.set_custom_context(custom)
+    end
 
-  # Provide a filter to transform payloads before sending them off
-  #
-  # @param key [Symbol] Unique filter key
-  # @param callback [Object, Proc] A filter that responds to #call(payload)
-  # @yield [Hash] A filter. Will be used if provided. Otherwise using `callback`
-  # @return [Bool] true
-  def self.add_filter(key, callback = nil, &block)
-    if callback.nil? && !block_given?
-      raise ArgumentError, '#add_filter needs either `callback\' or a block'
+    # Provide a user to the current transaction
+    #
+    # @param user [Object] An object representing a user
+    # @return [Object] Given user
+    def set_user(user)
+      agent&.set_user(user)
     end
 
-    agent && agent.add_filter(key, block || callback)
+    # Provide a filter to transform payloads before sending them off
+    #
+    # @param key [Symbol] Unique filter key
+    # @param callback [Object, Proc] A filter that responds to #call(payload)
+    # @yield [Hash] A filter. Used if provided. Otherwise using `callback`
+    # @return [Bool] true
+    def add_filter(key, callback = nil, &block)
+      if callback.nil? && !block_given?
+        raise ArgumentError, '#add_filter needs either `callback\' or a block'
+      end
+
+      agent&.add_filter(key, block || callback)
+    end
   end
 end