scout-apm 3.3.0__cp38-cp38-musllinux_1_2_x86_64.whl

scout_apm/api/__init__.py

@@ -0,0 +1,197 @@
+# coding=utf-8
+
+import sys
+
+import scout_apm.core
+from scout_apm.compat import ContextDecorator, text
+from scout_apm.core.config import ScoutConfig
+from scout_apm.core.error import ErrorMonitor
+from scout_apm.core.tracked_request import TrackedRequest
+
+# The async_ module can only be shipped on Python 3.6+
+try:
+    from scout_apm.async_.api import AsyncDecoratorMixin
+except ImportError:
+
+    class AsyncDecoratorMixin(object):
+        pass
+
+
+__all__ = [
+    "BackgroundTransaction",
+    "Config",
+    "Context",
+    "Error",
+    "WebTransaction",
+    "install",
+    "instrument",
+]
+
+
+class Context(object):
+    @classmethod
+    def add(self, key, value):
+        """Adds context to the currently executing request.
+
+        :key: Any String identifying the request context.
+              Example: "user_ip", "plan", "alert_count"
+        :value: Any json-serializable type.
+              Example: "1.1.1.1", "free", 100
+        :returns: nothing.
+        """
+        TrackedRequest.instance().tag(key, value)
+
+
+class Config(ScoutConfig):
+    pass
+
+
+install = scout_apm.core.install
+
+
+def ignore_transaction():
+    TrackedRequest.instance().tag("ignore_transaction", True)
+
+
+class instrument(AsyncDecoratorMixin, ContextDecorator):
+    def __init__(self, operation, kind="Custom", tags=None):
+        self.operation = text(kind) + "/" + text(operation)
+        if tags is None:
+            self.tags = {}
+        else:
+            self.tags = tags
+
+    def __enter__(self):
+        tracked_request = TrackedRequest.instance()
+        self.span = tracked_request.start_span(operation=self.operation)
+        for key, value in self.tags.items():
+            self.tag(key, value)
+        return self
+
+    def __exit__(self, *exc):
+        tracked_request = TrackedRequest.instance()
+        tracked_request.stop_span()
+        return False
+
+    def tag(self, key, value):
+        if self.span is not None:
+            self.span.tag(key, value)
+
+
+class Transaction(AsyncDecoratorMixin, ContextDecorator):
+    """
+    This Class is not meant to be used directly.
+    Use one of the subclasses
+    (WebTransaction or BackgroundTransaction)
+    """
+
+    def __init__(self, name, tags=None):
+        self.name = text(name)
+        if tags is None:
+            self.tags = {}
+        else:
+            self.tags = tags
+
+    @classmethod
+    def start(cls, kind, name, tags=None):
+        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
+        )
+        if tags is not None:
+            for key, value in tags.items():
+                tracked_request.tag(key, value)
+        return span
+
+    @classmethod
+    def stop(cls):
+        tracked_request = TrackedRequest.instance()
+        tracked_request.stop_span()
+        return True
+
+    # __enter__ must be defined by child classes.
+
+    # *exc is any exception raised. Ignore that
+    def __exit__(self, *exc):
+        WebTransaction.stop()
+        return False
+
+    def tag(self, key, value):
+        if self.span is not None:
+            self.span.tag(key, value)
+
+
+class WebTransaction(Transaction):
+    @classmethod
+    def start(cls, name, tags=None):
+        super(WebTransaction, cls).start("Controller", text(name), tags)
+
+    def __enter__(self):
+        super(WebTransaction, self).start("Controller", self.name, self.tags)
+
+
+class BackgroundTransaction(Transaction):
+    @classmethod
+    def start(cls, name, tags=None):
+        super(BackgroundTransaction, cls).start("Job", text(name), tags)
+
+    def __enter__(self):
+        super(BackgroundTransaction, self).start("Job", self.name, self.tags)
+
+
+def rename_transaction(name):
+    if name is not None:
+        tracked_request = TrackedRequest.instance()
+        tracked_request.tag("transaction.name", name)
+
+
+class Error(object):
+    @classmethod
+    def capture(
+        cls,
+        exception,
+        request_path=None,
+        request_params=None,
+        session=None,
+        custom_controller=None,
+        custom_params=None,
+    ):
+        """
+        Capture the exception manually.
+
+        Utilizes sys.exc_info to gather the traceback. This has the side
+        effect that if another exception is raised before calling
+        ``Error.capture``, the traceback will match the most recently
+        raised exception.
+
+        Includes any context added for the TrackedRequest.
+
+        :exception: Any exception.
+        :request_path: Any String identifying the relative path of the request.
+              Example: "/hello-world/"
+        :request_params: Any json-serializable dict representing the
+              querystring parameters.
+              Example: {"page": 1}
+        :session: Any json-serializable dict representing the
+              request session.
+              Example: {"step": 0}
+        :custom_controller: Any String identifying the controller or job.
+              Example: "send_email"
+        :custom_params: Any json-serializable dict.
+              Example: {"to": "scout@test.com", "from": "no-reply@test.com"}
+        :returns: nothing.
+        """
+        if isinstance(exception, Exception):
+            exc_info = (exception.__class__, exception, sys.exc_info()[2])
+            ErrorMonitor.send(
+                exc_info,
+                request_path=request_path,
+                request_params=request_params,
+                session=session,
+                custom_controller=custom_controller,
+                custom_params=custom_params,
+            )

