scout-apm 3.3.0__cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

scout_apm/core/config.py

@@ -0,0 +1,404 @@
+# coding=utf-8
+
+import logging
+import os
+import re
+import warnings
+from typing import Any, Dict, List, Optional, Union
+
+from scout_apm.core import platform_detection
+
+logger = logging.getLogger(__name__)
+
+key_regex = re.compile(r"[a-zA-Z0-9]{16}")
+
+
+class ScoutConfig(object):
+    """
+    Configuration object for the ScoutApm agent.
+
+    Contains a list of configuration "layers". When a configuration key is
+    looked up, each layer is asked in turn if it knows the value. The first one
+    to answer affirmatively returns the value.
+    """
+
+    def __init__(self):
+        self.layers = [
+            Env(),
+            Python(),
+            Derived(self),
+            Defaults(),
+            Null(),
+        ]
+
+    def value(self, key: str) -> Any:
+        value = self.locate_layer_for_key(key).value(key)
+        if key in CONVERSIONS:
+            return CONVERSIONS[key](value)
+        return value
+
+    def locate_layer_for_key(self, key: str) -> Any:
+        for layer in self.layers:
+            if layer.has_config(key):
+                return layer
+
+        # Should be unreachable because Null returns None for all keys.
+        raise ValueError("key {!r} not found in any layer".format(key))
+
+    def log(self) -> None:
+        logger.debug("Configuration Loaded:")
+        for key in self.known_keys:
+            if key in self.secret_keys:
+                continue
+
+            layer = self.locate_layer_for_key(key)
+            logger.debug(
+                "%-9s: %s = %s",
+                layer.__class__.__name__,
+                key,
+                layer.value(key),
+            )
+
+    known_keys = [
+        "app_server",
+        "application_root",
+        "collect_remote_ip",
+        "core_agent_config_file",
+        "core_agent_dir",
+        "core_agent_download",
+        "core_agent_launch",
+        "core_agent_log_file",
+        "core_agent_log_level",
+        "core_agent_permissions",
+        "core_agent_socket_path",
+        "core_agent_version",
+        "disabled_instruments",
+        "download_url",
+        "framework",
+        "framework_version",
+        "hostname",
+        "ignore",  # Deprecated in favor of ignore_endpoints
+        "ignore_endpoints",
+        "ignore_jobs",
+        "key",
+        "log_level",
+        "log_payload_content",
+        "monitor",
+        "name",
+        "revision_sha",
+        "sample_rate",
+        "endpoint_sample_rate",
+        "sample_endpoints",
+        "sample_jobs",
+        "job_sample_rate",
+        "scm_subdirectory",
+        "shutdown_message_enabled",
+        "shutdown_timeout_seconds",
+    ]
+
+    secret_keys = {"key"}
+
+    def core_agent_permissions(self) -> int:
+        try:
+            return int(str(self.value("core_agent_permissions")), 8)
+        except ValueError:
+            logger.exception(
+                "Invalid core_agent_permissions value, using default of 0o700"
+            )
+            return 0o700
+
+    @classmethod
+    def set(cls, **kwargs: Any) -> None:
+        """
+        Sets a configuration value for the Scout agent. Values set here will
+        not override values set in ENV.
+        """
+        for key, value in kwargs.items():
+            SCOUT_PYTHON_VALUES[key] = value
+
+    @classmethod
+    def unset(cls, *keys: str) -> None:
+        """
+        Removes a configuration value for the Scout agent.
+        """
+        for key in keys:
+            SCOUT_PYTHON_VALUES.pop(key, None)
+
+    @classmethod
+    def reset_all(cls) -> None:
+        """
+        Remove all configuration settings set via `ScoutConfig.set(...)`.
+
+        This is meant for use in testing.
+        """
+        SCOUT_PYTHON_VALUES.clear()
+
+
+# Module-level data, the ScoutConfig.set(key="value") adds to this
+SCOUT_PYTHON_VALUES = {}
+
+
+class Python(object):
+    """
+    A configuration overlay that lets other parts of python set values.
+    """
+
+    def has_config(self, key: str) -> bool:
+        return key in SCOUT_PYTHON_VALUES
+
+    def value(self, key: str) -> Any:
+        return SCOUT_PYTHON_VALUES[key]
+
+
+class Env(object):
+    """
+    Reads configuration from environment by prefixing the key
+    requested with "SCOUT_"
+
+    Example: the `key` config looks for SCOUT_KEY
+    environment variable
+    """
+
+    def has_config(self, key: str) -> bool:
+        env_key = self.modify_key(key)
+        return env_key in os.environ
+
+    def value(self, key: str) -> Any:
+        env_key = self.modify_key(key)
+        return os.environ[env_key]
+
+    def modify_key(self, key: str) -> str:
+        env_key = ("SCOUT_" + key).upper()
+        return env_key
+
+
+class Derived(object):
+    """
+    A configuration overlay that calculates from other values.
+    """
+
+    def __init__(self, config: ScoutConfig):
+        """
+        config argument is the overall ScoutConfig var, so we can lookup the
+        components of the derived info.
+        """
+        self.config = config
+
+    def has_config(self, key: str) -> bool:
+        return self.lookup_func(key) is not None
+
+    def value(self, key: str) -> Any:
+        return self.lookup_func(key)()
+
+    def lookup_func(self, key: str) -> Optional[Any]:
+        """
+        Returns the derive_#{key} function, or None if it isn't defined
+        """
+        func_name = "derive_" + key
+        return getattr(self, func_name, None)
+
+    def derive_core_agent_full_name(self) -> str:
+        triple = self.config.value("core_agent_triple")
+        if not platform_detection.is_valid_triple(triple):
+            warnings.warn(
+                "Invalid value for core_agent_triple: {}".format(triple), stacklevel=2
+            )
+        return "{name}-{version}-{triple}".format(
+            name="scout_apm_core",
+            version=self.config.value("core_agent_version"),
+            triple=triple,
+        )
+
+    def derive_core_agent_triple(self) -> str:
+        return platform_detection.get_triple()
+
+
+class Defaults(object):
+    """
+    Provides default values for important configurations
+    """
+
+    def __init__(self):
+        self.defaults = {
+            "app_server": "",
+            "application_root": os.getcwd(),
+            "collect_remote_ip": True,
+            "core_agent_dir": "/tmp/scout_apm_core",
+            "core_agent_download": True,
+            "core_agent_launch": True,
+            "core_agent_log_level": "info",
+            "core_agent_permissions": 700,
+            "core_agent_socket_path": "tcp://127.0.0.1:6590",
+            "core_agent_version": "v1.5.0",  # can be an exact tag name, or 'latest'
+            "disabled_instruments": [],
+            "download_url": (
+                "https://s3-us-west-1.amazonaws.com/scout-public-downloads/"
+                "apm_core_agent/release"
+            ),  # noqa: B950
+            "errors_batch_size": 5,
+            "errors_enabled": True,
+            "errors_ignored_exceptions": (),
+            "errors_host": "https://errors.scoutapm.com",
+            "framework": "",
+            "framework_version": "",
+            "hostname": None,
+            "ignore": [],
+            "ignore_endpoints": [],
+            "ignore_jobs": [],
+            "key": "",
+            "log_payload_content": False,
+            "monitor": False,
+            "name": "Python App",
+            "revision_sha": self._git_revision_sha(),
+            "sample_rate": 100,
+            "sample_endpoints": [],
+            "endpoint_sample_rate": None,
+            "sample_jobs": [],
+            "job_sample_rate": None,
+            "scm_subdirectory": "",
+            "shutdown_message_enabled": True,
+            "shutdown_timeout_seconds": 2.0,
+            "uri_reporting": "filtered_params",
+        }
+
+    def _git_revision_sha(self) -> str:
+        # N.B. The environment variable SCOUT_REVISION_SHA may also be used,
+        # but that will be picked up by Env
+        return os.environ.get("HEROKU_SLUG_COMMIT", "")
+
+    def has_config(self, key: str) -> bool:
+        return key in self.defaults
+
+    def value(self, key: str) -> Any:
+        return self.defaults[key]
+
+
+class Null(object):
+    """
+    Always answers that a key is present, but the value is None
+
+    Used as the last step of the layered configuration.
+    """
+
+    def has_config(self, key: str) -> bool:
+        return True
+
+    def value(self, key: str) -> None:
+        return None
+
+
+def _strip_leading_slash(path: str) -> str:
+    return path.lstrip(" /").strip()
+
+
+def convert_to_bool(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.lower() in ("yes", "true", "t", "1")
+    # Unknown type - default to false?
+    return False
+
+
+def convert_to_float(value: Any) -> float:
+    try:
+        return float(value)
+    except ValueError:
+        return 0.0
+
+
+def convert_sample_rate(value: Any) -> Optional[int]:
+    """
+    Converts sample rate to integer, ensuring it's between 0 and 100.
+    Allows None as a valid value.
+    """
+    if value is None:
+        return None
+    try:
+        rate = int(value)
+        if not (0 <= rate <= 100):
+            logger.warning(
+                f"Invalid sample rate {rate}. Must be between 0 and 100. "
+                "Defaulting to 100."
+            )
+            return 100
+        return rate
+    except (TypeError, ValueError):
+        logger.warning(
+            f"Invalid sample rate {value}. Must be a number between 0 and 100. "
+            "Defaulting to 100."
+        )
+        return 100
+
+
+def convert_to_list(value: Any) -> List[Any]:
+    if isinstance(value, list):
+        return value
+    if isinstance(value, tuple):
+        return list(value)
+    if isinstance(value, str):
+        # Split on commas
+        return [item.strip() for item in value.split(",") if item]
+    # Unknown type - default to empty?
+    return []
+
+
+def convert_ignore_paths(value: Any) -> List[str]:
+    """
+    Removes leading slashes from paths and returns a list of strings.
+    """
+    raw_paths = convert_to_list(value)
+    return [_strip_leading_slash(path) for path in raw_paths]
+
+
+def convert_endpoint_sampling(value: Union[str, Dict[str, Any]]) -> Dict[str, int]:
+    """
+    Converts endpoint sampling configuration from string or dict format
+    to a normalized dict.
+    Example: '/endpoint:40,/test:0' -> {'/endpoint': 40, '/test': 0}
+    """
+    if isinstance(value, dict):
+        return {_strip_leading_slash(k): int(v) for k, v in value.items()}
+    if isinstance(value, str):
+        if not value.strip():
+            return {}
+        result = {}
+        pairs = [pair.strip() for pair in value.split(",")]
+        for pair in pairs:
+            try:
+                endpoint, rate = pair.split(":")
+                rate_int = int(rate)
+                if not (0 <= rate_int <= 100):
+                    logger.warning(
+                        f"Invalid sampling rate {rate} for endpoint {endpoint}. "
+                        "Must be between 0 and 100."
+                    )
+                    continue
+                result[_strip_leading_slash(endpoint)] = rate_int
+            except ValueError:
+                logger.warning(f"Invalid sampling configuration: {pair}")
+                continue
+        return result
+    return {}
+
+
+CONVERSIONS = {
+    "collect_remote_ip": convert_to_bool,
+    "core_agent_download": convert_to_bool,
+    "core_agent_launch": convert_to_bool,
+    "disabled_instruments": convert_to_list,
+    "ignore": convert_ignore_paths,
+    "ignore_endpoints": convert_ignore_paths,
+    "ignore_jobs": convert_ignore_paths,
+    "monitor": convert_to_bool,
+    "sample_rate": convert_sample_rate,
+    "sample_endpoints": convert_endpoint_sampling,
+    "endpoint_sample_rate": convert_sample_rate,
+    "sample_jobs": convert_endpoint_sampling,
+    "job_sample_rate": convert_sample_rate,
+    "shutdown_message_enabled": convert_to_bool,
+    "shutdown_timeout_seconds": convert_to_float,
+}
+
+
+scout_config = ScoutConfig()

scout_apm/core/context.py

@@ -0,0 +1,140 @@
+# coding=utf-8
+
+import threading
+import time
+from threading import local as ThreadLocal
+
+from scout_apm.core.tracked_request import TrackedRequest
+
+try:
+    from asgiref.local import Local as AsgiRefLocal
+except ImportError:
+    # Old versions of Python or asgiref < 3.1
+    AsgiRefLocal = None
+
+try:
+    import asyncio
+except ImportError:
+    asyncio = None
+
+try:
+    from contextvars import ContextVar
+
+    scout_context_var = ContextVar("__scout_trackedrequest")
+except ImportError:
+    scout_context_var = None
+
+
+SCOUT_REQUEST_ATTR = "__scout_trackedrequest"
+
+
+def get_current_asyncio_task():
+    """
+    Cross-version implementation of asyncio.current_task()
+    Returns None if there is no task.
+    """
+    if asyncio:
+        try:
+            if hasattr(asyncio, "current_task"):
+                # Python 3.7 and up
+                return asyncio.current_task()
+            else:
+                # Python 3.6
+                return asyncio.Task.current_task()
+        except RuntimeError:
+            return None
+
+
+class SimplifiedAsgirefLocal:
+    """
+    A copy of asgiref 3.1+'s Local class without the sync_to_async /
+    async_to_sync compatibility.
+    """
+
+    CLEANUP_INTERVAL = 60  # seconds
+
+    def __init__(self):
+        self._storage = {}
+        self._last_cleanup = time.time()
+        self._clean_lock = threading.Lock()
+
+    def _get_context_id(self):
+        """
+        Get the ID we should use for looking up variables
+        """
+        # First, pull the current task if we can
+        context_id = get_current_asyncio_task()
+        # OK, let's try for a thread ID
+        if context_id is None:
+            context_id = threading.current_thread()
+        return context_id
+
+    def _cleanup(self):
+        """
+        Cleans up any references to dead threads or tasks
+        """
+        for key in list(self._storage.keys()):
+            if isinstance(key, threading.Thread):
+                if not key.is_alive():
+                    del self._storage[key]
+            elif isinstance(key, asyncio.Task):
+                if key.done():
+                    del self._storage[key]
+        self._last_cleanup = time.time()
+
+    def _maybe_cleanup(self):
+        """
+        Cleans up if enough time has passed
+        """
+        if time.time() - self._last_cleanup > self.CLEANUP_INTERVAL:
+            with self._clean_lock:
+                self._cleanup()
+
+    def __getattr__(self, key):
+        context_id = self._get_context_id()
+        if key in self._storage.get(context_id, {}):
+            return self._storage[context_id][key]
+        else:
+            raise AttributeError("%r object has no attribute %r" % (self, key))
+
+    def __setattr__(self, key, value):
+        if key in ("_storage", "_last_cleanup", "_clean_lock", "_thread_critical"):
+            return super().__setattr__(key, value)
+        self._maybe_cleanup()
+        self._storage.setdefault(self._get_context_id(), {})[key] = value
+
+    def __delattr__(self, key):
+        context_id = self._get_context_id()
+        if key in self._storage.get(context_id, {}):
+            del self._storage[context_id][key]
+        else:
+            raise AttributeError("%r object has no attribute %r" % (self, key))
+
+
+class LocalContext(object):
+    def __init__(self):
+        if AsgiRefLocal is not None:
+            self._local = AsgiRefLocal()
+        elif asyncio is not None:
+            self._local = SimplifiedAsgirefLocal()
+        else:
+            self._local = ThreadLocal()
+        self.use_context_var = scout_context_var is not None
+
+    def get_tracked_request(self):
+        if scout_context_var:
+            if not scout_context_var.get(None):
+                scout_context_var.set(TrackedRequest())
+            return scout_context_var.get()
+        if not hasattr(self._local, "tracked_request"):
+            self._local.tracked_request = TrackedRequest()
+        return self._local.tracked_request
+
+    def clear_tracked_request(self, instance):
+        if getattr(self._local, "tracked_request", None) is instance:
+            del self._local.tracked_request
+        if scout_context_var and scout_context_var.get(None) is instance:
+            scout_context_var.set(None)
+
+
+context = LocalContext()

scout_apm/core/error.py

@@ -0,0 +1,95 @@
+# coding=utf-8
+
+import logging
+import os
+
+from scout_apm.core.backtrace import capture_stacktrace
+from scout_apm.core.config import scout_config
+from scout_apm.core.error_service import ErrorServiceThread
+from scout_apm.core.tracked_request import TrackedRequest
+from scout_apm.core.web_requests import RequestComponents, filter_element
+
+logger = logging.getLogger(__name__)
+
+
+class ErrorMonitor(object):
+    @classmethod
+    def send(
+        cls,
+        exc_info,
+        request_components=None,
+        request_path=None,
+        request_params=None,
+        session=None,
+        environment=None,
+        custom_controller=None,
+        custom_params=None,
+    ):
+        if not scout_config.value("errors_enabled"):
+            return
+
+        exc_class, exc_value, traceback = exc_info
+
+        ignore_exceptions = scout_config.value("errors_ignored_exceptions")
+        if ignore_exceptions and isinstance(exc_value, tuple(ignore_exceptions)):
+            return
+
+        tracked_request = TrackedRequest.instance()
+
+        context = {}
+        context.update(tracked_request.tags)
+
+        if custom_params:
+            context["custom_params"] = custom_params
+
+        if custom_controller:
+            if request_components:
+                request_components.controller = custom_controller
+            else:
+                request_components = RequestComponents(
+                    module=None, controller=custom_controller, action=None
+                )
+
+        scm_subdirectory = scout_config.value("scm_subdirectory")
+        error = {
+            "exception_class": exc_class.__name__,
+            "message": str(exc_value),
+            "request_id": tracked_request.request_id,
+            "request_uri": request_path,
+            "request_params": filter_element("", request_params)
+            if request_params
+            else None,
+            "request_session": filter_element("", session) if session else None,
+            "environment": filter_element("", environment) if environment else None,
+            "trace": [
+                "{file}:{line}:in {function}".format(
+                    file=os.path.join(scm_subdirectory, frame["file"])
+                    if scm_subdirectory
+                    else frame["file"],
+                    line=frame["line"],
+                    function=frame["function"],
+                )
+                for frame in capture_stacktrace(traceback)
+            ],
+            "request_components": {
+                "module": request_components.module,
+                "controller": request_components.controller,
+                "action": request_components.action,
+            }
+            if request_components
+            else None,
+            "context": context,
+            "host": scout_config.value("hostname"),
+            "revision_sha": scout_config.value("revision_sha"),
+        }
+
+        if scout_config.value("log_payload_content"):
+            logger.debug(
+                "Sending error for request: %s. Payload: %r",
+                tracked_request.request_id,
+                error,
+            )
+        else:
+            logger.debug("Sending error for request: %s.", tracked_request.request_id)
+
+        ErrorServiceThread.send(error=error)