feat(tracer): auto-disable tracer when for AWS SAM and Chalice environments

aws_lambda_powertools/shared/constants.py

@@ -1,32 +1,16 @@
+# Tracer constants
 TRACER_CAPTURE_RESPONSE_ENV: str = "POWERTOOLS_TRACER_CAPTURE_RESPONSE"
 TRACER_CAPTURE_ERROR_ENV: str = "POWERTOOLS_TRACER_CAPTURE_ERROR"
 TRACER_DISABLED_ENV: str = "POWERTOOLS_TRACE_DISABLED"
+XRAY_SDK_MODULE: str = "aws_xray_sdk"
+XRAY_SDK_CORE_MODULE: str = "aws_xray_sdk.core"
+XRAY_TRACE_ID_ENV: str = "_X_AMZN_TRACE_ID"
+MIDDLEWARE_FACTORY_TRACE_ENV: str = "POWERTOOLS_TRACE_MIDDLEWARES"
 
+# Logger constants
 LOGGER_LOG_SAMPLING_RATE: str = "POWERTOOLS_LOGGER_SAMPLE_RATE"
 LOGGER_LOG_EVENT_ENV: str = "POWERTOOLS_LOGGER_LOG_EVENT"
 LOGGER_LOG_DEDUPLICATION_ENV: str = "POWERTOOLS_LOG_DEDUPLICATION_DISABLED"
-
-MIDDLEWARE_FACTORY_TRACE_ENV: str = "POWERTOOLS_TRACE_MIDDLEWARES"
-
-METRICS_NAMESPACE_ENV: str = "POWERTOOLS_METRICS_NAMESPACE"
-
-DATADOG_FLUSH_TO_LOG: str = "DD_FLUSH_TO_LOG"
-
-SERVICE_NAME_ENV: str = "POWERTOOLS_SERVICE_NAME"
-XRAY_TRACE_ID_ENV: str = "_X_AMZN_TRACE_ID"
-LAMBDA_TASK_ROOT_ENV: str = "LAMBDA_TASK_ROOT"
-
-
-LAMBDA_FUNCTION_NAME_ENV: str = "AWS_LAMBDA_FUNCTION_NAME"
-
-XRAY_SDK_MODULE: str = "aws_xray_sdk"
-XRAY_SDK_CORE_MODULE: str = "aws_xray_sdk.core"
-
-IDEMPOTENCY_DISABLED_ENV: str = "POWERTOOLS_IDEMPOTENCY_DISABLED"
-
-PARAMETERS_SSM_DECRYPT_ENV: str = "POWERTOOLS_PARAMETERS_SSM_DECRYPT"
-PARAMETERS_MAX_AGE_ENV: str = "POWERTOOLS_PARAMETERS_MAX_AGE"
-
 LOGGER_LAMBDA_CONTEXT_KEYS = [
     "function_arn",
     "function_memory_size",
@@ -35,17 +19,6 @@
     "cold_start",
     "xray_trace_id",
 ]
-
-# JSON indentation level
-PRETTY_INDENT: int = 4
-COMPACT_INDENT = None
-
-POWERTOOLS_DEV_ENV: str = "POWERTOOLS_DEV"
-POWERTOOLS_DEBUG_ENV: str = "POWERTOOLS_DEBUG"
-POWERTOOLS_LOG_LEVEL_ENV: str = "POWERTOOLS_LOG_LEVEL"
-POWERTOOLS_LOG_LEVEL_LEGACY_ENV: str = "LOG_LEVEL"
-LAMBDA_LOG_LEVEL_ENV: str = "AWS_LAMBDA_LOG_LEVEL"
-
 # Mapping of Lambda log levels to Python logging levels
 # https://docs.aws.amazon.com/lambda/latest/dg/configuration-logging.html#configuration-logging-log-levels
 LAMBDA_ADVANCED_LOGGING_LEVELS = {
@@ -57,3 +30,32 @@
     "ERROR": "ERROR",
     "FATAL": "CRITICAL",
 }
