elastic-apm 0.7.1 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b90f75ca9497c2110ac5f71c971fe80a964bd5bf719c15c0121ad9186ee89a84
-  data.tar.gz: 3788bad5ea05ecdc8feb1f25baa5be7236d44fc0ab4edd13cfdb2c198e84969d
+  metadata.gz: be39e840d3e28c527b2aa20b19e0c81820c9a7660977179439d19ce92cfd7903
+  data.tar.gz: 10fe2ea416b4ade09b0fdb5b76d7609135c0bae3c5ba855cf8dffccf110f4d35
 SHA512:
-  metadata.gz: 9b88aaa7b02daa8b925a44d892db0f8b5cd7d308d48d651dee250c7d0594becba5c92e8c5ce79bb6ba2dd377cdc0a8807b113644c941b9b3f33e53d59ecd00c8
-  data.tar.gz: cf6999d48e618e8d74c12533dd85170aa12df1554f96b9e960e537667fbae755cc17217267d49e6a56969563a944ef74a762438af91931c1337cecc33c19b05f
+  metadata.gz: e3d2e587d199b774c3d647a6790215866641c36305241870b5843d11af5d80a926a6326f9aa6b6f5112419184660cfb8c5ec7dc637ce364a5ed1eb04d1f32a6b
+  data.tar.gz: 9780322c3de755f2db259de818df6bfb2339c37ec24038412a378ec42a85991edbe4a0f7271c2a48ce6cc5246a73d17aabe081867517171c7e25de8bce5d0643

data/.rubocop.yml

@@ -20,6 +20,9 @@ Lint/RescueException:
 Lint/HandleExceptions:
   Enabled: false
 
+Lint/SplatKeywordArguments:
+  Enabled: false
+
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*.rb'

data/README.md

