scout-apm 3.0.2__cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl → 3.3.0__cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

scout_apm/api/__init__.py

@@ -97,6 +97,7 @@ class Transaction(AsyncDecoratorMixin, ContextDecorator):
         operation = text(kind) + "/" + text(name)
 
         tracked_request = TrackedRequest.instance()
+        tracked_request.operation = operation
         tracked_request.is_real_request = True
         span = tracked_request.start_span(
             operation=operation, should_capture_backtrace=False

scout_apm/async_/starlette.py

@@ -40,6 +40,7 @@ class ScoutMiddleware:
                     endpoint.__module__,
                     endpoint.__qualname__,
                 )
+                tracked_request.operation = controller_span.operation
             else:
                 # Mark the request as not real
                 tracked_request.is_real_request = False
@@ -90,11 +91,11 @@ def install_background_instrumentation():
         tracked_request = TrackedRequest.instance()
         tracked_request.is_real_request = True
 
-        with tracked_request.span(
-            operation="Job/{}.{}".format(
-                instance.func.__module__, instance.func.__qualname__
-            )
-        ):
+        operation = "Job/{}.{}".format(
+            instance.func.__module__, instance.func.__qualname__
+        )
+        tracked_request.operation = operation
+        with tracked_request.span(operation=operation):
             return await wrapped(*args, **kwargs)
 
     BackgroundTask.__call__ = wrapped_background_call(BackgroundTask.__call__)

scout_apm/bottle.py

@@ -5,12 +5,9 @@ from bottle import request, response
 
 import scout_apm.core
 from scout_apm.core.config import scout_config
+from scout_apm.core.queue_time import track_request_queue_time
 from scout_apm.core.tracked_request import TrackedRequest
-from scout_apm.core.web_requests import (
-    create_filtered_path,
-    ignore_path,
-    track_request_queue_time,
-)
+from scout_apm.core.web_requests import create_filtered_path, ignore_path
 
 
 class ScoutPlugin(object):
@@ -74,10 +71,10 @@ def wrap_callback(wrapped, instance, args, kwargs):
         "x-request-start", ""
     )
     track_request_queue_time(queue_time, tracked_request)
+    operation = "Controller{}".format(controller_name)
 
-    with tracked_request.span(
-        operation="Controller{}".format(controller_name), should_capture_backtrace=False
-    ):
+    with tracked_request.span(operation=operation):
+        tracked_request.operation = operation
         try:
             value = wrapped(*args, **kwargs)
         except Exception:

scout_apm/celery.py

@@ -5,6 +5,8 @@ import logging
 
 from celery.signals import before_task_publish, task_failure, task_postrun, task_prerun
 
+from scout_apm.core.queue_time import track_job_queue_time
+
 try:
     import django
     from django.views.debug import SafeExceptionReporterFilter
@@ -27,22 +29,17 @@ logger = logging.getLogger(__name__)
 
 def before_task_publish_callback(headers=None, properties=None, **kwargs):
     if "scout_task_start" not in headers:
-        headers["scout_task_start"] = datetime_to_timestamp(dt.datetime.utcnow())
+        headers["scout_task_start"] = datetime_to_timestamp(
+            dt.datetime.now(dt.timezone.utc)
+        )
 
 
 def task_prerun_callback(task=None, **kwargs):
     tracked_request = TrackedRequest.instance()
     tracked_request.is_real_request = True
 
-    start = getattr(task.request, "scout_task_start", None)
-    if start is not None:
-        now = datetime_to_timestamp(dt.datetime.utcnow())
-        try:
-            queue_time = now - start
-        except TypeError:
-            pass
-        else:
-            tracked_request.tag("queue_time", queue_time)
+    start_time_header = getattr(task.request, "scout_task_start", None)
+    track_job_queue_time(start_time_header, tracked_request)
 
     task_id = getattr(task.request, "id", None)
     if task_id:
@@ -59,7 +56,9 @@ def task_prerun_callback(task=None, **kwargs):
         tracked_request.tag("routing_key", delivery_info.get("routing_key", "unknown"))
         tracked_request.tag("queue", delivery_info.get("queue", "unknown"))
 
-    tracked_request.start_span(operation=("Job/" + task.name))
+    operation = "Job/" + task.name
+    tracked_request.start_span(operation=operation)
+    tracked_request.operation = operation
 
 
 def task_postrun_callback(task=None, **kwargs):

scout_apm/core/agent/commands.py

@@ -1,5 +1,6 @@
 # coding=utf-8
 
+import datetime as dt
 import logging
 import re
 
@@ -10,6 +11,18 @@ logger = logging.getLogger(__name__)
 key_regex = re.compile(r"^[a-zA-Z0-9]{20}$")
 
 
