Add one-click "Record this page" to observer toolbar

Adds a PERSIST_ONCE mode that records a single trace then reverts to
summary. A small record dot button sits next to the observer pill in
the toolbar — subtle by default, red on hover. Clicking it sets the
persist_once cookie, reloads the page to capture the trace, then
auto-reverts to summary and opens the Observer panel.

Author: davegaeddert

plain-observer/plain/observer/core.py

@@ -14,7 +14,7 @@
 if TYPE_CHECKING:
     from plain.http import Request
 
-__all__ = ["Observer", "ObserverMode"]
+__all__ = ["Observer", "ObserverMode", "PERSISTING_MODES", "RECORDING_MODES"]
 
 logger = logging.getLogger(__name__)
 
@@ -24,6 +24,7 @@ class ObserverMode(Enum):
 
     SUMMARY = "summary"  # Real-time monitoring only, no DB export
     PERSIST = "persist"  # Real-time monitoring + DB export
+    PERSIST_ONCE = "persist_once"  # Persist one trace then revert to summary
     DISABLED = "disabled"  # Observer explicitly disabled
 
     @classmethod
@@ -42,7 +43,12 @@ def validate(cls, mode: str | None, source: str = "value") -> str | None:
         if mode is None:
             return None
 
-        valid_modes = (cls.SUMMARY.value, cls.PERSIST.value, cls.DISABLED.value)
+        valid_modes = (
+            cls.SUMMARY.value,
+            cls.PERSIST.value,
+            cls.PERSIST_ONCE.value,
+            cls.DISABLED.value,
+        )
 
         if mode not in valid_modes:
             if settings.DEBUG:
@@ -62,6 +68,12 @@ def validate(cls, mode: str | None, source: str = "value") -> str | None:
         return mode
 
 
+# Modes that trigger DB export and log capture
+PERSISTING_MODES = (ObserverMode.PERSIST.value, ObserverMode.PERSIST_ONCE.value)
+# All modes that record traces (summary + persisting)
+RECORDING_MODES = (*PERSISTING_MODES, ObserverMode.SUMMARY.value)
+
+
 class Observer:
     """Central class for managing observer state and operations."""
 
@@ -131,12 +143,20 @@ def mode(self) -> str | 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)
+        return self.mode() in RECORDING_MODES
 
     def is_persisting(self) -> bool:
         """Check if full persisting (with DB export) is enabled."""
+        return self.mode() in PERSISTING_MODES
+
+    def is_recording_session(self) -> bool:
+        """Check if in continuous recording mode (not persist-once)."""
         return self.mode() == ObserverMode.PERSIST.value
 
+    def is_persist_once(self) -> bool:
+        """Check if persist-once mode is enabled (single trace recording)."""
+        return self.mode() == ObserverMode.PERSIST_ONCE.value
+
     def is_summarizing(self) -> bool:
         """Check if summary mode is enabled."""
         return self.mode() == ObserverMode.SUMMARY.value
@@ -161,6 +181,14 @@ def enable_persist_mode(self, response: Response) -> None:
             max_age=self.PERSIST_COOKIE_DURATION,
         )
 
