elastic-apm 4.7.3 → 4.9.0

data/docs/reference/metrics.md

@@ -0,0 +1,205 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/metrics.html
+applies_to:
+  stack:
+  serverless:
+    observability:
+  product:
+    apm_agent_ruby: ga
+---
+
+# 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.

data/docs/reference/opentracing-api.md

@@ -0,0 +1,76 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/opentracing.html
+applies_to:
+  stack:
+  serverless:
+    observability:
+  product:
+    apm_agent_ruby: ga
+---
+
+# OpenTracing API [opentracing]
+
+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`.
+
+
+## Operation Modes [operation-modes]
+
+This bridge allows for different operation modes in combination with the Elastic APM Agent.
+
+* Noop<br> If no Elastic APM agent is running, the bridge is in noop mode and does not actually record and report spans.
+* Mix and Match<br> 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<br> 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 [`instrument`](/reference/configuration.md#config-instrument) to `false`.
+
+
+## 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'`.
+
+
+## Set Elastic APM as the global tracer [init-tracer]
+
+```ruby
+::OpenTracing.global_tracer = ElasticAPM::OpenTracing::Tracer.new
+```
+
+
+## Elastic APM specific tags [elastic-apm-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`.
+
+
+## Caveats [unsupported]
+
+Not all features of the OpenTracing API are supported.
+
+
+### Context propagation [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.
+
+
+### Span References [references]
+
+Currently, this bridge only supports `child_of` references. Other references, like `follows_from` are not supported yet.
+
+
+### Baggage [baggage]
+
+The `Span.set_baggage` method is not supported. Baggage items are dropped with a warning log message.
+
+
+### Logs [opentracing-logs]
+
+Logs are currently not supported.
+

data/docs/reference/performance-tuning.md

