elastic-apm 4.7.3 → 4.8.0

data/docs/{context.asciidoc → reference/context.md}

@@ -1,14 +1,16 @@
-[[context]]
-=== Adding additional context
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/context.html
+---
 
-[float]
-==== Adding custom context
+# Adding additional context [context]
 
-You can add your own custom, nested JSON-compatible data to the current
-transaction using `ElasticAPM.set_custom_context(hash)` eg.:
 
-[source,ruby]
-----
+## Adding custom context [_adding_custom_context]
+
+You can add your own custom, nested JSON-compatible data to the current transaction using `ElasticAPM.set_custom_context(hash)` eg.:
+
+```ruby
 class ThingsController < ApplicationController
   before_action do
     ElasticAPM.set_custom_context(company: current_user.company)
@@ -16,31 +18,29 @@ class ThingsController < ApplicationController
 
   # ...
 end
-----
+```
+
 
-[float]
-==== Adding labels
+## Adding labels [_adding_labels]
 
-Labels are special in that they are indexed in your Elasticsearch database and
-therefore queryable.
+Labels are special in that they are indexed in your Elasticsearch database and therefore queryable.
 
-[source,ruby]
-----
+```ruby
 ElasticAPM.set_label(:company_name, 'Acme, Inc.')
-----
+```
 
 Note that `.`, `*` and `"` in keys are converted to `_`.
 
-[float]
-==== Providing info about the user
+
+## Providing info about the user [_providing_info_about_the_user]
 
 You can provide ElasticAPM with info about the current user.
 
-[source,ruby]
-----
+```ruby
 class ApplicationController < ActionController::Base
   before_action do
     current_user && ElasticAPM.set_user(current_user)
   end
 end
-----
+```
+

data/docs/reference/custom-instrumentation.md