scout_apm/async_/__init__.py

@@ -0,0 +1 @@
+# coding=utf-8

scout_apm/async_/api.py

@@ -0,0 +1,41 @@
+# coding=utf-8
+
+from functools import wraps
+
+
+class AsyncDecoratorMixin(object):
+    """Provide the ability to decorate both sync and async functions."""
+
+    is_async = False
+
+    @classmethod
+    def async_(cls, operation, tags=None, **kwargs):
+        """
+        Instrument an async function via a decorator.
+
+        This will return an awaitable which must be awaited.
+        Using this on a synchronous function will raise a
+        RuntimeError.
+
+        ``
+           @instrument.async_("Foo")
+           async def foo():
+              ...
+        ``
+        """
+        instance = cls(operation, tags=tags, **kwargs)
+        instance.is_async = True
+        return instance
+
+    def __call__(self, func):
+        if self.is_async:
+            # Until https://bugs.python.org/issue37398 has a resolution,
+            # manually wrap the async function
+            @wraps(func)
+            async def decorated(*args, **kwds):
+                with self._recreate_cm():
+                    return await func(*args, **kwds)
+
+            return decorated
+        else:
+            return super().__call__(func)

scout_apm/async_/instruments/jinja2.py

@@ -0,0 +1,13 @@
+# coding=utf-8
+
+import wrapt
+
+from scout_apm.core.tracked_request import TrackedRequest
+
+
+@wrapt.decorator
+async def wrapped_render_async(wrapped, instance, args, kwargs):
+    tracked_request = TrackedRequest.instance()
+    with tracked_request.span(operation="Template/Render") as span:
+        span.tag("name", instance.name)
+        return await wrapped(*args, **kwargs)

scout_apm/async_/starlette.py

