plain.observer 0.10.0__tar.gz → 0.11.0__tar.gz

{plain_observer-0.10.0 → plain_observer-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.observer
-Version: 0.10.0
+Version: 0.11.0
 Summary: On-page telemetry and observability tools for Plain.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause

plain_observer-0.11.0/plain/observer/AGENTS.md

@@ -0,0 +1,6 @@
+# Plain Observer AGENTS.md
+
+- Send a request and record traces: `plain agent request /some/path --user 1 --header "Observer: persist"`
+- Find traces by request ID: `plain observer traces --request-id abc-123-def`
+- Diagnose trace: `plain observer diagnose [TRACE_ID]`
+- Output raw trace data: `plain observer trace [TRACE_ID] --json`

{plain_observer-0.10.0 → plain_observer-0.11.0}/plain/observer/CHANGELOG.md

@@ -1,5 +1,28 @@
 # plain-observer changelog
 
+## [0.11.0](https://github.com/dropseed/plain/releases/plain-observer@0.11.0) (2025-10-08)
+
+### What's changed
+
+- Observer can now be enabled in DEBUG mode using an `Observer` HTTP header (e.g., `Observer: persist` or `Observer: summary`), which takes precedence over cookies ([cba149a](https://github.com/dropseed/plain/commit/cba149a40e))
+- Added validation for observer mode values that raises helpful errors in DEBUG mode when invalid values are provided ([cba149a](https://github.com/dropseed/plain/commit/cba149a40e))
+- Refactored `Observer` class to accept cookies and headers as constructor parameters, with new `from_request()` and `from_otel_context()` factory methods for improved testability ([cba149a](https://github.com/dropseed/plain/commit/cba149a40e))
+- Added AGENTS.md file with helpful commands for AI agents working with Plain Observer ([cba149a](https://github.com/dropseed/plain/commit/cba149a40e))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.10.1](https://github.com/dropseed/plain/releases/plain-observer@0.10.1) (2025-10-08)
+
+### What's changed
+
+- Fixed content negotiation priority in trace detail and shared views to prefer HTML over JSON by default ([00212835aa](https://github.com/dropseed/plain/commit/00212835aa))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.10.0](https://github.com/dropseed/plain/releases/plain-observer@0.10.0) (2025-10-07)
 
 ### What's changed

plain_observer-0.11.0/plain/observer/core.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import logging
+from collections.abc import MutableMapping
+from enum import Enum
+from typing import TYPE_CHECKING, Any, cast
+
+from opentelemetry import baggage
+
+from plain.http import Response
+from plain.http.cookie import unsign_cookie_value
+from plain.runtime import settings
+
+if TYPE_CHECKING:
+    from plain.http import Request
+
+logger = logging.getLogger(__name__)
+
+
+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
+
+    @classmethod
+    def validate(cls, mode: str | None, source: str = "value") -> str | None:
+        """Validate observer mode value.
+
+        In DEBUG mode, raises ValueError for invalid values.
+        In production, logs debug message and returns None for invalid values.
+
+        Args:
+            mode: The mode value to validate
+            source: Description of where the mode came from (for error messages)
+
+        Returns the mode if valid, None otherwise.
+        """
+        if mode is None:
+            return None
+
+        valid_modes = (cls.SUMMARY.value, cls.PERSIST.value, cls.DISABLED.value)
+
+        if mode not in valid_modes:
+            if settings.DEBUG:
+                raise ValueError(
+                    f"Invalid Observer {source}: '{mode}'. "
+                    f"Valid values are: {', '.join(valid_modes)}"
+                )
+            else:
+                logger.debug(
+                    "Invalid observer mode %s: '%s'. Expected one of: %s",
+                    source,
+                    mode,
+                    valid_modes,
+                )
+                return None
+
+        return mode
+
+
+class Observer:
+    """Central class for managing observer state and operations."""
+
+    COOKIE_NAME = "observer"
+    DEBUG_HEADER_NAME = "Observer"
+    SUMMARY_COOKIE_DURATION = 60 * 60 * 24 * 7  # 1 week in seconds
+    PERSIST_COOKIE_DURATION = 60 * 60 * 24  # 1 day in seconds
+
+    def __init__(self, *, cookies: dict[str, str], headers: dict[str, str]) -> None:
+        self.cookies = cookies
+        self.headers = headers
+
+    @classmethod
+    def from_request(cls, request: Request) -> Observer:
+        """Create an Observer instance from a request object."""
+        return cls(cookies=request.cookies, headers=request.headers)
+
+    @classmethod
+    def from_otel_context(cls, context: Any) -> Observer:
+        """Create an Observer instance from an OpenTelemetry context.
+
+        This method extracts cookies and headers from the OTEL baggage.
+        """
+        cookies = cast(
+            MutableMapping[str, str] | None,
+            baggage.get_baggage("http.request.cookies", context),
+        )
+        if not cookies:
+            cookies = {}
+
+        headers = cast(
+            MutableMapping[str, str] | None,
+            baggage.get_baggage("http.request.headers", context),
+        )
+        if not headers:
+            headers = {}
+
+        return cls(cookies=cookies, headers=headers)
+
+    def mode(self) -> str | None:
+        """Get the current observer mode from header (DEBUG only) or cookie.
+
+        In DEBUG mode, the Observer header takes precedence over the cookie.
+        Returns 'summary', 'persist', 'disabled', or None.
+
+        Raises ValueError if invalid value is found (DEBUG only).
+        """
+        # Check Observer header in DEBUG mode (takes precedence)
+        if settings.DEBUG:
+            if observer_header := self.headers.get(self.DEBUG_HEADER_NAME):
+                observer_mode = observer_header.lower()
+                return ObserverMode.validate(observer_mode, source="header value")
+
+        # Check cookie
+        observer_cookie = self.cookies.get(self.COOKIE_NAME)
+        if not observer_cookie:
+            return None
+
+        try:
+            mode = unsign_cookie_value(self.COOKIE_NAME, observer_cookie, default=None)
+            return ObserverMode.validate(mode, source="cookie value")
+        except Exception as e:
+            logger.debug("Failed to unsign observer cookie: %s", e)
+            return None
+
+    def is_enabled(self) -> bool:
+        """Check if observer is enabled (either summary or persist mode)."""
+        return self.mode() in (ObserverMode.SUMMARY.value, ObserverMode.PERSIST.value)
+
+    def is_persisting(self) -> bool:
+        """Check if full persisting (with DB export) is enabled."""
+        return self.mode() == ObserverMode.PERSIST.value
+
+    def is_summarizing(self) -> bool:
+        """Check if summary mode is enabled."""
+        return self.mode() == ObserverMode.SUMMARY.value
+
+    def is_disabled(self) -> bool:
+        """Check if observer is explicitly disabled."""
+        return self.mode() == ObserverMode.DISABLED.value
+
+    def enable_summary_mode(self, response: Response) -> None:
+        """Enable summary mode (real-time monitoring, no DB export)."""
+        response.set_signed_cookie(
+            self.COOKIE_NAME,
+            ObserverMode.SUMMARY.value,
+            max_age=self.SUMMARY_COOKIE_DURATION,
+        )
+
+    def enable_persist_mode(self, response: Response) -> None:
+        """Enable full persist mode (real-time monitoring + DB export)."""
+        response.set_signed_cookie(
+            self.COOKIE_NAME,
+            ObserverMode.PERSIST.value,
+            max_age=self.PERSIST_COOKIE_DURATION,
+        )
+
+    def disable(self, response: Response) -> None:
+        """Disable observer by setting cookie to disabled."""
+        response.set_signed_cookie(
+            self.COOKIE_NAME,
+            ObserverMode.DISABLED.value,
+            max_age=self.PERSIST_COOKIE_DURATION,
+        )
+
+    def get_current_trace_summary(self) -> str | None:
+        """Get performance summary string for the currently active trace."""
+        from .otel import get_current_trace_summary
+
+        return get_current_trace_summary()

{plain_observer-0.10.0 → plain_observer-0.11.0}/plain/observer/otel.py

@@ -8,7 +8,7 @@ from collections.abc import MutableMapping, Sequence
 from typing import TYPE_CHECKING, Any, cast
 
 import opentelemetry.context as context_api
-from opentelemetry import baggage, trace
+from opentelemetry import trace
 from opentelemetry.context import Context
 from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor, sampling
 from opentelemetry.semconv.attributes import url_attributes
@@ -20,7 +20,6 @@ from opentelemetry.trace import (
     format_trace_id,
 )
 
-from plain.http.cookie import unsign_cookie_value
 from plain.logs import app_logger
 from plain.models.otel import suppress_db_tracing
 from plain.runtime import settings
@@ -105,28 +104,20 @@ class ObserverSampler(sampling.Sampler):
                             attributes=attributes,
                         )
 
-        # If no processor decision, check cookies directly for root spans
+        # If no processor decision, check headers and cookies directly for root spans
         decision: sampling.Decision | None = None
         if parent_context:
-            # Check cookies for sampling decision
-            cookies = cast(
-                MutableMapping[str, str] | None,
-                baggage.get_baggage("http.request.cookies", parent_context),
-            )
-            if cookies and (observer_cookie := cookies.get(Observer.COOKIE_NAME)):
-                unsigned_value = unsign_cookie_value(
-                    Observer.COOKIE_NAME, observer_cookie, default=None
-                )
-
-                if unsigned_value in (
-                    ObserverMode.PERSIST.value,
-                    ObserverMode.SUMMARY.value,
-                ):
-                    # Always use RECORD_AND_SAMPLE so ParentBased works correctly
-                    # The processor will check the mode to decide whether to export
-                    decision = sampling.Decision.RECORD_AND_SAMPLE
-                else:
-                    decision = sampling.Decision.DROP
+            # Check Observer header (DEBUG only) and cookies
+            mode = Observer.from_otel_context(parent_context).mode()
+
+            # Set decision based on mode
+            if mode in (ObserverMode.PERSIST.value, ObserverMode.SUMMARY.value):
+                # Always use RECORD_AND_SAMPLE so ParentBased works correctly
+                # The processor will check the mode to decide whether to export
+                decision = sampling.Decision.RECORD_AND_SAMPLE
+            elif mode == ObserverMode.DISABLED.value:
+                # Explicitly disabled - never sample even with remote parent
+                decision = sampling.Decision.DROP
 
         # If there are links, assume it is to another trace/span that we are keeping
         if links:
@@ -441,25 +432,12 @@ class ObserverSpanProcessor(SpanProcessor):
         if not (context := parent_context or context_api.get_current()):
             return None
 
-        cookies = cast(
-            MutableMapping[str, str] | None,
-            baggage.get_baggage("http.request.cookies", context),
-        )
-        if not cookies:
-            return None
-
-        observer_cookie = cookies.get(Observer.COOKIE_NAME)
-        if not observer_cookie:
-            return None
+        # Check Observer header (DEBUG only) and cookies
+        mode = Observer.from_otel_context(context).mode()
 
-        try:
-            mode = unsign_cookie_value(
-                Observer.COOKIE_NAME, observer_cookie, default=None
-            )
-            if mode in (ObserverMode.SUMMARY.value, ObserverMode.PERSIST.value):
-                return mode
-        except Exception as e:
-            logger.warning("Failed to unsign observer cookie: %s", e)
+        # Only return valid recording modes (summary/persist), not disabled
+        if mode in (ObserverMode.SUMMARY.value, ObserverMode.PERSIST.value):
+            return mode
 
         return None
 

{plain_observer-0.10.0 → plain_observer-0.11.0}/plain/observer/toolbar.py

@@ -17,7 +17,7 @@ class ObserverToolbarItem(ToolbarItem):
     @cached_property
     def observer(self) -> Observer:
         """Get the Observer instance for this request."""
-        return Observer(self.request)
+        return Observer.from_request(self.request)
 
     def get_template_context(self) -> dict[str, Any]:
         context = super().get_template_context()

{plain_observer-0.10.0 → plain_observer-0.11.0}/plain/observer/views.py

@@ -37,13 +37,13 @@ class ObserverTracesView(AuthViewMixin, HTMXViewMixin, ListView):
 
     def get_template_context(self) -> dict[str, Any]:
         context = super().get_template_context()
-        context["observer"] = Observer(self.request)
+        context["observer"] = Observer.from_request(self.request)
         return context
 
     def htmx_put_mode(self) -> Response:
         """Set observer mode via HTMX PUT."""
         mode = self.request.data.get("mode")
-        observer = Observer(self.request)
+        observer = Observer.from_request(self.request)
 
         response = Response(status_code=204)
         response.headers["HX-Refresh"] = "true"
@@ -70,7 +70,7 @@ class ObserverTracesView(AuthViewMixin, HTMXViewMixin, ListView):
         """Handle POST requests to set observer mode."""
         action = self.request.data.get("observe_action")
         if action == "summary":
-            observer = Observer(self.request)
+            observer = Observer.from_request(self.request)
             response = Response(status_code=204)
             observer.enable_summary_mode(response)
             return response
@@ -95,7 +95,7 @@ class ObserverTraceDetailView(AuthViewMixin, HTMXViewMixin, DetailView):
 
     def get(self) -> Response | dict[str, Any]:
         """Return trace data as HTML, JSON, or logs based on content negotiation."""
-        preferred = self.request.get_preferred_type("application/json", "text/html")
+        preferred = self.request.get_preferred_type("text/html", "application/json")
         if (
             preferred == "application/json"
             or self.request.query_params.get("format") == "json"
@@ -152,7 +152,7 @@ class ObserverTraceSharedView(DetailView):
 
     def get(self) -> Response:
         """Return trace data as HTML or JSON based on content negotiation."""
-        preferred = self.request.get_preferred_type("application/json", "text/html")
+        preferred = self.request.get_preferred_type("text/html", "application/json")
         if (
             preferred == "application/json"
             or self.request.query_params.get("format") == "json"

{plain_observer-0.10.0 → plain_observer-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain.observer"
-version = "0.10.0"
+version = "0.11.0"
 description = "On-page telemetry and observability tools for Plain."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 license = "BSD-3-Clause"

plain_observer-0.10.0/plain/observer/core.py

@@ -1,74 +0,0 @@
-from __future__ import annotations
-
-from enum import Enum
-
-from plain.http import Request, Response
-
-
-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"
-    SUMMARY_COOKIE_DURATION = 60 * 60 * 24 * 7  # 1 week in seconds
-    PERSIST_COOKIE_DURATION = 60 * 60 * 24  # 1 day in seconds
-
-    def __init__(self, request: Request) -> None:
-        self.request = request
-
-    def mode(self) -> str | None:
-        """Get the current observer mode from signed cookie."""
-        return self.request.get_signed_cookie(self.COOKIE_NAME, default=None)
-
-    def is_enabled(self) -> bool:
-        """Check if observer is enabled (either summary or persist mode)."""
-        return self.mode() in (ObserverMode.SUMMARY.value, ObserverMode.PERSIST.value)
-
-    def is_persisting(self) -> bool:
-        """Check if full persisting (with DB export) is enabled."""
-        return self.mode() == ObserverMode.PERSIST.value
-
-    def is_summarizing(self) -> bool:
-        """Check if summary mode is enabled."""
-        return self.mode() == ObserverMode.SUMMARY.value
-
-    def is_disabled(self) -> bool:
-        """Check if observer is explicitly disabled."""
-        return self.mode() == ObserverMode.DISABLED.value
-
-    def enable_summary_mode(self, response: Response) -> None:
-        """Enable summary mode (real-time monitoring, no DB export)."""
-        response.set_signed_cookie(
-            self.COOKIE_NAME,
-            ObserverMode.SUMMARY.value,
-            max_age=self.SUMMARY_COOKIE_DURATION,
-        )
-
-    def enable_persist_mode(self, response: Response) -> None:
-        """Enable full persist mode (real-time monitoring + DB export)."""
-        response.set_signed_cookie(
-            self.COOKIE_NAME,
-            ObserverMode.PERSIST.value,
-            max_age=self.PERSIST_COOKIE_DURATION,
-        )
-
-    def disable(self, response: Response) -> None:
-        """Disable observer by setting cookie to disabled."""
-        response.set_signed_cookie(
-            self.COOKIE_NAME,
-            ObserverMode.DISABLED.value,
-            max_age=self.PERSIST_COOKIE_DURATION,
-        )
-
-    def get_current_trace_summary(self) -> str | None:
-        """Get performance summary string for the currently active trace."""
-        from .otel import get_current_trace_summary
-
-        return get_current_trace_summary()