plain.observer 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

plain/observer/CHANGELOG.md

@@ -1,5 +1,23 @@
 # plain-observer changelog
 
+## [0.6.0](https://github.com/dropseed/plain/releases/plain-observer@0.6.0) (2025-09-09)
+
+### What's changed
+
+- Added comprehensive log capture and display during trace recording, with logs shown in a unified timeline alongside spans ([9bfe938](https://github.com/dropseed/plain/commit/9bfe938f64))
+- Added new Log model with admin interface for managing captured log entries ([9bfe938](https://github.com/dropseed/plain/commit/9bfe938f64))
+- Observer now automatically enables debug logging during trace recording to capture more detailed information ([731196](https://github.com/dropseed/plain/commit/731196086f))
+- Added app_name and app_version fields to trace records for better application identification ([2870636](https://github.com/dropseed/plain/commit/2870636944))
+- Added span count display in trace detail views ([4d22c10](https://github.com/dropseed/plain/commit/4d22c1058d))
+- Enhanced database query counting to only include queries with actual query text, providing more accurate metrics ([3d102d3](https://github.com/dropseed/plain/commit/3d102d3796))
+- Improved trace limit cleanup logic to properly maintain the configured trace limit ([e9d124b](https://github.com/dropseed/plain/commit/e9d124bccd))
+- Added source code location attributes support for spans with file path, line number, and function information ([da36a17](https://github.com/dropseed/plain/commit/da36a17dab))
+- Updated Python version requirement to 3.13 minimum ([d86e307](https://github.com/dropseed/plain/commit/d86e307efb))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.5.0](https://github.com/dropseed/plain/releases/plain-observer@0.5.0) (2025-09-03)
 
 ### What's changed

plain/observer/admin.py

@@ -5,7 +5,7 @@ from plain.admin.views import (
     register_viewset,
 )
 
-from .models import Span, Trace
+from .models import Log, Span, Trace
 
 
 @register_viewset
@@ -77,3 +77,48 @@ class SpanViewset(AdminViewset):
 
     class DetailView(AdminModelDetailView):
         model = Span
+
+
+@register_viewset
+class LogViewset(AdminViewset):
+    class ListView(AdminModelListView):
+        nav_section = "Observer"
+        nav_icon = "activity"
+        model = Log
+        fields = [
+            "timestamp",
+            "level",
+            "logger",
+            "message",
+            "trace",
+            "span",
+        ]
+        queryset_order = ["-timestamp"]
+        allow_global_search = False
+        search_fields = ["logger", "message", "level"]
+        filters = ["level", "logger"]
+        actions = ["Delete selected", "Delete all"]
+
+        def perform_action(self, action: str, target_ids: list):
+            if action == "Delete selected":
+                Log.objects.filter(id__in=target_ids).delete()
+            elif action == "Delete all":
+                Log.objects.all().delete()
+
+        def get_objects(self):
+            return (
+                super()
+                .get_objects()
+                .select_related("trace", "span")
+                .only(
+                    "timestamp",
+                    "level",
+                    "logger",
+                    "message",
+                    "span__span_id",
+                    "trace__trace_id",
+                )
+            )
+
+    class DetailView(AdminModelDetailView):
+        model = Log

plain/observer/config.py

@@ -1,8 +1,13 @@
 from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.semconv.attributes import service_attributes
 
+from plain.logs import app_logger
 from plain.packages import PackageConfig, register_config
+from plain.runtime import settings
 
+from .logging import observer_log_handler
 from .otel import (
     ObserverCombinedSampler,
     ObserverSampler,
@@ -29,10 +34,20 @@ class Config(PackageConfig):
                 provider.add_span_processor(span_processor)
         else:
             # Start our own provider, new sampler, and span processor
-            provider = TracerProvider(sampler=sampler)
+            resource = Resource.create(
+                {
+                    service_attributes.SERVICE_NAME: settings.APP_NAME,
+                    service_attributes.SERVICE_VERSION: settings.APP_VERSION,
+                }
+            )
+            provider = TracerProvider(sampler=sampler, resource=resource)
             provider.add_span_processor(span_processor)
             trace.set_tracer_provider(provider)
 
+        # Install the logging handler to capture logs during traces
+        if observer_log_handler not in app_logger.handlers:
+            app_logger.addHandler(observer_log_handler)
+
     @staticmethod
     def get_existing_trace_provider():
         """Return the currently configured provider if set."""

plain/observer/logging.py

@@ -0,0 +1,74 @@
+import logging
+import threading
+from datetime import UTC, datetime
+
+from opentelemetry import trace
+from opentelemetry.trace import format_span_id, format_trace_id
+
+from .core import ObserverMode
+from .otel import get_observer_span_processor
+
+
+class ObserverLogHandler(logging.Handler):
+    """Custom logging handler that captures logs during active traces when observer is enabled."""
+
+    def __init__(self, level=logging.NOTSET):
+        super().__init__(level)
+        self._logs_lock = threading.Lock()
+        self._trace_logs = {}  # trace_id -> list of log records
+
+    def emit(self, record):
+        """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
+            current_span = trace.get_current_span()
+            if not current_span or not current_span.get_span_context().is_valid:
+                return
+
+            # Get trace and span IDs
+            trace_id = f"0x{format_trace_id(current_span.get_span_context().trace_id)}"
+            span_id = f"0x{format_span_id(current_span.get_span_context().span_id)}"
+
+            # Check if observer is recording this trace
+            processor = get_observer_span_processor()
+            if not processor:
+                return
+
+            # Check if we should record logs for this trace
+            with processor._traces_lock:
+                if trace_id not in processor._traces:
+                    return
+
+                trace_info = processor._traces[trace_id]
+                # Only capture logs in PERSIST mode
+                if trace_info["mode"] != ObserverMode.PERSIST.value:
+                    return
+
+            # Store the log record with span context
+            log_entry = {
+                "record": record,
+                "span_id": span_id,
+                "timestamp": datetime.fromtimestamp(record.created, tz=UTC),
+            }
+
+            with self._logs_lock:
+                if trace_id not in self._trace_logs:
+                    self._trace_logs[trace_id] = []
+                self._trace_logs[trace_id].append(log_entry)
+
+                # Limit logs per trace to prevent memory issues
+                if len(self._trace_logs[trace_id]) > 1000:
+                    self._trace_logs[trace_id] = self._trace_logs[trace_id][-500:]
+
+        except Exception:
+            # Don't let logging errors break the application
+            pass
+
+    def pop_logs_for_trace(self, trace_id):
+        """Get and remove all logs for a specific trace in one operation."""
+        with self._logs_lock:
+            return self._trace_logs.pop(trace_id, []).copy()
+
+
+# Global instance of the log handler
+observer_log_handler = ObserverLogHandler()

plain/observer/migrations/0004_trace_app_name_trace_app_version.py

@@ -0,0 +1,23 @@
+# Generated by Plain 0.61.0 on 2025-09-08 17:09
+
+from plain import models
+from plain.models import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("plainobserver", "0003_span_plainobserv_span_id_e7ade3_idx"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="trace",
+            name="app_name",
+            field=models.CharField(default="", max_length=255, required=False),
+        ),
+        migrations.AddField(
+            model_name="trace",
+            name="app_version",
+            field=models.CharField(default="", max_length=255, required=False),
+        ),
+    ]

plain/observer/migrations/0005_log_log_plainobserv_trace_i_fcfb7d_idx_and_more.py

@@ -0,0 +1,67 @@
+# Generated by Plain 0.61.0 on 2025-09-08 21:12
+
+import plain.models.deletion
+from plain import models
+from plain.models import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("plainobserver", "0004_trace_app_name_trace_app_version"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="Log",
+            fields=[
+                ("id", models.PrimaryKeyField()),
+                ("timestamp", models.DateTimeField()),
+                ("level", models.CharField(max_length=20)),
+                ("logger", models.CharField(max_length=255)),
+                ("message", models.TextField()),
+                (
+                    "span",
+                    models.ForeignKey(
+                        allow_null=True,
+                        on_delete=plain.models.deletion.SET_NULL,
+                        related_name="logs",
+                        required=False,
+                        to="plainobserver.span",
+                    ),
+                ),
+                (
+                    "trace",
+                    models.ForeignKey(
+                        on_delete=plain.models.deletion.CASCADE,
+                        related_name="logs",
+                        to="plainobserver.trace",
+                    ),
+                ),
+            ],
+            options={
+                "ordering": ["timestamp"],
+            },
+        ),
+        migrations.AddIndex(
+            model_name="log",
+            index=models.Index(
+                fields=["trace", "timestamp"], name="plainobserv_trace_i_fcfb7d_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="log",
+            index=models.Index(
+                fields=["trace", "span"], name="plainobserv_trace_i_1166af_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="log",
+            index=models.Index(
+                fields=["timestamp"], name="plainobserv_timesta_64f0dc_idx"
+            ),
+        ),
+        migrations.AddIndex(
+            model_name="log",
+            index=models.Index(fields=["trace"], name="plainobserv_trace_i_c64ee0_idx"),
+        ),
+    ]

plain/observer/migrations/0006_remove_log_logger.py

@@ -0,0 +1,16 @@
+# Generated by Plain 0.61.0 on 2025-09-09 15:50
+
+from plain.models import migrations
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("plainobserver", "0005_log_log_plainobserv_trace_i_fcfb7d_idx_and_more"),
+    ]
+
+    operations = [
+        migrations.RemoveField(
+            model_name="log",
+            name="logger",
+        ),
+    ]

plain/observer/models.py

@@ -1,5 +1,6 @@
 import json
 import secrets
+from collections import Counter
 from datetime import UTC, datetime
 from functools import cached_property
 
@@ -9,13 +10,24 @@ from opentelemetry.semconv._incubating.attributes import (
     session_attributes,
     user_attributes,
 )
+from opentelemetry.semconv._incubating.attributes.code_attributes import (
+    CODE_NAMESPACE,
+)
 from opentelemetry.semconv._incubating.attributes.db_attributes import (
     DB_QUERY_PARAMETER_TEMPLATE,
 )
-from opentelemetry.semconv.attributes import db_attributes
+from opentelemetry.semconv.attributes import db_attributes, service_attributes
+from opentelemetry.semconv.attributes.code_attributes import (
+    CODE_COLUMN_NUMBER,
+    CODE_FILE_PATH,
+    CODE_FUNCTION_NAME,
+    CODE_LINE_NUMBER,
+    CODE_STACKTRACE,
+)
 from opentelemetry.trace import format_trace_id
 
 from plain import models
+from plain.runtime import settings
 from plain.urls import reverse
 from plain.utils import timezone
 
@@ -33,6 +45,8 @@ class Trace(models.Model):
     request_id = models.CharField(max_length=255, default="", required=False)
     session_id = models.CharField(max_length=255, default="", required=False)
     user_id = models.CharField(max_length=255, default="", required=False)
+    app_name = models.CharField(max_length=255, default="", required=False)
+    app_version = models.CharField(max_length=255, default="", required=False)
 
     # Shareable URL fields
     share_id = models.CharField(max_length=32, default="", required=False)
@@ -78,31 +92,22 @@ class Trace(models.Model):
         return (self.end_time - self.start_time).total_seconds() * 1000
 
     def get_trace_summary(self, spans):
-        """Get a concise summary string for toolbar display.
-
-        Args:
-            spans: Optional list of span objects. If not provided, will query from database.
-        """
-
-        # Count database queries and track duplicates
-        query_counts = {}
-        db_queries = 0
-
+        # Count database queries with query text and track duplicates
+        query_texts = []
         for span in spans:
-            if span.attributes.get(db_attributes.DB_SYSTEM_NAME):
-                db_queries += 1
-                if query_text := span.attributes.get(db_attributes.DB_QUERY_TEXT):
-                    query_counts[query_text] = query_counts.get(query_text, 0) + 1
+            if query_text := span.attributes.get(db_attributes.DB_QUERY_TEXT):
+                query_texts.append(query_text)
 
-        # Count duplicate queries (queries that appear more than once)
-        duplicate_count = sum(count - 1 for count in query_counts.values() if count > 1)
+        query_counts = Counter(query_texts)
+        query_total = len(query_texts)
+        duplicate_count = sum(query_counts.values()) - len(query_counts)
 
         # Build summary: "n spans, n queries (n duplicates), Xms"
         parts = []
 
         # Queries count with duplicates
-        if db_queries > 0:
-            query_part = f"{db_queries} quer{'y' if db_queries == 1 else 'ies'}"
+        if query_total > 0:
+            query_part = f"{query_total} quer{'y' if query_total == 1 else 'ies'}"
             if duplicate_count > 0:
                 query_part += f" ({duplicate_count} duplicate{'' if duplicate_count == 1 else 's'})"
             parts.append(query_part)
@@ -127,6 +132,8 @@ class Trace(models.Model):
         request_id = ""
         user_id = ""
         session_id = ""
+        app_name = ""
+        app_version = ""
 
         for span in spans:
             if not span.parent:
@@ -146,6 +153,15 @@ class Trace(models.Model):
             user_id = user_id or span_attrs.get(user_attributes.USER_ID, "")
             session_id = session_id or span_attrs.get(session_attributes.SESSION_ID, "")
 
+            # Access Resource attributes if not found in span attributes
+            if resource := getattr(span, "resource", None):
+                app_name = app_name or resource.attributes.get(
+                    service_attributes.SERVICE_NAME, ""
+                )
+                app_version = app_version or resource.attributes.get(
+                    service_attributes.SERVICE_VERSION, ""
+                )
+
         # Convert timestamps
         start_time = (
             datetime.fromtimestamp(earliest_start / 1_000_000_000, tz=UTC)
@@ -166,11 +182,22 @@ class Trace(models.Model):
             request_id=request_id,
             user_id=user_id,
             session_id=session_id,
+            app_name=app_name or getattr(settings, "APP_NAME", ""),
+            app_version=app_version or getattr(settings, "APP_VERSION", ""),
             root_span_name=root_span.name if root_span else "",
         )
 
     def as_dict(self):
         spans = [span.span_data for span in self.spans.all().order_by("start_time")]
+        logs = [
+            {
+                "timestamp": log.timestamp.isoformat(),
+                "level": log.level,
+                "message": log.message,
+                "span_id": log.span_id,
+            }
+            for log in self.logs.all().order_by("timestamp")
+        ]
 
         return {
             "trace_id": self.trace_id,
@@ -182,9 +209,51 @@ class Trace(models.Model):
             "request_id": self.request_id,
             "user_id": self.user_id,
             "session_id": self.session_id,
+            "app_name": self.app_name,
+            "app_version": self.app_version,
             "spans": spans,
+            "logs": logs,
         }
 
+    def get_timeline_events(self):
+        """Get chronological list of spans and logs for unified timeline display."""
+        events = []
+
+        for span in self.spans.all().annotate_spans():
+            events.append(
+                {
+                    "type": "span",
+                    "timestamp": span.start_time,
+                    "instance": span,
+                    "span_level": span.level,
+                }
+            )
+
+            # Add logs for this span
+            for log in self.logs.filter(span=span):
+                events.append(
+                    {
+                        "type": "log",
+                        "timestamp": log.timestamp,
+                        "instance": log,
+                        "span_level": span.level + 1,
+                    }
+                )
+
+        # Add unlinked logs (logs without span)
+        for log in self.logs.filter(span__isnull=True):
+            events.append(
+                {
+                    "type": "log",
+                    "timestamp": log.timestamp,
+                    "instance": log,
+                    "span_level": 0,
+                }
+            )
+
+        # Sort by timestamp
+        return sorted(events, key=lambda x: x["timestamp"])
+
 
 class SpanQuerySet(models.QuerySet):
     def annotate_spans(self):
@@ -339,6 +408,29 @@ class Span(models.Model):
 
         return query_params
 
+    @cached_property
+    def source_code_location(self):
+        """Get the source code location attributes from this span."""
+        if not self.attributes:
+            return None
+
+        # Look for common semantic convention code attributes
+        code_attrs = {}
+        code_attribute_mappings = {
+            CODE_FILE_PATH: "File",
+            CODE_LINE_NUMBER: "Line",
+            CODE_FUNCTION_NAME: "Function",
+            CODE_NAMESPACE: "Namespace",
+            CODE_COLUMN_NUMBER: "Column",
+            CODE_STACKTRACE: "Stacktrace",
+        }
+
+        for attr_key, display_name in code_attribute_mappings.items():
+            if attr_key in self.attributes:
+                code_attrs[display_name] = self.attributes[attr_key]
+
+        return code_attrs if code_attrs else None
+
     def get_formatted_sql(self):
         """Get the pretty-formatted SQL query if this span contains one."""
         sql = self.sql_query
@@ -383,3 +475,39 @@ class Span(models.Model):
                     exception_attributes.EXCEPTION_STACKTRACE
                 )
         return None
+
+
+@models.register_model
+class Log(models.Model):
+    trace = models.ForeignKey(Trace, on_delete=models.CASCADE, related_name="logs")
+    span = models.ForeignKey(
+        Span,
+        on_delete=models.SET_NULL,
+        allow_null=True,
+        required=False,
+        related_name="logs",
+    )
+
+    timestamp = models.DateTimeField()
+    level = models.CharField(max_length=20)
+    message = models.TextField()
+
+    class Meta:
+        ordering = ["timestamp"]
+        indexes = [
+            models.Index(fields=["trace", "timestamp"]),
+            models.Index(fields=["trace", "span"]),
+            models.Index(fields=["timestamp"]),
+            models.Index(fields=["trace"]),
+        ]
+
+    @classmethod
+    def from_log_record(cls, *, record, trace, span):
+        """Create a Log instance from a Python log record."""
+        return cls(
+            trace=trace,
+            timestamp=datetime.fromtimestamp(record.created, tz=UTC),
+            level=record.levelname,
+            message=record.getMessage(),
+            span=span,
+        )

plain/observer/otel.py

@@ -10,6 +10,7 @@ from opentelemetry.semconv.attributes import url_attributes
 from opentelemetry.trace import SpanKind, format_span_id, 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
 
@@ -218,15 +219,12 @@ class ObserverSpanProcessor(SpanProcessor):
                 trace_info = self._traces[trace_id]
                 trace_info["mode"] = mode
 
-                # Clean up old traces if too many
-                if len(self._traces) > 1000:
-                    # Remove oldest 100 traces
-                    oldest_ids = sorted(self._traces.keys())[:100]
-                    for old_id in oldest_ids:
-                        del self._traces[old_id]
-
             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:
+                app_logger.debug_mode.start()
+
             # Store span (we know mode is truthy if we get here)
             trace_info["active_otel_spans"][span_id] = span
 
@@ -246,6 +244,10 @@ class ObserverSpanProcessor(SpanProcessor):
 
             trace_info = self._traces[trace_id]
 
+            # Disable DEBUG logging only for PERSIST mode spans
+            if trace_info["mode"] == ObserverMode.PERSIST.value:
+                app_logger.debug_mode.end()
+
             # Move span from active to completed
             if trace_info["active_otel_spans"].pop(span_id, None):
                 trace_info["completed_otel_spans"].append(span)
@@ -264,16 +266,29 @@ class ObserverSpanProcessor(SpanProcessor):
 
                 # Export if in persist mode
                 if trace_info["mode"] == ObserverMode.PERSIST.value:
+                    # Get and remove logs for this trace
+                    from .logging import observer_log_handler
+
+                    if observer_log_handler:
+                        logs = observer_log_handler.pop_logs_for_trace(trace_id)
+                    else:
+                        logs = []
+
                     logger.debug(
-                        "Exporting %d spans for trace %s",
+                        "Exporting %d spans and %d logs for trace %s",
                         len(trace_info["span_models"]),
+                        len(logs),
                         trace_id,
                     )
                     # The trace is done now, so we can get a more accurate summary
                     trace_info["trace"].summary = trace_info["trace"].get_trace_summary(
                         trace_info["span_models"]
                     )
-                    self._export_trace(trace_info["trace"], trace_info["span_models"])
+                    self._export_trace(
+                        trace=trace_info["trace"],
+                        spans=trace_info["span_models"],
+                        logs=logs,
+                    )
 
                 # Clean up trace
                 del self._traces[trace_id]
@@ -315,19 +330,38 @@ class ObserverSpanProcessor(SpanProcessor):
 
             return trace_info["trace"].get_trace_summary(span_models)
 
-    def _export_trace(self, trace, span_models):
-        """Export trace and spans to the database."""
-        from .models import Span, Trace
+    def _export_trace(self, *, trace, spans, logs):
+        """Export trace, spans, and logs to the database."""
+        from .models import Log, Span, Trace
 
         with suppress_db_tracing():
             try:
                 trace.save()
 
-                for span_model in span_models:
-                    span_model.trace = trace
+                for span in spans:
+                    span.trace = trace
 
                 # Bulk create spans
-                Span.objects.bulk_create(span_models)
+                Span.objects.bulk_create(spans)
+
+                # Create log models if we have logs
+                if logs:
+                    # Create a mapping of span_id to span_model
+                    span_id_to_model = {
+                        span_model.span_id: span_model for span_model in spans
+                    }
+
+                    log_models = []
+                    for log_entry in logs:
+                        log_model = Log.from_log_record(
+                            record=log_entry["record"],
+                            trace=trace,
+                            span=span_id_to_model.get(log_entry["span_id"]),
+                        )
+                        log_models.append(log_model)
+
+                    Log.objects.bulk_create(log_models)
+
             except Exception as e:
                 logger.warning(
                     "Failed to export trace to database: %s",
@@ -339,8 +373,11 @@ class ObserverSpanProcessor(SpanProcessor):
             if settings.OBSERVER_TRACE_LIMIT > 0:
                 try:
                     if Trace.objects.count() > settings.OBSERVER_TRACE_LIMIT:
+                        excess_count = (
+                            Trace.objects.count() - settings.OBSERVER_TRACE_LIMIT
+                        )
                         delete_ids = Trace.objects.order_by("start_time")[
-                            : settings.OBSERVER_TRACE_LIMIT
+                            :excess_count
                         ].values_list("id", flat=True)
                         Trace.objects.filter(id__in=delete_ids).delete()
                 except Exception as e: