elastic-apm 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf4e0bb9099082e09c366d33a1a1e028ee4c4d9cd7f6eea76427471ea483e293
-  data.tar.gz: 241dcd61a548362966a6899b1690f0aa7c7f4a4f13e72e0463d78eccab3af317
+  metadata.gz: 4e0d3d869c607c4a439fb2c19ae77c35572cadf74f34f6bb4c2075e393a00127
+  data.tar.gz: a126c14da9817c69b4b76ba17bd12521d865ea2b791b59ff978d0fa6bbafa256
 SHA512:
-  metadata.gz: efdd3acfcc32adfbcad767bcb674ddb9441b84931a2511093a072292e718670cc744ee6bce660f54a4a9310389773a71477afa723af80608d81f337a46ba5b2f
-  data.tar.gz: a6444edc4142d3dc5ef13c6a669efe147929c8dbc08fcca1247f69761796178c82d448fb0cc135dd1fc261befcebdd6dc8a7ad5b57e6de188b792b499c6b4d37
+  metadata.gz: c4951d4fce0cb88c5cb45006a24f272156785d2bf9558ce93b84b2756a178957dbb75149bf6a529e018845f626cdf581721750131227f095e09e06ed228ba208
+  data.tar.gz: 66407124c6987fffc19a0340a57cf781dc8655ca7385da04d3ebc08f4c1342195b7dce0b0c0e87ebbc1f79e81ec60697556fe1dfae7630ff9b893d8edd7c3edf

data/.gitignore

@@ -11,3 +11,4 @@
 .rspec_status
 
 Gemfile.lock
+/html_docs/

data/.rubocop.yml

@@ -28,6 +28,9 @@ Naming/FileName:
   Exclude:
     - 'lib/elastic-apm.rb'
 
+Naming/AccessorMethodName:
+  Enabled: false
+
 Style/Alias:
   Enabled: false
 

data/README.md

