plain.observer 0.0.0__tar.gz

plain_observer-0.0.0/.gitignore

@@ -0,0 +1,19 @@
+.venv
+.env
+*.egg-info
+*.py[co]
+__pycache__
+*.DS_Store
+
+# Test apps
+plain*/tests/.plain
+
+# Ottobot
+.aider*
+
+/llms-full.txt
+
+# Plain temp dirs
+.plain
+
+.vscode

plain_observer-0.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Dropseed, LLC
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

plain_observer-0.0.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: plain.observer
+Version: 0.0.0
+Summary: On-page telemetry and observability tools for Plain.
+Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: opentelemetry-sdk>=1.34.1
+Requires-Dist: plain-admin<1.0.0
+Requires-Dist: plain<1.0.0
+Description-Content-Type: text/markdown
+
+# plain.observer
+
+**Monitor.**

plain_observer-0.0.0/README.md

@@ -0,0 +1 @@
+plain/observer/README.md

plain_observer-0.0.0/plain/observer/CHANGELOG.md

@@ -0,0 +1 @@
+# plain-observer changelog

plain_observer-0.0.0/plain/observer/README.md

@@ -0,0 +1,3 @@
+# plain.observer
+
+**Monitor.**

plain_observer-0.0.0/plain/observer/admin.py

@@ -0,0 +1,102 @@
+from functools import cached_property
+
+from plain.admin.toolbar import ToolbarPanel, register_toolbar_panel
+from plain.admin.views import (
+    AdminModelDetailView,
+    AdminModelListView,
+    AdminViewset,
+    register_viewset,
+)
+
+from .core import Observer
+from .models import Span, Trace
+
+
+@register_viewset
+class TraceViewset(AdminViewset):
+    class ListView(AdminModelListView):
+        nav_section = "Observer"
+        model = Trace
+        fields = [
+            "trace_id",
+            "request_id",
+            "session_id",
+            "user_id",
+            "start_time",
+        ]
+        allow_global_search = False
+        # Actually want a button to delete ALL! not possible yet
+        # actions = ["Delete"]
+
+        # def perform_action(self, action: str, target_pks: list):
+        #     if action == "Delete":
+        #         Trace.objects.filter(id__in=target_pks).delete()
+
+    class DetailView(AdminModelDetailView):
+        model = Trace
+        template_name = "admin/observer/trace_detail.html"
+
+        def get_template_context(self):
+            context = super().get_template_context()
+            trace_id = self.url_kwargs["pk"]
+            context["trace"] = Trace.objects.get(pk=trace_id)
+            context["show_delete_button"] = False
+            return context
+
+
+@register_viewset
+class SpanViewset(AdminViewset):
+    class ListView(AdminModelListView):
+        nav_section = "Observer"
+        model = Span
+        fields = [
+            "name",
+            "kind",
+            "status",
+            "span_id",
+            "parent_id",
+            "start_time",
+        ]
+        queryset_order = ["-pk"]
+        allow_global_search = False
+        displays = ["Parents only"]
+        search_fields = ["name", "span_id", "parent_id"]
+
+        def get_objects(self):
+            return (
+                super()
+                .get_objects()
+                .only(
+                    "name",
+                    "kind",
+                    "span_id",
+                    "parent_id",
+                    "start_time",
+                )
+            )
+
+        def get_initial_queryset(self):
+            queryset = super().get_initial_queryset()
+            if self.display == "Parents only":
+                queryset = queryset.filter(parent_id="")
+            return queryset
+
+    class DetailView(AdminModelDetailView):
+        model = Span
+
+
+@register_toolbar_panel
+class ObserverToolbarPanel(ToolbarPanel):
+    name = "Observer"
+    template_name = "toolbar/observer.html"
+    button_template_name = "toolbar/observer_button.html"
+
+    @cached_property
+    def observer(self):
+        """Get the Observer instance for this request."""
+        return Observer(self.request)
+
+    def get_template_context(self):
+        context = super().get_template_context()
+        context["observer"] = self.observer
+        return context

plain_observer-0.0.0/plain/observer/cli.py

@@ -0,0 +1,23 @@
+import click
+
+from plain.cli import register_cli
+from plain.observer.models import Trace
+
+
+@register_cli("observer")
+@click.group("observer")
+def observer_cli():
+    pass
+
+
+@observer_cli.command()
+@click.option("--force", is_flag=True, help="Skip confirmation prompt.")
+def clear(force: bool):
+    """Clear all observer data."""
+    if not force:
+        click.confirm(
+            "Are you sure you want to clear all observer data? This cannot be undone.",
+            abort=True,
+        )
+
+    print("Deleted", Trace.objects.all().delete())

plain_observer-0.0.0/plain/observer/config.py

@@ -0,0 +1,36 @@
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+
+from plain.packages import PackageConfig, register_config
+
+from .otel import ObserverSampler, ObserverSpanProcessor
+
+
+@register_config
+class Config(PackageConfig):
+    package_label = "plainobserver"
+
+    def ready(self):
+        if self.has_existing_trace_provider():
+            return
+
+        self.setup_observer()
+
+    @staticmethod
+    def has_existing_trace_provider() -> bool:
+        """Check if there is an existing trace provider."""
+        current_provider = trace.get_tracer_provider()
+        return current_provider and not isinstance(
+            current_provider, trace.ProxyTracerProvider
+        )
+
+    @staticmethod
+    def setup_observer() -> None:
+        sampler = ObserverSampler()
+        provider = TracerProvider(sampler=sampler)
+
+        # Add our combined processor that handles both memory storage and export
+        observer_processor = ObserverSpanProcessor()
+        provider.add_span_processor(observer_processor)
+
+        trace.set_tracer_provider(provider)

