docs(rails): explain disabling agent, fixes #1466

docs/reference/getting-started-rails.md

@@ -31,3 +31,17 @@
 
 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`.

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