plain.observer 0.10.1__tar.gz → 0.11.1__tar.gz

{plain_observer-0.10.1 → plain_observer-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.observer
-Version: 0.10.1
+Version: 0.11.1
 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.1/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.1 → plain_observer-0.11.1}/plain/observer/CHANGELOG.md

@@ -1,5 +1,30 @@
 # plain-observer changelog
 
+## [0.11.1](https://github.com/dropseed/plain/releases/plain-observer@0.11.1) (2025-10-10)
+
+### What's changed
+
+- Trace list items now update the URL when clicked, allowing direct linking to specific traces ([9f29b68](https://github.com/dropseed/plain/commit/9f29b68a87))
+- Improved trace sidebar layout by moving the timestamp to the bottom right and creating better visual hierarchy ([9f29b68](https://github.com/dropseed/plain/commit/9f29b68a87))
+- Updated diagnose command prompt text to be less personal in tone ([c82d67b](https://github.com/dropseed/plain/commit/c82d67bfcf))
+
+### Upgrade instructions
+
+- No changes required
+
+## [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

{plain_observer-0.10.1 → plain_observer-0.11.1}/plain/observer/cli.py

@@ -564,9 +564,9 @@ def diagnose(
             raise click.ClickException(f"Trace with ID '{trace_id}' not found")
 
     prompt_lines: list[str] = [
-        "I have an OpenTelemetry trace data JSON from a Plain application. Analyze it for performance issues or improvements.",
+        "Below is OpenTelemetry trace data JSON from a Plain application. Analyze it for performance issues or improvements.",
         "",
-        "Focus on easy and obvious wins first and foremost. You have access to the codebase, so make sure you look at it before suggesting anything! If there is nothing obvious, that's ok -- tell me that and ask whether there are specific things we should look deeper into.",
+        "Focus on easy and obvious wins first and foremost. You have access to the codebase, so make sure you look at it before suggesting anything! If there is nothing obvious, that's ok -- say that and ask whether there are specific things we should look deeper into.",
         "",
         "If potential code changes are found, briefly explain them and ask whether we should implement them.",
         "",

plain_observer-0.11.1/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.1 → plain_observer-0.11.1}/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.1 → plain_observer-0.11.1}/plain/observer/templates/observer/traces.html

@@ -88,6 +88,7 @@
                                 hx-get="{{ trace_item.get_absolute_url() }}"
                                 hx-target="#trace"
                                 hx-swap="innerHTML"
+                                hx-push-url="true"
                                 class="block w-full text-left p-3 transition-colors hover:bg-white/5 focus:outline-none focus:bg-white/5"
                                 data-trace-id="{{ trace_item.trace_id }}">
                                 <div class="flex items-center justify-between gap-2">
@@ -98,9 +99,6 @@
                                         <div class="text-xs font-medium text-white/30 font-mono truncate">{{ trace_item.trace_id }}</div>
                                         {% endif %}
                                     </div>
-                                    <div class="flex items-center gap-1.5 flex-shrink-0">
-                                        <span class="text-white/40 text-xs" title="{{ trace_item.start_time|localtime }}">{{ trace_item.start_time|timesince }} ago</span>
-                                    </div>
                                 </div>
                                 <div class="mt-1 space-y-1">
                                     {% if trace_item.summary %}<div class="text-xs text-white/60">{{ trace_item.summary }}</div>{% endif %}
@@ -114,35 +112,38 @@
                                         <div class="text-xs text-white/30 font-mono truncate">{{ trace_item.trace_id }}</div>
                                     </div>
                                     {% endif %}
-                                    {% if trace_item.user_id or trace_item.session_id or trace_item.app_version %}
-                                    <div class="flex items-center gap-3 text-xs text-white/50">
-                                        {% if trace_item.user_id %}
-                                        <span class="flex items-center gap-1 flex-shrink-0">
-                                            <svg class="w-3 h-3 text-white/70" fill="currentColor" viewBox="0 0 16 16">
-                                                <path d="M3 14s-1 0-1-1 1-4 6-4 6 3 6 4-1 1-1 1zm5-6a3 3 0 1 0 0-6 3 3 0 0 0 0 6"/>
-                                            </svg>
-                                            {{ trace_item.user_id }}
-                                        </span>
-                                        {% endif %}
-                                        {% if trace_item.session_id %}
-                                        <span class="flex items-center gap-1 min-w-0 flex-shrink">
-                                            <svg class="w-3 h-3 text-white/70 flex-shrink-0" fill="currentColor" viewBox="0 0 16 16">
-                                                <path d="M13.5 3a.5.5 0 0 1 .5.5V11H2V3.5a.5.5 0 0 1 .5-.5zm-11-1A1.5 1.5 0 0 0 1 3.5V12h14V3.5A1.5 1.5 0 0 0 13.5 2zM0 12.5h16a1.5 1.5 0 0 1-1.5 1.5h-13A1.5 1.5 0 0 1 0 12.5"/>
-                                            </svg>
-                                            <span class="truncate" title="{{ trace_item.session_id }}">{{ trace_item.session_id }}</span>
-                                        </span>
-                                        {% endif %}
-                                        {% if trace_item.app_version %}
-                                        <span class="flex items-center gap-1 flex-shrink-0">
-                                            <svg class="w-3 h-3 text-white/70" fill="currentColor" viewBox="0 0 16 16">
-                                                <path d="M6 4.5a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0zm-1 0a.5.5 0 1 0-1 0 .5.5 0 0 0 1 0z"/>
-                                                <path d="M2 1h4.586a1 1 0 0 1 .707.293l7 7a1 1 0 0 1 0 1.414l-4.586 4.586a1 1 0 0 1-1.414 0l-7-7A1 1 0 0 1 1 6.586V2a1 1 0 0 1 1-1zm0 5.586 7 7L13.586 9l-7-7H2v4.586z"/>
-                                            </svg>
-                                            {{ trace_item.app_version }}
-                                        </span>
+                                    <div class="flex items-center justify-between gap-3 text-xs text-white/50">
+                                        {% if trace_item.user_id or trace_item.session_id or trace_item.app_version %}
+                                        <div class="flex items-center gap-3">
+                                            {% if trace_item.user_id %}
+                                            <span class="flex items-center gap-1 flex-shrink-0">
+                                                <svg class="w-3 h-3 text-white/70" fill="currentColor" viewBox="0 0 16 16">
+                                                    <path d="M3 14s-1 0-1-1 1-4 6-4 6 3 6 4-1 1-1 1zm5-6a3 3 0 1 0 0-6 3 3 0 0 0 0 6"/>
+                                                </svg>
+                                                {{ trace_item.user_id }}
+                                            </span>
+                                            {% endif %}
+                                            {% if trace_item.session_id %}
+                                            <span class="flex items-center gap-1 min-w-0 flex-shrink">
+                                                <svg class="w-3 h-3 text-white/70 flex-shrink-0" fill="currentColor" viewBox="0 0 16 16">
+                                                    <path d="M13.5 3a.5.5 0 0 1 .5.5V11H2V3.5a.5.5 0 0 1 .5-.5zm-11-1A1.5 1.5 0 0 0 1 3.5V12h14V3.5A1.5 1.5 0 0 0 13.5 2zM0 12.5h16a1.5 1.5 0 0 1-1.5 1.5h-13A1.5 1.5 0 0 1 0 12.5"/>
+                                                </svg>
+                                                <span class="truncate" title="{{ trace_item.session_id }}">{{ trace_item.session_id }}</span>
+                                            </span>
+                                            {% endif %}
+                                            {% if trace_item.app_version %}
+                                            <span class="flex items-center gap-1 flex-shrink-0">
+                                                <svg class="w-3 h-3 text-white/70" fill="currentColor" viewBox="0 0 16 16">
+                                                    <path d="M6 4.5a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0zm-1 0a.5.5 0 1 0-1 0 .5.5 0 0 0 1 0z"/>
+                                                    <path d="M2 1h4.586a1 1 0 0 1 .707.293l7 7a1 1 0 0 1 0 1.414l-4.586 4.586a1 1 0 0 1-1.414 0l-7-7A1 1 0 0 1 1 6.586V2a1 1 0 0 1 1-1zm0 5.586 7 7L13.586 9l-7-7H2v4.586z"/>
+                                                </svg>
+                                                {{ trace_item.app_version }}
+                                            </span>
+                                            {% endif %}
+                                        </div>
                                         {% endif %}
+                                        <span class="flex-shrink-0 text-white/40" title="{{ trace_item.start_time|localtime }}">{{ trace_item.start_time|timesince }} ago</span>
                                     </div>
-                                    {% endif %}
                                 </div>
                             </a>
                         </li>

{plain_observer-0.10.1 → plain_observer-0.11.1}/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.1 → plain_observer-0.11.1}/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

{plain_observer-0.10.1 → plain_observer-0.11.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain.observer"
-version = "0.10.1"
+version = "0.11.1"
 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.1/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()