+def format_dt_for_core_agent(event_time: dt.datetime) -> str:
+    """
+    Returns expected format for Core Agent compatibility.
+    Coerce any tz-aware datetime to UTC just in case.
+    """
+    # if we somehow got a naive datetime, convert it to UTC
+    if event_time.tzinfo is None:
+        logger.warning("Naive datetime passed to format_dt_for_core_agent")
+        event_time = event_time.astimezone(dt.timezone.utc)
+    return event_time.isoformat()
+
+
 class Register(object):
     __slots__ = ("app", "key", "hostname")
 
@@ -49,7 +62,7 @@ class StartSpan(object):
     def message(self):
         return {
             "StartSpan": {
-                "timestamp": self.timestamp.isoformat() + "Z",
+                "timestamp": format_dt_for_core_agent(self.timestamp),
                 "request_id": self.request_id,
                 "span_id": self.span_id,
                 "parent_id": self.parent,
@@ -69,7 +82,7 @@ class StopSpan(object):
     def message(self):
         return {
             "StopSpan": {
-                "timestamp": self.timestamp.isoformat() + "Z",
+                "timestamp": format_dt_for_core_agent(self.timestamp),
                 "request_id": self.request_id,
                 "span_id": self.span_id,
             }
@@ -86,7 +99,7 @@ class StartRequest(object):
     def message(self):
         return {
             "StartRequest": {
-                "timestamp": self.timestamp.isoformat() + "Z",
+                "timestamp": format_dt_for_core_agent(self.timestamp),
                 "request_id": self.request_id,
             }
         }
@@ -102,7 +115,7 @@ class FinishRequest(object):
     def message(self):
         return {
             "FinishRequest": {
-                "timestamp": self.timestamp.isoformat() + "Z",
+                "timestamp": format_dt_for_core_agent(self.timestamp),
                 "request_id": self.request_id,
             }
         }
@@ -121,7 +134,7 @@ class TagSpan(object):
     def message(self):
         return {
             "TagSpan": {
-                "timestamp": self.timestamp.isoformat() + "Z",
+                "timestamp": format_dt_for_core_agent(self.timestamp),
                 "request_id": self.request_id,
                 "span_id": self.span_id,
                 "tag": self.tag,
@@ -142,7 +155,7 @@ class TagRequest(object):
     def message(self):
         return {
             "TagRequest": {
-                "timestamp": self.timestamp.isoformat() + "Z",
+                "timestamp": format_dt_for_core_agent(self.timestamp),
                 "request_id": self.request_id,
                 "tag": self.tag,
                 "value": self.value,
@@ -162,7 +175,7 @@ class ApplicationEvent(object):
     def message(self):
         return {
             "ApplicationEvent": {
-                "timestamp": self.timestamp.isoformat() + "Z",
+                "timestamp": format_dt_for_core_agent(self.timestamp),
                 "event_type": self.event_type,
                 "event_value": self.event_value,
                 "source": self.source,

scout_apm/core/agent/manager.py

@@ -5,7 +5,6 @@ import hashlib
 import json
 import logging
 import os
-import signal
 import subprocess
 import tarfile
 import time
@@ -17,6 +16,8 @@ from scout_apm.core.config import scout_config
 
 logger = logging.getLogger(__name__)
 
+CA_ALREADY_RUNNING_EXIT_CODE = 3
+
 
 class CoreAgentManager(object):
     def __init__(self):
@@ -73,8 +74,10 @@ class CoreAgentManager(object):
                     stdout=devnull,
                 )
         except subprocess.CalledProcessError as err:
-            if err.returncode in [signal.SIGTERM, signal.SIGQUIT]:
-                logger.debug("Core agent returned signal: {}".format(err.returncode))
+            if err.returncode == CA_ALREADY_RUNNING_EXIT_CODE:
+                # Other processes may have already started the core agent.
+                logger.debug("Core agent already running.")
+                return True
             else:
                 logger.exception("CalledProcessError running Core Agent")
             return False

scout_apm/core/config.py

@@ -4,6 +4,7 @@ import logging
 import os
 import re
 import warnings
+from typing import Any, Dict, List, Optional, Union
 
 from scout_apm.core import platform_detection
 
@@ -30,13 +31,13 @@ class ScoutConfig(object):
             Null(),
         ]
 
-    def value(self, key):
+    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):
+    def locate_layer_for_key(self, key: str) -> Any:
         for layer in self.layers:
             if layer.has_config(key):
                 return layer
@@ -44,7 +45,7 @@ class ScoutConfig(object):
         # Should be unreachable because Null returns None for all keys.
         raise ValueError("key {!r} not found in any layer".format(key))
 
-    def log(self):
+    def log(self) -> None:
         logger.debug("Configuration Loaded:")
         for key in self.known_keys:
             if key in self.secret_keys:
@@ -76,13 +77,20 @@ class ScoutConfig(object):
         "framework",
         "framework_version",
         "hostname",
-        "ignore",
+        "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",
@@ -90,7 +98,7 @@ class ScoutConfig(object):
 
     secret_keys = {"key"}
 
-    def core_agent_permissions(self):
+    def core_agent_permissions(self) -> int:
         try:
             return int(str(self.value("core_agent_permissions")), 8)
         except ValueError:
@@ -100,7 +108,7 @@ class ScoutConfig(object):
             return 0o700
 
     @classmethod
-    def set(cls, **kwargs):
+    def set(cls, **kwargs: Any) -> None:
         """
         Sets a configuration value for the Scout agent. Values set here will
         not override values set in ENV.
@@ -109,7 +117,7 @@ class ScoutConfig(object):
             SCOUT_PYTHON_VALUES[key] = value
 
     @classmethod
-    def unset(cls, *keys):
+    def unset(cls, *keys: str) -> None:
         """
         Removes a configuration value for the Scout agent.
         """
@@ -117,7 +125,7 @@ class ScoutConfig(object):
             SCOUT_PYTHON_VALUES.pop(key, None)
 
     @classmethod
-    def reset_all(cls):
+    def reset_all(cls) -> None:
         """
         Remove all configuration settings set via `ScoutConfig.set(...)`.
 
@@ -135,10 +143,10 @@ class Python(object):
     A configuration overlay that lets other parts of python set values.
     """
 
-    def has_config(self, key):
+    def has_config(self, key: str) -> bool:
         return key in SCOUT_PYTHON_VALUES
 
-    def value(self, key):
+    def value(self, key: str) -> Any:
         return SCOUT_PYTHON_VALUES[key]
 
 
@@ -151,15 +159,15 @@ class Env(object):
     environment variable
     """
 
-    def has_config(self, key):
+    def has_config(self, key: str) -> bool:
         env_key = self.modify_key(key)
         return env_key in os.environ
 
-    def value(self, key):
+    def value(self, key: str) -> Any:
         env_key = self.modify_key(key)
         return os.environ[env_key]
 
-    def modify_key(self, key):
+    def modify_key(self, key: str) -> str:
         env_key = ("SCOUT_" + key).upper()
         return env_key
 
@@ -169,27 +177,27 @@ class Derived(object):
     A configuration overlay that calculates from other values.
     """
 
-    def __init__(self, config):
+    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):
+    def has_config(self, key: str) -> bool:
         return self.lookup_func(key) is not None
 
-    def value(self, key):
+    def value(self, key: str) -> Any:
         return self.lookup_func(key)()
 
-    def lookup_func(self, 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):
+    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(
@@ -201,7 +209,7 @@ class Derived(object):
             triple=triple,
         )
 
-    def derive_core_agent_triple(self):
+    def derive_core_agent_triple(self) -> str:
         return platform_detection.get_triple()
 
 
@@ -221,9 +229,12 @@ class Defaults(object):
             "core_agent_log_level": "info",
             "core_agent_permissions": 700,
             "core_agent_socket_path": "tcp://127.0.0.1:6590",
-            "core_agent_version": "v1.4.0",  # can be an exact tag name, or 'latest'
+            "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
+            "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": (),
@@ -231,26 +242,34 @@ class Defaults(object):
             "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):
+    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):
+    def has_config(self, key: str) -> bool:
         return key in self.defaults
 
-    def value(self, key):
+    def value(self, key: str) -> Any:
         return self.defaults[key]
 
 
@@ -261,14 +280,18 @@ class Null(object):
     Used as the last step of the layered configuration.
     """
 
-    def has_config(self, key):
+    def has_config(self, key: str) -> bool:
         return True
 
-    def value(self, key):
+    def value(self, key: str) -> None:
         return None
 
 
-def convert_to_bool(value):
+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):
@@ -277,14 +300,38 @@ def convert_to_bool(value):
     return False
 
 
-def convert_to_float(value):
+def convert_to_float(value: Any) -> float:
     try:
         return float(value)
     except ValueError:
         return 0.0
 
 
-def convert_to_list(value):
+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):
@@ -296,13 +343,59 @@ def convert_to_list(value):
     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_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_apm/core/metadata.py

@@ -4,7 +4,7 @@ import datetime as dt
 import sys
 from os import getpid
 
-from scout_apm.core.agent.commands import ApplicationEvent
+from scout_apm.core.agent.commands import ApplicationEvent, format_dt_for_core_agent
 from scout_apm.core.agent.socket import CoreAgentSocketThread
 from scout_apm.core.config import scout_config
 
@@ -15,7 +15,7 @@ def report_app_metadata():
             event_type="scout.metadata",
             event_value=get_metadata(),
             source="Pid: " + str(getpid()),
-            timestamp=dt.datetime.utcnow(),
+            timestamp=dt.datetime.now(dt.timezone.utc),
         )
     )
 
@@ -24,7 +24,7 @@ def get_metadata():
     data = {
         "language": "python",
         "language_version": "{}.{}.{}".format(*sys.version_info[:3]),
-        "server_time": dt.datetime.utcnow().isoformat() + "Z",
+        "server_time": format_dt_for_core_agent(dt.datetime.now(dt.timezone.utc)),
         "framework": scout_config.value("framework"),
         "framework_version": scout_config.value("framework_version"),
         "environment": "",