canvas 0.34.0__py3-none-any.whl → 0.35.0__py3-none-any.whl

canvas_sdk/utils/metrics.py

@@ -0,0 +1,192 @@
+import time
+from collections.abc import Callable, Generator
+from contextlib import contextmanager
+from datetime import timedelta
+from functools import wraps
+from typing import Any, TypeVar, cast, overload
+
+from django.conf import settings
+from statsd.client.base import StatsClientBase
+from statsd.client.udp import Pipeline
+from statsd.defaults.env import statsd as default_statsd_client
+
+LINE_PROTOCOL_TRANSLATION = str.maketrans(
+    {
+        ",": r"\,",
+        "=": r"\=",
+        " ": r"\ ",
+        ":": r"__",
+    }
+)
+
+
+def tags_to_line_protocol(tags: dict[str, Any]) -> str:
+    """Generate a tags string compatible with the InfluxDB line protocol.
+
+    See: https://docs.influxdata.com/influxdb/v1.1/write_protocols/line_protocol_tutorial/
+    """
+    return ",".join(
+        f"{tag_name}={str(tag_value).translate(LINE_PROTOCOL_TRANSLATION)}"
+        for tag_name, tag_value in tags.items()
+    )
+
+
+def get_qualified_name(fn: Callable) -> str:
+    """Get the qualified name of a function."""
+    return f"{fn.__module__}.{fn.__qualname__}"
+
+
+class StatsDClientProxy:
+    """Proxy for a StatsD client."""
+
+    def __init__(self) -> None:
+        self.client = default_statsd_client
+
+    def gauge(self, metric_name: str, value: float, tags: dict[str, str]) -> None:
+        """Sends a gauge metric to StatsD with properly formatted tags.
+
+        Args:
+            metric_name (str): The name of the metric.
+            value (float): The value to report.
+            tags (dict[str, str]): Dictionary of tags to attach to the metric.
+        """
+        if not settings.METRICS_ENABLED:
+            return
+
+        statsd_tags = tags_to_line_protocol(tags)
+        self.client.gauge(f"{metric_name},{statsd_tags}", value)
+
+    def timing(self, metric_name: str, delta: float | timedelta, tags: dict[str, str]) -> None:
+        """Sends a timing metric to StatsD with properly formatted tags.
+
+        Args:
+            metric_name (str): The name of the metric.
+            delta (float | timedelta): The value to report.
+            tags (dict[str, str]): Dictionary of tags to attach to the metric.
+        """
+        if not settings.METRICS_ENABLED:
+            return
+
+        statsd_tags = tags_to_line_protocol(tags)
+        self.client.timing(f"{metric_name},{statsd_tags}", delta)
+
+    def incr(self, metric_name: str, tags: dict[str, str], count: int = 1, rate: int = 1) -> None:
+        """Sends an increment metric to StatsD with properly formatted tags.
+
+        Args:
+            metric_name (str): The name of the metric.
+            count (int): The increment to report.
+            rate (int): The sample rate.
+            tags (dict[str, str]): Dictionary of tags to attach to the metric.
+        """
+        if not settings.METRICS_ENABLED:
+            return
+
+        statsd_tags = tags_to_line_protocol(tags)
+        self.client.incr(f"{metric_name},{statsd_tags}", count, rate)
+
+    def pipeline(self) -> "PipelineProxy":
+        """Returns a pipeline for batching StatsD metrics."""
+        return PipelineProxy(self.client)
+
+
+class PipelineProxy(StatsDClientProxy):
+    """Proxy for a StatsD pipeline."""
+
+    def __init__(self, client: StatsClientBase | None) -> None:
+        super().__init__()
+        self.client = Pipeline(client or self.client)
+
+    def send(self) -> None:
+        """Sends the batched metrics to StatsD."""
+        if not settings.METRICS_ENABLED:
+            return
+
+        self.client.send()
+
+
+statsd_client = StatsDClientProxy()
+
+
+@contextmanager
+def measure(
+    name: str,
+    extra_tags: dict[str, str] | None = None,
+    client: StatsDClientProxy | None = None,
+    track_plugins_usage: bool = False,
+) -> Generator[PipelineProxy, None, None]:
+    """A context manager for collecting metrics about a context block.
+
+    Args:
+        name: The name of the block being measured (added as a StatsD tag)
+        extra_tags: A dict of extra tags to be added to all recorded metrics.
+        client: An optional alternate StatsD client.
+        track_plugins_usage: Whether to track plugin usage (Adds plugin and handler tags if the caller was a plugin).
+
+    Yields:
+        A pipeline for collecting additional metrics in the same batch.
+    """
+    client = client or statsd_client
+
+    if track_plugins_usage:
+        from canvas_sdk.utils.plugins import is_plugin_caller
+
+        is_plugin, caller = is_plugin_caller()
+        if is_plugin and caller:
+            extra_tags = extra_tags or {}
+            extra_tags["plugin"] = caller.split(".")[0]
+            extra_tags["handler"] = caller
+
+    tags = {"name": name, **(extra_tags or {})}
+
+    pipeline = client.pipeline()
+    timing_start = time.perf_counter_ns()
+    try:
+        yield pipeline
+    except BaseException as ex:
+        tags = {**tags, "status": "error"}
+        raise ex
+    else:
+        tags = {**tags, "status": "success"}
+    finally:
+        duration_ms = (time.perf_counter_ns() - timing_start) / 1_000_000
+        pipeline.timing("plugins.timings", duration_ms, tags=tags)
+        pipeline.incr("plugins.executions", tags=tags)
+        pipeline.send()
+
+
+F = TypeVar("F", bound=Callable)
+
+
+@overload
+def measured(fn: F) -> F: ...
+
+
+@overload
+def measured(**options: Any) -> Callable[[F], F]: ...
+
+
+def measured(fn: F | None = None, **options: Any) -> Callable[[F], F] | F:
+    """Collect metrics about the decorated function.
+
+    Args:
+        fn: The decorated function.
+        options: Additional options for the decorator, such as `client` and `extra_tags`.
+
+    Returns:
+        A decorated function if called without arguments (@measured), or a
+        decorator if called with arguments (@measured(client=...))
+    """
+
+    def _decorator(fn: F) -> F:
+        @wraps(fn)
+        def _wrapped(*args: Any, **kwargs: Any) -> Any:
+            with measure(get_qualified_name(fn), **options):
+                return fn(*args, **kwargs)
+
+        return cast(F, _wrapped)
+
+    return _decorator(fn) if fn else _decorator
+
+
+__exports__ = ()

