improv: address Nicolas feedback; improve docs

Author: heitorlessa

docs/content/core/tracer.mdx

@@ -65,12 +65,16 @@ def handler(event, context):
     ...
 ```
 
+### disabling response auto-capture
+
+> New in 1.9.0
+
 <Note type="warning">
   <strong>Returning sensitive information from your Lambda handler or functions, where Tracer is used?</strong>
   <br/><br/>
-  You can disable Tracer from capturing their responses as tracing metadata with <strong><code>capture_response=False</code></strong> parameter in both capture_lambda_handler and capture_method decorators.
 </Note><br/>
 
+You can disable Tracer from capturing their responses as tracing metadata with <strong><code>capture_response=False</code></strong> parameter in both capture_lambda_handler and capture_method decorators.
 
 ```python:title=do_not_capture_response_as_metadata.py
 # Disables Tracer from capturing response and adding as metadata
@@ -80,6 +84,25 @@ def handler(event, context):
 	return "sensitive_information"
 ```
 
+### disabling exception auto-capture
+
+> New in 1.10.0
+
+<Note type="warning">
+  <strong>Can exceptions contain sensitive information from your Lambda handler or functions, where Tracer is used?</strong>
+  <br/><br/>
+</Note><br/>
+
+You can disable Tracer from capturing their exceptions as tracing metadata with <strong><code>capture_error=False</code></strong> parameter in both capture_lambda_handler and capture_method decorators.
+
+```python:title=do_not_capture_response_as_metadata.py
+# Disables Tracer from capturing response and adding as metadata
+# Useful when dealing with sensitive data
+@tracer.capture_lambda_handler(capture_error=False) # highlight-line
+def handler(event, context):
+	raise ValueError("some sensitive info in the stack trace...")
+```
+
 ### Annotations
 
 Annotations are key-values indexed by AWS X-Ray on a per trace basis. You can use them to filter traces as well as to create [Trace Groups](https://aws.amazon.com/about-aws/whats-new/2018/11/aws-xray-adds-the-ability-to-group-traces/).

docs/content/index.mdx

@@ -116,14 +116,19 @@ Utility | Description
 
 ## Environment variables
 
+<Note type="info">
+	<strong>Explicit parameters take precedence over environment variables.</strong><br/><br/>
+</Note>
+
 **Environment variables** used across suite of utilities.
 
 Environment variable | Description | Utility | Default
 ------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------- | -------------------------------------------------
 **POWERTOOLS_SERVICE_NAME** | Sets service name used for tracing namespace, metrics dimension and structured logging | All | `"service_undefined"`
 **POWERTOOLS_METRICS_NAMESPACE** | Sets namespace used for metrics | [Metrics](./core/metrics) | `None`
 **POWERTOOLS_TRACE_DISABLED** | Disables tracing | [Tracing](./core/tracer) | `false`
-**POWERTOOLS_TRACER_CAPTURE_RESPONSE** | Overrides tracer from auto-capturing response as metadata | [Tracing](./core/tracer) | `true`
+**POWERTOOLS_TRACER_CAPTURE_RESPONSE** | Captures Lambda or method return as metadata. | [Tracing](./core/tracer) | `true`
+**POWERTOOLS_TRACER_CAPTURE_ERROR** | Captures Lambda or method exception as metadata. | [Tracing](./core/tracer) | `true`
 **POWERTOOLS_TRACE_MIDDLEWARES** | Creates sub-segment for each custom middleware | [Middleware factory](./utilities/middleware_factory) | `false`
 **POWERTOOLS_LOGGER_LOG_EVENT** | Logs incoming event | [Logging](./core/logger) | `false`
 **POWERTOOLS_LOGGER_SAMPLE_RATE** | Debug log sampling | [Logging](./core/logger) | `0`

tests/functional/test_shared_functions.py

@@ -1,11 +1,9 @@
-import os
-
 from aws_lambda_powertools.shared.functions import resolve_env_var_choice
 
 
-def test_explicit_wins_over_env_var():
-    choice_env = os.getenv("CHOICE", True)
+def test_resolve_env_var_choice_explicit_wins_over_env_var():
+    assert resolve_env_var_choice(env="true", choice=False) is False
 
-    choice = resolve_env_var_choice(env=choice_env, choice=False)
 
-    assert choice is False
+def test_resolve_env_var_choice_env_wins_over_absent_explicit():
+    assert resolve_env_var_choice(env="true") == 1