introduces capture_headers config option (#392)

fixes #365
closes #392

Author: beniwohli

CHANGELOG.md

@@ -8,6 +8,7 @@
  * Added `transaction.type` to errors (#391)
  * Added parsing of `/proc/self/cgroup` to capture container meta data (#352)
  * Added option to configure logging for Flask using a log level (#344)
+ * Added `capture_headers` config option (#392)
 
 ## v4.0.3
 [Check the diff](https://github.com/elastic/apm-agent-python/compare/v4.0.2...v4.0.3)

docs/configuration.asciidoc

@@ -375,6 +375,24 @@ It contains the name of the field, and the name of the uploaded file, if provide
 WARNING: request bodies often contain sensitive values like passwords, credit card numbers etc.
 If your service handles data like this, we advise to only enable this feature with care.
 
+[float]
+[[config-capture-headers]]
+==== `capture_headers`
+
+|============
+| Environment                   | Django/Flask      | Default
+| `ELASTIC_APM_CAPTURE_HEADERS` | `CAPTURE_HEADERS` | `true`
+|============
+
+For transactions and errors that happen due to HTTP requests,
+the Python agent can optionally capture the request and response headers.
+
+Possible values: `true`, `false`
+
+WARNING: request headers often contain sensitive values like session IDs, cookies etc.
+See our documentation on <<sanitizing-data, sanitizing data>> for more information on how to
+filter such data.
+
 [float]
 [[config-transaction-max-spans]]
 ==== `transaction_max_spans`

docs/tuning.asciidoc

@@ -95,4 +95,17 @@ There are four settings you can modify to control this behavior:
 
 As you can see, 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 also split into separate error and span settings. 
 
-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 down these limits will help prevent excessive memory usage. 
+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 down these limits will help prevent excessive memory usage.
+
+[float]
+[[tuning-body-headers]]
+=== Collecting headers and request body
+
+You can configure the Elastic APM agent to capture headers of both requests and responses (<<config-capture-headers,`capture_headers`>>),
+as well as request bodies (<<config-capture-body,`capture_body`>>).
+By default, capturing request bodies is disabled.
+Enabling it for transactions may introduce noticeable overhead, as well as increased storage use, depending on the nature of your POST requests.
+In most scenarios, we advise against enabling request body capturing for transactions, and only enable it if necessary for errors.
+
+Capturing request/response headers has less overhead on the agent, but can have an impact on storage use.
+If storage use is a problem for you, it might be worth disabling.

elasticapm/conf/__init__.py

@@ -251,6 +251,7 @@ class Config(_ConfigBase):
     disable_send = _BoolConfigValue("DISABLE_SEND", default=False)
     instrument = _BoolConfigValue("DISABLE_INSTRUMENTATION", default=True)
     enable_distributed_tracing = _BoolConfigValue("ENABLE_DISTRIBUTED_TRACING", default=True)
+    capture_headers = _BoolConfigValue("CAPTURE_HEADERS", default=True)
 
 
 def setup_logging(handler, exclude=("gunicorn", "south", "elasticapm.errors")):

elasticapm/contrib/django/client.py

@@ -98,11 +98,12 @@ def get_user_info(self, request):
     def get_data_from_request(self, request, capture_body=False):
         result = {
             "env": dict(get_environ(request.META)),
-            "headers": dict(get_headers(request.META)),
             "method": request.method,
             "socket": {"remote_address": request.META.get("REMOTE_ADDR"), "encrypted": request.is_secure()},
             "cookies": dict(request.COOKIES),
         }
+        if self.config.capture_headers:
+            result["headers"] = dict(get_headers(request.META))
 
         if request.method in constants.HTTP_WITH_BODY:
             content_type = request.META.get("CONTENT_TYPE")
@@ -141,7 +142,7 @@ def get_data_from_request(self, request, capture_body=False):
     def get_data_from_response(self, response):
         result = {"status_code": response.status_code}
 
-        if hasattr(response, "items"):
+        if self.config.capture_headers and hasattr(response, "items"):
             result["headers"] = dict(response.items())
         return result
 

elasticapm/contrib/flask/__init__.py

@@ -93,7 +93,9 @@ def handle_exception(self, *args, **kwargs):
             exc_info=kwargs.get("exc_info"),
             context={
                 "request": get_data_from_request(
-                    request, capture_body=self.client.config.capture_body in ("errors", "all")
+                    request,
+                    capture_body=self.client.config.capture_body in ("errors", "all"),
+                    capture_headers=self.client.config.capture_headers,
                 )
             },
             custom={"app": self.app},
@@ -168,11 +170,15 @@ def request_finished(self, app, response):
             rule = build_name_with_http_method_prefix(rule, request)
             elasticapm.set_context(
                 lambda: get_data_from_request(
-                    request, capture_body=self.client.config.capture_body in ("transactions", "all")
+                    request,
+                    capture_body=self.client.config.capture_body in ("transactions", "all"),
+                    capture_headers=self.client.config.capture_headers,
                 ),
                 "request",
             )
-            elasticapm.set_context(lambda: get_data_from_response(response), "response")
+            elasticapm.set_context(
+                lambda: get_data_from_response(response, capture_headers=self.client.config.capture_headers), "response"
+            )
             if response.status_code:
                 result = "HTTP {}xx".format(response.status_code // 100)
             else:

elasticapm/contrib/flask/utils.py

@@ -5,14 +5,15 @@
 from elasticapm.utils.wsgi import get_environ, get_headers
 
 
-def get_data_from_request(request, capture_body=False):
+def get_data_from_request(request, capture_body=False, capture_headers=True):
     result = {
         "env": dict(get_environ(request.environ)),
-        "headers": dict(get_headers(request.environ)),
         "method": request.method,
         "socket": {"remote_address": request.environ.get("REMOTE_ADDR"), "encrypted": request.is_secure},
         "cookies": request.cookies,
     }
+    if capture_headers:
+        result["headers"] = dict(get_headers(request.environ))
     if request.method in constants.HTTP_WITH_BODY:
         body = None
         if request.content_type == "application/x-www-form-urlencoded":
@@ -37,13 +38,13 @@ def get_data_from_request(request, capture_body=False):
     return result
 
 
-def get_data_from_response(response):
+def get_data_from_response(response, capture_headers=True):
     result = {}
 
     if isinstance(getattr(response, "status_code", None), compat.integer_types):
         result["status_code"] = response.status_code
 
-    if getattr(response, "headers", None):
+    if capture_headers and getattr(response, "headers", None):
         headers = response.headers
         result["headers"] = {key: ";".join(headers.getlist(key)) for key in compat.iterkeys(headers)}
     return result

tests/contrib/django/django_tests.py

@@ -1358,6 +1358,26 @@ def test_capture_files(client, django_elasticapm_client):
         assert error["context"]["request"]["body"] == "[REDACTED]"
 
 
+@pytest.mark.parametrize(
+    "django_elasticapm_client", [{"capture_headers": "true"}, {"capture_headers": "false"}], indirect=True
+)
+def test_capture_headers(client, django_elasticapm_client):
+    with pytest.raises(MyException), override_settings(
+        **middleware_setting(django.VERSION, ["elasticapm.contrib.django.middleware.TracingMiddleware"])
+    ):
+        client.post(reverse("elasticapm-raise-exc"), **{"HTTP_SOME_HEADER": "foo"})
+    error = django_elasticapm_client.events[ERROR][0]
+    transaction = django_elasticapm_client.events[TRANSACTION][0]
+    if django_elasticapm_client.config.capture_headers:
+        assert error["context"]["request"]["headers"]["some-header"] == "foo"
+        assert transaction["context"]["request"]["headers"]["some-header"] == "foo"
+        assert "headers" in transaction["context"]["response"]
+    else:
+        assert "headers" not in error["context"]["request"]
+        assert "headers" not in transaction["context"]["request"]
+        assert "headers" not in transaction["context"]["response"]
+
+
 @pytest.mark.parametrize("django_elasticapm_client", [{"capture_body": "transactions"}], indirect=True)
 def test_options_request(client, django_elasticapm_client):
     with override_settings(

tests/contrib/flask/flask_tests.py

@@ -258,6 +258,34 @@ def test_options_request(flask_apm_client):
     assert transactions[0]["context"]["request"]["method"] == "OPTIONS"
 
 
+@pytest.mark.parametrize(
+    "elasticapm_client", [{"capture_headers": "true"}, {"capture_headers": "false"}], indirect=True
+)
+def test_capture_headers_errors(flask_apm_client):
+    resp = flask_apm_client.app.test_client().post("/an-error/", headers={"some-header": "foo"})
+    resp.close()
+    error = flask_apm_client.client.events[ERROR][0]
+    if flask_apm_client.client.config.capture_headers:
+        assert error["context"]["request"]["headers"]["some-header"] == "foo"
+    else:
+        assert "headers" not in error["context"]["request"]
+
+
+@pytest.mark.parametrize(
+    "elasticapm_client", [{"capture_headers": "true"}, {"capture_headers": "false"}], indirect=True
+)
+def test_capture_headers_transactions(flask_apm_client):
+    resp = flask_apm_client.app.test_client().post("/users/", headers={"some-header": "foo"})
+    resp.close()
+    transaction = flask_apm_client.client.events[TRANSACTION][0]
+    if flask_apm_client.client.config.capture_headers:
+        assert transaction["context"]["request"]["headers"]["some-header"] == "foo"
+        assert transaction["context"]["response"]["headers"]["foo"] == "bar;baz"
+    else:
+        assert "headers" not in transaction["context"]["request"]
+        assert "headers" not in transaction["context"]["response"]
+
+
 def test_streaming_response(flask_apm_client):
     resp = flask_apm_client.app.test_client().get("/streaming/")
     assert resp.data == b"01234"