canvas_sdk/utils/plugins.py

@@ -1,11 +1,14 @@
 import inspect
 from collections.abc import Callable
 from pathlib import Path
+from types import FrameType
 from typing import Any
 
+from canvas_sdk.utils.metrics import measured
 from settings import PLUGIN_DIRECTORY
 
 
+@measured
 def plugin_only(func: Callable[..., Any]) -> Callable[..., Any]:
     """Decorator to restrict a function's execution to plugins only."""
 
@@ -26,4 +29,25 @@ def plugin_only(func: Callable[..., Any]) -> Callable[..., Any]:
     return wrapper
 
 
+@measured
+def is_plugin_caller(depth: int = 10, frame: FrameType | None = None) -> tuple[bool, str | None]:
+    """Check if a function is called from a plugin."""
+    current_frame = frame or inspect.currentframe()
+    caller = current_frame.f_back if current_frame else None
+
+    if not caller:
+        return False, None
+
+    if "__is_plugin__" not in caller.f_globals:
+        if depth > 0:
+            return is_plugin_caller(frame=caller, depth=depth - 1)
+        else:
+            return False, None
+
+    module = caller.f_globals.get("__name__")
+    qualname = caller.f_code.co_qualname
+
+    return True, f"{module}.{qualname}"
+
+
 __exports__ = ()

canvas_sdk/v1/data/__init__.py

@@ -21,6 +21,7 @@ from .lab import (
     LabValueCoding,
 )
 from .medication import Medication, MedicationCoding