+    def enable_persist_once_mode(self, response: Response) -> None:
+        """Enable persist-once mode (persist one trace then revert to summary)."""
+        response.set_signed_cookie(
+            self.COOKIE_NAME,
+            ObserverMode.PERSIST_ONCE.value,
+            max_age=self.PERSIST_COOKIE_DURATION,
+        )
+
     def disable(self, response: Response) -> None:
         """Disable observer by setting cookie to disabled."""
         response.set_signed_cookie(

plain-observer/plain/observer/logging.py

@@ -8,7 +8,7 @@
 from opentelemetry import trace
 from opentelemetry.trace import format_span_id, format_trace_id
 
-from .core import ObserverMode
+from .core import PERSISTING_MODES
 from .otel import get_observer_span_processor
 
 
@@ -50,8 +50,7 @@ def emit(self, record: logging.LogRecord) -> None:
                     return
 
                 trace_info = processor._traces[trace_id]
-                # Only capture logs in PERSIST mode
-                if trace_info["mode"] != ObserverMode.PERSIST.value:
+                if trace_info["mode"] not in PERSISTING_MODES:
                     return
 
             # Store the formatted message with span context

plain-observer/plain/observer/otel.py

@@ -25,7 +25,7 @@
 from plain.postgres.otel import suppress_db_tracing
 from plain.runtime import settings
 
-from .core import Observer, ObserverMode
+from .core import PERSISTING_MODES, RECORDING_MODES, Observer, ObserverMode
 
 if TYPE_CHECKING:
     from plain.observer.models import Span as ObserverSpanModel
@@ -108,9 +108,7 @@ def should_sample(
             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
+            if mode in RECORDING_MODES:
                 decision = sampling.Decision.RECORD_AND_SAMPLE
             elif mode == ObserverMode.DISABLED.value:
                 # Explicitly disabled - never sample even with remote parent
@@ -233,8 +231,7 @@ def on_start(self, span: Any, parent_context: Context | None = None) -> None:
 
             span_id = f"0x{format_span_id(span.get_span_context().span_id)}"
 
-            # Enable DEBUG logging only for PERSIST mode (when logs are captured)
-            if trace_info["mode"] == ObserverMode.PERSIST.value:
+            if trace_info["mode"] in PERSISTING_MODES:
                 app_logger.debug_mode.start()
 
             # Store span (we know mode is truthy if we get here)
@@ -256,8 +253,7 @@ def on_end(self, span: ReadableSpan) -> None:
 
             trace_info = self._traces[trace_id]
 
-            # Disable DEBUG logging only for PERSIST mode spans
-            if trace_info["mode"] == ObserverMode.PERSIST.value:
+            if trace_info["mode"] in PERSISTING_MODES:
                 app_logger.debug_mode.end()
 
             # Move span from active to completed
@@ -276,8 +272,7 @@ def on_end(self, span: ReadableSpan) -> None:
                     for s in all_spans
                 ]
 
-                # Export if in persist mode
-                if trace_info["mode"] == ObserverMode.PERSIST.value:
+                if trace_info["mode"] in PERSISTING_MODES:
                     # Get and remove logs for this trace
                     from .logging import observer_log_handler
 
@@ -432,7 +427,7 @@ def _get_recording_mode(
         mode = Observer.from_otel_context(context).mode()
 
         # Only return valid recording modes (summary/persist), not disabled
-        if mode in (ObserverMode.SUMMARY.value, ObserverMode.PERSIST.value):
+        if mode in RECORDING_MODES:
             return mode
 
         return None

plain-observer/plain/observer/templates/toolbar/observer_button.html

@@ -1,10 +1,27 @@
+{# Observer pill + record dot, visually semi-attached #}
+<div class="inline-flex items-center gap-px">
+
+{# Record dot — separate clickable circle, tight against the pill #}
+{% if observer.is_summarizing() or observer.is_persist_once() %}
+<button
+    type="button"
+    class="inline-flex items-center justify-center cursor-pointer rounded-full px-1.5 py-px bg-white/8 text-white/30 hover:text-red-400 hover:bg-white/12 transition-colors self-stretch"
+    data-observer-record-page
+    title="Record this page"
+>
+    <svg class="size-1.5" viewBox="0 0 16 16" fill="currentColor">
+        <circle cx="8" cy="8" r="8"/>
+    </svg>
+</button>
+{% endif %}
+
 {# Request pill — observer state + request stats, clickable to open Observer panel #}
 <button
     type="button"
     class="inline-flex items-center cursor-pointer text-xs rounded-full px-1 py-px bg-white/8 text-white/80 hover:bg-white/12 overflow-hidden divide-x divide-white/10 [&>span]:px-1.5"
     data-toolbar-tab="Observer"
 >
-    {% if observer.is_persisting() %}
+    {% if observer.is_recording_session() %}
     <span class="inline-flex items-center">
         <span class="relative inline-flex size-1.5 mr-1.5 flex-shrink-0">
             <span class="absolute inline-flex h-full w-full animate-ping rounded-full bg-red-400 opacity-75"></span>
@@ -76,6 +93,8 @@
 </span>
 {% endif %}
 
+</div>
+
 <script nonce="{{ request.csp_nonce }}">
 (function() {
     function formatBytes(bytes) {
@@ -97,5 +116,44 @@
             el.classList.remove("hidden");
         }
     });
+
+    const recordBtn = document.querySelector("[data-observer-record-page]");
+
+    {% if observer.is_persist_once() %}
+    // Revert persist_once cookie back to summary, then re-enable record button
+    const revertForm = new FormData();
+    revertForm.append("observe_action", "summary");
+    if (recordBtn) recordBtn.disabled = true;
+    fetch("{{ url('observer:traces') }}", {
+        method: "POST",
+        body: revertForm,
+        credentials: "same-origin"
+    }).then(function() {
+        if (recordBtn) recordBtn.disabled = false;
+    });
+
+    window.addEventListener("load", function() {
+        if (window.plainToolbar) {
+            window.plainToolbar.showTab("Observer");
+        }
+    });
+    {% endif %}
+
+    if (recordBtn) {
+        recordBtn.addEventListener("click", function(e) {
+            e.stopPropagation();
+            recordBtn.style.color = "#f87171";
+            recordBtn.disabled = true;
+            const form = new FormData();
+            form.append("observe_action", "persist_once");
+            fetch("{{ url('observer:traces') }}", {
+                method: "POST",
+                body: form,
+                credentials: "same-origin"
+            }).then(function() {
+                window.location.reload();
+            });
+        });
+    }
 })();
 </script>

plain-observer/plain/observer/views.py

@@ -74,6 +74,11 @@ def post(self) -> Response:
             response = Response(status_code=204)
             observer.enable_summary_mode(response)
             return response
+        elif action == "persist_once":
+            observer = Observer.from_request(self.request)
+            response = Response(status_code=204)
+            observer.enable_persist_once_mode(response)
+            return response
         return Response("Invalid action", status_code=400)