From 758349494616825c869badfd55ed16047d7c4b4b Mon Sep 17 00:00:00 2001 From: Werner Robitza Date: Mon, 27 Jul 2026 09:23:47 +0200 Subject: [PATCH] docs(rails): explain disabling agent, fixes #1466 The option to enable the agent dynamically was always present but not documented everywhere, and not tested either. --- docs/reference/getting-started-rails.md | 14 ++++++++++++++ spec/elastic_apm/rails_spec.rb | 16 ++++++++++++++++ 2 files changed, 30 insertions(+) diff --git a/docs/reference/getting-started-rails.md b/docs/reference/getting-started-rails.md index d80549b3c..b0a027618 100644 --- a/docs/reference/getting-started-rails.md +++ b/docs/reference/getting-started-rails.md @@ -31,3 +31,17 @@ Or if you prefer environment variables, skip the file and set `ELASTIC_APM_SERVE 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). +To load the gem without starting the agent in a particular Rails environment, +set [`enabled`](/reference/configuration.md#config-enabled) to `false`. +For example, to start the agent only in production, use ERB in +`config/elastic_apm.yml`: + +```yaml +enabled: <%= Rails.env.production? %> +server_url: http://localhost:8200 +secret_token: '' +``` + +You can also set `ELASTIC_APM_ENABLED=false` in an environment where the agent +should not start. The `ElasticAPM` API remains available when the agent is +disabled, but calls that collect data return `nil`. diff --git a/spec/elastic_apm/rails_spec.rb b/spec/elastic_apm/rails_spec.rb index 8dcf32adc..7b0de65d9 100644 --- a/spec/elastic_apm/rails_spec.rb +++ b/spec/elastic_apm/rails_spec.rb @@ -30,6 +30,22 @@ ElasticAPM.stop end end + + it "doesn't start the agent when disabled by config" do + ElasticAPM::Rails.start(enabled: false) + + expect(ElasticAPM.agent).to be nil + expect(ElasticAPM).to_not be_running + end + + it "doesn't start the agent when disabled by the environment" do + with_env('ELASTIC_APM_ENABLED' => 'false') do + ElasticAPM::Rails.start({}) + + expect(ElasticAPM.agent).to be nil + expect(ElasticAPM).to_not be_running + end + end end describe 'Rails console' do