+from .message import Message, MessageAttachment, MessageTransmission
 from .note import Note, NoteType
 from .observation import (
     Observation,
@@ -89,6 +90,9 @@ __all__ = __exports__ = (
     "LabValueCoding",
     "Medication",
     "MedicationCoding",
+    "Message",
+    "MessageAttachment",
+    "MessageTransmission",
     "Note",
     "NoteType",
     "Observation",

canvas_sdk/v1/data/message.py

@@ -0,0 +1,82 @@
+from django.db import models
+
+
+class TransmissionChannel(models.TextChoices):
+    """Transmission channel."""
+
+    MANUAL = "manual", "Manual"
+    TEXT_MESSAGE = "sms", "Text Message"
+    EMAIL = "email", "Email"
+    NOOP = "noop", "No-op"
+
+
+class Message(models.Model):
+    """Message."""
+
+    class Meta:
+        managed = False
+        db_table = "canvas_sdk_data_api_message_001"
+
+    id = models.UUIDField()
+    dbid = models.BigIntegerField(primary_key=True)
+    created = models.DateTimeField()
+    modified = models.DateTimeField()
+    content = models.TextField()
+    sender = models.ForeignKey(
+        "v1.CanvasUser", on_delete=models.DO_NOTHING, related_name="sent_messages", null=True
+    )
+    recipient = models.ForeignKey(
+        "v1.CanvasUser", on_delete=models.DO_NOTHING, related_name="received_messages", null=True
+    )
+    note = models.ForeignKey(
+        "v1.Note", on_delete=models.DO_NOTHING, related_name="message", null=True
+    )
+    read = models.BooleanField()
+
+
+class MessageAttachment(models.Model):
+    """Message attachment."""
+
+    class Meta:
+        managed = False
+        db_table = "canvas_sdk_data_api_messageattachment_001"
+
+    id = models.UUIDField()
+    dbid = models.BigIntegerField(primary_key=True)
+    file = models.TextField()
+    content_type = models.CharField(max_length=255)
+    message = models.ForeignKey(
+        "v1.Message", on_delete=models.DO_NOTHING, related_name="message", null=True
+    )
+
+
+class MessageTransmission(models.Model):
+    """Message Transmission."""
+
+    class Meta:
+        managed = False
+        db_table = "canvas_sdk_data_api_messagetransmission_001"
+
+    id = models.UUIDField()
+    dbid = models.BigIntegerField(primary_key=True)
+    created = models.DateTimeField()
+    modified = models.DateTimeField()
+    message = models.ForeignKey(
+        "v1.Message", on_delete=models.DO_NOTHING, related_name="transmissions", null=True
+    )
+    delivered = models.BooleanField()
+    failed = models.BooleanField()
+
+    contact_point_system = models.CharField(choices=TransmissionChannel.choices)
+    contact_point_value = models.CharField(max_length=255)
+
+    comment = models.TextField()
+    delivered_by = models.ForeignKey(
+        "v1.Staff",
+        on_delete=models.DO_NOTHING,
+        related_name="transmissions_delivered",
+        null=True,
+    )
+
+
+__exports__ = ("TransmissionChannel", "Message", "MessageAttachment", "MessageTransmission")

plugin_runner/load_all_plugins.py

@@ -18,11 +18,8 @@ from canvas_generated.messages.events_pb2 import PLUGIN_CREATED
 from canvas_generated.messages.events_pb2 import Event as EventRequest
 from canvas_sdk.events.base import Event
 from canvas_sdk.protocols.base import BaseProtocol
-from canvas_sdk.utils import stats
 from plugin_runner.plugin_runner import LOADED_PLUGINS, load_or_reload_plugin
 
-stats.STATS_ENABLED = False
-
 ORIGINAL_PATH = sys.path.copy()
 
 

plugin_runner/plugin_runner.py

@@ -5,7 +5,6 @@ import pathlib
 import pickle
 import pkgutil
 import sys
-import time
 import traceback
 from collections import defaultdict
 from collections.abc import AsyncGenerator
@@ -29,7 +28,8 @@ from canvas_sdk.effects import Effect
 from canvas_sdk.effects.simple_api import Response
 from canvas_sdk.events import Event, EventRequest, EventResponse, EventType
 from canvas_sdk.protocols import ClinicalQualityMeasure
-from canvas_sdk.utils.stats import get_duration_ms, statsd_client
+from canvas_sdk.utils import metrics
+from canvas_sdk.utils.metrics import measured, statsd_client
 from logger import log
 from plugin_runner.authentication import token_for_plugin
 from plugin_runner.installation import install_plugins
@@ -177,121 +177,118 @@ class PluginRunner(PluginRunnerServicer):
         self, request: EventRequest, context: Any
     ) -> AsyncGenerator[EventResponse, None]:
         """This is invoked when an event comes in."""
-        event_start_time = time.time()
         event = Event(request)
-        event_type = event.type
-        event_name = event.name
-        relevant_plugins = EVENT_HANDLER_MAP[event_name]
-        relevant_plugin_handlers = []
-
-        log.debug(f"Processing {relevant_plugins} for {event_name}")
-        sentry_sdk.set_tag("event-name", event_name)
-
-        if relevant_plugins:
-            await reconnect_if_needed()
-
-        if event_type in [EventType.PLUGIN_CREATED, EventType.PLUGIN_UPDATED]:
-            plugin_name = event.target.id
-            # filter only for the plugin(s) that were created/updated
-            relevant_plugins = [p for p in relevant_plugins if p.startswith(f"{plugin_name}:")]
-        elif event_type in {EventType.SIMPLE_API_AUTHENTICATE, EventType.SIMPLE_API_REQUEST}:
-            # The target plugin's name will be part of the home-app URL path, so other plugins that
-            # respond to SimpleAPI request events are not relevant
-            plugin_name = event.context["plugin_name"]
-            relevant_plugins = [p for p in relevant_plugins if p.startswith(f"{plugin_name}:")]
-
-        effect_list = []
-
-        for plugin_name in relevant_plugins:
-            log.debug(f"Processing {plugin_name}")
-            sentry_sdk.set_tag("plugin-name", plugin_name)
-
-            plugin = LOADED_PLUGINS[plugin_name]
-            handler_class = plugin["class"]
-            base_plugin_name = plugin_name.split(":")[0]
+        with metrics.measure(
+            metrics.get_qualified_name(self.HandleEvent), extra_tags={"event": event.name}
+        ):
+            event_type = event.type
+            event_name = event.name
+            relevant_plugins = EVENT_HANDLER_MAP[event_name]
+            relevant_plugin_handlers = []
+
+            log.debug(f"Processing {relevant_plugins} for {event_name}")
+            sentry_sdk.set_tag("event-name", event_name)
+
+            if relevant_plugins:
+                await reconnect_if_needed()
+
+            if event_type in [EventType.PLUGIN_CREATED, EventType.PLUGIN_UPDATED]:
+                plugin_name = event.target.id
+                # filter only for the plugin(s) that were created/updated
+                relevant_plugins = [p for p in relevant_plugins if p.startswith(f"{plugin_name}:")]
+            elif event_type in {EventType.SIMPLE_API_AUTHENTICATE, EventType.SIMPLE_API_REQUEST}:
+                # The target plugin's name will be part of the home-app URL path, so other plugins that
+                # respond to SimpleAPI request events are not relevant
+                plugin_name = event.context["plugin_name"]
+                relevant_plugins = [p for p in relevant_plugins if p.startswith(f"{plugin_name}:")]
+
+            effect_list = []
+
+            for plugin_name in relevant_plugins:
+                log.debug(f"Processing {plugin_name}")
+                sentry_sdk.set_tag("plugin-name", plugin_name)
+
+                plugin = LOADED_PLUGINS[plugin_name]
+                handler_class = plugin["class"]
+                base_plugin_name = plugin_name.split(":")[0]
+
+                secrets = plugin.get("secrets", {})
+
+                secrets.update(
+                    {"graphql_jwt": token_for_plugin(plugin_name=plugin_name, audience="home")}
+                )
 
-            secrets = plugin.get("secrets", {})
+                try:
+                    handler = handler_class(event, secrets, ENVIRONMENT)
 
-            secrets.update(
-                {"graphql_jwt": token_for_plugin(plugin_name=plugin_name, audience="home")}
-            )
+                    if not handler.accept_event():
+                        continue
+                    relevant_plugin_handlers.append(handler_class)
 
-            try:
-                handler = handler_class(event, secrets, ENVIRONMENT)
-
-                if not handler.accept_event():
+                    classname = (
+                        handler.__class__.__name__
+                        if isinstance(handler, ClinicalQualityMeasure)
+                        else None
+                    )
+                    handler_name = metrics.get_qualified_name(handler.compute)
+                    with metrics.measure(
+                        name=handler_name,
+                        extra_tags={
+                            "plugin": base_plugin_name,
+                            "event": event_name,
+                        },
+                    ):
+                        _effects = await sync_to_async(handler.compute)()
+                        effects = [
+                            Effect(
+                                type=effect.type,
+                                payload=effect.payload,
+                                plugin_name=base_plugin_name,
+                                classname=classname,
+                                handler_name=handler_name,
+                            )
+                            for effect in _effects
+                        ]
+
+                        effects = validate_effects(effects)
+
+                        apply_effects_to_context(effects, event=event)
+
+                        log.info(f"{plugin_name}.compute() completed.")
+
+                except Exception as e:
+                    log.error(f"Encountered exception in plugin {plugin_name}:")
+
+                    for error_line_with_newlines in traceback.format_exception(e):
+                        for error_line in error_line_with_newlines.split("\n"):
+                            log.error(error_line)
+
+                    sentry_sdk.capture_exception(e)
                     continue
-                relevant_plugin_handlers.append(handler_class)
 
-                classname = (
-                    handler.__class__.__name__
-                    if isinstance(handler, ClinicalQualityMeasure)
-                    else None
-                )
-
-                compute_start_time = time.time()
-                _effects = await sync_to_async(handler.compute)()
-                effects = [
-                    Effect(
-                        type=effect.type,
-                        payload=effect.payload,
-                        plugin_name=base_plugin_name,
-                        classname=classname,
+                effect_list += effects
+
+            sentry_sdk.set_tag("plugin-name", None)
+
+            # Special handling for SimpleAPI requests: if there were no relevant handlers (as determined
+            # by calling ignore_event on handlers), then set the effects list to be a single 404 Not
+            # Found response effect. If multiple handlers were able to respond, log an error and set the
+            # effects list to be a single 500 Internal Server Error response effect.
+            if event.type in {EventType.SIMPLE_API_AUTHENTICATE, EventType.SIMPLE_API_REQUEST}:
+                if len(relevant_plugin_handlers) == 0:
+                    effect_list = [Response(status_code=HTTPStatus.NOT_FOUND).apply()]
+                elif len(relevant_plugin_handlers) > 1:
+                    log.error(
+                        f"Multiple handlers responded to {EventType.Name(EventType.SIMPLE_API_REQUEST)}"
+                        f" {event.context['path']}"
                     )
-                    for effect in _effects
-                ]
-
-                effects = validate_effects(effects)
-
-                apply_effects_to_context(effects, event=event)
+                    effect_list = [Response(status_code=HTTPStatus.INTERNAL_SERVER_ERROR).apply()]
 
-                compute_duration = get_duration_ms(compute_start_time)
+            # Don't log anything if a plugin handler didn't actually run.
+            if relevant_plugins:
+                log.info(f"Responded to Event {event_name}.")
 
-                log.info(f"{plugin_name}.compute() completed ({compute_duration} ms)")
-                statsd_client.timing(
-                    "plugins.protocol_duration_ms",
-                    delta=compute_duration,
-                    tags={"plugin": plugin_name},
-                )
-            except Exception as e:
-                log.error(f"Encountered exception in plugin {plugin_name}:")
-
-                for error_line_with_newlines in traceback.format_exception(e):
-                    for error_line in error_line_with_newlines.split("\n"):
-                        log.error(error_line)
-
-                sentry_sdk.capture_exception(e)
-
-                continue
-
-            effect_list += effects
-
-        sentry_sdk.set_tag("plugin-name", None)
-
-        # Special handling for SimpleAPI requests: if there were no relevant handlers (as determined
-        # by calling ignore_event on handlers), then set the effects list to be a single 404 Not
-        # Found response effect. If multiple handlers were able to respond, log an error and set the
-        # effects list to be a single 500 Internal Server Error response effect.
-        if event.type in {EventType.SIMPLE_API_AUTHENTICATE, EventType.SIMPLE_API_REQUEST}:
-            if len(relevant_plugin_handlers) == 0:
-                effect_list = [Response(status_code=HTTPStatus.NOT_FOUND).apply()]
-            elif len(relevant_plugin_handlers) > 1:
-                log.error(
-                    f"Multiple handlers responded to {EventType.Name(EventType.SIMPLE_API_REQUEST)}"
-                    f" {event.context['path']}"
-                )
-                effect_list = [Response(status_code=HTTPStatus.INTERNAL_SERVER_ERROR).apply()]
-
-        event_duration = get_duration_ms(event_start_time)
-
-        # Don't log anything if a plugin handler didn't actually run.
-        if relevant_plugins:
-            log.info(f"Responded to Event {event_name} ({event_duration} ms)")
-            statsd_client.timing(
-                "plugins.event_duration_ms", delta=event_duration, tags={"event": event_name}
-            )
-
-        yield EventResponse(success=True, effects=effect_list)
+            yield EventResponse(success=True, effects=effect_list)
 
     async def ReloadPlugins(
         self, request: ReloadPluginsRequest, context: Any
@@ -560,6 +557,7 @@ def refresh_event_type_map() -> None:
                 log.warning(f"Unknown RESPONDS_TO type: {type(responds_to)}")
 
 
+@measured
 def load_plugins(specified_plugin_paths: list[str] | None = None) -> None:
     """Load the plugins."""
     # first mark each plugin as inactive since we want to remove it from
@@ -596,14 +594,9 @@ def load_plugins(specified_plugin_paths: list[str] | None = None) -> None:
 
     refresh_event_type_map()
 
-    log_nr_event_handlers()
-
-
-def log_nr_event_handlers() -> None:
-    """Log the number of event handlers for each event."""
     for key in EventType.keys():  # noqa: SIM118
         value = len(EVENT_HANDLER_MAP[key]) if key in EVENT_HANDLER_MAP else 0
-        statsd_client.timing("plugins.event_nr_handlers", value, tags={"event": key})
+        statsd_client.gauge("plugins.event_handler_count", value, tags={"event": key})
 
 
 _cleanup_coroutines = []