elastic-apm 4.7.3 → 4.8.0

data/docs/custom-instrumentation.asciidoc

@@ -1,80 +0,0 @@
-[[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 <<api-agent-start_transaction,`ElasticAPM.start_transaction`>> and
-<<api-agent-start_span,`ElasticAPM.start_span`>>.
-
-[float]
-==== Helpers
-
-ElasticAPM includes some nifty helpers if you just want to instrument a regular
-method.
-
-[source,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
-----
-
-[float]
-==== 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:
-
-[source,ruby]
-----
-class ThingsController < ApplicationController
-  def index
-    @result_of_work = ElasticAPM.with_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.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 <<api-agent-start,ElasticAPM.start>>.

data/docs/debugging.asciidoc

@@ -1,44 +0,0 @@
-[[debugging]]
-== Troubleshooting
-
-Hopefully the agent Just Works™, but depending on your situation the agent might need some tuning.
-
-First, to learn more about what's going on inside the agent, you can increase the amount of log messages it writes. To do this, set the log level with the option `log_level = 0` -- `0` being the level of most messages, `DEBUG`.
-
-In your `config/elastic_apm.yml`:
-
-[source,yaml]
-----
-log_level: <%= Logger::DEBUG %>
-----
-
-[float]
-[[debugging-log-messages]]
-=== Log messages
-
-[float]
-[[debugging-errors-queue-full]]
-==== `Queue is full (256 items), skipping…`
-
-The agent has an internal queue that holds events after they are done, and before they are safely serialized and sent to APM Server. To avoid using up all of your memory, this queue has a fixed size. Depending on your load and server setup, events may be added to the queue faster than they are consumed, hence the warning.
-
-Things to consider:
-
-  - Is `server_url` misconfigured or APM Server down? If the agent fails to connect you will also see log messages containing `Connection error` or `Couldn't establish connection to APM Server`.
-  - Experiencing high load? The agent can spawn multiple instances of its Workers that pick off the queue by changing the option `pool_size` (default is `1`).
-  - If you have high load you may also consider setting `transaction_sample_rate` to something smaller than `1.0`. This determines whether to include _spans_ for every _transaction_. If you have enough traffic, skipping some (probably) identical spans won't have a noticeable effect on your data.
-
-[float]
-[[disable-agent]]
-=== Disable the Agent
-
-In the unlikely event the agent causes disruptions to a production application,
-you can disable the agent while you troubleshoot.
-
-If you have access to <<dynamic-configuration,dynamic configuration>>,
-you can disable the recording of events by setting <<config-recording,`recording`>> to `false`.
-When changed at runtime from a supported source, there's no need to restart your application.
-
-If that doesn't work, or you don't have access to dynamic configuration, you can disable the agent by setting
-<<config-enabled,`enabled`>> to `false`.
-You'll need to restart your application for the changes to apply.

data/docs/getting-started-rails.asciidoc

@@ -1,30 +0,0 @@
-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
-
-[float]
-==== Setup
-
-Add the gem to your `Gemfile`:
-
-[source,ruby]
-----
-gem 'elastic-apm'
-----
-
-Create a file `config/elastic_apm.yml`:
-
-[source,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>>.

data/docs/graphql.asciidoc

@@ -1,23 +0,0 @@
-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::[]
-
-[[graphql]]
-== GraphQL (experimental)
-
-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:
-
-[source,ruby]
-----
-class MySchema < GraphQL::Schema
-  # ...
-
-  tracer ElasticAPM::GraphQL # <-- include this
-end
-----

data/docs/index.asciidoc

@@ -1,38 +0,0 @@
-include::{asciidoc-dir}/../../shared/versions/stack/current.asciidoc[]
-include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
-
-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
-
-include::./introduction.asciidoc[]
-
-include::./set-up.asciidoc[]
-
-include::./supported-technologies.asciidoc[]
-
-include::./configuration.asciidoc[]
-
-include::./advanced.asciidoc[]
-
-include::./api.asciidoc[]
-
-include::./metrics.asciidoc[]
-
-include::./logs.asciidoc[]
-
-include::./opentracing.asciidoc[]
-
-include::./graphql.asciidoc[]
-
-include::./performance-tuning.asciidoc[]
-
-include::./debugging.asciidoc[]
-
-include::./upgrading.asciidoc[]
-
-include::./release-notes.asciidoc[]

data/docs/introduction.asciidoc

@@ -1,36 +0,0 @@
-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
-
-The Elastic APM Ruby Agent sends performance metrics and error logs to the APM Server.
-It has built-in support for <<getting-started-rails,Ruby on Rails>> and other
-<<getting-started-rack,Rack-compatible>> applications.
-It also offers an API which allows you to instrument any application.
-
-[float]
-[[how-it-works]]
-=== How does the Agent work?
-
-The agent auto-instruments <<supported-technologies,supported technologies>> and records interesting events,
-like HTTP requests and database queries. To do this, it uses relevant public APIs when they are provided by the libraries. Otherwise, it carefully wraps the necessary internal methods.
-This means that for the supported technologies, there are no code changes required.
-
-The Agent automatically keeps track of queries to your data stores to measure their duration and metadata (like the DB statement),
-as well as HTTP related information (like the URL, parameters, and headers).
-
-These events, called Transactions and Spans, are sent to the APM Server.
-The APM Server converts them to a format suitable for Elasticsearch, and sends them to an Elasticsearch cluster.
-You can then use the APM app in Kibana to gain insight into latency issues and error culprits within your application.
-
-[float]
-[[additional-components]]
-=== Additional Components
-
-APM Agents work in conjunction with the {apm-guide-ref}/index.html[APM Server], {ref}/index.html[Elasticsearch], and {kibana-ref}/index.html[Kibana].
-The {apm-guide-ref}/index.html[APM Guide] provides details on how these components work together,
-and provides a matrix outlining {apm-guide-ref}/agent-server-compatibility.html[Agent and Server compatibility].

data/docs/metrics.asciidoc

@@ -1,235 +0,0 @@
-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::[]
-
-[[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 <<config-metrics-interval,`metrics_interval`>>.
-
-The metrics will be stored in the `apm-*` index and have the `processor.event` property set to `metric`.
-
-[float]
-[[metrics-system]]
-=== System metrics
-
-**Note:** Metrics from the Ruby agent are Linux only for now.
-
-[float]
-[[metric-system.cpu.total.norm.pct]]
-==== `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.
-
-[float]
-[[metric-system.memory.total]]
-==== `system.memory.total`
-
-* *Type:* Long
-* *Format:* Bytes
-
-The total memory of the system in bytes.
-
-[float]
-[[metric-system.memory.actual.free]]
-==== `system.memory.actual.free`
-
-* *Type:* Long
-* *Format:* Bytes
-
-Free memory of the system in bytes.
-
-[float]
-[[metric-system.process.cpu.total.norm.pct]]
-==== `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%.
-
-[float]
-[[metric-system.process.memory.size]]
-==== `system.process.memory.size`
-
-* *Type:* Long
-* *Format:* Bytes
-
-The total virtual memory the process has.
-
-[float]
-[[metric-system.process.memory.rss.bytes]]
-==== `system.process.memory.rss.bytes`
-
-* *Type:* Long
-* *Format:* Bytes
-
-The Resident Set Size,
-the amount of memory the process occupies in main memory (RAM).
-
-[float]
-[[metrics-ruby]]
-=== Ruby Metrics
-
-[float]
-[[metric-ruby.gc.counts]]
-==== `ruby.gc.count`
-
-* *Type:* Integer
-* *Format:* Count
-
-The number of Garbage Collection runs since the process started.
-
-[float]
-[[metric-ruby.threads]]
-==== `ruby.threads`
-
-* *Type:* Integer
-* *Format:* Count
-
-The number of threads belonging to the current process.
-
-[float]
-[[metric-ruby.heap.slots.live]]
-==== `ruby.heap.slots.live`
-
-* *Type:* Integer
-* *Format:* Slots
-
-Current amount of heap slots that are live.
-
-**NB:** Not currently supported on JRuby.
-
-[float]
-[[metric-ruby.heap.slots.free]]
-==== `ruby.heap.slots.free`
-
-* *Type:* Integer
-* *Format:* Slots
-
-Current amount of heap slots that are free.
-
-**NB:** Not currently supported on JRuby.
-
-[float]
-[[metrics-ruby.heap.allocations.total]]
-==== `ruby.heap.allocations.total`
-
-* *Type:* Integer
-* *Format:* Objects
-
-Current amount of allocated objects on the heap.
-
-**NB:** Not currently supported on JRuby.
-
-[float]
-[[metrics-ruby.gc.time]]
-==== `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`.
-
-[float]
-[[metrics-jvm-metrics]]
-=== JVM Metrics
-
-The following metrics are available when using JRuby. They use the ruby java API to gather metrics via MXBean.
-
-[float]
-[[metric-jvm.memory.heap.used]]
-==== `jvm.memory.heap.used`
-
-* *Type:* Long
-* *Format:* Bytes
-
-The amount of used heap memory in bytes.
-
-[float]
-[[metric-jvm.memory.heap.committed]]
-==== `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.
-
-[float]
-[[metric-jvm.memory.heap.max]]
-==== `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.
-
-[float]
-[[metric-jvm.memory.non_heap.used]]
-==== `jvm.memory.non_heap.used`
-
-* *Type:* Long
-* *Format:* Bytes
-
-The amount of used non-heap memory in bytes.
-
-[float]
-[[metric-jvm.memory.non_heap.committed]]
-==== `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.
-
-[float]
-[[metric-jvm.memory.non_heap.max]]
-==== `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.
-
-[float]
-[[metric-jvm.memory.heap.pool.used]]
-==== `jvm.memory.heap.pool.used`
-
-* *Type:* Long
-* *Format:* Bytes
-
-The amount of used memory in bytes of the memory pool.
-
-[float]
-[[metric-jvm.memory.heap.pool.committed]]
-==== `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.
-
-[float]
-[[metric-jvm.memory.heap.pool.max]]
-==== `jvm.memory.heap.pool.max`
-
-* *Type:* Long
-* *Format:* Bytes
-
-The maximum amount of memory in bytes that can be used for the memory pool.

data/docs/opentracing.asciidoc

@@ -1,94 +0,0 @@
-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 API
-
-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 app
-- `user.email` - sets the user email,
-  appears in the "User" tab in the transaction details in the Elastic APM app
-- `user.username` - sets the user name,
-  appears in the "User" tab in the transaction details in the Elastic APM app
-- `result` - sets the result of the transaction. Overrides the default value of `success`.
-  If the `error` tag is set to `true`, the default value is `error`.
-
-[float]
-[[unsupported]]
-== Caveats
-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]
-[[opentracing-logs]]
-=== Logs
-Logs are currently not supported.

data/docs/performance-tuning.asciidoc

@@ -1,106 +0,0 @@
-[[tuning-and-overhead]]
-== Performance tuning
-
-Using any APM solution comes with trade-offs, and the Elastic APM Ruby Agent is no different.
-Instrumenting your code, using timers, recording context data, etc., uses resources—for example:
-
-* CPU time
-* Memory
-* Bandwidth
-* Elasticsearch storage
-
-We invest a lot of effort to ensure that the Ruby Agent is suitable for production code
-and that its overhead remains as low as possible.
-However, because every application is different, there are some knobs you can turn and tweak to adapt the Agent to your specific needs.
-
-[float]
-[[tuning-sample-rate]]
-=== Transaction sample rate
-
-By default, the Agent samples every transaction.
-The easiest way to reduce both the overhead of the agent and storage requirements,
-is to tell it to do less, i.e., sample fewer transactions.
-To do this, set the <<config-transaction-sample-rate,`transaction_sample_rate`>>
-to a value between `0.0` and `1.0`—the percentage of transactions you'd like to randomly sample.
-The Agent will still record the overall time and result of unsampled transactions,
-but not context information, tags, or spans.
-
-[float]
-[[tuning-frame-context]]
-=== Collecting frame context
-
-The Agent automatically captures several lines of source code around each frame location in the stack trace.
-This enables the APM app to provide greater insight into exactly where an error or span is occurring in your code.
-This insight does come at a cost—in terms of performance, stack trace collection is the most expensive thing the Agent does.
-
-There are settings you can modify to control this behavior:
-
-1. Disable stack trace frame collection for short-duration spans by setting
-<<config-span-frames-min-duration-ms,`span_frames_min_duration`>> to `0`.
-
-2. Modify the number of source code lines collected.
-These settings are divided between app frames, which represent your application code,
-and library frames, which represent the code of your dependencies.
-Each of these categories are further split into separate error and span settings.
-+
-* <<config-source-lines-error-app-frames, `source_lines_error_app_frames`>>
-* <<config-source-lines-error-library-frames,`source_lines_error_library_frames`>>
-* <<config-source-lines-span-app-frames,`source_lines_span_app_frames`>>
-* <<config-source-lines-span-library-frames,`source_lines_span_library_frames`>>
-
-3. If you're using the API to create a custom span, you can disable stack trace collection with the
-<<api-agent-start_span,`include_stacktrace` argument>>.
-
-Reading source files inside a running application can cause a lot of disk I/O,
-and sending up source lines for each frame will have a network and storage cost that is quite high.
-Turning these limits down will prevent storing excessive amounts of data in Elasticsearch.
-
-[float]
-[[tuning-queue]]
-=== Transaction queue
-
-The Agent does not send every transaction as it happens.
-Instead, to reduce load on the APM Server, the Agent uses a queue.
-The queue is flushed periodically, or when it reaches a maximum size.
-
-While this reduces the load on the APM Server, holding on to transaction data in a queue uses memory.
-If you notice a large increase in memory use, try adjusting these settings:
-
- * <<config-api-request-time,`api_request_time`>> to reduce the duration of a single streaming request.
- This setting is helpful if you have a sustained high number of transactions.
- * <<config-api-request-size,`api_request_size`>> to reduce the maximum size of one request.
- This setting can help if you experience transaction peaks (a large number in a short period of time).
-
-Keep in mind that reducing the value of either setting will cause the agent to send more HTTP requests to the APM Server,
-potentially causing a higher load.
-
-[float]
-[[tuning-max-spans]]
-=== Spans per transaction
-
-The number of spans per transaction will influence both how much time the agent spends in each transaction collecting contextual data,
-and how much storage space is needed in Elasticsearch.
-In our experience, most _usual_ transactions should have well below 100 spans.
-In some cases, however, the number of spans can explode—for example:
-
-* Long-running transactions
-* Unoptimized code, e.g., doing hundreds of SQL queries in a loop
-
-To avoid these edge cases which overload both the Agent and the APM Server,
-the Agent will stop recording spans when a specified limit is reached.
-This limit is configurable with <<config-transaction-max-spans,`transaction_max_spans`>>.
-
-[float]
-[[tuning-body-headers]]
-=== Capturing headers and request body
-
-You can configure the Agent to capture headers and request bodies with
-<<config-capture-headers,`capture_headers`>> and <<config-capture-body,`capture_body`>>.
-By default, headers are captured and request bodies are not.
-
-Depending on the nature of your POST requests, capturing request bodies for transactions may introduce noticeable overhead,
-as well as increased storage use.
-In most scenarios, we advise against enabling request body capturing for transactions, and only enabling it if necessary for errors.
-
-Capturing request/response headers has less overhead on the agent than capturing request bodies,
-but can have an impact on storage use.

data/docs/redirects.asciidoc

@@ -1,9 +0,0 @@
-["appendix",role="exclude",id="redirects"]
-= Deleted pages
-
-The following pages have moved or been deleted.
-
-[role="exclude",id="log-correlation"]
-=== Log correlation
-
-This section has moved. See <<logs>>.