document how to drop events in processing (#585)

also, exit early if any processor returns a falsy value, and log why
the event was dropped.

Author: beniwohli

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+[Check the diff](https://github.com/elastic/apm-agent-python/compare/v5.1.2...master)
+
+### Bugfixes
+ * drop events immediately if a processor returns a falsy value (#585)
+
 ## v5.1.2
 [Check the diff](https://github.com/elastic/apm-agent-python/compare/v5.1.1...v5.1.2)
 

docs/sanitizing-data.asciidoc

@@ -5,9 +5,11 @@ Sometimes it is necessary to sanitize the data sent to Elastic APM,
 e.g. remove sensitive data.
 
 To do this with the Elastic APM module, you create a processor.
-A processor is a function that takes a `client` instance as well as an event (an error or a transaction),
+A processor is a function that takes a `client` instance as well as an event (an error, a transaction, a span, or a metricset),
 and returns the modified event.
 
+To completely drop an event, your processor should return `False` (or any other "falsy" value) instead of the event.
+
 This is an example of a processor that removes the exception stacktrace from an error:
 
 [source,python]
@@ -23,7 +25,8 @@ def my_processor(client, event):
 ----
 
 You can use the `@for_events` decorator to limit for which event type the processor should be called.
-Possible choices are `ERROR`, `TRANSACTION`, and `SPAN`, all of which are defined in `elasticapm.conf.constants`.
+Possible choices are `ERROR`, `TRANSACTION`, `SPAN` and `METRICSET`,
+all of which are defined in `elasticapm.conf.constants`.
 
 To use this processor, update your `ELASTIC_APM` settings like this:
 

elasticapm/base.py

@@ -230,6 +230,15 @@ def queue(self, event_type, data, flush=False):
         for processor in self.processors:
             if not hasattr(processor, "event_types") or event_type in processor.event_types:
                 data = processor(self, data)
+                if not data:
+                    self.logger.debug(
+                        "Dropped event of type %s due to processor %s.%s",
+                        event_type,
+                        getattr(processor, "__module__"),
+                        getattr(processor, "__name__"),
+                    )
+                    data = None  # normalize all "falsy" values to None
+                    break
         if flush and is_master_process():
             # don't flush in uWSGI master process to avoid ending up in an unpredictable threading state
             flush = False

tests/processors/tests.py

@@ -32,6 +32,8 @@
 
 from __future__ import absolute_import
 
+import logging
+
 import mock
 import pytest
 
@@ -289,3 +291,20 @@ def foo(client, event):
         return True
 
     assert foo.event_types == {"error", "transaction"}
+
+
+def test_drop_events_in_processor(sending_elasticapm_client, caplog):
+    def dropping_processor(client, event):
+        return None
+
+    shouldnt_be_called_processor = mock.Mock()
+
+    sending_elasticapm_client.processors = [dropping_processor, shouldnt_be_called_processor]
+    with caplog.at_level(logging.DEBUG):
+        sending_elasticapm_client.queue(SPAN, {"some": "data"})
+    sending_elasticapm_client.close()
+    assert shouldnt_be_called_processor.call_count == 0
+    assert len(sending_elasticapm_client.httpserver.requests) == 0
+    record = caplog.records[0]
+    assert record.message == "Dropped event of type span due to processor tests.processors.tests.dropping_processor"
+    assert record.levelname == "DEBUG"