@@ -0,0 +1,77 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/tuning-and-overhead.html
+applies_to:
+  stack:
+  serverless:
+    observability:
+  product:
+    apm_agent_ruby: ga
+---
+
+# Performance tuning [tuning-and-overhead]
+
+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.
+
+
+## Transaction sample rate [tuning-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 [`transaction_sample_rate`](/reference/configuration.md#config-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.
+
+
+## Collecting frame context [tuning-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 [`span_frames_min_duration`](/reference/configuration.md#config-span-frames-min-duration-ms) 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.
+
+    * [`source_lines_error_app_frames`](/reference/configuration.md#config-source-lines-error-app-frames)
+    * [`source_lines_error_library_frames`](/reference/configuration.md#config-source-lines-error-library-frames)
+    * [`source_lines_span_app_frames`](/reference/configuration.md#config-source-lines-span-app-frames)
+    * [`source_lines_span_library_frames`](/reference/configuration.md#config-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 [`include_stacktrace` argument](/reference/api-reference.md#api-agent-start_span).
+
+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.
+
+
+## Transaction queue [tuning-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:
+
+* [`api_request_time`](/reference/configuration.md#config-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.
+* [`api_request_size`](/reference/configuration.md#config-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.
+
+
+## Spans per transaction [tuning-max-spans]
+
+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 [`transaction_max_spans`](/reference/configuration.md#config-transaction-max-spans).
+
+
+## Capturing headers and request body [tuning-body-headers]
+
+You can configure the Agent to capture headers and request bodies with [`capture_headers`](/reference/configuration.md#config-capture-headers) and [`capture_body`](/reference/configuration.md#config-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/reference/set-up-apm-ruby-agent.md

@@ -0,0 +1,22 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/set-up.html
+applies_to:
+  stack:
+  serverless:
+    observability:
+  product:
+    apm_agent_ruby: ga
+---
+
+# Set up the APM Ruby agent [set-up]
+
+To get you off the ground, we’ve prepared guides for setting up the Agent with different frameworks:
+
+* [Rails](/reference/getting-started-rails.md)
+* [Rack](/reference/getting-started-rack.md)
+
+For custom instrumentation, see the [*API reference*](/reference/api-reference.md).
+
+
+

data/docs/reference/supported-technologies.md

@@ -0,0 +1,134 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/supported-technologies.html
+applies_to:
+  stack:
+  serverless:
+    observability:
+  product:
+    apm_agent_ruby: ga
+---
+
+# Supported technologies [supported-technologies]
+
+The Elastic APM Ruby Agent has built-in support for many frameworks and libraries. Generally, we want to support all of the most popular libraries. If your favorite is missing, feel free to request it in an issue, or better yet, create a pull request.
+
+
+## Ruby [supported-technologies-ruby]
+
+We follow Ruby’s own maintenance policy and officially support all currently maintained versions per [Ruby Maintenance Branches](https://www.ruby-lang.org/en/downloads/branches/) < 4.0.
+
+
+## Web Frameworks and Libraries [supported-technologies-web]
+
+We have automatic support for Ruby on Rails and all Rack compatible web frameworks.
+
+We test against all supported minor versions of Rails, Sinatra, and Grape.
+
+
+### Ruby on Rails [supported-technologies-rails]
+
+We currently support Rails >= 4.2 <= 7.2. This follows Rails' own [Security policy](https://rubyonrails.org/security/).
+
+See [Getting started with Rails](/reference/getting-started-rails.md).
+
+
+### Sinatra [supported-technologies-sinatra]
+
+We currently support Sinatra >= 1.0 <= 2.2.
+
+See [Getting started with Rack](/reference/getting-started-rack.md).
+
+
+### Grape [supported-technologies-grape]
+
+We currently support Grape >= 1.2 <= 1.6.
+
+See [Grape example](/reference/getting-started-rack.md#getting-started-grape).
+
+
+## Databases [supported-technologies-databases]
+
+We automatically instrument database actions using:
+
+* ActiveRecord (>= 4.2 <= 7.2)
+* DynamoDB (>= 1.0 <= 1.158.0)
+* Elasticsearch (>= 0.9 <= 9.2.0)
+* Mongo (>= 2.1 <= 2.22.0)
+* Redis (>= 3.1 <= 5.4.1)
+* Sequel (>= 4.35 <= 5.100.0)
+
+
+## External HTTP requests [supported-technologies-http]
+
+We automatically instrument and add support for distributed tracing to external requests using these libraries:
+
+* `net/http`
+* Http.rb (>= 3.0 < 6.0)
+* Faraday (>= 0.2.1 <= 2.14.0)
+
+**Note:** These libraries usually assume `localhost` if no `Host` is specified, so the agent does as well.
+
+
+## Background Processing [supported-technologies-backgroud-processing]
+
+We automatically instrument background processing using:
+
+* DelayedJob (<= 4.2.0)
+* Sidekiq (<= 8.1.0)
+* Shoryuken (<= 6.2.1)
+* Sneakers (2.12.0) (Experimental, see [#676](https://github.com/elastic/apm-agent-ruby/pull/676))
+* Resque (>= 2.0.0 <= 2.7.0)
+* SuckerPunch (>= 2.0.0 <= 3.3.0)
+
+
+## Resque [supported-technologies-resque]
+
+To make the agent work with Resque, you need to require `elastic_apm/resque` before you boot your Resque worker process.
+
+For example in your `Rakefile`:
+
+```ruby
+require 'resque'
+require 'elastic_apm'
+require 'elastic_apm/resque'
+```
+
+When you start Resque, you should see a series of messages like the following in the Resque logs:
+
+```ruby
+I, [XXX #81227]  INFO -- : Starting worker main
+D, [XXX #81227] DEBUG -- : Registered signals
+I, [XXX #81227]  INFO -- : Running before_first_fork hooks
+D, [XXX #81227] DEBUG -- : Starting ElasticAPM agent
+```
+
+Also be sure to set the Resque environment variable `RUN_AT_EXIT_HOOKS` to `true`. Otherwise, the fork may be terminated before the agent has a chance to send all the fork’s events to the APM server.
+
+
+## SuckerPunch [supported-technologies-sucker-punch]
+
+Asynchronously executed jobs in SuckerPunch are automatically instrumented.
+
+Note that errors raised in the user-defined `JobClass#perform` method will be first handled by the SuckerPunch exception handler before being handled by the agent. The handler is accessed/set via `SuckerPunch.exception_handler` in version 2.0. The agent transaction will be marked as successful unless you re-raise the error in the exception handler. You can also explicitly report the error via [`ElasticAPM.report`](/reference/api-reference.md#api-agent-report) in a custom SuckerPunch exception handler.
+
+
+## gRPC [supported-technologies-grpc]
+
+We automatically instrument gRPC using the `grpc` gem. Note that this is experimental, as the `grpc` gem’s support for `Interceptors` is experimental as of version 1.27.0.
+
+To instrument a client, add the `ElasticAPM::GRPC::ClientInterceptor` as an `interceptor` at Stub creation.
+
+```ruby
+Helloworld::Greeter::Stub.new(
+  'localhost:50051',
+  interceptors: [ElasticAPM::GRPC::ClientInterceptor.new]
+)
+```
+
+To instrument a server, add the `ElasticAPM::GRPC::ServerInterceptor`.
+
+```ruby
+GRPC::RpcServer.new(interceptors: [ElasticAPM::GRPC::ServerInterceptor.new])
+```
+

data/docs/reference/toc.yml

@@ -0,0 +1,24 @@
+project: 'APM Ruby agent reference'
+toc:
+  - file: index.md
+  - file: set-up-apm-ruby-agent.md
+    children:
+      - file: getting-started-rails.md
+      - file: getting-started-rack.md
+  - file: supported-technologies.md
+  - file: configuration.md
+  - file: advanced-topics.md
+    children:
+      - file: context.md
+      - file: custom-instrumentation.md
+  - file: api-reference.md
+  - file: metrics.md
+  - file: logs.md
+  - file: opentracing-api.md
+  - file: graphql.md
+  # TO DO: Not available on master
+  # - file: log-correlation.md
+  - file: performance-tuning.md
+  - file: upgrading.md
+  - title: Troubleshooting
+    crosslink: docs-content://troubleshoot/observability/apm-agent-ruby/apm-ruby-agent.md

data/docs/reference/upgrading.md

@@ -0,0 +1,25 @@
+---
+mapped_pages:
+  - https://www.elastic.co/guide/en/apm/agent/ruby/current/upgrading.html
+applies_to:
+  stack:
+  serverless:
+    observability:
+  product:
+    apm_agent_ruby: ga
+---
+
+# Upgrading [upgrading]
+
+Upgrades between minor versions of the agent, like from 2.1 to 2.2 are always backwards compatible. Upgrades that involve a major version bump often come with some backwards incompatible changes.
+
+Before upgrading the agent, be sure to review the:
+
+* [Agent release notes](/release-notes/index.md)
+* [Agent and Server compatibility chart](docs-content://solutions/observability/apps/apm-agent-compatibility.md)
+
+
+## End of life dates [end-of-life-dates]
+
+We love all our products, but sometimes we must say goodbye to a release so that we can continue moving forward on future development and innovation. Our [End of life policy](https://www.elastic.co/support/eol) defines how long a given release is considered supported, as well as how long a release is considered still in active development or maintenance.
+