plain.observer

Request tracing and debugging tools built on OpenTelemetry.

• Overview
• Observer modes
  • Summary mode
  • Persist mode
  • Disabled mode
• Toolbar integration
• CLI commands
• Admin integration
• Settings
• FAQs
• Installation

Overview

You can use Observer to trace requests and debug performance issues in your Plain application. Observer integrates with OpenTelemetry to capture spans, database queries, and logs for individual requests.

When enabled, Observer shows you a real-time summary of each request including query counts, duplicate queries, and total duration. You can also persist traces to the database for later analysis.

# Access the Observer from any request
from plain.observer import Observer

observer = Observer.from_request(request)

# Check the current mode
if observer.is_enabled():
    print("Observer is tracking this request")

if observer.is_persisting():
    print("Traces will be saved to the database")

# Get a summary of the current trace
summary = observer.get_current_trace_summary()
# Returns something like: "5 queries (2 duplicates) • 45.2ms"

The Observer class provides methods to check the current mode and enable/disable tracing via cookies.

Observer modes

Observer has three modes that control how traces are captured.

Summary mode

Summary mode captures spans in memory for real-time monitoring but does not save them to the database. This is useful for debugging during development without filling up your database.

from plain.observer import Observer

def my_view(request):
    observer = Observer.from_request(request)
    response = Response("OK")
    observer.enable_summary_mode(response)
    return response

The summary cookie lasts for 1 week.

Persist mode

Persist mode captures spans and saves them to the database. This includes full trace data, spans, and log entries. Use this when you need to analyze traces after the request completes.

observer.enable_persist_mode(response)

The persist cookie lasts for 1 day.

Disabled mode

You can explicitly disable Observer to prevent any tracing, even if a parent trace exists.

observer.disable(response)

Toolbar integration

If you have plain.toolbar installed, Observer automatically adds a panel showing the current mode and trace summary. You can toggle between modes directly from the toolbar.

The toolbar panel displays:

• Current observer mode (Summary, Persist, or Disabled)
• Query count with duplicate detection
• Total request duration
• Link to view persisted traces

CLI commands

Observer provides CLI commands for managing and viewing traces.

# List recent traces
plain observer traces
plain observer traces --limit 50
plain observer traces --user-id 123
plain observer traces --json

# View a specific trace
plain observer trace <trace_id>
plain observer trace <trace_id> --json

# List spans
plain observer spans
plain observer spans --trace-id <trace_id>

# View a specific span
plain observer span <span_id>

# Clear all trace data
plain observer clear
plain observer clear --force

The traces and spans commands support filtering by user ID, session ID, or request ID, and can output JSON for programmatic use.

Admin integration

When plain.admin is installed, Observer registers viewsets for browsing Traces, Spans, and Logs. You can find these under the "Observer" section in the admin navigation.

The admin views let you:

• Browse and search traces by request ID, user ID, or session ID
• View span hierarchies and timing
• Filter spans by parent status
• Search and filter log entries by level or message

Settings

Observer uses these settings with sensible defaults.

# app/settings.py

# URL patterns to ignore (regex patterns)
OBSERVER_IGNORE_URL_PATTERNS = [
    "/assets/.*",
    "/observer/.*",
    "/pageviews/.*",
    "/favicon.ico",
    "/.well-known/.*",
]

# Maximum number of traces to keep in the database (oldest are deleted)
OBSERVER_TRACE_LIMIT = 100

FAQs

How do I enable Observer in production?

Observer is controlled by a signed cookie, so you can enable it for specific users or sessions. The toolbar provides an easy way to toggle modes, or you can set the cookie programmatically in a view.

Can I use Observer with an external OpenTelemetry collector?

Yes. Observer uses the ObserverSampler and ObserverSpanProcessor which integrate with OpenTelemetry's standard APIs. You can combine Observer with other samplers using ObserverCombinedSampler.

Why are some URLs not being traced?

Observer ignores certain URL patterns by default (assets, observer routes, etc.) to reduce noise. You can customize this with the OBSERVER_IGNORE_URL_PATTERNS setting.

How do I get the trace summary in a template?

In persist or summary mode, you can access the summary from the Observer instance:

# In your view
context["trace_summary"] = Observer.from_request(request).get_current_trace_summary()

What data is stored when persisting traces?

The Trace model stores trace ID, timing, request ID, user ID, and session ID. Each trace has related Span records with full OpenTelemetry span data (including SQL queries and attributes) and Log entries captured during the request.

Installation

Install the plain.observer package from PyPI:

uv add plain.observer

Add plain.observer to your INSTALLED_PACKAGES:

# app/settings.py
INSTALLED_PACKAGES = [
    # ...
    "plain.observer",
]

Include the observer URLs in your URL configuration:

# app/urls.py
from plain.observer.urls import ObserverRouter
from plain.urls import Router, include

class AppRouter(Router):
    namespace = ""
    urls = [
        # ...
        include("observer/", ObserverRouter),
    ]

Run migrations to create the necessary database tables:

plain migrate

After installation, Observer will automatically integrate with your application's toolbar (if using plain.toolbar). You can access the web interface at /observer/traces/ or use the CLI commands to analyze traces.

Content Security Policy (CSP)

If you're using a Content Security Policy (CSP), the Observer toolbar panel requires frame-ancestors 'self' to display trace information in an iframe.

Without this directive, the toolbar panel will fail to load with a CSP error: "Refused to frame... because an ancestor violates the following Content Security Policy directive: 'frame-ancestors 'none'".

Example CSP configuration:

DEFAULT_RESPONSE_HEADERS = {
    "Content-Security-Policy": (
        "default-src 'self'; "
        "script-src 'self' 'nonce-{request.csp_nonce}'; "
        "style-src 'self' 'nonce-{request.csp_nonce}'; "
        "frame-ancestors 'self'; "  # Required for Observer toolbar
        # ... other directives
    ),
}