plain.observer 0.9.0__tar.gz → 0.10.0__tar.gz

{plain_observer-0.9.0 → plain_observer-0.10.0}/.gitignore

@@ -16,3 +16,4 @@ plain*/tests/.plain
 
 .vscode
 /.claude
+/.benchmarks

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

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

@@ -1,5 +1,28 @@
 # plain-observer changelog
 
+## [0.10.0](https://github.com/dropseed/plain/releases/plain-observer@0.10.0) (2025-10-07)
+
+### What's changed
+
+- Model configuration now uses `model_options` descriptor instead of `class Meta` for improved consistency with Plain framework patterns ([17a378d](https://github.com/dropseed/plain/commit/17a378dcfb))
+- Custom QuerySet classes are now defined as descriptors on the model class instead of being configured in Meta ([2578301](https://github.com/dropseed/plain/commit/2578301819))
+- Internal model metadata split into separate `model_options` and `_model_meta` attributes for better organization ([73ba469](https://github.com/dropseed/plain/commit/73ba469ba0))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.9.1](https://github.com/dropseed/plain/releases/plain-observer@0.9.1) (2025-10-06)
+
+### What's changed
+
+- Added comprehensive type annotations throughout the package for improved IDE support and type checking ([ffb8624](https://github.com/dropseed/plain/commit/ffb8624d6f))
+- Package has been validated with 100% type coverage and added to the type validation script ([ffb8624](https://github.com/dropseed/plain/commit/ffb8624d6f))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.9.0](https://github.com/dropseed/plain/releases/plain-observer@0.9.0) (2025-09-30)
 
 ### What's changed

{plain_observer-0.9.0 → plain_observer-0.10.0}/plain/observer/admin.py

@@ -1,3 +1,8 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from plain import models
 from plain.admin.views import (
     AdminModelDetailView,
     AdminModelListView,
@@ -24,7 +29,7 @@ class TraceViewset(AdminViewset):
         allow_global_search = False
         actions = ["Delete"]
 
-        def perform_action(self, action: str, target_ids: list):
+        def perform_action(self, action: str, target_ids: Sequence[int]) -> None:
             if action == "Delete":
                 Trace.query.filter(id__in=target_ids).delete()
 
@@ -52,11 +57,11 @@ class SpanViewset(AdminViewset):
         search_fields = ["name", "span_id", "parent_id"]
         actions = ["Delete"]
 
-        def perform_action(self, action: str, target_ids: list):
+        def perform_action(self, action: str, target_ids: Sequence[int]) -> None:
             if action == "Delete":
                 Span.query.filter(id__in=target_ids).delete()
 
-        def get_objects(self):
+        def get_objects(self) -> models.QuerySet:
             return (
                 super()
                 .get_objects()
@@ -69,7 +74,7 @@ class SpanViewset(AdminViewset):
                 )
             )
 
-        def get_initial_queryset(self):
+        def get_initial_queryset(self) -> models.QuerySet:
             queryset = super().get_initial_queryset()
             if self.display == "Parents only":
                 queryset = queryset.filter(parent_id="")
@@ -99,13 +104,13 @@ class LogViewset(AdminViewset):
         filters = ["level", "logger"]
         actions = ["Delete selected", "Delete all"]
 
-        def perform_action(self, action: str, target_ids: list):
+        def perform_action(self, action: str, target_ids: Sequence[int]) -> None:
             if action == "Delete selected":
                 Log.query.filter(id__in=target_ids).delete()
             elif action == "Delete all":
                 Log.query.all().delete()
 
-        def get_objects(self):
+        def get_objects(self) -> models.QuerySet:
             return (
                 super()
                 .get_objects()

{plain_observer-0.9.0 → plain_observer-0.10.0}/plain/observer/cli.py

@@ -1,6 +1,10 @@
+from __future__ import annotations
+
 import json
 import sys
 import urllib.request
+from datetime import datetime
+from typing import Any, cast
 
 import click
 
@@ -11,13 +15,13 @@ from plain.observer.models import Span, Trace
 
 @register_cli("observer")
 @click.group("observer")
-def observer_cli():
+def observer_cli() -> None:
     pass
 
 
 @observer_cli.command()
 @click.option("--force", is_flag=True, help="Skip confirmation prompt.")
-def clear(force: bool):
+def clear(force: bool) -> None:
     """Clear all observer data."""
     query = Trace.query.all()
     trace_count = query.count()
@@ -40,7 +44,13 @@ def clear(force: bool):
 @click.option("--request-id", help="Filter by request ID")
 @click.option("--session-id", help="Filter by session ID")
 @click.option("--json", "output_json", is_flag=True, help="Output as JSON")
-def trace_list(limit, user_id, request_id, session_id, output_json):
+def trace_list(
+    limit: int,
+    user_id: str | None,
+    request_id: str | None,
+    session_id: str | None,
+    output_json: bool,
+) -> None:
     """List recent traces."""
     # Build query
     query = Trace.query.all()
@@ -136,7 +146,7 @@ def trace_list(limit, user_id, request_id, session_id, output_json):
 @observer_cli.command("trace")
 @click.argument("trace_id")
 @click.option("--json", "output_json", is_flag=True, help="Output as JSON")
-def trace_detail(trace_id, output_json):
+def trace_detail(trace_id: str, output_json: bool) -> None:
     """Display detailed information about a specific trace."""
     try:
         trace = Trace.query.get(trace_id=trace_id)
@@ -154,7 +164,7 @@ def trace_detail(trace_id, output_json):
 @click.option("--trace-id", help="Filter by trace ID")
 @click.option("--limit", default=50, help="Number of spans to show (default: 50)")
 @click.option("--json", "output_json", is_flag=True, help="Output as JSON")
-def span_list(trace_id, limit, output_json):
+def span_list(trace_id: str | None, limit: int, output_json: bool) -> None:
     """List recent spans."""
     # Build query
     query = Span.query.all()
@@ -256,7 +266,7 @@ def span_list(trace_id, limit, output_json):
 @observer_cli.command("span")
 @click.argument("span_id")
 @click.option("--json", "output_json", is_flag=True, help="Output as JSON")
-def span_detail(span_id, output_json):
+def span_detail(span_id: str, output_json: bool) -> None:
     """Display detailed information about a specific span."""
     try:
         span = Span.query.select_related("trace").get(span_id=span_id)
@@ -354,22 +364,24 @@ def span_detail(span_id, output_json):
                         click.echo(f"    {key}: {value}")
 
 
-def format_trace_output(trace):
+def format_trace_output(trace: Trace) -> str:
     """Format trace output for display - extracted for reuse."""
-    output_lines = []
+    output_lines: list[str] = []
 
     # Trace details with aligned labels
     label_width = 12
+    start_time = cast(datetime, trace.start_time)
+    end_time = cast(datetime, trace.end_time)
     output_lines.append(
         click.style(
             f"{'Trace:':<{label_width}} {trace.trace_id}", fg="bright_blue", bold=True
         )
     )
     output_lines.append(
-        f"{'Start:':<{label_width}} {trace.start_time.strftime('%Y-%m-%d %H:%M:%S.%f')[:-3]} UTC"
+        f"{'Start:':<{label_width}} {start_time.strftime('%Y-%m-%d %H:%M:%S.%f')[:-3]} UTC"
     )
     output_lines.append(
-        f"{'End:':<{label_width}} {trace.end_time.strftime('%Y-%m-%d %H:%M:%S.%f')[:-3]} UTC"
+        f"{'End:':<{label_width}} {end_time.strftime('%Y-%m-%d %H:%M:%S.%f')[:-3]} UTC"
     )
     output_lines.append(f"{'Duration:':<{label_width}} {trace.duration_ms():.2f}ms")
 
@@ -387,19 +399,17 @@ def format_trace_output(trace):
     output_lines.append(click.style("Spans:", fg="bright_blue", bold=True))
 
     # Get annotated spans with nesting levels
-    spans = trace.spans.query.all().annotate_spans()
+    spans = trace.spans.query.all().annotate_spans()  # type: ignore[attr-defined]
 
     # Build parent-child relationships
     span_dict = {span.span_id: span for span in spans}
-    children = {}
+    children: dict[str, list[str]] = {}
     for span in spans:
         if span.parent_id:
-            if span.parent_id not in children:
-                children[span.parent_id] = []
-            children[span.parent_id].append(span.span_id)
+            children.setdefault(span.parent_id, []).append(span.span_id)
 
-    def format_span_tree(span, level=0):
-        lines = []
+    def format_span_tree(span: Span, level: int = 0) -> list[str]:
+        lines: list[str] = []
         # Simple 4-space indentation
         prefix = "    " * level
 
@@ -502,7 +512,13 @@ def format_trace_output(trace):
     is_flag=True,
     help="Print the prompt without running the agent",
 )
-def diagnose(trace_id, url, json_input, agent_command, print_only):
+def diagnose(
+    trace_id: str | None,
+    url: str | None,
+    json_input: str | None,
+    agent_command: str | None,
+    print_only: bool,
+) -> None:
     """Generate a diagnostic prompt for analyzing a trace.
 
     By default, provide a trace ID from the database. Use --url for a shareable
@@ -515,6 +531,8 @@ def diagnose(trace_id, url, json_input, agent_command, print_only):
     elif input_count > 1:
         raise click.UsageError("Cannot specify multiple input methods")
 
+    trace_data: Any
+
     if json_input:
         if json_input == "-":
             try:
@@ -545,7 +563,7 @@ def diagnose(trace_id, url, json_input, agent_command, print_only):
         except Trace.DoesNotExist:
             raise click.ClickException(f"Trace with ID '{trace_id}' not found")
 
-    prompt_lines = [
+    prompt_lines: list[str] = [
         "I have an 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.",

{plain_observer-0.9.0 → plain_observer-0.10.0}/plain/observer/config.py

@@ -1,3 +1,7 @@
+from __future__ import annotations
+
+from typing import cast
+
 from opentelemetry import trace
 from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import TracerProvider
@@ -20,7 +24,7 @@ from .otel import (
 class Config(PackageConfig):
     package_label = "plainobserver"
 
-    def ready(self):
+    def ready(self) -> None:
         sampler = ObserverSampler()
         span_processor = ObserverSpanProcessor()
 
@@ -55,11 +59,11 @@ class Config(PackageConfig):
             app_logger.addHandler(observer_log_handler)
 
     @staticmethod
-    def get_existing_trace_provider():
+    def get_existing_trace_provider() -> TracerProvider | None:
         """Return the currently configured provider if set."""
         current_provider = trace.get_tracer_provider()
         if current_provider and not isinstance(
             current_provider, trace.ProxyTracerProvider
         ):
-            return current_provider
+            return cast(TracerProvider, current_provider)
         return None

{plain_observer-0.9.0 → plain_observer-0.10.0}/plain/observer/core.py

@@ -1,5 +1,9 @@
+from __future__ import annotations
+
 from enum import Enum
 
+from plain.http import Request, Response
+
 
 class ObserverMode(Enum):
     """Observer operation modes."""
@@ -16,30 +20,30 @@ class 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):
+    def __init__(self, request: Request) -> None:
         self.request = request
 
-    def mode(self):
+    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):
+    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):
+    def is_persisting(self) -> bool:
         """Check if full persisting (with DB export) is enabled."""
         return self.mode() == ObserverMode.PERSIST.value
 
-    def is_summarizing(self):
+    def is_summarizing(self) -> bool:
         """Check if summary mode is enabled."""
         return self.mode() == ObserverMode.SUMMARY.value
 
-    def is_disabled(self):
+    def is_disabled(self) -> bool:
         """Check if observer is explicitly disabled."""
         return self.mode() == ObserverMode.DISABLED.value
 
-    def enable_summary_mode(self, response):
+    def enable_summary_mode(self, response: Response) -> None:
         """Enable summary mode (real-time monitoring, no DB export)."""
         response.set_signed_cookie(
             self.COOKIE_NAME,
@@ -47,7 +51,7 @@ class Observer:
             max_age=self.SUMMARY_COOKIE_DURATION,
         )
 
-    def enable_persist_mode(self, response):
+    def enable_persist_mode(self, response: Response) -> None:
         """Enable full persist mode (real-time monitoring + DB export)."""
         response.set_signed_cookie(
             self.COOKIE_NAME,
@@ -55,7 +59,7 @@ class Observer:
             max_age=self.PERSIST_COOKIE_DURATION,
         )
 
-    def disable(self, response):
+    def disable(self, response: Response) -> None:
         """Disable observer by setting cookie to disabled."""
         response.set_signed_cookie(
             self.COOKIE_NAME,
@@ -63,7 +67,7 @@ class Observer:
             max_age=self.PERSIST_COOKIE_DURATION,
         )
 
-    def get_current_trace_summary(self):
+    def get_current_trace_summary(self) -> str | None:
         """Get performance summary string for the currently active trace."""
         from .otel import get_current_trace_summary
 

{plain_observer-0.9.0 → plain_observer-0.10.0}/plain/observer/logging.py

@@ -1,6 +1,9 @@
+from __future__ import annotations
+
 import logging
 import threading
 from datetime import UTC, datetime
+from typing import TypedDict
 
 from opentelemetry import trace
 from opentelemetry.trace import format_span_id, format_trace_id
@@ -9,15 +12,22 @@ from .core import ObserverMode
 from .otel import get_observer_span_processor
 
 
+class ObserverLogEntry(TypedDict):
+    message: str
+    level: str
+    span_id: str
+    timestamp: datetime
+
+
 class ObserverLogHandler(logging.Handler):
     """Custom logging handler that captures logs during active traces when observer is enabled."""
 
-    def __init__(self, level=logging.NOTSET):
+    def __init__(self, level: int = logging.NOTSET) -> None:
         super().__init__(level)
         self._logs_lock = threading.Lock()
-        self._trace_logs = {}  # trace_id -> list of log records
+        self._trace_logs: dict[str, list[ObserverLogEntry]] = {}
 
-    def emit(self, record):
+    def emit(self, record: logging.LogRecord) -> None:
         """Emit a log record if we're in an active observer trace."""
         try:
             # Get the current span to determine if we're in an active trace
@@ -45,7 +55,7 @@ class ObserverLogHandler(logging.Handler):
                     return
 
             # Store the formatted message with span context
-            log_entry = {
+            log_entry: ObserverLogEntry = {
                 "message": self.format(record),
                 "level": record.levelname,
                 "span_id": span_id,
@@ -65,7 +75,7 @@ class ObserverLogHandler(logging.Handler):
             # Don't let logging errors break the application
             pass
 
-    def pop_logs_for_trace(self, trace_id):
+    def pop_logs_for_trace(self, trace_id: str) -> list[ObserverLogEntry]:
         """Get and remove all logs for a specific trace in one operation."""
         with self._logs_lock:
             return self._trace_logs.pop(trace_id, []).copy()

{plain_observer-0.9.0 → plain_observer-0.10.0}/plain/observer/models.py

@@ -1,10 +1,15 @@
+from __future__ import annotations
+
 import json
 import secrets
 from collections import Counter
+from collections.abc import Iterable, Mapping, Sequence
 from datetime import UTC, datetime
 from functools import cached_property
+from typing import TYPE_CHECKING, Any, cast
 
 import sqlparse
+from opentelemetry.sdk.trace import ReadableSpan
 from opentelemetry.semconv._incubating.attributes import (
     exception_attributes,
     session_attributes,
@@ -52,48 +57,55 @@ class Trace(models.Model):
     share_id = models.CharField(max_length=32, default="", required=False)
     share_created_at = models.DateTimeField(allow_null=True, required=False)
 
-    class Meta:
-        ordering = ["-start_time"]
-        constraints = [
+    if TYPE_CHECKING:
+        from plain.models.fields.related_managers import BaseRelatedManager
+
+        spans: BaseRelatedManager
+        logs: BaseRelatedManager
+
+    model_options = models.Options(
+        ordering=["-start_time"],
+        constraints=[
             models.UniqueConstraint(
                 fields=["trace_id"],
                 name="observer_unique_trace_id",
             )
-        ]
-        indexes = [
+        ],
+        indexes=[
             models.Index(fields=["trace_id"]),
             models.Index(fields=["start_time"]),
             models.Index(fields=["request_id"]),
             models.Index(fields=["share_id"]),
             models.Index(fields=["session_id"]),
-        ]
+        ],
+    )
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.trace_id
 
-    def get_absolute_url(self):
+    def get_absolute_url(self) -> str:
         """Return the canonical URL for this trace."""
         return reverse("observer:trace_detail", trace_id=self.trace_id)
 
-    def generate_share_id(self):
+    def generate_share_id(self) -> str:
         """Generate a unique share ID for this trace."""
         self.share_id = secrets.token_urlsafe(24)
         self.share_created_at = timezone.now()
         self.save(update_fields=["share_id", "share_created_at"])
         return self.share_id
 
-    def remove_share_id(self):
+    def remove_share_id(self) -> None:
         """Remove the share ID from this trace."""
         self.share_id = ""
         self.share_created_at = None
         self.save(update_fields=["share_id", "share_created_at"])
 
-    def duration_ms(self):
+    def duration_ms(self) -> float:
         return (self.end_time - self.start_time).total_seconds() * 1000
 
-    def get_trace_summary(self, spans):
+    def get_trace_summary(self, spans: Iterable[Span]) -> str:
         # Count database queries with query text and track duplicates
-        query_texts = []
+        query_texts: list[str] = []
         for span in spans:
             if query_text := span.attributes.get(db_attributes.DB_QUERY_TEXT):
                 query_texts.append(query_text)
@@ -103,7 +115,7 @@ class Trace(models.Model):
         duplicate_count = sum(query_counts.values()) - len(query_counts)
 
         # Build summary: "n spans, n queries (n duplicates), Xms"
-        parts = []
+        parts: list[str] = []
 
         # Queries count with duplicates
         if query_total > 0:
@@ -119,7 +131,7 @@ class Trace(models.Model):
         return " • ".join(parts)
 
     @classmethod
-    def from_opentelemetry_spans(cls, spans):
+    def from_opentelemetry_spans(cls, spans: Sequence[ReadableSpan]) -> Trace:
         """Create a Trace instance from a list of OpenTelemetry spans."""
         # Get trace information from the first span
         first_span = spans[0]
@@ -187,7 +199,7 @@ class Trace(models.Model):
             root_span_name=root_span.name if root_span else "",
         )
 
-    def as_dict(self):
+    def as_dict(self) -> dict[str, Any]:
         spans = [
             span.span_data for span in self.spans.query.all().order_by("start_time")
         ]
@@ -217,9 +229,9 @@ class Trace(models.Model):
             "logs": logs,
         }
 
-    def get_timeline_events(self):
+    def get_timeline_events(self) -> list[dict[str, Any]]:
         """Get chronological list of spans and logs for unified timeline display."""
-        events = []
+        events: list[dict[str, Any]] = []
 
         for span in self.spans.query.all().annotate_spans():
             events.append(
@@ -257,13 +269,13 @@ class Trace(models.Model):
         return sorted(events, key=lambda x: x["timestamp"])
 
 
-class SpanQuerySet(models.QuerySet):
-    def annotate_spans(self):
+class SpanQuerySet(models.QuerySet["Span"]):
+    def annotate_spans(self) -> list[Span]:
         """Annotate spans with nesting levels and duplicate query warnings."""
-        spans = list(self.order_by("start_time"))
+        spans: list[Span] = list(self.order_by("start_time"))
 
         # Build span dictionary for parent lookups
-        span_dict = {span.span_id: span for span in spans}
+        span_dict: dict[str, Span] = {span.span_id: span for span in spans}
 
         # Calculate nesting levels
         for span in spans:
@@ -275,7 +287,7 @@ class SpanQuerySet(models.QuerySet):
                 parent_level = parent.level if parent else 0
                 span.level = parent_level + 1
 
-        query_counts = {}
+        query_counts: dict[str, int] = {}
 
         # First pass: count queries
         for span in spans:
@@ -283,7 +295,7 @@ class SpanQuerySet(models.QuerySet):
                 query_counts[sql_query] = query_counts.get(sql_query, 0) + 1
 
         # Second pass: add annotations
-        query_occurrences = {}
+        query_occurrences: dict[str, int] = {}
         for span in spans:
             span.annotations = []
 
@@ -318,24 +330,30 @@ class Span(models.Model):
     status = models.CharField(max_length=50, default="", required=False)
     span_data = models.JSONField(default=dict, required=False)
 
-    class Meta:
-        queryset_class = SpanQuerySet
-        ordering = ["-start_time"]
-        constraints = [
+    query = SpanQuerySet()
+
+    model_options = models.Options(
+        ordering=["-start_time"],
+        constraints=[
             models.UniqueConstraint(
                 fields=["trace", "span_id"],
                 name="observer_unique_span_id",
             )
-        ]
-        indexes = [
+        ],
+        indexes=[
             models.Index(fields=["span_id"]),
             models.Index(fields=["trace", "span_id"]),
             models.Index(fields=["trace"]),
             models.Index(fields=["start_time"]),
-        ]
+        ],
+    )
+
+    if TYPE_CHECKING:
+        level: int
+        annotations: list[dict[str, Any]]
 
     @classmethod
-    def from_opentelemetry_span(cls, otel_span, trace):
+    def from_opentelemetry_span(cls, otel_span: ReadableSpan, trace: Trace) -> Span:
         """Create a Span instance from an OpenTelemetry span."""
 
         span_data = json.loads(otel_span.to_json())
@@ -357,51 +375,51 @@ class Span(models.Model):
             span_data=span_data,
         )
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.span_id
 
     @property
-    def attributes(self):
+    def attributes(self) -> Mapping[str, Any]:
         """Get attributes from span_data."""
-        return self.span_data.get("attributes", {})
+        return cast(Mapping[str, Any], self.span_data.get("attributes", {}))
 
     @property
-    def events(self):
+    def events(self) -> list[Mapping[str, Any]]:
         """Get events from span_data."""
-        return self.span_data.get("events", [])
+        return cast(list[Mapping[str, Any]], self.span_data.get("events", []))
 
     @property
-    def links(self):
+    def links(self) -> list[Mapping[str, Any]]:
         """Get links from span_data."""
-        return self.span_data.get("links", [])
+        return cast(list[Mapping[str, Any]], self.span_data.get("links", []))
 
     @property
-    def resource(self):
+    def resource(self) -> Mapping[str, Any]:
         """Get resource from span_data."""
-        return self.span_data.get("resource", {})
+        return cast(Mapping[str, Any], self.span_data.get("resource", {}))
 
     @property
-    def context(self):
+    def context(self) -> Mapping[str, Any]:
         """Get context from span_data."""
-        return self.span_data.get("context", {})
+        return cast(Mapping[str, Any], self.span_data.get("context", {}))
 
-    def duration_ms(self):
+    def duration_ms(self) -> float:
         if self.start_time and self.end_time:
             return (self.end_time - self.start_time).total_seconds() * 1000
         return 0
 
     @cached_property
-    def sql_query(self):
+    def sql_query(self) -> str | None:
         """Get the SQL query if this span contains one."""
         return self.attributes.get(db_attributes.DB_QUERY_TEXT)
 
     @cached_property
-    def sql_query_params(self):
+    def sql_query_params(self) -> dict[str, Any]:
         """Get query parameters from attributes that start with 'db.query.parameter.'"""
         if not self.attributes:
             return {}
 
-        query_params = {}
+        query_params: dict[str, Any] = {}
         for key, value in self.attributes.items():
             if key.startswith(DB_QUERY_PARAMETER_TEMPLATE + "."):
                 param_name = key.replace(DB_QUERY_PARAMETER_TEMPLATE + ".", "")
@@ -410,7 +428,7 @@ class Span(models.Model):
         return query_params
 
     @cached_property
-    def source_code_location(self):
+    def source_code_location(self) -> dict[str, Any] | None:
         """Get the source code location attributes from this span."""
         if not self.attributes:
             return None
@@ -432,7 +450,7 @@ class Span(models.Model):
 
         return code_attrs if code_attrs else None
 
-    def get_formatted_sql(self):
+    def get_formatted_sql(self) -> str | None:
         """Get the pretty-formatted SQL query if this span contains one."""
         sql = self.sql_query
         if not sql:
@@ -450,22 +468,27 @@ class Span(models.Model):
             comma_first=False,
         )
 
-    def format_event_timestamp(self, timestamp):
+    def format_event_timestamp(
+        self, timestamp: float | int | datetime | str
+    ) -> datetime | str:
         """Convert event timestamp to a readable datetime."""
         if isinstance(timestamp, int | float):
+            ts_value = float(timestamp)
             try:
                 # Try as seconds first
-                if timestamp > 1e10:  # Likely nanoseconds
-                    timestamp = timestamp / 1e9
-                elif timestamp > 1e7:  # Likely milliseconds
-                    timestamp = timestamp / 1e3
+                if ts_value > 1e10:  # Likely nanoseconds
+                    ts_value /= 1e9
+                elif ts_value > 1e7:  # Likely milliseconds
+                    ts_value /= 1e3
 
-                return datetime.fromtimestamp(timestamp, tz=UTC)
+                return datetime.fromtimestamp(ts_value, tz=UTC)
             except (ValueError, OSError):
-                return str(timestamp)
-        return timestamp
+                return str(ts_value)
+        if isinstance(timestamp, datetime):
+            return timestamp
+        return str(timestamp)
 
-    def get_exception_stacktrace(self):
+    def get_exception_stacktrace(self) -> str | None:
         """Get the exception stacktrace if this span has an exception event."""
         if not self.events:
             return None
@@ -493,11 +516,12 @@ class Log(models.Model):
     level = models.CharField(max_length=20)
     message = models.TextField()
 
-    class Meta:
-        ordering = ["timestamp"]
-        indexes = [
+    model_options = models.Options(
+        ordering=["timestamp"],
+        indexes=[
             models.Index(fields=["trace", "timestamp"]),
             models.Index(fields=["trace", "span"]),
             models.Index(fields=["timestamp"]),
             models.Index(fields=["trace"]),
-        ]
+        ],
+    )

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

@@ -1,13 +1,24 @@
+from __future__ import annotations
+
 import logging
 import re
 import threading
 from collections import defaultdict
+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.sdk.trace import SpanProcessor, sampling
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace import ReadableSpan, SpanProcessor, sampling
 from opentelemetry.semconv.attributes import url_attributes
-from opentelemetry.trace import SpanKind, format_span_id, format_trace_id
+from opentelemetry.trace import (
+    Link,
+    SpanKind,
+    TraceState,
+    format_span_id,
+    format_trace_id,
+)
 
 from plain.http.cookie import unsign_cookie_value
 from plain.logs import app_logger
@@ -16,10 +27,16 @@ from plain.runtime import settings
 
 from .core import Observer, ObserverMode
 
+if TYPE_CHECKING:
+    from plain.observer.models import Span as ObserverSpanModel
+    from plain.observer.models import Trace as TraceModel
+
+    from .logging import ObserverLogEntry
+
 logger = logging.getLogger(__name__)
 
 
-def get_observer_span_processor():
+def get_observer_span_processor() -> ObserverSpanProcessor | None:
     """Get the span collector instance from the tracer provider."""
     if not (current_provider := trace.get_tracer_provider()):
         return None
@@ -30,7 +47,11 @@ def get_observer_span_processor():
         # It's a composite processor, check its _span_processors
         if composite_processor := current_provider._active_span_processor:
             if hasattr(composite_processor, "_span_processors"):
-                for processor in composite_processor._span_processors:
+                processors = cast(
+                    Sequence[SpanProcessor],
+                    getattr(composite_processor, "_span_processors", ()),
+                )
+                for processor in processors:
                     if isinstance(processor, ObserverSpanProcessor):
                         return processor
 
@@ -55,25 +76,25 @@ def get_current_trace_summary() -> str | None:
 class ObserverSampler(sampling.Sampler):
     """Samples traces based on request path and cookies."""
 
-    def __init__(self):
+    def __init__(self) -> None:
         # Custom parent-based sampler
         self._delegate = sampling.ParentBased(sampling.ALWAYS_OFF)
 
         # TODO ignore url namespace instead? admin, observer, assets
-        self._ignore_url_paths = [
+        self._ignore_url_paths: list[re.Pattern[str]] = [
             re.compile(p) for p in settings.OBSERVER_IGNORE_URL_PATTERNS
         ]
 
     def should_sample(
         self,
-        parent_context,
-        trace_id,
-        name,
+        parent_context: Context | None,
+        trace_id: int,
+        name: str,
         kind: SpanKind | None = None,
-        attributes=None,
-        links=None,
-        trace_state=None,
-    ):
+        attributes: MutableMapping[str, Any] | None = None,
+        links: Sequence[Link] | None = None,
+        trace_state: TraceState | None = None,
+    ) -> sampling.SamplingResult:
         # First, drop if the URL should be ignored.
         if attributes:
             if url_path := attributes.get(url_attributes.URL_PATH, ""):
@@ -85,24 +106,27 @@ class ObserverSampler(sampling.Sampler):
                         )
 
         # If no processor decision, check cookies directly for root spans
-        decision = None
+        decision: sampling.Decision | None = None
         if parent_context:
             # Check cookies for sampling decision
-            if cookies := baggage.get_baggage("http.request.cookies", parent_context):
-                if observer_cookie := cookies.get(Observer.COOKIE_NAME):
-                    unsigned_value = unsign_cookie_value(
-                        Observer.COOKIE_NAME, observer_cookie, default=False
-                    )
+            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
+                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
 
         # If there are links, assume it is to another trace/span that we are keeping
         if links:
@@ -133,20 +157,20 @@ class ObserverSampler(sampling.Sampler):
 class ObserverCombinedSampler(sampling.Sampler):
     """Combine another sampler with ``ObserverSampler``."""
 
-    def __init__(self, primary: sampling.Sampler, secondary: sampling.Sampler):
+    def __init__(self, primary: sampling.Sampler, secondary: sampling.Sampler) -> None:
         self.primary = primary
         self.secondary = secondary
 
     def should_sample(
         self,
-        parent_context,
-        trace_id,
-        name,
+        parent_context: Context | None,
+        trace_id: int,
+        name: str,
         kind: SpanKind | None = None,
-        attributes=None,
-        links=None,
-        trace_state=None,
-    ):
+        attributes: MutableMapping[str, Any] | None = None,
+        links: Sequence[Link] | None = None,
+        trace_state: TraceState | None = None,
+    ) -> sampling.SamplingResult:
         result = self.primary.should_sample(
             parent_context,
             trace_id,
@@ -183,9 +207,9 @@ class ObserverSpanProcessor(SpanProcessor):
     database.
     """
 
-    def __init__(self):
+    def __init__(self) -> None:
         # Span storage
-        self._traces = defaultdict(
+        self._traces: defaultdict[str, dict[str, Any]] = defaultdict(
             lambda: {
                 "trace": None,  # Trace model instance
                 "active_otel_spans": {},  # span_id -> opentelemetry span
@@ -196,11 +220,11 @@ class ObserverSpanProcessor(SpanProcessor):
             }
         )
         self._traces_lock = threading.Lock()
-        self._ignore_url_paths = [
+        self._ignore_url_paths: list[re.Pattern[str]] = [
             re.compile(p) for p in settings.OBSERVER_IGNORE_URL_PATTERNS
         ]
 
-    def on_start(self, span, parent_context=None):
+    def on_start(self, span: Any, parent_context: Context | None = None) -> None:
         """Called when a span starts."""
         trace_id = f"0x{format_trace_id(span.get_span_context().trace_id)}"
 
@@ -232,7 +256,7 @@ class ObserverSpanProcessor(SpanProcessor):
             if not span.parent:
                 trace_info["root_span_id"] = span_id
 
-    def on_end(self, span):
+    def on_end(self, span: ReadableSpan) -> None:
         """Called when a span ends."""
         trace_id = f"0x{format_trace_id(span.get_span_context().trace_id)}"
         span_id = f"0x{format_span_id(span.get_span_context().span_id)}"
@@ -330,7 +354,13 @@ class ObserverSpanProcessor(SpanProcessor):
 
             return trace_info["trace"].get_trace_summary(span_models)
 
-    def _export_trace(self, *, trace, spans, logs):
+    def _export_trace(
+        self,
+        *,
+        trace: TraceModel,
+        spans: Sequence[ObserverSpanModel],
+        logs: Sequence[ObserverLogEntry],
+    ) -> None:
         """Export trace, spans, and logs to the database."""
         from .models import Log, Span, Trace
 
@@ -342,7 +372,7 @@ class ObserverSpanProcessor(SpanProcessor):
                     span.trace = trace
 
                 # Bulk create spans
-                Span.query.bulk_create(spans)
+                Span.query.bulk_create(spans)  # type: ignore[arg-type]
 
                 # Create log models if we have logs
                 if logs:
@@ -387,7 +417,9 @@ class ObserverSpanProcessor(SpanProcessor):
                         "Failed to clean up old observer traces: %s", e, exc_info=True
                     )
 
-    def _get_recording_mode(self, span, parent_context) -> str | None:
+    def _get_recording_mode(
+        self, span: Any, parent_context: Context | None
+    ) -> str | None:
         # Again check the span attributes, in case we relied on another sampler
         if span.attributes:
             if url_path := span.attributes.get(url_attributes.URL_PATH, ""):
@@ -409,10 +441,15 @@ class ObserverSpanProcessor(SpanProcessor):
         if not (context := parent_context or context_api.get_current()):
             return None
 
-        if not (cookies := baggage.get_baggage("http.request.cookies", context)):
+        cookies = cast(
+            MutableMapping[str, str] | None,
+            baggage.get_baggage("http.request.cookies", context),
+        )
+        if not cookies:
             return None
 
-        if not (observer_cookie := cookies.get(Observer.COOKIE_NAME)):
+        observer_cookie = cookies.get(Observer.COOKIE_NAME)
+        if not observer_cookie:
             return None
 
         try:
@@ -426,11 +463,11 @@ class ObserverSpanProcessor(SpanProcessor):
 
         return None
 
-    def shutdown(self):
+    def shutdown(self) -> None:
         """Cleanup when shutting down."""
         with self._traces_lock:
             self._traces.clear()
 
-    def force_flush(self, timeout_millis=None):
+    def force_flush(self, timeout_millis: int | None = None) -> bool:
         """Required by SpanProcessor interface."""
         return True

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

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 from functools import cached_property
+from typing import Any
 
 from plain.toolbar import ToolbarItem, register_toolbar_item
 
@@ -12,11 +15,11 @@ class ObserverToolbarItem(ToolbarItem):
     button_template_name = "toolbar/observer_button.html"
 
     @cached_property
-    def observer(self):
+    def observer(self) -> Observer:
         """Get the Observer instance for this request."""
         return Observer(self.request)
 
-    def get_template_context(self):
+    def get_template_context(self) -> dict[str, Any]:
         context = super().get_template_context()
         context["observer"] = self.observer
         return context

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

@@ -1,3 +1,8 @@
+from __future__ import annotations
+
+from typing import Any
+
+from plain import models
 from plain.auth.views import AuthViewMixin
 from plain.htmx.views import HTMXViewMixin
 from plain.http import JsonResponse, Response
@@ -14,28 +19,28 @@ class ObserverTracesView(AuthViewMixin, HTMXViewMixin, ListView):
     context_object_name = "traces"
     admin_required = True
 
-    def get_objects(self):
+    def get_objects(self) -> models.QuerySet:
         return Trace.query.all()
 
-    def check_auth(self):
+    def check_auth(self) -> None:
         # Allow the view if we're in DEBUG
         if settings.DEBUG:
             return
 
         super().check_auth()
 
-    def get_response(self):
+    def get_response(self) -> Response:
         response = super().get_response()
         # So we can load it in the toolbar
         response.headers["X-Frame-Options"] = "SAMEORIGIN"
         return response
 
-    def get_template_context(self):
+    def get_template_context(self) -> dict[str, Any]:
         context = super().get_template_context()
         context["observer"] = Observer(self.request)
         return context
 
-    def htmx_put_mode(self):
+    def htmx_put_mode(self) -> Response:
         """Set observer mode via HTMX PUT."""
         mode = self.request.data.get("mode")
         observer = Observer(self.request)
@@ -54,14 +59,14 @@ class ObserverTracesView(AuthViewMixin, HTMXViewMixin, ListView):
 
         return response
 
-    def htmx_delete_traces(self):
+    def htmx_delete_traces(self) -> Response:
         """Clear all traces via HTMX DELETE."""
         Trace.query.filter(share_id="").delete()
         response = Response(status_code=204)
         response.headers["HX-Refresh"] = "true"
         return response
 
-    def post(self):
+    def post(self) -> Response:
         """Handle POST requests to set observer mode."""
         action = self.request.data.get("observe_action")
         if action == "summary":
@@ -79,16 +84,16 @@ class ObserverTraceDetailView(AuthViewMixin, HTMXViewMixin, DetailView):
     context_object_name = "trace"
     admin_required = True
 
-    def get_object(self):
+    def get_object(self) -> Trace | None:
         return Trace.query.get_or_none(trace_id=self.url_kwargs.get("trace_id"))
 
-    def check_auth(self):
+    def check_auth(self) -> None:
         # Allow the view if we're in DEBUG
         if settings.DEBUG:
             return
         super().check_auth()
 
-    def get(self):
+    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")
         if (
@@ -108,13 +113,13 @@ class ObserverTraceDetailView(AuthViewMixin, HTMXViewMixin, DetailView):
 
         return super().get()
 
-    def get_template_names(self):
+    def get_template_names(self) -> list[str]:
         if self.is_htmx_request():
             # Use a different template for HTMX requests
             return ["observer/trace.html"]
         return super().get_template_names()
 
-    def htmx_delete(self):
+    def htmx_delete(self) -> Response:
         self.object.delete()
 
         # Redirect to traces list after deletion
@@ -122,11 +127,11 @@ class ObserverTraceDetailView(AuthViewMixin, HTMXViewMixin, DetailView):
         response.headers["HX-Redirect"] = reverse("observer:traces")
         return response
 
-    def htmx_post_share(self):
+    def htmx_post_share(self) -> Response:
         self.object.generate_share_id()
         return super().get()
 
-    def htmx_delete_share(self):
+    def htmx_delete_share(self) -> Response:
         self.object.remove_share_id()
         return super().get()
 
@@ -137,15 +142,15 @@ class ObserverTraceSharedView(DetailView):
     template_name = "observer/trace_share.html"
     context_object_name = "trace"
 
-    def get_object(self):
+    def get_object(self) -> Trace | None:
         return Trace.query.get_or_none(share_id=self.url_kwargs["share_id"])
 
-    def get_template_context(self):
+    def get_template_context(self) -> dict[str, Any]:
         context = super().get_template_context()
         context["is_share_view"] = True
         return context
 
-    def get(self):
+    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")
         if (

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

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