v0.152.0
dropseed/plain
Plain
Documentation
Docs plain-connect plain connect CHANGELOG.md

plain-connect changelog

0.7.2 (2026-06-26)

What's changed

  • Added a "Reading your data back" docs section pointing at the separate plain-cloud CLI for reading exported data back (production exceptions, slow endpoints, slow queries, recent deploys). (5f3b10eff8)

Upgrade instructions

  • No changes required.

0.7.1 (2026-06-03)

What's changed

  • Removed the plain.observer coexistence handling now that observer is retired: the "Observer coexistence" docs section and FAQs are gone, and the TracerProvider/LoggerProvider conflict errors no longer reference observer ordering in INSTALLED_PACKAGES. (1bab9f784a)

Upgrade instructions

  • No changes required.

0.7.0 (2026-05-22)

What's changed

  • New toolbar item links the current request to its exported trace in Plain Cloud. When plain.toolbar is installed and CONNECT_EXPORT_TOKEN is set, a "Trace" button appears in the dev toolbar pointing at a short /t/<trace_id> URL that resolves the trace back to its app and redirects to the full waterfall view. Requests dropped by CONNECT_TRACE_SAMPLE_RATE show a muted "Not sampled" badge instead, so it's clear why no link is available. (1fe612bf96, 66d2cdc20e)
  • CONNECT_FORMS_URL is replaced by CONNECT_CLOUD_URL (default https://plainframework.com). The new setting is the single Plain Cloud base URL — used to build both the toolbar's /t/<trace_id> link and the support submission /forms/<endpoint_id> URL. Two settings collapsed into one. (cbd6d7195a)

Upgrade instructions

  • Rename CONNECT_FORMS_URL to CONNECT_CLOUD_URL in app/settings.py (and PLAIN_CONNECT_FORMS_URL → PLAIN_CONNECT_CLOUD_URL if set via env var). The default value changes from https://plainframework.com/forms to https://plainframework.com — the /forms suffix is now appended internally by connect_support_url(). If you were pointing CONNECT_FORMS_URL at a custom endpoint, set CONNECT_CLOUD_URL to the same base (without the /forms suffix).

0.6.1 (2026-05-20)

What's changed

  • Support-form README fix: replaced the non-functional referrerpolicy="strict-origin-when-cross-origin" attribute on the <form> example with <meta name="referrer" content="strict-origin-when-cross-origin">. referrerpolicy is not a valid attribute on <form> — browsers silently ignored it and Plain Cloud kept rejecting submissions with Origin: null. The meta-tag override actually works. (dcd05214ff)

Upgrade instructions

  • If you copied the previous example and your support form was failing with Origin: null, update the page to use the meta-tag pattern from the README.

0.6.0 (2026-05-20)

What's changed

  • New {% connect_support_fields %} template tag and connect_support_url(endpoint_id) global for posting contact forms to a Plain Cloud support endpoint. The tag injects three hidden inputs into your own <form>: an HMAC-signed render token, an encrypted identity token (when plain.auth is installed and the visitor is signed in), and a honeypot field. Any non-reserved field name is captured into the conversation's extras automatically — no extra configuration needed. (f1a692e985)
  • New CONNECT_SECRET_KEY setting consolidates the per-feature identity key into a single shared secret used by both pageviews and the support widget. Get the value from the App settings page on Plain Cloud. (f1a692e985)
  • New CONNECT_FORMS_URL setting (default https://plainframework.com/forms) for the support submission base URL. (f1a692e985)
  • New preflight check connect.secret_key warns when CONNECT_PAGEVIEWS_TOKEN is set without CONNECT_SECRET_KEY — pageviews still work, but signed-in user attribution silently won't. (f1a692e985)
  • The anonymous-visitor id is now stored under plain_anonymous_id in localStorage so future plain.connect widgets can stitch submissions from the same browser together. (f1a692e985)

Upgrade instructions

  • Rename CONNECT_PAGEVIEWS_IDENTITY_KEY to CONNECT_SECRET_KEY (env var: PLAIN_CONNECT_PAGEVIEWS_IDENTITY_KEY → PLAIN_CONNECT_SECRET_KEY). Same value, single setting now shared across connect features.
  • Returning anonymous visitors will get a fresh id on their next page load — the localStorage key changed from plain_pageviews_anonymous_id to plain_anonymous_id, and the migration was removed before release. Expect a one-time discontinuity in returning-visitor counts.

0.5.0 (2026-05-19)

What's changed

  • Pageview beacons now carry the matched URL route pattern (e.g. /blog/<slug>/) on the server-rendered initial load, mirroring the http.route span attribute. This lets pageviews aggregate by view instead of by raw URL. SPA navigations send a blank route. (93f12bc8c6)
  • Docs now note that a strict Content-Security-Policy must allow the pageview ingest host in connect-src — beacons are sent with navigator.sendBeacon, and the browser blocks them otherwise. (2cab277d3e)

Upgrade instructions

  • No changes required.

0.4.0 (2026-05-18)

What's changed

  • New {% connect_pageviews %} template tag for first-party pageview tracking, independent of the OTLP export. Drop it into your base template before </body> and set CONNECT_PAGEVIEWS_TOKEN to enable it — it reports the URL, title, referrer, and an anonymous id on each page load and SPA navigation (pushState / back-forward). The tag renders nothing until the token is set. (ab468e6bf9)
  • Optional signed-in user attribution: set CONNECT_PAGEVIEWS_IDENTITY_KEY and the tag encrypts the authenticated user's id (AES-256-GCM) into an opaque token, so the raw id never appears in page HTML. The user is read from plain.auth when installed; apps without it still get anonymous pageviews. (ab468e6bf9)
  • New CONNECT_PAGEVIEWS_TOKEN, CONNECT_PAGEVIEWS_IDENTITY_KEY, and CONNECT_PAGEVIEWS_URL settings. (ab468e6bf9)

Upgrade instructions

  • No changes required. Pageview tracking is opt-in — it stays off until you add the {% connect_pageviews %} tag and set CONNECT_PAGEVIEWS_TOKEN.

0.3.5 (2026-05-08)

What's changed

  • New agent rule (plain-connect.md) that points AI agents at the separate plain-cloud CLI for reading telemetry data back (production exceptions, slow endpoints, slow queries, recent deploys). Discovery-first guidance: use plain-cloud openapi | jq '.paths | keys' instead of hardcoding paths. (c3d58e7a17)

Upgrade instructions

  • Run plain agents install to pick up the new rule.

0.3.4 (2026-05-07)

What's changed

  • Renamed plain-cloud to plain-connect. The package, module path, and config label all change: plain.cloud → plain.connect, and the package label plaincloud → plainconnect. All settings move from the CLOUD_* prefix to CONNECT_* (e.g. CLOUD_EXPORT_TOKEN → CONNECT_EXPORT_TOKEN, PLAIN_CLOUD_EXPORT_TOKEN → PLAIN_CONNECT_EXPORT_TOKEN). The destination service is still Plain Cloud — plain-connect is the app integration package that ships telemetry to it. (304fc185cc)

Upgrade instructions

  • Replace plain-cloud with plain-connect in your dependencies (e.g. pyproject.toml).
  • In app/settings.py, replace "plain.cloud" with "plain.connect" in INSTALLED_PACKAGES.
  • Rename any CLOUD_* settings to CONNECT_*, and any PLAIN_CLOUD_* env vars to PLAIN_CONNECT_*.

0.3.3 (2026-05-05)

What's changed

  • Exposes __version__ from importlib.metadata on plain.cloud for version probes that don't want to scrape pip metadata. (c6cf6edb)

Upgrade instructions

  • No changes required.

0.3.2 (2026-04-30)

What's changed

  • Suppressed Sentry capture for OTLP exporter batch failures. The OpenTelemetry SDK's exporters log "Failed to export X batch" at ERROR after retries are exhausted, which Sentry's LoggingIntegration would otherwise turn into an issue per app per incident — noise the app owner can't act on (network/edge timeouts, ingest backend hiccups). The records still flow to console/file/etc.; only the Sentry capture is suppressed. Mirrors the Sentry SDK's own self-protection for sentry_sdk.errors and urllib3.connectionpool. (eb771d82d2de)

Upgrade instructions

  • No changes required.

0.3.1 (2026-04-28)

What's changed

  • The OTLP span, metric, and log exporters now use gzip compression and a 30-second timeout, reducing egress bandwidth and giving slow ingest endpoints more headroom before requests are dropped. (891864bcf710)

Upgrade instructions

  • No changes required.

0.3.0 (2026-04-27)

What's changed

  • Added OTLP log export. Records from the plain and app loggers, plus anything propagating to the root logger, are bridged into OTLP log records and exported alongside traces and metrics, with trace_id / span_id populated from the active span. Two new settings: CLOUD_EXPORT_LOGS (default True) and CLOUD_LOG_LEVEL (default "INFO", accepts a level name or int). The root logger's effective level is widened upward to CLOUD_LOG_LEVEL when narrower so libraries using getLogger(__name__) reach the exporter; it is never narrowed. To prevent feedback loops under transport failure, the exporter ignores records from the opentelemetry namespace and from any OTel SDK exporter thread (OtelBatchSpanRecordProcessor, OtelBatchLogRecordProcessor, OtelPeriodicExportingMetricReader). Application urllib3 logs are exported normally. (3937adee2153)
  • Added a LoggerProvider collision check that mirrors the existing TracerProvider check, so plain.cloud will fail loudly with the "list before plain.observer" message if another package has already installed a logger provider. (3937adee2153)

Upgrade instructions

  • No changes required. To opt out of log export, set CLOUD_EXPORT_LOGS=False (or PLAIN_CLOUD_EXPORT_LOGS=false). To raise/lower the severity floor, set CLOUD_LOG_LEVEL (e.g. "WARNING").

0.2.0 (2026-04-27)

What's changed

  • Changed the default CLOUD_EXPORT_URL to https://ingest.plainframework.com (was https://plainframework.com/otel). Projects relying on the default will now export to the dedicated ingest subdomain. (e58c02eaab9e)

Upgrade instructions

  • If you were depending on the previous default, set PLAIN_CLOUD_EXPORT_URL=https://plainframework.com/otel (or assign CLOUD_EXPORT_URL in app/settings.py) to keep the old endpoint. Otherwise no changes required.

0.1.5 (2026-04-13)

What's changed

  • Removed redundant atexit shutdown registrations that duplicated the shutdown hooks already registered elsewhere. (dfb2ce53cd5c)

Upgrade instructions

  • No changes required.

0.1.4 (2026-04-02)

What's changed

  • Switched metrics export to delta temporality for Counter, Histogram, and UpDownCounter. Each export now contains only the increment since the last collection, making server-side aggregation in ClickHouse straightforward. (ab431cb5ffe6)

Upgrade instructions

  • No changes required.

0.1.3 (2026-04-01)

What's changed

  • Added CLOUD_EXPORT_ENABLED setting (defaults to True) to allow disabling all OTEL reporting without removing the token. Set PLAIN_CLOUD_EXPORT_ENABLED=false to turn it off. (e9c4d140b227)
  • Raises RuntimeError if another tracer provider is already configured when plain.cloud initializes — ensures plain.cloud is listed before plain.observer in INSTALLED_PACKAGES. (40252d96ce7d)

Upgrade instructions

  • No changes required.

0.1.2 (2026-04-01)

What's changed

  • CLOUD_EXPORT_URL now defaults to https://plainframework.com/otel — no need to set it manually. Export is gated on CLOUD_EXPORT_TOKEN instead, so only one env var is needed to start pushing telemetry. (fa711758acda)

Upgrade instructions

  • If you had PLAIN_CLOUD_EXPORT_URL set to https://plainframework.com/otel, you can remove it — that's now the default.
  • If you relied on leaving CLOUD_EXPORT_URL empty to disable export, set CLOUD_EXPORT_TOKEN to empty instead (or just don't set it).

0.1.1 (2026-04-01)

What's changed

  • Updated export endpoint URLs in docs and default settings from plaincloud.com to plainframework.com/otel. (15bb896cdbe6)

Upgrade instructions

  • If you have PLAIN_CLOUD_EXPORT_URL set to https://ingest.plaincloud.com, update it to https://plainframework.com/otel.

0.1.0 (2026-04-01)

What's changed

  • Initial release. Sets up OpenTelemetry TracerProvider and MeterProvider with OTLP HTTP exporters, pushing traces and metrics to Plain Cloud. Configure with CLOUD_EXPORT_URL and CLOUD_EXPORT_TOKEN settings. Includes head-based trace sampling via CLOUD_TRACE_SAMPLE_RATE. Inactive when CLOUD_EXPORT_URL is not set. Coexists with plain-observer — observer layers its sampler and span processor on top. (e3971506cb)