remaned several settings to align closer to other language agents (#145)

* removed `collect_source` setting, it is replaced by more fine grained
* settings
* renamed setting `disable_instrumentation` to `instrument` and inverted
* meaning
* remove `keyword_max_length` setting and hard-code it
* renamed `max_event_queue_length` to `max_queue_size`
* renamed source line settings variables
* renamed `timeout` to `server_timeout`
* renamed `transaction_send_frequency` to `flush_interval`

closes #145

Author: beniwohli

CHANGELOG.asciidoc

@@ -25,9 +25,9 @@ https://github.com/elastic/apm-agent-python/compare/v1.0.0\...master[Check the H
  * switched to `time.perf_counter` as timing function on Python 3 ({pull}138[#138])
  * BREAKING: Several settings and APIs have been renamed ({pull}111[#111], {pull}119[#119], {pull}143[#143]):
  ** The decorator for custom instrumentation, `elasticapm.trace`, is now `elasticapm.capture_span`
- ** The setting `traces_send_frequency` has been renamed to `transaction_send_frequency`.
+ ** The setting `traces_send_frequency` has been renamed to `flush_interval`.
      The name of the analogous environment variable changed from `ELASTIC_APM_TRACES_SEND_FREQ`
-     to `ELASTIC_APM_TRANSACTION_SEND_FREQ`
+     to `ELASTIC_APM_FLUSH_INTERVAL`
  ** The `app_name` setting has been renamed to `service_name`.
      The name of the analogous environment variable changed from `ELASTIC_APM_APP_NAME`
      to `ELASTIC_APM_SERVICE_NAME`.
@@ -39,6 +39,11 @@ https://github.com/elastic/apm-agent-python/compare/v1.0.0\...master[Check the H
  * BREAKING: added `elasticapm.set_custom_context` in favor of the more generic `set_custom_data` function ({pull}133[#133])
  * BREAKING: `include_patterns` and `exclude_patterns` now use shell globs instead of regular expressions, and
              are matched against the full path file path of the module, not against the module name ({pull}137[#137])
+ * BREAKING: renamed several configuration options to align better with other language agents ({pull}145[#145]):
+ ** `disable_instrumentation` became `instrument` and inverted its meaning
+ ** `max_event_queue_length` became `max_queue_size`
+ ** `timeout` became `server_timeout`
+
 
 [[release-1.0.0]]
 [float]

docs/configuration.asciidoc

@@ -195,13 +195,13 @@ Transactions that match any of the of the configured patterns will be ignored an
 
 
 [float]
-[[config-timeout]]
-==== `timeout`
+[[config-server-timeout]]
+==== `server_timeout`
 
 [options="header"]
 |============
-| Environment           | Django/Flask  | Default
-| `ELASTIC_APM_TIMEOUT` | `TIMEOUT`     | `5`
+| Environment                  | Django/Flask         | Default
+| `ELASTIC_APM_SERVER_TIMEOUT` | `SERVER_TIMEOUT`     | `5`
 |============
 
 A timeout in seconds.
@@ -255,7 +255,7 @@ logger.info('something happened', extra={'stack': False})
 | `ELASTIC_APM_COLLECT_LOCAL_VARIABLES` | `COLLECT_LOCAL_VARIABLES` | `errors`
 |============
 
-Possible values: `errors`, `transactions`, `all`, `none`
+Possible values: `errors`, `transactions`, `all`, `off`
 
 The Elastic APM Python agent can collect local variables for stack frames.
 By default, this is only done for errors.
@@ -288,42 +288,26 @@ With this setting, you can limit the length of resulting string.
 
 With this setting, you can limit the length of lists in local variables.
 
-[float]
-[[config-collect-source]]
-==== `collect_source`
-
-|============
-| Environment                  | Django/Flask     | Default
-| `ELASTIC_APM_COLLECT_SOURCE` | `COLLECT_SOURCE` | `all`
-|============
-
-Possible values: `errors`, `transactions`, `all`, `none`
-
-The Elastic APM Python agent can collect source code for stack frames.
-
-NOTE: collecting the source code for frames has a non-trivial overhead.
-If you notice a performance impact when running Elastic APM, changing
-this setting to `errors` can help.
 
 [float]
-[[config-source_lines_app_frames_errors]]
-==== `source_lines_app_frames_errors`
+[[config-source-lines-error-app-frames]]
+==== `source_lines_error_app_frames`
 [float]
-[[config-source_lines_app_frames_transactions]]
-==== `source_lines_app_frames_transactions`
+[[config-source-lines-span-app-frames]]
+==== `source_lines_span_app_frames`
 [float]
-[[config-source_lines_library_frames_errors]]
-==== `source_lines_library_frames_errors`
+[[config-source-lines-error-library-frames]]
+==== `source_lines_error_library_frames`
 [float]
-[[config-source_lines_library_frames_transactions]]
-==== `source_lines_library_frames_transactions`
+[[config-source-lines-span-library-frames]]
+==== `source_lines_span_library_frames`
 
 |============
-| Environment                                            | Django/Flask                               | Default
-| `ELASTIC_APM_SOURCE_LINES_APP_FRAMES_ERRORS`           | `SOURCE_LINES_APP_FRAMES_ERRORS`           | `5`
-| `ELASTIC_APM_SOURCE_LINES_APP_FRAMES_TRANSACTIONS`     | `SOURCE_LINES_APP_FRAMES_TRANSACTIONS`     | `5`
-| `ELASTIC_APM_SOURCE_LINES_LIBRARY_FRAMES_ERRORS`       | `SOURCE_LINES_LIBRARY_FRAMES_ERRORS`       | `5`
-| `ELASTIC_APM_SOURCE_LINES_LIBRARY_FRAMES_TRANSACTIONS` | `SOURCE_LINES_LIBRARY_FRAMES_TRANSACTIONS` | `0`
+| Environment                                     | Django/Flask                        | Default
+| `ELASTIC_APM_SOURCE_LINES_ERROR_APP_FRAMES`     | `SOURCE_LINES_ERROR_APP_FRAMES`     | `5`
+| `ELASTIC_APM_SOURCE_LINES_SPAN_APP_FRAMES`      | `SOURCE_LINES_SPAN_APP_FRAMES`      | `5`
+| `ELASTIC_APM_SOURCE_LINES_ERROR_LIBRARY_FRAMES` | `SOURCE_LINES_ERROR_LIBRARY_FRAMES` | `5`
+| `ELASTIC_APM_SOURCE_LINES_SPAN_LIBRARY_FRAMES`  | `SOURCE_LINES_SPAN_LIBRARY_FRAMES`  | `0`
 |============
 
 By default, the APM agent collects source code snippets for
@@ -332,20 +316,21 @@ By default, the APM agent collects source code snippets for
  * transaction spans, only for in-app frames.
 
 With the above settings, you can modify how many lines of source code is collected.
-Note however that especially for transactions, collecting source code can have a large impact on storage use in your Elasticsearch cluster.
+
+WARNING: Especially for transactions, collecting source code can have a large impact on storage use in your Elasticsearch cluster.
 
 [float]
-[[config-transaction-send-frequency]]
-==== `transaction_send_frequency`
+[[config-flush-interval]]
+==== `flush_interval`
 
 |============
-| Environment                         | Django/Flask            | Default
-| `ELASTIC_APM_TRANSACTION_SEND_FREQ` | `TRANSACTION_SEND_FREQ` | `60`
+| Environment                  | Django/Flask     | Default
+| `ELASTIC_APM_FLUSH_INTERVAL` | `FLUSH_INTERVAL` | `60`
 |============
 
 Interval with which transactions should be sent to the APM server, in seconds.
 A lower value will increase the load on your APM server,
-while a higher value can increase the memory pressure of your app.
+while a higher value can increase the memory pressure on your app.
 A higher value also impacts the time until transactions are indexed and searchable in Elasticsearch.
 
 
@@ -364,12 +349,12 @@ Setting an upper limit will prevent overloading the agent and the APM server wit
 
 
 [float]
-[[config-max-event-queue-length]]
-==== `max_event_queue_length`
+[[config-max-queue-size]]
+==== `max_queue_size`
 
 |============
-| Environment                          | Django/Flask             | Default
-| `ELASTIC_APM_MAX_EVENT_QUEUE_LENGTH` | `MAX_EVENT_QUEUE_LENGTH` | `500`
+| Environment                          | Django/Flask     | Default
+| `ELASTIC_APM_MAX_EVENT_QUEUE_LENGTH` | `MAX_QUEUE_SIZE` | `500`
 |============
 
 Maximum queue length of transactions before sending transactions to the APM server.
@@ -462,22 +447,22 @@ If set to `True`, the agent won't send any events to the APM server, independent
 
 
 [float]
-[[config-disable-instrumentation]]
-==== `disable_instrumentation`
+[[config-instrument]]
+==== `instrument`
 |============
-| Environment                 | Django/Flask   | Default
-| `ELASTIC_APM_DISABLE_INSTRUMENTATION`  | `DISABLE_INSTRUMENTATION` | `False`
+| Environment               | Django/Flask | Default
+| `ELASTIC_APM_INSTRUMENT`  | `INSTRUMENT` | `True`
 |============
 
-If set to `True`, the agent won't instrument any code.
+If set to `False`, the agent won't instrument any code.
 This disables most of the tracing functionality, but can be useful to debug possible instrumentation issues.
 
 
 [float]
 [[config-verify-server-cert]]
 ==== `verify_server_cert`
 |============
-| Environment                 | Django/Flask   | Default
+| Environment                       | Django/Flask         | Default
 | `ELASTIC_APM_VERIFY_SERVER_CERT`  | `VERIFY_SERVER_CERT` | `True`
 |============
 

elasticapm/base.py

@@ -130,20 +130,19 @@ def __init__(self, config=None, **defaults):
         self.instrumentation_store = TransactionsStore(
             lambda: self._get_stack_info_for_trace(
                 stacks.iter_stack_frames(),
-                with_source_context=self.config.collect_source in ('all', 'transactions'),
-                library_frame_context_lines=self.config.source_lines_library_frames_transactions,
-                in_app_frame_context_lines=self.config.source_lines_app_frames_transactions,
+                library_frame_context_lines=self.config.source_lines_span_library_frames,
+                in_app_frame_context_lines=self.config.source_lines_span_app_frames,
                 with_locals=self.config.collect_local_variables in ('all', 'transactions'),
                 locals_processor_func=lambda local_var: varmap(lambda k, v: shorten(
                     v,
                     list_length=self.config.local_var_list_max_length,
                     string_length=self.config.local_var_max_length,
                 ), local_var)
             ),
-            collect_frequency=self.config.transaction_send_frequency,
+            collect_frequency=self.config.flush_interval,
             sample_rate=self.config.transaction_sample_rate,
             max_spans=self.config.transaction_max_spans,
-            max_queue_length=self.config.max_event_queue_length,
+            max_queue_size=self.config.max_queue_size,
             ignore_patterns=self.config.transactions_ignore_patterns,
         )
         self.include_paths_re = stacks.get_path_regex(self.config.include_paths) if self.config.include_paths else None
@@ -245,7 +244,7 @@ def end_transaction(self, name, result=''):
             self._collect_transactions()
         if not self._send_timer:
             # send first batch of data after config._wait_to_first_send
-            self._start_send_timer(timeout=min(self.config._wait_to_first_send, self.config.transaction_send_frequency))
+            self._start_send_timer(timeout=min(self.config._wait_to_first_send, self.config.flush_interval))
         return transaction
 
     def close(self):
@@ -302,7 +301,7 @@ def _collect_transactions(self):
         self._start_send_timer()
 
     def _start_send_timer(self, timeout=None):
-        timeout = timeout or self.config.transaction_send_frequency
+        timeout = timeout or self.config.flush_interval
         self._send_timer = threading.Timer(timeout, self._collect_transactions)
         self._send_timer.start()
 
@@ -323,7 +322,7 @@ def _send_remote(self, url, data, headers=None):
                 fail_callback=self.handle_transport_fail
             )
         else:
-            url = transport.send(data, headers, timeout=self.config.timeout)
+            url = transport.send(data, headers, timeout=self.config.server_timeout)
             self.handle_transport_success(url=url)
 
     def get_service_info(self):
@@ -429,10 +428,9 @@ def _build_msg_for_logging(self, event_type, date=None, context=None, custom=Non
                 frames = stack
             frames = stacks.get_stack_info(
                 frames,
-                with_source_context=self.config.collect_source in ('errors', 'all'),
                 with_locals=self.config.collect_local_variables in ('errors', 'all'),
-                library_frame_context_lines=self.config.source_lines_library_frames_errors,
-                in_app_frame_context_lines=self.config.source_lines_app_frames_errors,
+                library_frame_context_lines=self.config.source_lines_error_library_frames,
+                in_app_frame_context_lines=self.config.source_lines_error_app_frames,
                 include_paths_re=self.include_paths_re,
                 exclude_paths_re=self.exclude_paths_re,
                 locals_processor_func=lambda local_var: varmap(lambda k, v: shorten(
@@ -530,15 +528,13 @@ def _get_transport(self, parsed_url):
         return self._transports[parsed_url]
 
     def _get_stack_info_for_trace(self, frames,
-                                  with_source_context=True,
                                   library_frame_context_lines=None,
                                   in_app_frame_context_lines=None,
                                   with_locals=True,
                                   locals_processor_func=None):
         """Overrideable in derived clients to add frames/info, e.g. templates"""
         return stacks.get_stack_info(
             frames,
-            with_source_context=with_source_context,
             library_frame_context_lines=library_frame_context_lines,
             in_app_frame_context_lines=in_app_frame_context_lines,
             with_locals=with_locals,

elasticapm/conf/__init__.py

@@ -142,10 +142,9 @@ class Config(_ConfigBase):
     include_paths = _ListConfigValue('INCLUDE_PATHS')
     exclude_paths = _ListConfigValue('EXCLUDE_PATHS', default=compat.get_default_library_patters())
     filter_exception_types = _ListConfigValue('FILTER_EXCEPTION_TYPES')
-    timeout = _ConfigValue('TIMEOUT', type=float, default=5)
+    server_timeout = _ConfigValue('SERVER_TIMEOUT', type=float, default=5)
     hostname = _ConfigValue('HOSTNAME', default=socket.gethostname())
     auto_log_stacks = _BoolConfigValue('AUTO_LOG_STACKS', default=True)
-    keyword_max_length = _ConfigValue('KEYWORD_MAX_LENGTH', type=int, default=1024)
     transport_class = _ConfigValue('TRANSPORT_CLASS', default='elasticapm.transport.http.AsyncTransport',
                                    required=True)
     processors = _ListConfigValue('PROCESSORS', default=[
@@ -156,17 +155,15 @@ class Config(_ConfigBase):
         'elasticapm.processors.sanitize_http_request_querystring',
         'elasticapm.processors.sanitize_http_request_body',
     ])
-    transaction_send_frequency = _ConfigValue('TRACES_SEND_FREQ', type=int, default=60)
+    flush_interval = _ConfigValue('FLUSH_INTERVAL', type=int, default=60)
     transaction_sample_rate = _ConfigValue('TRANSACTION_SAMPLE_RATE', type=float, default=1.0)
     transaction_max_spans = _ConfigValue('TRANSACTION_MAX_SPANS', type=int, default=500)
-    max_event_queue_length = _ConfigValue('MAX_EVENT_QUEUE_LENGTH', type=int, default=500)
+    max_queue_size = _ConfigValue('MAX_QUEUE_SIZE', type=int, default=500)
     collect_local_variables = _ConfigValue('COLLECT_LOCAL_VARIABLES', default='errors')
-    collect_source = _ConfigValue('COLLECT_SOURCE', default='all')
-    source_lines_library_frames_errors = _ConfigValue('SOURCE_LINES_LIBRARY_FRAMES_ERRORS', type=int, default=5)
-    source_lines_library_frames_transactions = _ConfigValue('SOURCE_LINES_LIBRARY_FRAMES_TRANSACTIONS', type=int,
-                                                            default=0)
-    source_lines_app_frames_errors = _ConfigValue('SOURCE_LINES_APP_FRAMES_ERRORS', type=int, default=5)
-    source_lines_app_frames_transactions = _ConfigValue('SOURCE_LINES_APP_FRAMES_TRANSACTIONS', type=int, default=5)
+    source_lines_error_library_frames = _ConfigValue('SOURCE_LINES_ERROR_LIBRARY_FRAMES', type=int, default=5)
+    source_lines_span_library_frames = _ConfigValue('SOURCE_LINES_SPAN_LIBRARY_FRAMES', type=int, default=0)
+    source_lines_error_app_frames = _ConfigValue('SOURCE_LINES_ERROR_APP_FRAMES', type=int, default=5)
+    source_lines_span_app_frames = _ConfigValue('SOURCE_LINES_SPAN_APP_FRAMES', type=int, default=5)
     local_var_max_length = _ConfigValue('LOCAL_VAR_MAX_LENGTH', type=int, default=200)
     local_var_list_max_length = _ConfigValue('LOCAL_VAR_LIST_MAX_LENGTH', type=int, default=10)
     async_mode = _BoolConfigValue('ASYNC_MODE', default=True)
@@ -176,7 +173,7 @@ class Config(_ConfigBase):
     framework_name = _ConfigValue('FRAMEWORK_NAME', default=None)
     framework_version = _ConfigValue('FRAMEWORK_VERSION', default=None)
     disable_send = _BoolConfigValue('DISABLE_SEND', default=False)
-    disable_instrumentation = _BoolConfigValue('DISABLE_INSTRUMENTATION', default=False)
+    instrument = _BoolConfigValue('DISABLE_INSTRUMENTATION', default=True)
 
     # undocumented configuration
     _wait_to_first_send = _ConfigValue('_WAIT_TO_FIRST_SEND', type=int, default=5)

elasticapm/conf/constants.py

@@ -5,3 +5,5 @@
 TRANSACTIONS_API_PATH = '/v1/transactions'
 
 TIMESTAMP_FORMAT = '%Y-%m-%dT%H:%M:%S.%fZ'
+
+KEYWORD_MAX_LENGTH = 1024

elasticapm/contrib/asyncio/client.py

@@ -21,11 +21,11 @@ def _send_remote(self, url, data, headers=None):
         transport = self._get_transport(parsed)
         loop = asyncio.get_event_loop()
         task = loop.create_task(
-            transport.send(data, headers, timeout=self.config.timeout))
+            transport.send(data, headers, timeout=self.config.server_timeout))
         task.add_done_callback(self.handle_transport_response)
 
     def _start_send_timer(self, timeout=None):
-        timeout = timeout or self.config.transaction_send_frequency
+        timeout = timeout or self.config.flush_interval
         self._send_timer = AsyncTimer(timeout, self._collect_transactions)
 
     def _stop_send_timer(self):

elasticapm/contrib/django/apps.py

@@ -17,10 +17,10 @@ def __init__(self, *args, **kwargs):
     def ready(self):
         self.client = get_client()
         register_handlers(self.client)
-        if not self.client.config.disable_instrumentation:
+        if self.client.config.instrument:
             instrument(self.client)
         else:
-            self.client.logger.debug("Skipping instrumentation. DISABLE_INSTRUMENTATION is set.")
+            self.client.logger.debug("Skipping instrumentation. INSTRUMENT is set to False.")
 
 
 def register_handlers(client):

elasticapm/contrib/django/client.py

@@ -173,7 +173,6 @@ def capture(self, event_type, request=None, **kwargs):
         return result
 
     def _get_stack_info_for_trace(self, frames,
-                                  with_source_context=True,
                                   library_frame_context_lines=None,
                                   in_app_frame_context_lines=None,
                                   with_locals=True,
@@ -182,7 +181,6 @@ def _get_stack_info_for_trace(self, frames,
         frames until some other module comes up."""
         frames = list(iterate_with_template_sources(
             frames,
-            with_source_context=with_source_context,
             with_locals=with_locals,
             library_frame_context_lines=library_frame_context_lines,
             in_app_frame_context_lines=in_app_frame_context_lines,

elasticapm/contrib/django/utils.py

@@ -9,7 +9,7 @@ class Template(object):
         pass
 
 
-def iterate_with_template_sources(frames, with_source_context=True, with_locals=True,
+def iterate_with_template_sources(frames, with_locals=True,
                                   library_frame_context_lines=None, in_app_frame_context_lines=None,
                                   include_paths_re=None, exclude_paths_re=None, locals_processor_func=None):
     template = None
@@ -40,7 +40,6 @@ def iterate_with_template_sources(frames, with_source_context=True, with_locals=
 
         yield get_frame_info(
             frame, lineno,
-            with_source_context=with_source_context,
             library_frame_context_lines=library_frame_context_lines,
             in_app_frame_context_lines=in_app_frame_context_lines,
             with_locals=with_locals,

elasticapm/contrib/flask/__init__.py

@@ -113,9 +113,7 @@ def init_app(self, app, **defaults):
             pass
 
         # Instrument to get spans
-        if self.client.config.disable_instrumentation:
-            logger.debug("Skipping instrumentation. DISABLE_INSTRUMENTATION is set.")
-        else:
+        if self.client.config.instrument:
             elasticapm.instrumentation.control.instrument()
 
             signals.request_started.connect(self.request_started, sender=app)
@@ -125,6 +123,8 @@ def init_app(self, app, **defaults):
                 register_instrumentation(self.client)
             except ImportError:
                 pass
+        else:
+            logger.debug("Skipping instrumentation. INSTRUMENT is set to False.")
 
     def request_started(self, app):
         if not (self.app.debug and not self.client.config.debug):