plain_observer-0.0.0/plain/observer/core.py

@@ -0,0 +1,63 @@
+from enum import Enum
+
+
+class ObserverMode(Enum):
+    """Observer operation modes."""
+
+    SUMMARY = "summary"  # Real-time monitoring only, no DB export
+    PERSIST = "persist"  # Real-time monitoring + DB export
+    DISABLED = "disabled"  # Observer explicitly disabled
+
+
+class Observer:
+    """Central class for managing observer state and operations."""
+
+    COOKIE_NAME = "observer"
+    COOKIE_DURATION = 60 * 60 * 24  # 1 day in seconds
+
+    def __init__(self, request):
+        self.request = request
+
+    def mode(self):
+        """Get the current observer mode from signed cookie."""
+        return self.request.get_signed_cookie(self.COOKIE_NAME, default=None)
+
+    def is_enabled(self):
+        """Check if observer is enabled (either summary or persist mode)."""
+        return self.mode() in (ObserverMode.SUMMARY.value, ObserverMode.PERSIST.value)
+
+    def is_persisting(self):
+        """Check if full persisting (with DB export) is enabled."""
+        return self.mode() == ObserverMode.PERSIST.value
+
+    def is_summarizing(self):
+        """Check if summary mode is enabled."""
+        return self.mode() == ObserverMode.SUMMARY.value
+
+    def is_disabled(self):
+        """Check if observer is explicitly disabled."""
+        return self.mode() == ObserverMode.DISABLED.value
+
+    def enable_summary_mode(self, response):
+        """Enable summary mode (real-time monitoring, no DB export)."""
+        response.set_signed_cookie(
+            self.COOKIE_NAME, ObserverMode.SUMMARY.value, max_age=self.COOKIE_DURATION
+        )
+
+    def enable_persist_mode(self, response):
+        """Enable full persist mode (real-time monitoring + DB export)."""
+        response.set_signed_cookie(
+            self.COOKIE_NAME, ObserverMode.PERSIST.value, max_age=self.COOKIE_DURATION
+        )
+
+    def disable(self, response):
+        """Disable observer by setting cookie to disabled."""
+        response.set_signed_cookie(
+            self.COOKIE_NAME, ObserverMode.DISABLED.value, max_age=self.COOKIE_DURATION
+        )
+
+    def get_current_trace_summary(self):
+        """Get performance summary string for the currently active trace."""
+        from .otel import get_current_trace_summary
+
+        return get_current_trace_summary()

plain_observer-0.0.0/plain/observer/default_settings.py

@@ -0,0 +1,9 @@
+OBSERVER_IGNORE_URL_PATTERNS: list[str] = [
+    "/admin/.*",
+    "/assets/.*",
+    "/observer/.*",
+    "/pageviews/.*",
+    "/favicon.ico",
+    "/.well-known/.*",
+]
+OBSERVER_TRACE_LIMIT: int = 100

plain_observer-0.0.0/plain/observer/migrations/0001_initial.py

@@ -0,0 +1,96 @@
+# Generated by Plain 0.52.2 on 2025-07-17 02:27
+
+import plain.models.deletion
+from plain import models
+from plain.models import migrations
+
+
+class Migration(migrations.Migration):
+    initial = True
+
+    dependencies = []
+
+    operations = [
+        migrations.CreateModel(
+            name="Trace",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True)),
+                ("trace_id", models.CharField(max_length=255)),
+                ("start_time", models.DateTimeField()),
+                ("end_time", models.DateTimeField()),
+                ("root_span_name", models.TextField(default="", required=False)),
+                (
+                    "request_id",
+                    models.CharField(default="", max_length=255, required=False),
+                ),
+                (
+                    "session_id",
+                    models.CharField(default="", max_length=255, required=False),
+                ),
+                (
+                    "user_id",
+                    models.CharField(default="", max_length=255, required=False),
+                ),
+            ],
+            options={
+                "ordering": ["-start_time"],
+            },
+        ),
+        migrations.CreateModel(
+            name="Span",
+            fields=[
+                ("id", models.BigAutoField(auto_created=True, primary_key=True)),
+                ("span_id", models.CharField(max_length=255)),
+                ("name", models.CharField(max_length=255)),
+                ("kind", models.CharField(max_length=50)),
+                (
+                    "parent_id",
+                    models.CharField(default="", max_length=255, required=False),
+                ),
+                ("start_time", models.DateTimeField()),
+                ("end_time", models.DateTimeField()),
+                ("status", models.CharField(default="", max_length=50, required=False)),
+                ("span_data", models.JSONField(default=dict, required=False)),
+            ],
+            options={
+                "ordering": ["-start_time"],
+            },
+        ),
+        migrations.AddConstraint(
+            model_name="trace",
+            constraint=models.UniqueConstraint(
+                fields=("trace_id",), name="observer_unique_trace_id"
+            ),
+        ),
+        migrations.AddField(
+            model_name="span",
+            name="trace",
+            field=models.ForeignKey(
+                on_delete=plain.models.deletion.CASCADE,
+                related_name="spans",
+                to="plainobserver.trace",
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="span",
+            index=models.Index(
+                fields=["trace", "span_id"], name="plainobserv_trace_i_89a97c_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="span",
+            index=models.Index(fields=["trace"], name="plainobserv_trace_i_84958a_idx"),
+        ),
+        migrations.AddIndex(
+            model_name="span",
+            index=models.Index(
+                fields=["start_time"], name="plainobserv_start_t_cb47a3_idx"
+            ),
+        ),
+        migrations.AddConstraint(
+            model_name="span",
+            constraint=models.UniqueConstraint(
+                fields=("trace", "span_id"), name="observer_unique_span_id"
+            ),
+        ),
+    ]