@@ -0,0 +1,101 @@
+# coding=utf-8
+
+import wrapt
+from starlette.background import BackgroundTask
+
+import scout_apm.core
+from scout_apm.core.tracked_request import TrackedRequest
+from scout_apm.core.web_requests import asgi_track_request_data
+
+
+class ScoutMiddleware:
+    def __init__(self, app):
+        self.app = app
+        installed = scout_apm.core.install()
+        self._do_nothing = not installed
+        if installed:
+            install_background_instrumentation()
+
+    async def __call__(self, scope, receive, send):
+        if self._do_nothing or scope["type"] != "http":
+            return await self.app(scope, receive, send)
+
+        tracked_request = TrackedRequest.instance()
+        # Assume the request is real until we determine it's not. This is useful
+        # when the asyncio instrumentation is determining if a new Task should
+        # reuse the existing tracked request.
+        tracked_request.is_real_request = True
+        # Can't name controller until post-routing - see final clause
+        controller_span = tracked_request.start_span(operation="Controller/Unknown")
+
+        asgi_track_request_data(scope, tracked_request)
+
+        def grab_extra_data():
+            if "endpoint" in scope:
+                # Rename top span
+                endpoint = scope["endpoint"]
+                if not hasattr(endpoint, "__qualname__"):
+                    endpoint = endpoint.__class__
+                controller_span.operation = "Controller/{}.{}".format(
+                    endpoint.__module__,
+                    endpoint.__qualname__,
+                )
+                tracked_request.operation = controller_span.operation
+            else:
+                # Mark the request as not real
+                tracked_request.is_real_request = False
+
+            # From AuthenticationMiddleware - bypass request.user because it
+            # throws AssertionError if 'user' is not in Scope, and we need a
+            # try/except already
+            try:
+                username = scope["user"].display_name
+            except (KeyError, AttributeError):
+                pass
+            else:
+                tracked_request.tag("username", username)
+
+        async def wrapped_send(data):
+            type_ = data.get("type", None)
+            if type_ == "http.response.start" and 500 <= data.get("status", 200) <= 599:
+                tracked_request.tag("error", "true")
+            elif type_ == "http.response.body" and not data.get("more_body", False):
+                # Finish HTTP span when body finishes sending, not later (e.g.
+                # after background tasks)
+                grab_extra_data()
+                tracked_request.stop_span()
+            return await send(data)
+
+        try:
+            await self.app(scope, receive, wrapped_send)
+        except Exception as exc:
+            tracked_request.tag("error", "true")
+            raise exc
+        finally:
+            if tracked_request.end_time is None:
+                grab_extra_data()
+                tracked_request.stop_span()
+
+
+background_instrumentation_installed = False
+
+
+def install_background_instrumentation():
+    global background_instrumentation_installed
+    if background_instrumentation_installed:
+        return
+    background_instrumentation_installed = True
+
+    @wrapt.decorator
+    async def wrapped_background_call(wrapped, instance, args, kwargs):
+        tracked_request = TrackedRequest.instance()
+        tracked_request.is_real_request = True
+
+        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

@@ -0,0 +1,86 @@
+# coding=utf-8
+
+import wrapt
+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
+
+
+class ScoutPlugin(object):
+    def __init__(self):
+        self.name = "scout"
+        self.api = 2
+
+    def set_config_from_bottle(self, app):
+        bottle_configs = {}
+        prefix = "scout."
+        prefix_len = len(prefix)
+        for key, value in app.config.items():
+            if key.startswith(prefix) and len(key) > prefix_len:
+                scout_key = key[prefix_len:]
+                bottle_configs[scout_key] = value
+        scout_config.set(**bottle_configs)
+
+    def setup(self, app):
+        self.set_config_from_bottle(app)
+        installed = scout_apm.core.install()
+        self._do_nothing = not installed
+
+    def apply(self, callback, context):
+        if self._do_nothing:
+            return callback
+        return wrap_callback(callback)
+
+
+@wrapt.decorator
+def wrap_callback(wrapped, instance, args, kwargs):
+    tracked_request = TrackedRequest.instance()
+    tracked_request.is_real_request = True
+
+    path = request.path
+    # allitems() is an undocumented bottle internal
+    tracked_request.tag("path", create_filtered_path(path, request.query.allitems()))
+    if ignore_path(path):
+        tracked_request.tag("ignore_transaction", True)
+
+    if request.route.name is not None:
+        controller_name = request.route.name
+    else:
+        controller_name = request.route.rule
+    if controller_name == "/":
+        controller_name = "/home"
+    if not controller_name.startswith("/"):
+        controller_name = "/" + controller_name
+
+    if scout_config.value("collect_remote_ip"):
+        # Determine a remote IP to associate with the request. The
+        # value is spoofable by the requester so this is not suitable
+        # to use in any security sensitive context.
+        user_ip = (
+            request.headers.get("x-forwarded-for", "").split(",")[0]
+            or request.headers.get("client-ip", "").split(",")[0]
+            or request.environ.get("REMOTE_ADDR")
+        )
+        tracked_request.tag("user_ip", user_ip)
+
+    queue_time = request.headers.get("x-queue-start", "") or request.headers.get(
+        "x-request-start", ""
+    )
+    track_request_queue_time(queue_time, tracked_request)
+    operation = "Controller{}".format(controller_name)
+
+    with tracked_request.span(operation=operation):
+        tracked_request.operation = operation
+        try:
+            value = wrapped(*args, **kwargs)
+        except Exception:
+            tracked_request.tag("error", "true")
+            raise
+        else:
+            if 500 <= response.status_code <= 599:
+                tracked_request.tag("error", "true")
+            return value