@@ -0,0 +1,72 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/custom-instrumentation.html
+---
+
+# Custom instrumentation [custom-instrumentation]
+
+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 also possible to create your own transactions as well as provide spans for any automatic or custom transaction.
+
+See [`ElasticAPM.start_transaction`](/reference/api-reference.md#api-agent-start_transaction) and [`ElasticAPM.start_span`](/reference/api-reference.md#api-agent-start_span).
+
+
+## Helpers [_helpers]
+
+ElasticAPM includes some nifty helpers if you just want to instrument a regular method.
+
+```ruby
+class Thing
+  include ElasticAPM::SpanHelpers
+
+  def do_the_work
+    # ...
+  end
+  span_method :do_hard_work # takes optional `name` and `type`
+
+  def self.do_all_the_work
+    # ...
+  end
+  span_class_method :do_hard_work, 'Custom name', 'custom.work_thing'
+end
+```
+
+
+## Custom span example [_custom_span_example]
+
+If you are already inside a Transaction (most likely) and you want to instrument some work inside it, add a custom span:
+
+```ruby
+class ThingsController < ApplicationController
+  def index
+    @result_of_work = ElasticAPM.with_span "Heavy work" do
+      do_the_heavy_work
+    end
+  end
+end
+```
+
+
+## Custom transaction example [_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:
+
+```ruby
+class Something
+  def do_work
+    transaction = ElasticAPM.start_transaction 'Something#do_work'
+
+    begin
+      Sequel[:users] # many third party libs will be automatically instrumented
+    rescue Exception => e
+      ElasticAPM.report(e)
+      raise
+    ensure
+      ElasticAPM.end_transaction('result')
+    end
+  end
+end
+```
+
+**Note:** If the agent isn’t started beforehand this will do nothing. See [ElasticAPM.start](/reference/api-reference.md#api-agent-start).

data/docs/{getting-started-rack.asciidoc → reference/getting-started-rack.md}

@@ -1,31 +1,26 @@
-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::[]
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/getting-started-rack.html
+---
 
-[[getting-started-rack]]
-=== Getting started with Rack
+# Getting started with Rack [getting-started-rack]
 
 Add the gem to your `Gemfile`:
 
-[source,ruby]
-----
+```ruby
 gem 'elastic-apm'
-----
+```
 
 Create a file `config/elastic_apm.yml`:
 
-[source,yaml]
-----
+```yaml
 server_url: http://localhost:8200
 secret_token: ''
-----
+```
 
 Include the middleware, start (and stop) Elastic APM when booting your app:
 
-[source,ruby]
-----
+```ruby
 # config.ru
 
 app = lambda do |env|
@@ -43,21 +38,19 @@ 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]
-----
+## Sinatra example [getting-started-sinatra]
+
+```ruby
 # Example config.ru
 
 require 'sinatra/base'
 
 class MySinatraApp < Sinatra::Base
   use ElasticAPM::Middleware
-  
+
   # ...
 end
 
@@ -70,14 +63,12 @@ ElasticAPM.start(app: MySinatraApp, ...)
 run MySinatraApp
 
 at_exit { ElasticAPM.stop }
-----
+```
+
 
-[float]
-[[getting-started-grape]]
-==== Grape example
+## Grape example [getting-started-grape]
 
-[source,ruby]
-----
+```ruby
 # Example config.ru
 
 require 'grape'
@@ -94,5 +85,5 @@ end
 ElasticAPM::Grape.start(Twitter::API, config)
 
 run Twitter::API
+```
 
-----

data/docs/reference/getting-started-rails.md

@@ -0,0 +1,27 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/getting-started-rails.html
+---
+
+# Getting started with Rails [getting-started-rails]
+
+
+## Setup [_setup]
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem 'elastic-apm'
+```
+
+Create a file `config/elastic_apm.yml`:
+
+```yaml
+server_url: http://localhost:8200
+secret_token: ''
+```
+
+Or if you prefer environment variables, skip the file and set `ELASTIC_APM_SERVER_URL` and `ELASTIC_APM_SECRET_TOKEN` in your local or server environment.
+
+This automatically sets up error logging and performance tracking but of course there are knobs to turn if you’d like to. See [*Configuration*](/reference/configuration.md).
+

data/docs/reference/graphql.md

@@ -0,0 +1,21 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/graphql.html
+---
+
+# GraphQL [graphql]
+
+The agent comes with support for GraphQL based APIs.
+
+This slightly alters how transactions are named when they relate to GraphQL queries, so they are easier to tell apart and debug.
+
+To enable GraphQL support, add the included Tracer to your schema:
+
+```ruby
+class MySchema < GraphQL::Schema
+  # ...
+
+  tracer ElasticAPM::GraphQL # <-- include this
+end
+```
+

data/docs/reference/index.md

@@ -0,0 +1,24 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/introduction.html
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/index.html
+---
+
+# APM Ruby agent [introduction]
+
+The Elastic APM Ruby Agent sends performance metrics and error logs to the APM Server. It has built-in support for [Ruby on Rails](/reference/getting-started-rails.md) and other [Rack-compatible](/reference/getting-started-rack.md) applications. It also offers an API which allows you to instrument any application.
+
+
+## How does the Agent work? [how-it-works]
+
+The agent auto-instruments [supported technologies](/reference/supported-technologies.md) 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.
+
+
+## Additional Components [additional-components]
+
+APM Agents work in conjunction with the [APM Server](docs-content://solutions/observability/apps/application-performance-monitoring-apm.md), [Elasticsearch](docs-content://get-started/index.md), and [Kibana](docs-content://get-started/the-stack.md). The [APM Guide](docs-content://solutions/observability/apps/application-performance-monitoring-apm.md) provides details on how these components work together, and provides a matrix outlining [Agent and Server compatibility](docs-content://solutions/observability/apps/apm-agent-compatibility.md).
+

data/docs/{logs.asciidoc → reference/logs.md}

@@ -1,40 +1,32 @@
-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::[]
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/log-correlation.html
+---
 
-[[logs]]
-== Logs
+# Logs [logs]
 
 Elastic Ruby APM Agent provides the following log features:
 
-- <<log-correlation-ids>>: Automatically inject correlation IDs that allow navigation between logs, traces and services.
-- <<log-reformatting>>: Automatically reformat plaintext logs in {ecs-logging-ref}/intro.html[ECS logging] format.
+* [Log correlation](#log-correlation-ids): Automatically inject correlation IDs that allow navigation between logs, traces and services.
+* [Log reformatting (experimental)](#log-reformatting): Automatically reformat plaintext logs in [ECS logging](ecs-logging://reference/intro.md) format.
 
-Those features are part of {observability-guide}/application-logs.html[Application log ingestion strategies].
+Those features are part of [Application log ingestion strategies](docs-content://solutions/observability/logs/stream-application-logs.md).
 
-The {ecs-logging-ruby-ref}/intro.html[`ecs-logging-ruby`] library can also be used to format logs in the {ecs-logging-ref}/intro.html[ECS logging] format without an APM agent.
-When deployed with the Ruby APM agent, the agent will provide <<log-correlation-ids,log correlation>> IDs.
+The [`ecs-logging-ruby`](ecs-logging-ruby://reference/index.md) library can also be used to format logs in the [ECS logging](ecs-logging://reference/intro.md) format without an APM agent. When deployed with the Ruby APM agent, the agent will provide [log correlation](#log-correlation-ids) IDs.
 
-[float]
-[[log-correlation-ids]]
-=== Log correlation
 
-{apm-guide-ref}/log-correlation.html[Log correlation] allows you to navigate to all logs belonging to a particular trace
-and vice-versa: for a specific log, see in which context it has been logged and which parameters the user provided.
+## Log correlation [log-correlation-ids]
 
+[Log correlation](docs-content://solutions/observability/apps/logs.md) allows you to navigate to all logs belonging to a particular trace and vice-versa: for a specific log, see in which context it has been logged and which parameters the user provided.
 
 Trace/log correlation can be set up in three different ways.
 
-[float]
-[[rails-tagged-logging]]
-==== Rails TaggedLogging
 
-Rails applications configured with an `ActiveSupport::TaggedLogging` logger can append the correlation IDs to log output.
-For example in your `config/environments/production.rb` file, add the following:
+### Rails TaggedLogging [rails-tagged-logging]
 
-[source,ruby]
-----
+Rails applications configured with an `ActiveSupport::TaggedLogging` logger can append the correlation IDs to log output. For example in your `config/environments/production.rb` file, add the following:
+
+```ruby
 config.log_tags = [ :request_id, proc { ElasticAPM.log_ids } ]
 
 # Logs will then include the correlation IDs:
@@ -44,19 +36,16 @@ config.log_tags = [ :request_id, proc { ElasticAPM.log_ids } ]
 # [transaction.id=c1ae84c8642891eb trace.id=b899fc7915e801b7558e336e4952bafe]   Rendering text template
 # [transaction.id=c1ae84c8642891eb trace.id=b899fc7915e801b7558e336e4952bafe]   Rendered text template (Duration: 0.1ms | Allocations: 17)
 # [transaction.id=c1ae84c8642891eb trace.id=b899fc7915e801b7558e336e4952bafe] Completed 200 OK in 1ms (Views: 0.4ms | Allocations: 171)
-----
-**Note:** Because of the order in which Rails computes the tags for logs and executes the request, the span id might not be included.
-Consider using `Lograge` instead, as the timing of its hooks allow the span id to be captured in logs.
+```
+
+**Note:** Because of the order in which Rails computes the tags for logs and executes the request, the span id might not be included. Consider using `Lograge` instead, as the timing of its hooks allow the span id to be captured in logs.
+
 
-[float]
-[[lograge]]
-==== Lograge
+### Lograge [lograge]
 
-With `lograge` enabled and set up in your Rails application, modify the `custom_options` block in the Rails environment
-configuration file. The returned `Hash` will be included in the structured Lograge logs.
+With `lograge` enabled and set up in your Rails application, modify the `custom_options` block in the Rails environment configuration file. The returned `Hash` will be included in the structured Lograge logs.
 
-[source,ruby]
-----
+```ruby
 config.lograge.custom_options = lambda do |event|
   ElasticAPM.log_ids do |transaction_id, span_id, trace_id|
     { :'transaction.id' => transaction_id,
@@ -68,12 +57,11 @@ end
 # Logs will then include the correlation IDs:
 #
 # I, [2019-09-16T11:59:05.439602 #8674]  INFO -- : method=GET path=/ format=html controller=ApplicationController action=index status=200 duration=0.36 view=0.20 transaction.id=56a9186a9257aa08 span.id=8e84a786ab0abbb2 trace.id=1bbab8ac4c7c9584f53eb882ff0dfdd8
-----
+```
 
 You can also nest the ids in a separate document as in the following example:
 
-[source,ruby]
-----
+```ruby
 config.lograge.custom_options = lambda do |event|
   ElasticAPM.log_ids do |transaction_id, span_id, trace_id|
     { elastic_apm: { :'transaction.id' => transaction_id,
@@ -85,16 +73,14 @@ end
 # Logs will then include the correlation IDs in a separate document:
 #
 # I, [2019-09-16T13:39:35.962603 #9327]  INFO -- : method=GET path=/ format=html controller=ApplicationController action=index status=200 duration=0.37 view=0.20 elastic_apm={:transaction_id=>"2fb84f5d0c48a296", :span_id=>"2e5c5a7c85f83be7", :trace_id=>"43e1941c4a6fff343a4e018ff7b92000"}
-----
+```
 
-[float]
-[[manually-formatting-logs]]
-==== Manually formatting logs
+
+### Manually formatting logs [manually-formatting-logs]
 
 You can access the correlation ids directly and add them through the log formatter.
 
-[source,ruby]
-----
+```ruby
 require 'elastic_apm'
 require 'logger'
 
@@ -111,16 +97,14 @@ end
 # [2019-09-16 11:54:59 +0200][RailsTestApp][INFO][transaction.id=3b92edcccc0a6d1e span.id=3bde4e9c85ab359c trace.id=1275686e35de91f776557637e799651e]   Rendering text template
 # [2019-09-16 11:54:59 +0200][RailsTestApp][INFO][transaction.id=3b92edcccc0a6d1e span.id=f3d7e32f176d4c93 trace.id=1275686e35de91f776557637e799651e]   Rendered text template (Duration: 0.1ms | Allocations: 17)
 # [2019-09-16 11:54:59 +0200][RailsTestApp][INFO][transaction.id=3b92edcccc0a6d1e span.id=3bde4e9c85ab359c trace.id=1275686e35de91f776557637e799651e] Completed 200 OK in 1ms (Views: 0.3ms | Allocations: 187)
-----
+```
+
 
-[float]
-==== Extracting trace IDs from the logs
+### Extracting trace IDs from the logs [_extracting_trace_ids_from_the_logs]
 
-For log correlation to work, the trace IDs must be extracted from the log message and stored in separate fields in the Elasticsearch document. There are many ways to achieve this, for example by using ingest node and defining a pipeline with a grok processor.
-You can extract the trace id from the Lograge output generated above like this:
+For log correlation to work, the trace IDs must be extracted from the log message and stored in separate fields in the Elasticsearch document. There are many ways to achieve this, for example by using ingest node and defining a pipeline with a grok processor. You can extract the trace id from the Lograge output generated above like this:
 
-[source,json]
-----
+```json
 PUT _ingest/pipeline/extract_trace_id
 {
   "description": "Extract trace id from Lograge logs",
@@ -134,15 +118,13 @@ PUT _ingest/pipeline/extract_trace_id
     }
   ]
 }
-----
+```
 
-Please see {apm-guide-ref}/log-correlation.html[Observability integrations] for more information.
+Please see [Observability integrations](docs-content://solutions/observability/apps/logs.md) for more information.
 
-[float]
-[[log-reformatting]]
-=== Log reformatting (experimental)
 
-Log reformatting is controlled by the <<config-log-ecs-formatting, `log_ecs_reformatting`>> configuration option, and is disabled by default.
+## Log reformatting (experimental) [log-reformatting]
 
-The reformatted logs will include both the <<log-correlation-ids, trace and service correlation>> IDs.
+Log reformatting is controlled by the [`log_ecs_reformatting`](/reference/configuration.md#config-log-ecs-formatting) configuration option, and is disabled by default.
 
+The reformatted logs will include both the [trace and service correlation](#log-correlation-ids) IDs.

data/docs/reference/metrics.md

@@ -0,0 +1,199 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/metrics.html
+---
+
+# Metrics [metrics]
+
+The Ruby agent tracks various system and application metrics. These metrics will be sent regularly to the APM Server and from there to Elasticsearch. You can adjust the interval by setting [`metrics_interval`](/reference/configuration.md#config-metrics-interval).
+
+The metrics will be stored in the `apm-*` index and have the `processor.event` property set to `metric`.
+
+
+## System metrics [metrics-system]
+
+**Note:** Metrics from the Ruby agent are Linux only for now.
+
+
+### `system.cpu.total.norm.pct` [metric-system.cpu.total.norm.pct]
+
+* **Type:** Float
+* **Format:** Percent
+
+The percentage of CPU time in states other than Idle and IOWait, normalised by the number of cores.
+
+
+### `system.memory.total` [metric-system.memory.total]
+
+* **Type:** Long
+* **Format:** Bytes
+
+The total memory of the system in bytes.
+
+
+### `system.memory.actual.free` [metric-system.memory.actual.free]
+
+* **Type:** Long
+* **Format:** Bytes
+
+Free memory of the system in bytes.
+
+
+### `system.process.cpu.total.norm.pct` [metric-system.process.cpu.total.norm.pct]
+
+* **Type:** Float
+* **Format:** Percent
+
+The percentage of CPU time spent by the process since the last event. This value is normalized by the number of CPU cores and it ranges from 0 to 100%.
+
+
+### `system.process.memory.size` [metric-system.process.memory.size]
+
+* **Type:** Long
+* **Format:** Bytes
+
+The total virtual memory the process has.
+
+
+### `system.process.memory.rss.bytes` [metric-system.process.memory.rss.bytes]
+
+* **Type:** Long
+* **Format:** Bytes
+
+The Resident Set Size, the amount of memory the process occupies in main memory (RAM).
+
+
+## Ruby Metrics [metrics-ruby]
+
+
+### `ruby.gc.count` [metric-ruby.gc.counts]
+
+* **Type:** Integer
+* **Format:** Count
+
+The number of Garbage Collection runs since the process started.
+
+
+### `ruby.threads` [metric-ruby.threads]
+
+* **Type:** Integer
+* **Format:** Count
+
+The number of threads belonging to the current process.
+
+
+### `ruby.heap.slots.live` [metric-ruby.heap.slots.live]
+
+* **Type:** Integer
+* **Format:** Slots
+
+Current amount of heap slots that are live.
+
+**NB:** Not currently supported on JRuby.
+
+
+### `ruby.heap.slots.free` [metric-ruby.heap.slots.free]
+
+* **Type:** Integer
+* **Format:** Slots
+
+Current amount of heap slots that are free.
+
+**NB:** Not currently supported on JRuby.
+
+
+### `ruby.heap.allocations.total` [metrics-ruby.heap.allocations.total]
+
+* **Type:** Integer
+* **Format:** Objects
+
+Current amount of allocated objects on the heap.
+
+**NB:** Not currently supported on JRuby.
+
+
+### `ruby.gc.time` [metrics-ruby.gc.time]
+
+* **Type:** Float
+* **Format:** Seconds
+
+The total time spent in garbage collection.
+
+**NB:** You need to enable Ruby’s GC Profiler for this to get reported. You can do this at any time when your application boots by calling `GC::Profiler.enable`.
+
+
+## JVM Metrics [metrics-jvm-metrics]
+
+The following metrics are available when using JRuby. They use the ruby java API to gather metrics via MXBean.
+
+
+### `jvm.memory.heap.used` [metric-jvm.memory.heap.used]
+
+* **Type:** Long
+* **Format:** Bytes
+
+The amount of used heap memory in bytes.
+
+
+### `jvm.memory.heap.committed` [metric-jvm.memory.heap.committed]
+
+* **Type:** Long
+* **Format:** Bytes
+
+The amount of heap memory in bytes that is committed for the Java virtual machine to use. This amount of memory is guaranteed for the Java virtual machine to use.
+
+
+### `jvm.memory.heap.max` [metric-jvm.memory.heap.max]
+
+* **Type:** Long
+* **Format:** Bytes
+
+The amount of heap memory in bytes that is committed for the Java virtual machine to use. This amount of memory is guaranteed for the Java virtual machine to use.
+
+
+### `jvm.memory.non_heap.used` [metric-jvm.memory.non_heap.used]
+
+* **Type:** Long
+* **Format:** Bytes
+
+The amount of used non-heap memory in bytes.
+
+
+### `jvm.memory.non_heap.committed` [metric-jvm.memory.non_heap.committed]
+
+* **Type:** Long
+* **Format:** Bytes
+
+The amount of non-heap memory in bytes that is committed for the Java virtual machine to use. This amount of memory is guaranteed for the Java virtual machine to use.
+
+
+### `jvm.memory.non_heap.max` [metric-jvm.memory.non_heap.max]
+
+* **Type:** Long
+* **Format:** Bytes
+
+The maximum amount of non-heap memory in bytes that can be used for memory management. If the maximum memory size is undefined, the value is -1.
+
+
+### `jvm.memory.heap.pool.used` [metric-jvm.memory.heap.pool.used]
+
+* **Type:** Long
+* **Format:** Bytes
+
+The amount of used memory in bytes of the memory pool.
+
+
+### `jvm.memory.heap.pool.committed` [metric-jvm.memory.heap.pool.committed]
+
+* **Type:** Long
+* **Format:** Bytes
+
+The amount of memory in bytes that is committed for the memory pool. This amount of memory is guaranteed for this specific pool.
+
+
+### `jvm.memory.heap.pool.max` [metric-jvm.memory.heap.pool.max]
+
+* **Type:** Long
+* **Format:** Bytes
+
+The maximum amount of memory in bytes that can be used for the memory pool.