elastic-apm 3.0.0 → 3.1.0

data/docs/custom-instrumentation.asciidoc

@@ -1,12 +1,12 @@
 [[custom-instrumentation]]
 === Custom instrumentation
 
-When <<introduction,installed>> and <<configuration,properly configured>>
+When installed and 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
+But it is also possible to create your own transactions as well as provide spans for
 any automatic or custom transaction.
 
 See <<api-agent-start_transaction,`ElasticAPM.start_transaction`>> and

data/docs/debugging.asciidoc

@@ -1,5 +1,5 @@
 [[debugging]]
-== Debugging the agent itself
+== Troubleshooting
 
 Hopefully the agent Just Works™, but depending on your situation the agent might need some tuning.
 

data/docs/getting-started-rack.asciidoc

@@ -5,7 +5,7 @@ https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html[elastic
 endif::[]
 
 [[getting-started-rack]]
-== Getting started with Rack
+=== Getting started with Rack
 
 Add the gem to your `Gemfile`:
 
@@ -64,6 +64,9 @@ end
 # Takes optional ElasticAPM::Config values
 ElasticAPM.start(app: MySinatraApp, ...)
 
+# You can also do the following, which is equivalent to the above:
+# ElasticAPM::Sinatra.start(MySinatraApp, ...)
+
 run MySinatraApp
 
 at_exit { ElasticAPM.stop }

data/docs/getting-started-rails.asciidoc

@@ -5,10 +5,10 @@ https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html[elastic
 endif::[]
 
 [[getting-started-rails]]
-== Getting started with Rails
+=== Getting started with Rails
 
 [float]
-=== Setup
+==== Setup
 
 Add the gem to your `Gemfile`:
 

data/docs/index.asciidoc

@@ -1,5 +1,4 @@
-:branch: current
-:server-branch: 6.5
+include::{asciidoc-dir}/../../shared/versions/stack/current.asciidoc[]
 include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 
 ifdef::env-github[]
@@ -12,21 +11,21 @@ endif::[]
 
 include::./introduction.asciidoc[]
 
-include::./getting-started-rails.asciidoc[]
+include::./set-up.asciidoc[]
 
-include::./getting-started-rack.asciidoc[]
+include::./supported-technologies.asciidoc[]
 
 include::./configuration.asciidoc[]
 
-include::./log-correlation.asciidoc[]
+include::./advanced.asciidoc[]
 
-include::./metrics.asciidoc[]
+include::./api.asciidoc[]
 
-include::./advanced.asciidoc[]
+include::./metrics.asciidoc[]
 
-include::./supported-technologies.asciidoc[]
+include::./opentracing.asciidoc[]
 
-include::./api.asciidoc[]
+include::./log-correlation.asciidoc[]
 
 include::./debugging.asciidoc[]
 

data/docs/introduction.asciidoc

@@ -5,15 +5,27 @@ https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html[elastic
 endif::[]
 
 [[introduction]]
-
 == Introduction
 
-Welcome to the APM Ruby Agent documentation.
-
-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 the APM Server.
 It has built-in support for <<getting-started-rails,Ruby on Rails>> and other
 <<getting-started-rack,Rack-compatible>> applications.
+It also offers an API which allows you to instrument any application.
+
+[float]
+[[how-it-works]]
+=== How does the Agent work?
+
+The agent auto-instruments <<supported-technologies,supported technologies>> and records interesting events,
+like HTTP requests and database queries. To do this, it uses relevant public APIs when they are provided by the libraries. Otherwise, it carefully wraps the necessary internal methods.
+This means that for the supported technologies, there are no code changes required.
+
+The Agent automatically keeps track of queries to your data stores to measure their duration and metadata (like the DB statement),
+as well as HTTP related information (like the URL, parameters, and headers).
+
+These events, called Transactions and Spans, are sent to the APM Server.
+The APM Server converts them to a format suitable for Elasticsearch, and sends them to an Elasticsearch cluster.
+You can then use the APM app in Kibana to gain insight into latency issues and error culprits within your application.
 
 [float]
 [[additional-components]]
@@ -21,13 +33,3 @@ It has built-in support for <<getting-started-rails,Ruby on Rails>> and other
 
 APM Agents work in conjunction with the {apm-server-ref-v}/index.html[APM Server], {ref}/index.html[Elasticsearch], and {kibana-ref}/index.html[Kibana].
 Please view the {apm-overview-ref-v}/index.html[APM Overview] for details on how these components work together. 
-
-[float]
-[[framework-support]]
-=== Framework Support
-
-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>>.

data/docs/opentracing.asciidoc

@@ -4,7 +4,7 @@ please view this documentation at https://www.elastic.co/guide/en/apm/agent/ruby
 endif::[]
 
 [[opentracing]]
-=== OpenTracing bridge
+== OpenTracing API
 
 The Elastic APM OpenTracing bridge allows to create Elastic APM `Transactions` and `Spans`,
 using the OpenTracing API.
@@ -16,7 +16,7 @@ subsequent spans are mapped to Elastic APM `Span`.
 
 [float]
 [[operation-modes]]
-=== Operation Modes
+== Operation Modes
 
 This bridge allows for different operation modes in combination with the Elastic APM Agent.
 
@@ -34,12 +34,12 @@ This bridge allows for different operation modes in combination with the Elastic
 
 [float]
 [[getting-started]]
-=== Getting started
+== Getting started
 Either `require 'elastic_apm/opentracing'` during the boot of your app or specify the `require:` argument to your `Gemfile`, eg. `gem 'elastic_apm', require: 'elastic_apm/opentracing'`.
 
 [float]
 [[init-tracer]]
-=== Set Elastic APM as the global tracer
+== Set Elastic APM as the global tracer
 
 [source,ruby]
 ----
@@ -48,47 +48,47 @@ Either `require 'elastic_apm/opentracing'` during the boot of your app or specif
 
 [float]
 [[elastic-apm-tags]]
-=== Elastic APM specific tags
+== Elastic APM specific tags
 
 Elastic APM defines some tags which are not included in the OpenTracing API but are relevant in the context of Elastic APM.
 
 - `type` - sets the type of the transaction,
   for example `request`, `ext` or `db`
 - `user.id` - sets the user id,
-  appears in the "User" tab in the transaction details in the Elastic APM UI
+  appears in the "User" tab in the transaction details in the Elastic APM app
 - `user.email` - sets the user email,
-  appears in the "User" tab in the transaction details in the Elastic APM UI
+  appears in the "User" tab in the transaction details in the Elastic APM app
 - `user.username` - sets the user name,
-  appears in the "User" tab in the transaction details in the Elastic APM UI
+  appears in the "User" tab in the transaction details in the Elastic APM app
 - `result` - sets the result of the transaction. Overrides the default value of `success`.
   If the `error` tag is set to `true`, the default value is `error`.
 
 [float]
 [[unsupported]]
-=== Caveats
+== Caveats
 Not all features of the OpenTracing API are supported.
 
 [float]
 [[propagation]]
-==== Context propagation
+=== Context propagation
 This bridge only supports the format `OpenTracing::FORMAT_RACK`, using HTTP headers with capitalized names, prefixed with `HTTP_` as Rack does it.
 
 `OpenTracing::FORMAT_BINARY` is currently not supported.
 
 [float]
 [[references]]
-==== Span References
+=== Span References
 Currently, this bridge only supports `child_of` references.
 Other references,
 like `follows_from` are not supported yet.
 
 [float]
 [[baggage]]
-==== Baggage
+=== Baggage
 The `Span.set_baggage` method is not supported.
 Baggage items are dropped with a warning log message.
 
 [float]
 [[logs]]
-==== Logs
+=== Logs
 Logs are currently not supported.

data/docs/release-notes.asciidoc

@@ -1,4 +1,14 @@
+:pull: https://github.com/elastic/apm-server/pull/
+
 [[release-notes]]
 == Release notes
 
-Release notes are published in the https://github.com/elastic/apm-agent-ruby/blob/master/CHANGELOG.md[changelog].
+All notable changes to this project will be documented here.
+This project adheres to http://semver.org/spec/v2.0.0.html[Semantic Versioning].
+
+* <<release-notes-3.x>>
+* <<release-notes-2.x>>
+* <<release-notes-1.x>>
+* <<release-notes-0.x>>
+
+include::../CHANGELOG.asciidoc[]

data/docs/set-up.asciidoc

@@ -0,0 +1,16 @@
+ifdef::env-github[]
+NOTE: For the best reading experience,
+please view this documentation at
+https://www.elastic.co/guide/en/apm/agent/ruby/current/set-up.html[elastic.co]
+endif::[]
+
+[[set-up]]
+== Set up the Agent
+
+To get you off the ground, we’ve prepared guides for setting up the Agent with different frameworks:
+
+include::./getting-started-rails.asciidoc[]
+
+include::./getting-started-rack.asciidoc[]
+
+For custom instrumentation, see the <<api>>.

data/docs/supported-technologies.asciidoc

@@ -7,10 +7,8 @@ endif::[]
 == 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
+libraries. Generally, we want to support all of the most popular libraries. If your favorite
+is missing, feel free to request it in an issue, or better yet, create a pull
 request.
 
 [float]

data/lib/elastic_apm.rb

@@ -14,6 +14,7 @@ require 'elastic_apm/util'
 require 'elastic_apm/middleware'
 
 require 'elastic_apm/railtie' if defined?(::Rails::Railtie)
+require 'elastic_apm/sinatra' if defined?(::Sinatra)
 
 # ElasticAPM
 module ElasticAPM # rubocop:disable Metrics/ModuleLength
@@ -80,7 +81,6 @@ module ElasticAPM # rubocop:disable Metrics/ModuleLength
     end
     # rubocop:enable Metrics/AbcSize
 
-    # rubocop:disable Metrics/MethodLength
     # Start a new transaction
     #
     # @param name [String] A description of the transaction, eg
@@ -102,7 +102,6 @@ module ElasticAPM # rubocop:disable Metrics/ModuleLength
         trace_context: trace_context
       )
     end
-    # rubocop:enable Metrics/MethodLength
 
     # Ends the current transaction with `result`
     #
@@ -150,6 +149,7 @@ module ElasticAPM # rubocop:disable Metrics/ModuleLength
     end
     # rubocop:enable Metrics/MethodLength
 
+    # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
     # Start a new span
     #
     # @param name [String] A description of the span, eq `SELECT FROM "users"`

data/lib/elastic_apm/agent.rb

@@ -17,6 +17,7 @@ module ElasticAPM
   # @api private
   class Agent
     include Logging
+    extend Forwardable
 
     LOCK = Mutex.new
 
@@ -61,10 +62,7 @@ module ElasticAPM
       !!@instance
     end
 
-    # rubocop:disable Metrics/MethodLength
     def initialize(config)
-      @config = config
-
       @stacktrace_builder = StacktraceBuilder.new(config)
       @context_builder = ContextBuilder.new(config)
       @error_builder = ErrorBuilder.new(self)
@@ -77,7 +75,6 @@ module ElasticAPM
       ) { |event| enqueue event }
       @metrics = Metrics.new(config) { |event| enqueue event }
     end
-    # rubocop:enable Metrics/MethodLength
 
     attr_reader(
       :central_config,
@@ -90,6 +87,8 @@ module ElasticAPM
       :transport
     )
 
+    def_delegator :@central_config, :config
+
     # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def start
       unless config.disable_start_message
@@ -150,6 +149,7 @@ module ElasticAPM
       instrumenter.start_transaction(
         name,
         type,
+        config: config,
         context: context,
         trace_context: trace_context
       )

data/lib/elastic_apm/central_config.rb

@@ -81,11 +81,15 @@ module ElasticAPM
         update[key] = @modified_options.delete(key)
       end
 
-      config.assign(update)
+      update_config(update)
     end
 
     private
 
+    def update_config(new_options)
+      @config = config.dup.tap { |new_config| new_config.assign(new_options) }
+    end
+
     # rubocop:disable Metrics/MethodLength
     def handle_success(resp)
       if resp.status == 304
@@ -107,7 +111,7 @@ module ElasticAPM
     # rubocop:enable Metrics/MethodLength
 
     def handle_error(error)
-      error(
+      debug(
         'Failed fetching config: %s, trying again in %d seconds',
         error.response.body, DEFAULT_MAX_AGE
       )
@@ -119,7 +123,7 @@ module ElasticAPM
 
     def perform_request
       Http.post(
-        config.server_url + '/agent/v1/config/',
+        config.server_url + '/config/v1/agents',
         body: @service_info,
         headers: { etag: 1, content_type: 'application/json' }
       )

data/lib/elastic_apm/config.rb

@@ -21,7 +21,7 @@ module ElasticAPM
 
     # rubocop:disable Metrics/LineLength, Layout/ExtraSpacing
     option :config_file,                       type: :string, default: 'config/elastic_apm.yml'
-    option :server_url,                        type: :string, default: 'http://localhost:8200'
+    option :server_url,                        type: :url,    default: 'http://localhost:8200'
     option :secret_token,                      type: :string
 
     option :active,                            type: :bool,   default: true
@@ -215,7 +215,7 @@ module ElasticAPM
     def set_sinatra(app)
       self.service_name = format_name(service_name || app.to_s)
       self.framework_name = framework_name || 'Sinatra'
-      self.framework_version = framework_version || Sinatra::VERSION
+      self.framework_version = framework_version || ::Sinatra::VERSION
       self.__root_path = Dir.pwd
     end
 

data/lib/elastic_apm/config/options.rb

@@ -48,6 +48,7 @@ module ElasticAPM
           when :bool then normalize_bool(val)
           when :list then normalize_list(val)
           when :dict then normalize_dict(val)
+          when :url then normalize_url(val)
           else
             # raise "Unknown options type '#{type.inspect}'"
             val
@@ -69,6 +70,11 @@ module ElasticAPM
           return val unless val.is_a?(String)
           Hash[val.split(/[&,]/).map { |kv| kv.split('=') }]
         end
+
+        def normalize_url(val)
+          val = val.to_s
+          val.end_with?('/') ? val.chomp('/') : val
+        end
       end
 
       # @api private

data/lib/elastic_apm/context.rb

@@ -9,25 +9,39 @@ require 'elastic_apm/context/user'
 module ElasticAPM
   # @api private
   class Context
-    def initialize(custom: {}, labels: {}, user: nil)
+    def initialize(custom: {}, labels: {}, user: nil, service: nil)
       @custom = custom
       @labels = labels
       @user = user || User.new
+      @service = service
     end
 
+    Service = Struct.new(:framework)
+    Framework = Struct.new(:name, :version)
+
     attr_accessor :request
     attr_accessor :response
     attr_accessor :user
     attr_reader :custom
     attr_reader :labels
+    attr_reader :service
 
+    # rubocop:disable Metrics/CyclomaticComplexity
     def empty?
       return false if labels.any?
       return false if custom.any?
       return false if user.any?
+      return false if service
       return false if request || response
 
       true
     end
+    # rubocop:enable Metrics/CyclomaticComplexity
+
+    def set_service(framework_name: nil, framework_version: nil)
+      @service = Service.new(
+        Framework.new(framework_name, framework_version)
+      )
+    end
   end
 end