elastic-apm 2.1.2 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7026cd778a6226802c4bb0b0c384b67c86df3a60430a4283f7b48f45da16e8a6
-  data.tar.gz: c415bff2b4c720a3a5b981a27c1ca91500233be95d6f1a73c6bb46ba5d2e2344
+  metadata.gz: 556f800e5882b54fe89a4249a6ca5ce98bdfe04b9148f813b75ff17087834c70
+  data.tar.gz: 073241c2a7c78fbebd32434791339a321548e12de242f72598bc11c9bda833b2
 SHA512:
-  metadata.gz: 6e6db8df5ab8e2d7313813b3ca4524c8b32a11e9fe14940cb6d7b55483847015b0716bd760124be452ff4d17708a926edd242f715ab887820a5e0f24eb85d4ac
-  data.tar.gz: 7a9e88ef324250a4715b7e60e7c5f32256eea3965556a3b77535c6bd6673dce72c3f8fea92dac321976f1a75ee81ab4174d4502b9655ddfcecabb114f518ee83
+  metadata.gz: b53f5c630ce8313593d4ecb0485d48bd3d552e672217409ce2cef9366aa06f881e633108c421d670b77df050fb2069eab09cb5b297a89a977ba0a7fcbe22b5e1
+  data.tar.gz: 7216c6d7628565b4e7295267ebba268461d693edecc5806fd83a92e9d2917aaf77ee075c0bcca20e0f67fdd9a90b3068d4fdabe5ddebbaa2a50353fd0a102169

data/.rubocop.yml

@@ -63,5 +63,11 @@ Rails/Delegate:
 Style/NumericPredicate:
   Enabled: false
 
+Style/PerlBackrefs:
+  Enabled: false
+
 Layout/EmptyLineAfterGuardClause:
   Enabled: false
+
+Naming/MemoizedInstanceVariableName:
+  Enabled: false

data/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to this project will be documented in this file.
 
 This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## 2.2.0 (2019-01-22)