+POWERTOOLS_LOG_LEVEL_ENV: str = "POWERTOOLS_LOG_LEVEL"
+POWERTOOLS_LOG_LEVEL_LEGACY_ENV: str = "LOG_LEVEL"
+LAMBDA_LOG_LEVEL_ENV: str = "AWS_LAMBDA_LOG_LEVEL"
+
+# Metrics constants
+METRICS_NAMESPACE_ENV: str = "POWERTOOLS_METRICS_NAMESPACE"
+DATADOG_FLUSH_TO_LOG: str = "DD_FLUSH_TO_LOG"
+SERVICE_NAME_ENV: str = "POWERTOOLS_SERVICE_NAME"
+
+# Parameters constants
+PARAMETERS_SSM_DECRYPT_ENV: str = "POWERTOOLS_PARAMETERS_SSM_DECRYPT"
+PARAMETERS_MAX_AGE_ENV: str = "POWERTOOLS_PARAMETERS_MAX_AGE"
+
+# Runtime and environment constants
+LAMBDA_TASK_ROOT_ENV: str = "LAMBDA_TASK_ROOT"
+SAM_LOCAL_ENV: str = "AWS_SAM_LOCAL"
+CHALICE_LOCAL_ENV: str = "AWS_CHALICE_CLI_MODE"
+LAMBDA_FUNCTION_NAME_ENV: str = "AWS_LAMBDA_FUNCTION_NAME"
+
+# Debug constants
+POWERTOOLS_DEV_ENV: str = "POWERTOOLS_DEV"
+POWERTOOLS_DEBUG_ENV: str = "POWERTOOLS_DEBUG"
+
+# JSON constants
+PRETTY_INDENT: int = 4
+COMPACT_INDENT = None
+
+# Idempotency constants
+IDEMPOTENCY_DISABLED_ENV: str = "POWERTOOLS_IDEMPOTENCY_DISABLED"

aws_lambda_powertools/tracing/tracer.py

@@ -7,11 +7,11 @@
 import os
 from typing import Any, Callable, Dict, List, Optional, Sequence, Union, cast, overload
 
-from ..shared import constants
-from ..shared.functions import resolve_env_var_choice, resolve_truthy_env_var_choice
-from ..shared.lazy_import import LazyLoader
-from ..shared.types import AnyCallableT
-from .base import BaseProvider, BaseSegment
+from aws_lambda_powertools.shared import constants
+from aws_lambda_powertools.shared.functions import resolve_env_var_choice, resolve_truthy_env_var_choice
+from aws_lambda_powertools.shared.lazy_import import LazyLoader
+from aws_lambda_powertools.shared.types import AnyCallableT
+from aws_lambda_powertools.tracing.base import BaseProvider, BaseSegment
 
 is_cold_start = True
 logger = logging.getLogger(__name__)
@@ -766,13 +766,15 @@ def _is_tracer_disabled() -> Union[bool, str]:
         """
         logger.debug("Verifying whether Tracing has been disabled")
         is_lambda_env = os.getenv(constants.LAMBDA_TASK_ROOT_ENV)
+        is_lambda_sam_cli = os.getenv(constants.SAM_LOCAL_ENV)
+        is_chalice_cli = os.getenv(constants.CHALICE_LOCAL_ENV)
         is_disabled = resolve_truthy_env_var_choice(env=os.getenv(constants.TRACER_DISABLED_ENV, "false"))
 
         if is_disabled:
             logger.debug("Tracing has been disabled via env var POWERTOOLS_TRACE_DISABLED")
             return is_disabled
 
-        if not is_lambda_env:
+        if not is_lambda_env or (is_lambda_sam_cli or is_chalice_cli):
             logger.debug("Running outside Lambda env; disabling Tracing")
             return True
 

docs/core/tracer.md

@@ -227,7 +227,7 @@ Tracer keeps a copy of its configuration after the first initialization. This is
 
 ## Testing your code
 
-Tracer is disabled by default when not running in the AWS Lambda environment - This means no code changes or environment variables to be set.
+Tracer is disabled by default when not running in the AWS Lambda environment, including AWS SAM CLI and Chalice environments. This means no code changes or environment variables to be set.
 
 ## Tips
 

tests/functional/test_tracing.py

@@ -73,6 +73,35 @@ def handler(event, context):
     handler({}, {})
 
 
+def test_tracer_lambda_running_in_sam_cli(monkeypatch, dummy_response):
+    # GIVEN tracer runs in AWS SAM CLI (ie: `AWS_SAM_LOCAL` is set)
+    monkeypatch.setenv("AWS_SAM_LOCAL", "true")
+    monkeypatch.setenv("LAMBDA_TASK_ROOT", "/opt/")
+    tracer = Tracer()
+
+    # WHEN a lambda function is run through SAM CLI emulator
+    @tracer.capture_lambda_handler
+    def handler(event, context):
+        return dummy_response
+
+    # THEN tracer should run in disabled mode, and not raise an Exception
+    handler({}, {})
+
+
+def test_tracer_lambda_running_in_chalice(monkeypatch, dummy_response):
+    # GIVEN tracer runs in CHALICE (ie: `AWS_CHALICE_CLI_MODE` is set)
+    monkeypatch.setenv("AWS_CHALICE_CLI_MODE", "true")
+    tracer = Tracer()
+
+    # WHEN a lambda function is run through SAM CLI emulator
+    @tracer.capture_lambda_handler
+    def handler(event, context):
+        return dummy_response
+
+    # THEN tracer should run in disabled mode, and not raise an Exception
+    handler({}, {})
+
+
 def test_tracer_metadata_disabled(dummy_response):
     # GIVEN tracer is disabled, and annotations/metadata are used
     tracer = Tracer(disabled=True)