@@ -1,4 +1,6 @@
-# ElasticAPM (ALPHA)
+# elastic-apm – Elastic APM agent for Ruby (ALPHA)
+
+[![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/) [![Gem](https://img.shields.io/gem/v/formatador.svg?style=flat-square)](https://rubygems.org/gems/elastic-apm)
 
 This is the official Rubygem for adding [Elastic][]'s [APM][] to your Ruby app.
 
@@ -51,5 +53,9 @@ run MySinatraApp
 at_exit { ElasticAPM.stop }
 ```
 
+# License
+
+Apache 2.0
+
 [Elastic]: https://elastic.co
 [APM]: https://www.elastic.co/guide/en/apm/server/index.html

data/docs/api.asciidoc

@@ -0,0 +1,210 @@
+[[api]]
+== Public API
+
+Although most usage is covered automatically when using the APM Agent it also has a public API that allows custom usage.
+
+[float]
+[[agent-life-cycle]]
+=== Agent life cycle
+
+Controlling when the agent starts and stops.
+
+[float]
+[[api-start]]
+==== `ElasticAPM.start`
+
+To create and start an ElasticAPM agent use `ElasticAPM.start`:
+
+[source,ruby]
+----
+ElasticAPM.start(server_url: 'http://localhost:8200')
+----
+
+  * `config`: A 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.**
+
+[float]
+[[api-stop]]
+==== `ElasticAPM.stop`
+
+Stop the currently running agent. Use this inside `at_exit` in your <<getting-started-rack,Rack app>> to gracefully shut down.
+
+[float]
+[[api-running]]
+==== `ElasticAPM.running?`
+
+Returns whether the ElasticAPM Agent is currently running.
+
+[float]
+[[api-agent]]
+==== `ElasticAPM.agent`
+
+Returns the currently running agent or nil.
+
+=== Instrumentation
+
+[float]
+[[api-current-transaction]]
+==== `ElasticAPM.current_transaction`
+
+Returns the current `ElasticAPM::Transaction` or nil.
+
+[float]
+[[api-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)`.
+
+[source,ruby]
+----
+transaction = ElasticAPM.transaction('Do things') do
+  # ...
+end
+
+transaction.submit(200)
+----
+
+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.
+
+Returns the transaction.
+
+[float]
+[[api-span]]
+==== `ElasticAPM.span`
+
+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)`.
+
+[source,ruby]
+----
+ElasticAPM.transaction 'Do things' do
+  ElasticAPM.span 'Do one of the things' do
+    Database.query # ...
+  end
+end
+----
+
+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.
+
+Return the span or the return value of the given block.
+
+[float]
+[[api-build-context]]
+==== `ElasticAPM.build_context`
+
+Build a new _Context_ from a Rack `env`.
+
+A context provides information about the current request, response, user and more.
+
+Arguments:
+
+  * `rack_env`: An instance of Rack::Env
+
+Returns the built context.
+
+=== Errors
+
+[float]
+[[api-report]]
+==== `ElasticAPM.report`
+
+Send an `Exception` to Elastic APM.
+
+If reported inside a transaction, the context from that will be added.
+
+[source,ruby]
+----
+begin
+  do_a_thing_and_fail
+rescue Exception => e
+  ElasticAPM.report(e)
+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`.
+
+Returns `[ElasticAPM::Error]`.
+
+[float]
+[[api-report-message]]
+==== `ElasticAPM.report_message`
+
+Send a custom message to Elastic APM.
+
+If reported inside a transaction, the context from that will be added.
+
+[source,ruby]
+----
+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]`.
+
+=== Context
+
+[float]
+[[api-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.
+
+[source,ruby]
+----
+before_action do
+  ElasticAPM.set_tag(company_id: current_user.company.id)
+end
+----
+
+Arguments:
+
+  * `key`: A string key.
+  * `value`: A string value.
+
+Returns the set `value`.
+
+[float]
+[[api-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.
+
+If called several times during a transaction the custom context will be destructively merged with `merge!`.
+
+[source,ruby]
+----
+before_action do
+  ElasticAPM.set_custom_context(company: current_user.company.to_h)
+end
+----
+
+Arguments:
+
+  * `context`: A hash of JSON-compatible key-values. Can be nested.
+
+Returns current custom context.
+

data/docs/configuration.asciidoc

@@ -0,0 +1,32 @@
+[[configuration]]
+== Configuration
+
+There are several ways to shape how Elastic APM behaves.
+
+=== Rails
+
+The recommended way to configure Elastic APM for Rails is to create a file `config/elastic_apm.yml` and specify options in there:
+
+[source,yaml]
+----
+---
+server_url: 'http://localhost:8200'
+secret_token: 'very_very_secret'
+----
+
+=== Sinatra and Rack
+
+When using APM with Sinatra and Rack, you should configure it when starting the agent:
+
+[source,ruby]
+----
+ElasticAPM.start(
+  server_url: 'http://localhost:8200',
+  secret_token: 'very_very_secret'
+)
+----
+
+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.
+

data/docs/context.asciidoc

@@ -0,0 +1,27 @@
+[[context]]
+=== Adding additional context
+
+==== Adding custom context
+
+You can add your own custom, nested JSON-compatible data to the current transaction using `ElasticAPM.add_custom_context(hash)` eg.:
+
+[source,ruby]
+----
+class ThingsController < ApplicationController
+  before_action do
+    ElasticAPM.add_custom_context(company: current_user.company)
+  end
+
+  # ...
+end
+----
+
+==== Adding tags
+
+Tags are special in that they are indexed in your Elasticsearch database and therefore searchable.
+
+[source,ruby]
+----
+ElasticAPM.set_tag(:company_name, 'Acme, Inc.')
+----
+

data/docs/custom-instrumentation.asciidoc

@@ -0,0 +1,14 @@
+[[custom-instrumentation]]
+=== Custom instrumentation
+
+When installed ElasticAPM will automatically wrap your app's request/responses in transactions and report its errors.
+
+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`>>.
+
+[[injectors]]
+=== Injectors -- automatic integrations with third-party libraries
+
+ElasticAPM has built-in integrations for some popular libraries. Use `config.enabled_injectors` to add or remove specific integrations. See <<configuration,Configuration>>.
+

data/docs/getting-started-rack.asciidoc

@@ -0,0 +1,26 @@
+[[getting-started-rack]]
+== Getting started with Rack
+
+[source,ruby]
+----
+# config.ru
+
+require 'sinatra/base'
+
+class MySinatraApp < Sinatra::Base
+  use ElasticAPM::Middleware
+  
+  # ...
+end
+
+# Takes optional ElasticAPM::Config values
+ElasticAPM.start(
+  app: MySinatraApp, # required
+  server_url: 'http://localhost:8200'
+)
+
+run MySinatraApp
+
+at_exit { ElasticAPM.stop }
+----
+

data/docs/getting-started-rails.asciidoc

@@ -0,0 +1,13 @@
+[[getting-started-rails]]
+== Getting started with Rails
+
+=== Setup
+
+Add the gem to your `Gemfile`:
+
+[source,ruby]
+----
+gem 'elastic-apm'
+----
+
+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

@@ -0,0 +1,33 @@
+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::[]
+
+= APM Ruby Agent Reference (Alpha)
+
+== 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.
+
+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.
+
+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[]
+include::./configuration.asciidoc[]
+
+[[advanced]]
+== Advanced Topics
+include::./context.asciidoc[]
+include::./custom-instrumentation.asciidoc[]
+
+include::./api.asciidoc[]
+

data/elastic-apm.gemspec

@@ -10,6 +10,7 @@ Gem::Specification.new do |spec|
 
   spec.summary       = 'The official Elastic APM agent for Ruby'
   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.0.0"
 

data/lib/elastic_apm.rb

@@ -6,6 +6,7 @@ require 'elastic_apm/log'
 # 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/util'
@@ -57,10 +58,12 @@ module ElasticAPM
   # `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, type = nil, &block)
-    agent && agent.transaction(name, type, &block)
+  def self.transaction(name, type = nil, context: nil, &block)
+    return call_through(&block) unless agent
+    agent.transaction(name, type, context: context, &block)
   end
 
   # Starts a new span under the current Transaction
@@ -71,7 +74,17 @@ module ElasticAPM
   # @yield [Span] Optional block encapsulating span
   # @return [Span] Unless block given
   def self.span(name, type = nil, context: nil, &block)
-    agent && agent.span(name, type, context: context, &block)
+    return call_through(&block) unless agent
+    agent.span(name, type, context: context, &block)
+  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
 
   ### Errors
@@ -79,14 +92,48 @@ module ElasticAPM
   # Report and exception to APM
   #
   # @param exception [Exception] The exception
-  # @param rack_env [Rack::Env] An optional Rack env
   # @param handled [Boolean] Whether the exception was rescued
-  # @return [Error] An [Error] instance
-  def self.report(exception, rack_env: nil, handled: true)
-    agent && agent.report(exception, rack_env: rack_env, handled: handled)
+  # @return [Error] The generated [Error]
+  def self.report(exception, handled: true)
+    agent && agent.report(exception, handled: handled)
   end
 
+  # 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
+
+  ### Context
+
+  # 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
+
+  # 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
+
+  class << self
+    private
+
+    def call_through
+      unless agent
+        return yield if block_given?
+      end
+
+      nil
+    end
+  end
 end