scout_apm/celery.py

@@ -0,0 +1,153 @@
+# coding=utf-8
+
+import datetime as dt
+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
+
+    def get_safe_settings():
+        return SafeExceptionReporterFilter().get_safe_settings()
+
+except ImportError:
+    # Django not installed
+    get_safe_settings = None
+
+import scout_apm.core
+from scout_apm.compat import datetime_to_timestamp
+from scout_apm.core.config import scout_config
+from scout_apm.core.error import ErrorMonitor
+from scout_apm.core.tracked_request import TrackedRequest
+
+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.now(dt.timezone.utc)
+        )
+
+
+def task_prerun_callback(task=None, **kwargs):
+    tracked_request = TrackedRequest.instance()
+    tracked_request.is_real_request = True
+
+    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:
+        tracked_request.tag("task_id", task_id)
+    parent_task_id = getattr(task.request, "parent_id", None)
+    if parent_task_id:
+        tracked_request.tag("parent_task_id", parent_task_id)
+
+    delivery_info = getattr(task.request, "delivery_info", None)
+    if delivery_info:
+        tracked_request.tag("is_eager", delivery_info.get("is_eager", False))
+        tracked_request.tag("exchange", delivery_info.get("exchange", "unknown"))
+        tracked_request.tag("priority", delivery_info.get("priority", "unknown"))
+        tracked_request.tag("routing_key", delivery_info.get("routing_key", "unknown"))
+        tracked_request.tag("queue", delivery_info.get("queue", "unknown"))
+
+    operation = "Job/" + task.name
+    tracked_request.start_span(operation=operation)
+    tracked_request.operation = operation
+
+
+def task_postrun_callback(task=None, **kwargs):
+    tracked_request = TrackedRequest.instance()
+    tracked_request.stop_span()
+
+
+def task_failure_callback(
+    sender,
+    task_id=None,
+    exception=None,
+    args=None,
+    kwargs=None,
+    traceback=None,
+    einfo=None,
+    **remaining,
+):
+    tracked_request = TrackedRequest.instance()
+    tracked_request.tag("error", "true")
+
+    custom_controller = sender.name
+    custom_params = {
+        "celery": {
+            "task_id": task_id,
+            "args": args,
+            "kwargs": kwargs,
+        }
+    }
+
+    # Look up the django settings if populated.
+    environment = None
+    if get_safe_settings:
+        try:
+            environment = get_safe_settings()
+        except django.core.exceptions.ImproperlyConfigured as exc:
+            # Django not setup correctly
+            logger.debug(
+                "Celery integration does not have django configured properly: %r", exc
+            )
+            pass
+        except Exception as exc:
+            logger.debug(
+                "Celery task_failure callback exception: %r", exc, exc_info=exc
+            )
+            pass
+
+    # Celery occassionally will send the traceback as a string rather
+    # than a Stack trace object as the docs indicate. In that case,
+    # fall back to the billiard ExceptionInfo instance
+    traceback = traceback if traceback and not isinstance(traceback, str) else einfo.tb
+    exc_info = (exception.__class__, exception, traceback)
+    ErrorMonitor.send(
+        exc_info,
+        environment=environment,
+        custom_params=custom_params,
+        custom_controller=custom_controller,
+    )
+
+
+def install(app=None):
+    if app is not None:
+        copy_configuration(app)
+
+    installed = scout_apm.core.install()
+    if not installed:
+        return
+
+    before_task_publish.connect(before_task_publish_callback)
+    task_prerun.connect(task_prerun_callback)
+    task_failure.connect(task_failure_callback)
+    task_postrun.connect(task_postrun_callback)
+
+
+def copy_configuration(app):
+    prefix = "scout_"
+    prefix_len = len(prefix)
+
+    to_set = {}
+    for key, value in app.conf.items():
+        key_lower = key.lower()
+        if key_lower.startswith(prefix) and len(key_lower) > prefix_len:
+            scout_key = key_lower[prefix_len:]
+            to_set[scout_key] = value
+
+    scout_config.set(**to_set)
+
+
+def uninstall():
+    before_task_publish.disconnect(before_task_publish_callback)
+    task_prerun.disconnect(task_prerun_callback)
+    task_postrun.disconnect(task_postrun_callback)
+    task_failure.disconnect(task_failure_callback)