@@ -1,8 +1,17 @@
-# elastic-apm – Elastic APM agent for Ruby (BETA)
+# elastic-apm
+## Elastic APM agent for ♦️Ruby (🚧 BETA)
 
 [![Jenkins](https://img.shields.io/jenkins/s/https/apm-ci.elastic.co/job/elastic+apm-agent-ruby+master.svg)](https://apm-ci.elastic.co/job/elastic+apm-agent-ruby+master/)
 
-This is the official Rubygem for adding [Elastic][]'s [APM][] to your Ruby app.
+This is the official Rubygem for [Elastic][] [APM][].
+
+💡 We'd love to get feedback and information about you setup – please answer this [☑ short survey](https://goo.gl/forms/LQktvn4rkLWBNSWy1).
+
+---
+
+## Documentation
+
+[Full documentation at Elasti.co](https://www.elastic.co/guide/en/apm/agent/ruby/index.html).
 
 <div>
 <ul>
@@ -21,7 +30,14 @@ This is the official Rubygem for adding [Elastic][]'s [APM][] to your Ruby app.
 </ul>
 </div>
 
-# License
+---
+
+## Getting help
+
+If you find a bug, please [report an issue](https://github.com/elastic/apm-agent-ruby/issues).
+For any other assistance, please open or add to a topic on the [APM discuss forum](https://discuss.elastic.co/c/apm).
+
+## License
 
 Apache 2.0
 

data/bin/build_docs

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -ex
+
+# Requires elastic/docs to be checked out at ../docs
+../docs/build_docs.pl --doc docs/index.asciidoc --chunk 1

data/docs/api.asciidoc

@@ -1,7 +1,8 @@
 [[api]]
 == Public API
 
-Although most usage is covered automatically when using the APM Agent it also has a public API that allows custom usage.
+Although most usage is covered automatically, Elastic APM also has a public API that
+allows custom usage.
 
 [float]
 [[agent-life-cycle]]
@@ -10,7 +11,7 @@ Although most usage is covered automatically when using the APM Agent it also ha
 Controlling when the agent starts and stops.
 
 [float]
-[[api-start]]
+[[api-agent-start]]
 ==== `ElasticAPM.start`
 
 To create and start an ElasticAPM agent use `ElasticAPM.start`:
@@ -20,26 +21,27 @@ To create and start an ElasticAPM agent use `ElasticAPM.start`:
 ElasticAPM.start(server_url: 'http://localhost:8200')
 ----
 
-  * `config`: A hash or `ElasticAPM::Config` instance with configuration options. See <<configuration,Configuration>>.
+  * `config`: An optional hash or `ElasticAPM::Config` instance with configuration
+  options.  See <<configuration,Configuration>>.
 
-If you are using Rails this is done automatically for you.
-
-**ElasticAPM expects a single instance of the Agent.**
+If you are using <<getting-started-rails,Ruby on Rails>> this is done automatically for you.
+If not see <<getting-started-rack,Getting started with Rack>>.
 
 [float]
-[[api-stop]]
+[[api-agent-stop]]
 ==== `ElasticAPM.stop`
 
-Stop the currently running agent. Use this inside `at_exit` in your <<getting-started-rack,Rack app>> to gracefully shut down.
+Stop the currently running agent. Use this inside `at_exit` in your
+<<getting-started-rack,Rack app>> to gracefully shut down.
 
 [float]
-[[api-running]]
+[[api-agent-running]]
 ==== `ElasticAPM.running?`
 
 Returns whether the ElasticAPM Agent is currently running.
 
 [float]
-[[api-agent]]
+[[api-agent-agent]]
 ==== `ElasticAPM.agent`
 
 Returns the currently running agent or nil.
@@ -48,45 +50,57 @@ Returns the currently running agent or nil.
 === Instrumentation
 
 [float]
-[[api-current-transaction]]
+[[api-agent-current-transaction]]
 ==== `ElasticAPM.current_transaction`
 
 Returns the current `ElasticAPM::Transaction` or nil.
 
 [float]
-[[api-transaction]]
+[[api-agent-transaction]]
 ==== `ElasticAPM.transaction`
 
 Start a _transaction_ eg. a web request or background job.
 
-If called without a block you are expected to end and submit the transaction yourself.
-If given a block, the code inside will be wrapped in a transaction. You still need to submit it yourself with `transaction.submit(status)`.
+If called without a block you are expected to end the transaction yourself.
+If given a block, the code inside will be wrapped in a transaction.
+
+You need to submit it yourself with `transaction.submit(status)`.
 
 [source,ruby]
 ----
+# call with block
 transaction = ElasticAPM.transaction('Do things') do
-  # ...
-end
+  do_work # ...
+end # .done is called when block ends
 
 transaction.submit(200)
+
+# without block
+transaction = ElasticAPM.transaction('Do things')
+do_work
+transaction.submit(200) # .submit(result) will also .done(result)
 ----
 
 Arguments:
 
   * `name`: A name for your transaction. Transactions are grouped by name. **Required**.
   * `type`: A `type` for your transaction eg. `db.postgresql.sql`.
-  * `rack_env: env`: An optional Rack `env` used to enrich the transaction with information about the current request.
-  * `&block`: An optional block to wrap with the transaction. The block is passed the transaction as an optional argument.
+  * `context:`: An optional <<api-context,Context>> used to enrich the transaction with
+  information about the current request.
+  * `&block`: An optional block to wrap with the transaction. The block is passed the
+  transaction as an optional argument.
 
 Returns the transaction.
 
 [float]
-[[api-span]]
+[[api-agent-span]]
 ==== `ElasticAPM.span`
 
-Most transactions have nested spans signifying work of a specific sort eg. database queries or external web requests.
+Most transactions have nested spans signifying work of a specific sort eg. database
+queries or external web requests.
 
-If given a block, wrap the code inside in a span. If not you are expected to close the span yourself with `span.done(result)`.
+If given a block, wrap the code inside in a span.
+If not you are expected to close the span yourself with `span.done(result)`.
 
 [source,ruby]
 ----
@@ -102,12 +116,14 @@ Arguments:
   * `name`: A name for your span. **Required**.
   * `type`: The type of work eg. `db.postgresql.query`.
   * `context`: An instance of `Span::Context`.
-  * `&block`: An optional block to wrap with the span. The block is passed the span as an optional argument.
+  * `include_stacktrace`: Whether or not to collect a Stacktrace.
+  * `&block`: An optional block to wrap with the span.
+  The block is passed the span as an optional argument.
 
 Return the span or the return value of the given block.
 
 [float]
-[[api-build-context]]
+[[api-agent-build-context]]
 ==== `ElasticAPM.build_context`
 
 Build a new _Context_ from a Rack `env`.
@@ -124,7 +140,7 @@ Returns the built context.
 === Errors
 
 [float]
-[[api-report]]
+[[api-agent-report]]
 ==== `ElasticAPM.report`
 
 Send an `Exception` to Elastic APM.
@@ -143,12 +159,13 @@ end
 Arguments:
 
   * `exception`: An instance of `Exception`. **Required**.
-  * `handled`: Whether the error was _handled_ eg. wasn't rescued and was represented to the user. Default: `true`.
+  * `handled`: Whether the error was _handled_ eg. wasn't rescued and was represented
+  to the user. Default: `true`.
 
 Returns `[ElasticAPM::Error]`.
 
 [float]
-[[api-report-message]]
+[[api-agent-report-message]]
 ==== `ElasticAPM.report_message`
 
 Send a custom message to Elastic APM.
@@ -163,7 +180,6 @@ ElasticAPM.report_message('This should probably never happen?!')
 Arguments:
 
   * `message`: A custom error string. **Required**.
-  * `handled`: Whether the error was _handled_ eg. wasn't rescued and was represented to the user. Default: `true`.
 
 Returns `[ElasticAPM::Error]`.
 
@@ -171,15 +187,17 @@ Returns `[ElasticAPM::Error]`.
 === Context
 
 [float]
-[[api-set-tag]]
+[[api-agent-set-tag]]
 ==== `ElasticAPM.set_tag`
 
-Add a tag to the current transaction. Tags are basic key-value pairs that are indexed in your Elasticsearch database and therefore searchable.
+Add a tag to the current transaction.
+Tags are basic key-value pairs that are indexed in your Elasticsearch database and
+therefore searchable.
 
 [source,ruby]
 ----
 before_action do
-  ElasticAPM.set_tag(company_id: current_user.company.id)
+  ElasticAPM.set_tag(:company_id, current_user.company.id)
 end
 ----
 
@@ -191,12 +209,15 @@ Arguments:
 Returns the set `value`.
 
 [float]
-[[api-set-custom-context]]
+[[api-agent-set-custom-context]]
 ==== `ElasticAPM.set_custom_context`
 
-Add custom context to the current transaction. Use this to further specify a context that will help you track or diagnose what's going on inside your app.
+Add custom context to the current transaction.
+Use this to further specify a context that will help you track or diagnose what's
+going on inside your app.
 
-If called several times during a transaction the custom context will be destructively merged with `merge!`.
+If called several times during a transaction the custom context will be destructively
+merged with `merge!`.
 
 [source,ruby]
 ----
@@ -212,7 +233,7 @@ Arguments:
 Returns current custom context.
 
 [float]
-[[api-set-user]]
+[[api-agent-set-user]]
 ==== `ElasticAPM.set_user`
 
 Add the current user to the current transaction's context.
@@ -223,3 +244,48 @@ Arguments:
 
 Returns the given user
 
+[float]
+=== Data
+
+[float]
+[[api-agent-add-filter]]
+==== `ElasticAPM.add_filter`
+
+Provide a filter to transform payloads before sending.
+
+Arguments:
+
+  * `key`: A unique key identifying the filter
+  * `callable`: An object or proc (responds to `.call(payload)`)
+
+Return the altered payload.
+
+Example:
+
+[source,ruby]
+----
+ElasticAPM.add_filter(:filter_pings) do |payload|
+  payload['transactions']&.reject! do |t|
+    t['name'] == 'PingsController#index'
+  end
+end
+----
+
+[float]
+[[api-transaction]]
+=== Transaction
+
+Things
+
+[float]
+[[api-span]]
+=== Span
+
+Things
+
+[float]
+[[api-context]]
+=== Context
+
+Things
+

data/docs/configuration.asciidoc

@@ -1,12 +1,10 @@
 [[configuration]]
 == Configuration
 
-There are several ways to shape how Elastic APM behaves.
+There are several ways to configure how Elastic APM behaves.
 
-[float]
-=== Rails
-
-The recommended way to configure Elastic APM for Rails is to create a file `config/elastic_apm.yml` and specify options in there:
+The recommended way to configure Elastic APM is to create a file
+`config/elastic_apm.yml` and specify options in there:
 
 [source,yaml]
 ----
@@ -15,20 +13,362 @@ server_url: 'http://localhost:8200'
 secret_token: 'very_very_secret'
 ----
 
+Options are applied in the following order (last one wins):
+
+1. Defaults
+2. Arguments to `ElasticAPM.start` / `Config.new`
+3. Config file eg. `config/elastic_apm.yml`
+4. Environment variables
+
+[float]
+=== Ruby on Rails
+
+When using Rails it's also possible to specify options inside
+`config/application.rb`:
+
+[source,ruby]
+----
+# config/application.rb
+config.elastic_apm.service_name = 'MyApp'
+----
+
 [float]
 === Sinatra and Rack
 
-When using APM with Sinatra and Rack, you should configure it when starting the agent:
+When using APM with Sinatra and Rack you can configure it when starting
+the agent:
 
 [source,ruby]
 ----
+# config.ru or similar
 ElasticAPM.start(
-  server_url: 'http://localhost:8200',
-  secret_token: 'very_very_secret'
+  app: MyApp,
+  service_name: 'SomeOtherName'
 )
 ----
 
 See <<getting-started-rack>>.
 
-NOTE: This part of the documentation is still lacking. For full list of configuration options, see https://github.com/elastic/apm-agent-ruby/blob/master/lib/elastic_apm/config.rb.
+[float]
+=== Options
+
+Some options can be set with `ENV` variables and all of them may be set in
+your source code.
+
+When setting values for lists using `ENV` variables, strings are split by comma
+eg `ELASTIC_APM_ENBALED_ENVIRONMENTS=development,production`.
+
+[float]
+[[config-config-file]]
+==== `config_file`
+
+[options="header"]
+|============
+| Environment               | `Config` key  | Default
+| `ELASTIC_APM_CONFIG_FILE` | `config_file` | `config/elastic_apm.yml`
+|============
+
+Path to the configuration Yaml-file.
+Elastic APM will load config options from this if the file exists.
+
+[float]
+[[config-server-url]]
+==== `server_url`
+
+[options="header"]
+|============
+| Environment              | `Config` key   | Default
+| `ELASTIC_APM_SERVER_URL` | `server_url`   | `'http://localhost:8200'`
+|============
+
+The URL for your APM Server.
+The URL must be fully qualified, including protocol (`http` or `https`)
+and port.
+
+[float]
+[[config-secret-token]]
+==== `secret_token`
+
+[options="header"]
+|============
+| Environment                | `Config` key    | Default | Example
+| `ELASTIC_APM_SECRET_TOKEN` | `secret_token`  | `nil`   | A random string
+|============
+
+This string is used to ensure that only your agents can send data to your APM server.
+Both the agents and the APM server have to be configured with the same secret token.
+One example to generate a secure secret token is:
+
+[source,bash]
+----
+ruby -r securerandom -e 'print SecureRandom.uuid'
+----
+
+WARNING: Secret tokens only provide any real security if your APM server use TLS.
+
+[float]
+[[config-service-name]]
+==== `service_name`
+
+[options="header"]
+|============
+| Environment                | `Config` key   | Default    | Example
+| `ELASTIC_APM_SERVICE_NAME` | `service_name` | App's name | `MyApp`
+|============
+
+The name of your service.
+This is used to keep all the errors and transactions of your service together and is
+the primary filter in the Elastic APM user interface.
+
+If you're using Ruby on Rails this will default to your app's name.
+If you're using Sinatra it will default to the name of your app's class.
+
+NOTE: The service name must conform to this regular expression: `^[a-zA-Z0-9 _-]+$`.
+In less regexy terms: Your service name must only contain characters from the ASCII
+alphabet, numbers, dashes, underscores and spaces.
+
+[float]
+[[config-service-version]]
+==== `service_version`
+[options="header"]
+|============
+| Environment                    | `Config` key      | Default   | Example
+| `ELASTIC_APM_SERVICE_VERSION`  | `service_version` | `git` sha | A string indicating the version of the deployed service
+|============
+
+Deployed version of your service.
+Defaults to `git rev-parse --verify HEAD`.
+
+[float]
+[[config-environment]]
+==== `environment`
+
+[options="header"]
+|============
+| Environment               | `Config` key   | Default    | Example
+| `ELASTIC_APM_ENVIRONMENT` | `environment`  | From `ENV` | `"production"`
+|============
+
+The name of the environment this service is deployed in,
+e.g. "production" or "staging".
+
+Defaults to `ENV['RAILS_ENV'] || ENV['RACK_ENV']`.
+
+[float]
+[[config-enabled-environments]]
+==== `enabled-environments`
+
+[options="header"]
+|============
+| Environment                        | `Config` key           | Default
+| `ELASTIC_APM_ENABLED_ENVIRONMENTS` | `enabled_environments` | `['production']`
+|============
+
+Specify which environments to enable APM in.
+
+If the current envrironment isn't included, the agent will effectively be a _noop_
+and do nothing.
+So you can keep in your custom instrumentation code without the agent sending
+anything nor complain.
+
+[float]
+[[config-framework-name]]
+==== `framework_name`
+[options="header"]
+|============
+| Environment                  | `Config` key     | Default
+| `ELASTIC_APM_FRAMEWORK_NAME` | `framework_name` | Depending on framework
+|============
+
+Name of the used framework.
+For Rails or Sinatra, this defaults to `Ruby on Rails` and `Sinatra` respectively,
+otherwise defaults to `nil`.
+
+[float]
+[[config-framework-version]]
+==== `framework_version`
+[options="header"]
+|============
+| Environment                     | `Config` key        | Default
+| `ELASTIC_APM_FRAMEWORK_VERSION` | `framework_version` | Depending on framework
+|============
+
+Version number of the used framework.
+For Ruby on Rails and Sinatra, this defaults to the used version of the framework,
+otherwise, the default is `nil`.
+
+[float]
+[[config-hostname]]
+==== `hostname`
+
+[options="header"]
+|============
+| Environment                | `Config` key  | Default    | Example
+| `ELASTIC_APM_HOSTNAME`     | `hostname`    | `hostname` | `app-server01.example.com`
+|============
+
+The host name to use when sending error and transaction data to the APM server.
+
+[float]
+[[config-source-lines-error-app-frames]]
+==== `source_lines_error_app_frames`
+[float]
+[[config-source-lines-error-library-frames]]
+==== `source_lines_error_library_frames`
+[float]
+[[config-source-lines-span-app-frames]]
+==== `source_lines_span_app_frames`
+[float]
+[[config-source-lines-span-library-frames]]
+==== `source_lines_span_library_frames`
+
+|============
+| Environment                                     | `Config` key                        | Default
+| `ELASTIC_APM_SOURCE_LINES_ERROR_APP_FRAMES`     | `source_lines_error_app_frames`     | `5`
+| `ELASTIC_APM_SOURCE_LINES_ERROR_LIBRARY_FRAMES` | `source_lines_error_library_frames` | `5`
+| `ELASTIC_APM_SOURCE_LINES_SPAN_APP_FRAMES`      | `source_lines_span_app_frames`      | `0`
+| `ELASTIC_APM_SOURCE_LINES_SPAN_LIBRARY_FRAMES`  | `source_lines_span_library_frames`  | `0`
+|============
+
+By default, the APM agent collects source code snippets for errors.
+With the above settings, you can modify how many lines of source code is collected.
+
+We differ between errors and spans, as well as library frames and app frames.
+
+WARNING: Especially for spans, collecting source code can have a large impact on
+storage use in your Elasticsearch cluster.
+
+[float]
+[[config-span-frames-min-duration-ms]]
+==== `span_frames_min_duration`
+
+| ============
+| Environment                            | `Config` keys              | Default
+| `ELASTIC_APM_SPAN_FRAMES_MIN_DURATION` | `span_frames_min_duration` | `-1`
+| ============
+
+In its default settings, the APM agent will collect a stack trace with every recorded span.
+While this is very helpful to find the exact place in your code that causes the span,
+collecting this stack trace does have some overhead.
+
+With the default setting, `-1`, stack traces will be collected for all spans.
+Setting it to a positive value, e.g. `5`, will limit stack trace collection to spans
+with durations equal or longer than the given value in milliseconds, e.g. 5 milliseconds.
+
+To disable stack trace collection for spans completely, set the value to 0.
+
+[float]
+[[config-max-queue-size]]
+==== `max_queue_size`
+
+|============
+| Environment                  | `Config` key     | Default
+| `ELASTIC_APM_MAX_QUEUE_SIZE` | `max_queue_size` | `500`
+|============
+
+Maximum queue length of transactions before sending transactions to the APM server.
+A lower value will increase the load on your APM server,
+while a higher value can increase the memory pressure of your app.
+A higher value also impacts the time until transactions are indexed and searchable
+in Elasticsearch.
+
+This setting is useful to limit memory consumption if you experience a sudden spike
+of traffic.
+
+[float]
+[[config-flush-interval]]
+==== `flush_interval`
+
+|============
+| Environment                  | `Config` key     | Default
+| `ELASTIC_APM_FLUSH_INTERVAL` | `flush_interval` | `10`
+|============
+
+Interval with which transactions should be sent to the APM server, in seconds.
+A lower value will increase the load on your APM server,
+while a higher value can increase the memory pressure on your app.
+A higher value also impacts the time until transactions are indexed and searchable
+in Elasticsearch.
+
+[float]
+[[config-transaction-sample-rate]]
+==== `transaction_sample_rate`
+
+|============
+| Environment                           | `Config` key              | Default
+| `ELASTIC_APM_TRANSACTION_SAMPLE_RATE` | `transaction_sample_rate` | `1.0`
+|============
+
+By default, the agent will sample every transaction (e.g. request to your service).
+To reduce overhead and storage requirements, you can set the sample rate to a value
+between `0.0` and `1.0`.
+We still record overall time and the result for unsampled transactions, but no
+context information, tags, or spans.
+
+[float]
+[[config-transaction-max-spans]]
+==== `transaction_max_spans`
+
+|============
+| Environment                         | `Config` key            | Default
+| `ELASTIC_APM_TRANSACTION_MAX_SPANS` | `transaction_max_spans` | `500`
+|============
+
+Limits the amount of spans that are recorded per transaction.
+This is helpful in cases where a transaction creates a very high amount of spans
+(e.g. thousands of SQL queries).
+Setting an upper limit will prevent overloading the agent and the APM server with
+too much work for such edge cases.
+
+[float]
+[[config-verify-server-cert]]
+==== `verify_server_cert`
+|============
+| Environment                       | `Config` key         | Default
+| `ELASTIC_APM_VERIFY_SERVER_CERT`  | `verify_server_cert` | `true`
+|============
+
+By default, the agent verifies the SSL certificate if you use an HTTPS connection to
+the APM server.
+Verification can be disabled by changing this setting to `false`.
+
+[float]
+[[config-disabled-spies]]
+==== `disabled_spies`
+
+[options="header"]
+|============
+| Environment                  | `Config` key     | Default
+| `ELASTIC_APM_DISABLED_SPIES` | `disabled_spies` | `['json']`
+|============
+
+Elastic APM automatically instruments select third party libraries.
+Use this option to disable any of these.
+
+Get an array of enabled spies with `ElasticAPM.agent.config.enabled_spies`.
+
+[float]
+[[config-custom-key-filters]]
+==== `custom_key_filters`
+[options="header"]
+|============
+| Environment                      | `Config` key         | Default | Example
+| `ELASTIC_APM_CUSTOM_KEY_FILTERS` | `custom_key_filters` | `[]`    | `['MyAuthHeader']`
+|============
+
+Elastic APM strips
+https://github.com/elastic/apm-agent-ruby/blob/1.x/lib/elastic_apm/filters/secrets_filter.rb[
+what looks like confidential information] from the request/response headers.
+Use this option to add your own custom header keys to the list of filtered keys.
+
+
+[float]
+[[config-filter-exception-types]]
+==== `filter_exception_types`
+|============
+| Environment | `Config` key             | Default | Example
+| N/A         | `filter_exception_types` | `[]`    | `[MyApp::Errors::IgnoredError]`
+|============
+
+Use this to filter error tracking for specific error constants.
 

data/docs/custom-instrumentation.asciidoc

@@ -1,14 +1,93 @@
 [[custom-instrumentation]]
 === Custom instrumentation
 
-When installed 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-span,`ElasticAPM.span`>>.
+See <<api-transaction,`ElasticAPM.transaction`>> and <<api-agent-span,`ElasticAPM.span`>>.
 
-[[injectors]]
-=== Injectors -- automatic integrations with third-party libraries
+[float]
+==== Helpers
 
-ElasticAPM has built-in integrations for some popular libraries. Use `config.enabled_injectors` to add or remove specific integrations. See <<configuration,Configuration>>.
+ElasticAPM includes some nifty helpers if you just want to instrument a regular method.
+
+[source,ruby]
+----
+class ThingsController < ApplicationController
+  include SpanHelpers
+
+  def index
+    @result = do_hard_work
+  end
+
+  private
+
+  def do_hard_work
+    # ...
+  end
+
+  span_method :do_hard_work # takes optional `name` and `type`
+end
+----
+
+[float]
+==== Custom span example
+
+If you are already inside a Transaction (most likely) and you want to intrument
+some work inside it, add a custom span:
+
+[source,ruby]
+----
+class ThingsController < ApplicationController
+  def index
+    @result_of_work = ElasticAPM.span "Heavy work" do
+      do_the_heavy_work
+    end
+  end
+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:
+
+[source,ruby]
+----
+class Something
+  def do_work
+    transaction = ElasticAPM.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
+    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].
 

data/docs/getting-started-rack.asciidoc

@@ -1,10 +1,52 @@
 [[getting-started-rack]]
 == Getting started with Rack
 
+Add the gem to your `Gemfile`:
+
+[source,ruby]
+----
+gem 'elastic-apm'
+----
+
+Create a file `config/elastic_apm.yml`:
+
+[source,yaml]
+----
+server_url: http://localhost:8100
+secret_token: ''
+----
+
+Include the middleware, start (and stop) Elastic APM when booting your app:
+
 [source,ruby]
 ----
 # config.ru
 
+app = lambda do |env|
+  [200, {'Content-Type' => 'text/plain'}, ['ok']]
+end
+
+# Wraps all requests in transactions and reports exceptions
+use ElasticAPM::Middleware
+
+# Start an instance of the Agent
+ElasticAPM.start(service_name: 'NothingButRack')
+
+run app
+
+# Gracefully stop the agent when process exits.
+# Makes sure any pending transactions are sent.
+at_exit { ElasticAPM.stop }
+----
+
+[float]
+[[getting-started-sinatra]]
+==== Sinatra example
+
+[source,ruby]
+----
+# Example config.ru
+
 require 'sinatra/base'
 
 class MySinatraApp < Sinatra::Base
@@ -14,10 +56,7 @@ class MySinatraApp < Sinatra::Base
 end
 
 # Takes optional ElasticAPM::Config values
-ElasticAPM.start(
-  app: MySinatraApp, # required
-  server_url: 'http://localhost:8200'
-)
+ElasticAPM.start(app: MySinatraApp, ...)
 
 run MySinatraApp
 

data/docs/getting-started-rails.asciidoc

@@ -11,4 +11,12 @@ Add the gem to your `Gemfile`:
 gem 'elastic-apm'
 ----
 
+Create a file `config/elastic_apm.yml`:
+
+[source,yaml]
+----
+server_url: http://localhost:8100
+secret_token: ''
+----
+
 This automatically sets up error logging and performance tracking but of course there are knobs to turn if you'd like to. See <<configuration>>.

data/docs/index.asciidoc

@@ -4,19 +4,19 @@ endif::[]
 
 = APM Ruby Agent Reference (Beta)
 
+[[introduction]]
 == Introduction
 
 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,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:
 
  * https://www.elastic.co/guide/en/apm/server/current/index.html[APM Server]
- * https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html[Elasticsearch]
 
 [[framework-support]]
-The Elastic APM Ruby Agent officially supports <<getting-started-rails,Rails>> versions 4.x on onwards.
+The Elastic APM Ruby Agent officially supports <<getting-started-rails,Ruby on Rails>> versions 4.x on onwards.
 
 For Sinatra and other Rack compatible frameworks, see <<getting-started-rack,Getting started with Rack>>.
 

data/lib/elastic_apm.rb

@@ -10,6 +10,7 @@ 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'

data/lib/elastic_apm/agent.rb

@@ -30,10 +30,13 @@ module ElasticAPM
       config = Config.new(config) unless config.is_a?(Config)
 
       unless config.enabled_environments.include?(config.environment)
-        puts format(
-          '%sNot tracking anything in "%s" env',
-          Log::PREFIX, config.environment
-        )
+        unless config.disable_environment_warning?
+          puts format(
+            '%sNot tracking anything in "%s" env',
+            Log::PREFIX, config.environment
+          )
+        end
+
         return
       end
 

data/lib/elastic_apm/config.rb

@@ -13,9 +13,10 @@ module ElasticAPM
 
       environment: ENV['RAILS_ENV'] || ENV['RACK_ENV'],
       enabled_environments: %w[production],
+      disable_environment_warning: false,
 
-      log_path: '-',
-      log_level: Logger::INFO,
+      log_path: nil,
+      log_level: Logger::DEBUG,
 
       max_queue_size: 500,
       flush_interval: 10,
@@ -36,6 +37,7 @@ module ElasticAPM
       source_lines_span_app_frames: 5,
       source_lines_error_library_frames: 0,
       source_lines_span_library_frames: 0,
+      span_frames_min_duration: -1,
 
       disabled_spies: %w[json],
 
@@ -43,6 +45,8 @@ module ElasticAPM
       current_user_email_method: :email,
       current_user_username_method: :username,
 
+      custom_key_filters: [],
+
       view_paths: [],
       root_path: Dir.pwd
     }.freeze
@@ -51,10 +55,13 @@ module ElasticAPM
       'ELASTIC_APM_SERVER_URL' => 'server_url',
       'ELASTIC_APM_SECRET_TOKEN' => 'secret_token',
 
-      'ELASTIC_APM_SERVICE_NAME' => 'service_name',
-      'ELASTIC_APM_SERVICE_VERSION' => 'service_version',
       'ELASTIC_APM_ENVIRONMENT' => 'environment',
       'ELASTIC_APM_ENABLED_ENVIRONMENTS' => [:list, 'enabled_environments'],
+      'ELASTIC_APM_DISABLE_ENVIRONMENT_WARNING' =>
+        [:bool, 'disable_environment_warning'],
+
+      'ELASTIC_APM_SERVICE_NAME' => 'service_name',
+      'ELASTIC_APM_SERVICE_VERSION' => 'service_version',
       'ELASTIC_APM_FRAMEWORK_NAME' => 'framework_name',
       'ELASTIC_APM_FRAMEWORK_VERSION' => 'framework_version',
       'ELASTIC_APM_HOSTNAME' => 'hostname',
@@ -67,6 +74,10 @@ module ElasticAPM
         [:int, 'source_lines_error_library_frames'],
       'ELASTIC_APM_SOURCE_LINES_SPAN_LIBRARY_FRAMES' =>
         [:int, 'source_lines_span_library_frames'],
+      'ELASTIC_APM_SPAN_FRAMES_MIN_DURATION' =>
+        [:int, 'span_frames_min_duration'],
+
+      'ELASTIC_APM_CUSTOM_KEY_FILTERS' => [:list, 'custom_key_filters'],
 
       'ELASTIC_APM_MAX_QUEUE_SIZE' => [:int, 'max_queue_size'],
       'ELASTIC_APM_FLUSH_INTERVAL' => 'flush_interval',
@@ -86,6 +97,8 @@ module ElasticAPM
       set_from_env
 
       yield self if block_given?
+
+      build_logger unless logger
     end
 
     attr_accessor :config_file
@@ -93,16 +106,19 @@ module ElasticAPM
     attr_accessor :server_url
     attr_accessor :secret_token
 
+    attr_accessor :environment
+    attr_accessor :enabled_environments
+    attr_accessor :disable_environment_warning
+
     attr_accessor :service_name
     attr_accessor :service_version
-    attr_accessor :environment
     attr_accessor :framework_name
     attr_accessor :framework_version
     attr_accessor :hostname
-    attr_accessor :enabled_environments
 
     attr_accessor :log_path
     attr_accessor :log_level
+    attr_accessor :logger
 
     attr_accessor :max_queue_size
     attr_accessor :flush_interval
@@ -123,6 +139,7 @@ module ElasticAPM
     attr_accessor :source_lines_span_app_frames
     attr_accessor :source_lines_error_library_frames
     attr_accessor :source_lines_span_library_frames
+    attr_accessor :span_frames_min_duration
 
     attr_accessor :disabled_spies
 
@@ -134,8 +151,9 @@ module ElasticAPM
     attr_accessor :current_user_email_method
     attr_accessor :current_user_username_method
 
-    attr_reader   :logger
+    attr_reader   :custom_key_filters
 
+    alias :disable_environment_warning? :disable_environment_warning
     alias :verify_server_cert? :verify_server_cert
 
     def app=(app)
@@ -166,8 +184,8 @@ module ElasticAPM
       server_url.start_with?('https')
     end
 
-    def logger=(logger)
-      @logger = logger || build_logger(log_path, log_level)
+    def custom_key_filters=(filters)
+      @custom_key_filters = Array(filters).map(&Regexp.method(:new))
     end
 
     # rubocop:disable Metrics/MethodLength
@@ -251,10 +269,11 @@ module ElasticAPM
       self.view_paths = app.config.paths['app/views'].existent
     end
 
-    def build_logger(path, level)
-      logger = Logger.new(path == '-' ? STDOUT : path)
-      logger.level = level
-      logger
+    def build_logger
+      logger = Logger.new(log_path == '-' ? $stdout : log_path)
+      logger.level = log_level
+
+      self.logger = logger
     end
 
     def format_name(str)

data/lib/elastic_apm/filters/secrets_filter.rb

@@ -21,6 +21,7 @@ module ElasticAPM
 
       def initialize(config)
         @config = config
+        @key_filters = KEY_FILTERS + config.custom_key_filters
       end
 
       def call(payload)
@@ -47,7 +48,7 @@ module ElasticAPM
       end
 
       def filter_key?(key)
-        KEY_FILTERS.any? { |regex| key =~ regex }
+        @key_filters.any? { |regex| key =~ regex }
       end
 
       def filter_value?(value)

data/lib/elastic_apm/http.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'net/http'
+require 'openssl'
 require 'zlib'
 
 require 'elastic_apm/service_info'

data/lib/elastic_apm/serializers.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module ElasticAPM
   # @api private
   module Serializers

data/lib/elastic_apm/span.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 require 'elastic_apm/span/context'
 
 module ElasticAPM
@@ -22,11 +24,13 @@ module ElasticAPM
       @type = type || DEFAULT_TYPE
       @parent = parent
       @context = context
+
       @stacktrace = nil
+      @original_backtrace = nil
     end
     # rubocop:enable Metrics/ParameterLists
 
-    attr_accessor :name, :context, :type, :stacktrace
+    attr_accessor :name, :context, :type, :stacktrace, :original_backtrace
     attr_reader :id, :duration, :parent, :relative_start
 
     def start
@@ -38,6 +42,15 @@ module ElasticAPM
     def done
       @duration = Util.micros - @transaction.timestamp - relative_start
 
+      if original_backtrace && long_enough_for_stacktrace?
+        self.stacktrace =
+          @transaction.instrumenter.agent.stacktrace_builder.build(
+            original_backtrace, type: :span
+          )
+      end
+
+      self.original_backtrace = nil # release it
+
       self
     end
 
@@ -55,5 +68,17 @@ module ElasticAPM
         " type:#{type.inspect}" \
         '>'
     end
+
+    private
+
+    def long_enough_for_stacktrace?
+      min_duration = @transaction.instrumenter.config.span_frames_min_duration
+
+      case min_duration
+      when -1 then true
+      when 0 then false
+      else duration / 1000 >= min_duration
+      end
+    end
   end
 end

data/lib/elastic_apm/span_helpers.rb

@@ -9,9 +9,16 @@ module ElasticAPM
         __span_method_on(singleton_class, method, name, type)
       end
 
+      def span_method(method, name, type)
+        __span_method_on(self, method, name, type)
+      end
+
       private
 
-      def __span_method_on(klass, method, name, type)
+      def __span_method_on(klass, method, name = nil, type = nil)
+        name ||= method.to_s
+        type ||= Span::DEFAULT_TYPE
+
         klass.class_eval <<-RUBY, __FILE__, __LINE__ + 1
           alias :"__without_apm_#{method}" :"#{method}"
 

data/lib/elastic_apm/stacktrace/frame.rb

@@ -26,6 +26,7 @@ module ElasticAPM
 
         padding = (context_line_count - 1) / 2
         from = lineno - padding - 1
+        from = 0 if from < 0
         to = lineno + padding - 1
         file_lines = read_lines(abs_path, from..to)
 

data/lib/elastic_apm/transaction.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
 module ElasticAPM
   # rubocop:disable Metrics/ClassLength
   # @api private
@@ -55,7 +57,7 @@ module ElasticAPM
     end
 
     def submit(result = nil, status: nil, headers: {})
-      done result
+      done result unless duration
 
       if status
         context.response = Context::Response.new(status, headers: headers)
@@ -104,9 +106,8 @@ module ElasticAPM
       span = next_span(name, type, context)
       spans << span
 
-      if backtrace
-        span.stacktrace =
-          @instrumenter.agent.stacktrace_builder.build(backtrace, type: :span)
+      if backtrace && span_frames_min_duration?
+        span.original_backtrace = backtrace
       end
 
       span.start
@@ -143,6 +144,10 @@ module ElasticAPM
         context: context
       )
     end
+
+    def span_frames_min_duration?
+      @instrumenter.agent.config.span_frames_min_duration != 0
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end

data/lib/elastic_apm/util/dig.rb

@@ -1,4 +1,4 @@
-# Monkeypatch/backport/polyfill Enumerable#dig to Ruby < 2.3
+# Backport Enumerable#dig to Ruby < 2.3
 #
 # Implementation from
 #   https://github.com/Invoca/ruby_dig/blob/master/lib/ruby_dig.rb

data/lib/elastic_apm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ElasticAPM
-  VERSION = '0.7.1'.freeze
+  VERSION = '0.7.2'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: elastic-apm
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.2
 platform: ruby
 authors:
 - Mikkel Malmberg
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-17 00:00:00.000000000 Z
+date: 2018-06-04 00:00:00.000000000 Z
 dependencies: []
 description: 
 email:
@@ -27,6 +27,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- bin/build_docs
 - bin/console
 - bin/setup
 - bin/with_framework