+
+### Added
+
+- Support for [OpenTracing](https://opentracing.io) ([#273](https://github.com/elastic/apm-agent-ruby/pull/273))
+- Add capture_* options ([#279](https://github.com/elastic/apm-agent-ruby/pull/279))
+- Evaluate the config file as ERB ([#288](https://github.com/elastic/apm-agent-ruby/pull/288))
+
+### Changed
+
+- Rename `Traceparent` object to `TraceContext` ([#271](https://github.com/elastic/apm-agent-ruby/pull/271))
+
+### Fixed
+
+- An issue where Spans would not get Stacktraces attached ([#282](https://github.com/elastic/apm-agent-ruby/pull/282))
+- Skip `caller` unless needed ([#287](https://github.com/elastic/apm-agent-ruby/pull/283))
+
 ## 2.1.2 (2018-12-07)
 
 ### Fixed

data/Gemfile

@@ -18,6 +18,7 @@ gem 'elasticsearch', require: nil
 gem 'fakeredis', require: nil
 gem 'json-schema', require: nil
 gem 'mongo', require: nil
+gem 'opentracing', require: nil
 gem 'rake', require: nil
 gem 'sequel', require: nil
 gem 'sidekiq', require: nil

data/docs/advanced.asciidoc

@@ -1,8 +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/introduction.html[elastic.co]
+endif::[]
+
 [[advanced]]
 == Advanced Topics
 
 * <<context>>
 * <<custom-instrumentation>>
+* <<opentracing>>
 
 include::./context.asciidoc[]
-include::./custom-instrumentation.asciidoc[]
+include::./custom-instrumentation.asciidoc[]
+include::./opentracing.asciidoc[]

data/docs/api.asciidoc

@@ -1,3 +1,9 @@
+ifdef::env-github[]
+NOTE: For the best reading experience,
+please view this documentation at
+https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html[elastic.co]
+endif::[]
+
 [[api]]
 == Public API
 
@@ -76,7 +82,7 @@ Arguments:
   * `type`: A `type` for your transaction eg. `db.postgresql.sql`.
   * `context:`: An optional <<api-context,Context>> used to enrich the
   transaction with information about the current request.
-  * `traceparent:`: An optional `Traceparent` object for Distributed Tracing.
+  * `trace_context:`: An optional `TraceContext` object for Distributed Tracing.
 
 Returns the transaction.
 
@@ -111,7 +117,7 @@ Arguments:
   * `type`: A `type` for your transaction eg. `db.postgresql.sql`.
   * `context:`: An optional <<api-context,Context>> used to enrich the
   transaction with information about the current request.
-  * `traceparent:`: An optional `Traceparent` object for Distributed Tracing.
+  * `trace_context:`: An optional `TraceContext` object for Distributed Tracing.
   * `&block`: A block to wrap. Optionally yields the transaction.
 
 Returns the return value of the given block.

data/docs/configuration.asciidoc

@@ -1,3 +1,9 @@
+ifdef::env-github[]
+NOTE: For the best reading experience,
+please view this documentation at
+https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html[elastic.co]
+endif::[]
+
 [[configuration]]
 == Configuration
 
@@ -10,7 +16,7 @@ The recommended way to configure Elastic APM is to create a file
 ----
 ---
 server_url: 'http://localhost:8200'
-secret_token: 'very_very_secret'
+secret_token: <%= ENV["VERY_SECRET_TOKEN"] %>
 ----
 
 Options are applied in the following order (last one wins):
@@ -70,6 +76,13 @@ eg `ELASTIC_APM_ENABLED_ENVIRONMENTS=development,production`.
 
 Path to the configuration YAML-file.
 Elastic APM will load config options from this if the file exists.
+The file will be evaluated as ERB, so you can include `ENV` variables like in
+your `database.yml`, eg:
+
+[source,ruby]
+----
+secret_token: <%= ENV['VERY_SECRET_TOKEN'] %>
+----
 
 [float]
 [[config-server-url]]
@@ -149,6 +162,36 @@ APM Server has its own limit of 30 seconds before it will close requests.
 
 It has to be provided in *<<config-format-duration, duration format>>*.
 
+[float]
+[[config-capture-body]]
+==== `capture_body`
+|============
+| Environment                | `Config` key   | Default
+| `ELASTIC_APM_CAPTURE_BODY` | `capture_body` | `true`
+|============
+
+Whether or not to attach the request body to transactions and errors.
+
+[float]
+[[config-capture-headers]]
+==== `capture_headers`
+|============
+| Environment                   | `Config` key      | Default
+| `ELASTIC_APM_CAPTURE_HEADERS` | `capture_headers` | `true`
+|============
+
+Whether or not to attach the request headers to transactions and errors.
+
+[float]
+[[config-capture-env]]
+==== `capture_env`
+|============
+| Environment               | `Config` key  | Default
+| `ELASTIC_APM_CAPTURE_ENV` | `capture_env` | `true`
+|============
+
+Whether or not to attach `ENV` from Rack to transactions and errors.
+
 [float]
 [[config-custom-key-filters]]
 ==== `custom_key_filters`

data/docs/getting-started-rack.asciidoc

@@ -1,3 +1,9 @@
+ifdef::env-github[]
+NOTE: For the best reading experience,
+please view this documentation at
+https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html[elastic.co]
+endif::[]
+
 [[getting-started-rack]]
 == Getting started with Rack
 

data/docs/getting-started-rails.asciidoc

@@ -1,3 +1,9 @@
+ifdef::env-github[]
+NOTE: For the best reading experience,
+please view this documentation at
+https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html[elastic.co]
+endif::[]
+
 [[getting-started-rails]]
 == Getting started with Rails
 

data/docs/index.asciidoc

@@ -1,4 +1,5 @@
 :branch: current
+:server-branch: 6.5
 include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
 
 ifdef::env-github[]

data/docs/introduction.asciidoc

@@ -1,11 +1,11 @@
-[[introduction]]
-
 ifdef::env-github[]
 NOTE: For the best reading experience,
 please view this documentation at
 https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html[elastic.co]
 endif::[]
 
+[[introduction]]
+
 == Introduction
 
 Welcome to the APM Ruby Agent documentation.
@@ -19,8 +19,8 @@ It has built-in support for <<getting-started-rails,Ruby on Rails>> and other
 [[additional-components]]
 === Additional Components
 
-APM Agents work in conjunction with the {apm-server-ref}/index.html[APM Server], {ref}/index.html[Elasticsearch], and {kibana-ref}/index.html[Kibana].
-Please view the {apm-get-started-ref}/index.html[APM Overview] for details on how these components work together. 
+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]]
@@ -30,4 +30,4 @@ 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>>.
+<<getting-started-rack,Getting started with Rack>>.

data/docs/opentracing.asciidoc

@@ -0,0 +1,94 @@
+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]
+endif::[]
+
+[[opentracing]]
+=== OpenTracing bridge
+
+The Elastic APM OpenTracing bridge allows to create Elastic APM `Transactions` and `Spans`,
+using the OpenTracing API.
+In other words,
+it translates the calls to the OpenTracing API to Elastic APM and thus allows for reusing existing instrumentation.
+
+The first span of a service will be converted to an Elastic APM `Transaction`,
+subsequent spans are mapped to Elastic APM `Span`.
+
+[float]
+[[operation-modes]]
+=== Operation Modes
+
+This bridge allows for different operation modes in combination with the Elastic APM Agent.
+
+- Noop +
+  If no Elastic APM agent is running, the bridge is in noop mode and does not actually record and report spans.
+- Mix and Match +
+  If you want to leverage the auto instrumentation of Elastic APM,
+  but also want do create custom spans or use the OpenTracing API to add custom tags to the spans created by Elastic APM,
+  you can just do that.
+  The OpenTracing bridge and the standard Elastic APM API interact seamlessly.
+- Manual instrumentation +
+  If you don't want Elastic APM to auto-instrument known frameworks,
+  but instead only rely on manual instrumentation,
+  disable the auto instrumentation setting the configuration option <<config-instrument,`instrument`>> to `false`.
+
+[float]
+[[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
+
+[source,ruby]
+----
+::OpenTracing.global_tracer = ElasticAPM::OpenTracing::Tracer.new
+----
+
+[float]
+[[elastic-apm-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
+- `user.email` - sets the user email,
+  appears in the "User" tab in the transaction details in the Elastic APM UI
+- `user.username` - sets the user name,
+  appears in the "User" tab in the transaction details in the Elastic APM UI
+- `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
+Not all features of the OpenTracing API are supported.
+
+[float]
+[[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
+Currently, this bridge only supports `child_of` references.
+Other references,
+like `follows_from` are not supported yet.
+
+[float]
+[[baggage]]
+==== Baggage
+The `Span.set_baggage` method is not supported.
+Baggage items are dropped with a warning log message.
+
+[float]
+[[logs]]
+==== Logs
+Logs are currently not supported.

data/docs/supported-technologies.asciidoc

@@ -1,3 +1,8 @@
+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]
+endif::[]
+
 [[supported-technologies]]
 == Supported technologies
 

data/lib/elastic_apm.rb

@@ -84,6 +84,7 @@ module ElasticAPM # rubocop:disable Metrics/ModuleLength
 
     deprecate :transaction, :with_transaction
 
+    # rubocop:disable Metrics/MethodLength
     # Start a new transaction
     #
     # @param name [String] A description of the transaction, eg
@@ -96,15 +97,23 @@ module ElasticAPM # rubocop:disable Metrics/ModuleLength
       name = nil,
       type = nil,
       context: nil,
+      trace_context: nil,
       traceparent: nil
     )
+      if traceparent
+        trace_context ||= traceparent
+        warn "[ElasticAPM] [DEPRECATED] `start_transaction' with" \
+          "`traceparent:' has been renamed. Use `trace_context:' instead."
+      end
+
       agent&.start_transaction(
         name,
         type,
         context: context,
-        traceparent: traceparent
+        trace_context: trace_context
       )
     end
+    # rubocop:enable Metrics/MethodLength
 
     # Ends the current transaction with `result`
     #
@@ -124,12 +133,24 @@ module ElasticAPM # rubocop:disable Metrics/ModuleLength
     # @param context [Context] An optional [Context]
     # @yield [Transaction]
     # @return result of block
-    def with_transaction(name = nil, type = nil, context: nil, traceparent: nil)
+    def with_transaction(
+      name = nil,
+      type = nil,
+      context: nil,
+      trace_context: nil,
+      traceparent: nil
+    )
       unless block_given?
         raise ArgumentError,
           'expected a block. Do you want `start_transaction\' instead?'
       end
 
+      if traceparent
+        trace_context ||= traceparent
+        warn "[ElasticAPM] [DEPRECATED] `with_transaction' with " \
+          "`traceparent:' has been renamed. Use `trace_context:' instead."
+      end
+
       return yield(nil) unless agent
 
       begin
@@ -138,7 +159,7 @@ module ElasticAPM # rubocop:disable Metrics/ModuleLength
             name,
             type,
             context: context,
-            traceparent: traceparent
+            trace_context: trace_context
           )
         yield transaction
       ensure
@@ -156,15 +177,20 @@ module ElasticAPM # rubocop:disable Metrics/ModuleLength
     # @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)
+    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,
+          context: context,
           include_stacktrace: include_stacktrace,
           &block
         )
@@ -188,13 +214,24 @@ module ElasticAPM # rubocop:disable Metrics/ModuleLength
     # @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)
+    def start_span(
+      name,
+      type = nil,
+      context: nil,
+      include_stacktrace: true,
+      trace_context: nil
+    )
       agent&.start_span(
         name,
         type,
         context: context,
-        backtrace: include_stacktrace ? caller : nil
-      )
+        trace_context: trace_context
+      ).tap do |span|
+        break unless span && include_stacktrace
+        break unless agent.config.span_frames_min_duration?
+
+        span.original_backtrace ||= caller
+      end
     end
 
     # Ends the current span
@@ -217,7 +254,8 @@ module ElasticAPM # rubocop:disable Metrics/ModuleLength
       name,
       type = nil,
       context: nil,
-      include_stacktrace: true
+      include_stacktrace: true,
+      trace_context: nil
     )
       unless block_given?
         raise ArgumentError,
@@ -229,7 +267,11 @@ module ElasticAPM # rubocop:disable Metrics/ModuleLength
       begin
         span =
           start_span(
-            name, type, context: context, include_stacktrace: include_stacktrace
+            name,
+            type,
+            context: context,
+            include_stacktrace: include_stacktrace,
+            trace_context: trace_context
           )
         yield span
       ensure