scout_apm/compat.py

@@ -0,0 +1,104 @@
+# coding=utf-8
+
+import datetime as dt
+import gzip
+import inspect
+import queue
+from contextlib import ContextDecorator
+from functools import wraps
+from html import escape
+from urllib.parse import parse_qsl, urlencode, urljoin
+
+import certifi
+import urllib3
+
+
+def iteritems(dictionary):
+    return dictionary.items()
+
+
+# datetime_to_timestamp converts a naive UTC datetime to a unix timestamp
+def datetime_to_timestamp(datetime_obj):
+    return datetime_obj.replace(tzinfo=dt.timezone.utc).timestamp()
+
+
+def text(value, encoding="utf-8", errors="strict"):
+    """
+    Convert a value to str on Python 3 and unicode on Python 2.
+    """
+    if isinstance(value, str):
+        return value
+    elif isinstance(value, bytes):
+        return str(value, encoding, errors)
+    else:
+        return str(value)
+
+
+def get_pos_args(func):
+    return inspect.getfullargspec(func).args
+
+
+def unwrap_decorators(func):
+    unwrapped = func
+    while True:
+        # N.B. only some decorators set __wrapped__ on Python 2.7
+        try:
+            unwrapped = unwrapped.__wrapped__
+        except AttributeError:
+            break
+    return unwrapped
+
+
+def kwargs_only(func):
+    """
+    Source: https://pypi.org/project/kwargs-only/
+    Make a function only accept keyword arguments.
+    This can be dropped in Python 3 in lieu of:
+        def foo(*, bar=default):
+    Source: https://pypi.org/project/kwargs-only/
+    """
+    if hasattr(inspect, "signature"):  # pragma: no cover
+        # Python 3
+        signature = inspect.signature(func)
+        arg_names = list(signature.parameters.keys())
+    else:  # pragma: no cover
+        # Python 2
+        signature = inspect.getargspec(func)
+        arg_names = signature.args
+
+    if len(arg_names) > 0 and arg_names[0] in ("self", "cls"):
+        allowable_args = 1
+    else:
+        allowable_args = 0
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        if len(args) > allowable_args:
+            raise TypeError(
+                "{} should only be called with keyword args".format(func.__name__)
+            )
+        return func(*args, **kwargs)
+
+    return wrapper
+
+
+def urllib3_cert_pool_manager(**kwargs):
+    return urllib3.PoolManager(cert_reqs="CERT_REQUIRED", ca_certs=certifi.where())
+
+
+def gzip_compress(data):
+    return gzip.compress(data)
+
+
+__all__ = [
+    "ContextDecorator",
+    "datetime_to_timestamp",
+    "escape",
+    "gzip_compress",
+    "kwargs_only",
+    "parse_qsl",
+    "queue",
+    "text",
+    "urlencode",
+    "urljoin",
+]