canvas 0.34.1__py3-none-any.whl → 0.35.1__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()