plain.connect 0.3.4__tar.gz

plain_connect-0.3.4/.gitignore

@@ -0,0 +1,26 @@
+.venv
+/.env
+*.egg-info
+*.py[co]
+__pycache__
+*.DS_Store
+*.swp
+*.swo
+
+/*.code-workspace
+
+# Test apps
+plain*/tests/.plain
+
+# Agent scratch files
+/scratch
+
+# Plain temp dirs
+.plain
+
+.vscode
+/.claude/settings.local.json
+/.claude/skills/announcements/
+/CLAUDE.local.md
+/.benchmarks
+.claude/worktrees

plain_connect-0.3.4/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Dropseed, LLC
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

plain_connect-0.3.4/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: plain.connect
+Version: 0.3.4
+Summary: Connect your Plain app to Plain Cloud via OTLP export.
+Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.34.1
+Requires-Dist: opentelemetry-sdk>=1.34.1
+Requires-Dist: plain<1.0.0,>=0.113.0
+Description-Content-Type: text/markdown
+
+# plain.connect
+
+**Connect your Plain app to Plain Cloud via OTLP export.**
+
+- [Overview](#overview)
+- [Settings](#settings)
+- [Sampling](#sampling)
+- [What gets exported](#what-gets-exported)
+- [Observer coexistence](#observer-coexistence)
+- [FAQs](#faqs)
+- [Installation](#installation)
+
+## Overview
+
+You can use plain.connect to export traces, metrics, and logs from your Plain app to Plain Cloud. The framework already instruments itself with OpenTelemetry spans and histograms — plain.connect activates them by providing the OTLP exporters and bridges Python's `logging` module into OTLP log records.
+
+Set one environment variable and your app starts pushing telemetry:
+
+```
+PLAIN_CONNECT_EXPORT_TOKEN=your-token
+```
+
+If `CONNECT_EXPORT_TOKEN` is not set, the package is a no-op — safe to install without configuration.
+
+## Settings
+
+| Setting                     | Default                               | Description                                                 |
+| --------------------------- | ------------------------------------- | ----------------------------------------------------------- |
+| `CONNECT_EXPORT_URL`        | `"https://ingest.plainframework.com"` | OTLP ingest endpoint (override to use a custom endpoint)    |
+| `CONNECT_EXPORT_TOKEN`      | `""`                                  | Auth token for the export endpoint                          |
+| `CONNECT_TRACE_SAMPLE_RATE` | `1.0`                                 | Probability of exporting a trace (0.0–1.0)                  |
+| `CONNECT_EXPORT_LOGS`       | `True`                                | Set to `False` to disable OTLP log export                   |
+| `CONNECT_LOG_LEVEL`         | `"INFO"`                              | Minimum severity exported via OTLP logs (level name or int) |
+
+All settings can be set via `PLAIN_`-prefixed environment variables or in `app/settings.py`.
+
+## Sampling
+
+By default, all traces are exported. To reduce volume, set a sample rate:
+
+```python
+CONNECT_TRACE_SAMPLE_RATE = 0.1  # Export 10% of traces
+```
+
+Metrics are not affected by sampling — histograms aggregate in-process and export periodically regardless of the trace sample rate.
+
+## What gets exported
+
+**Traces** — HTTP request spans and database query spans instrumented by the framework.
+
+**Metrics** — OTel histograms like `db.client.query.duration`, aggregated and pushed every 60 seconds.
+
+**Logs** — Records from the `plain` and `app` loggers, plus anything propagating to the root logger, are bridged into OTLP log records and exported with `trace_id` / `span_id` set from the active span. The minimum severity is controlled by `CONNECT_LOG_LEVEL` (default `INFO`); the root logger's level is widened to that floor when needed so libraries using `getLogger(__name__)` reach the exporter. To prevent feedback loops, two sources are skipped on the export path: the `opentelemetry` namespace, and any record emitted from inside the OTLP exporter's background thread (e.g. urllib3 connection errors raised by the exporter's own HTTP call). Your application's urllib3 logs are exported normally.
+
+## Observer coexistence
+
+If [plain.observer](../../plain-observer/plain/observer/README.md) is also installed, both work simultaneously. plain.connect handles production export while observer provides the local dev toolbar and admin trace viewer. Observer detects the existing TracerProvider and layers its sampler and span processor on top.
+
+## FAQs
+
+#### Do I need plain.observer to use plain.connect?
+
+No. plain.connect works independently. Observer is for local dev tooling; plain.connect is for production export.
+
+#### What happens if the export endpoint is unreachable?
+
+The OTLP exporters batch and retry automatically. If the endpoint is down, telemetry is dropped after retries — it does not block your application.
+
+#### Does this add latency to requests?
+
+No. Trace spans are exported in a background thread via `BatchSpanProcessor`. Metrics are flushed periodically by a background thread. Neither blocks request handling.
+
+## Installation
+
+```python
+# app/settings.py
+INSTALLED_PACKAGES = [
+    "plain.connect",
+    # ...
+]
+```
+
+Place `plain.connect` **before** `plain.observer` in `INSTALLED_PACKAGES` so it sets up the TracerProvider first.

plain_connect-0.3.4/README.md

@@ -0,0 +1 @@
+plain/connect/README.md

plain_connect-0.3.4/plain/connect/CHANGELOG.md

@@ -0,0 +1,122 @@
+# plain-connect changelog
+
+## [0.3.4](https://github.com/dropseed/plain/releases/plain-connect@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](https://github.com/dropseed/plain/commit/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](https://github.com/dropseed/plain/releases/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](https://github.com/dropseed/plain/commit/c6cf6edb))
+
+### Upgrade instructions
+
+- No changes required.
+
+## [0.3.2](https://github.com/dropseed/plain/releases/plain-connect@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](https://github.com/dropseed/plain/commit/eb771d82d2de))
+
+### Upgrade instructions
+
+- No changes required.
+
+## [0.3.1](https://github.com/dropseed/plain/releases/plain-connect@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](https://github.com/dropseed/plain/commit/891864bcf710))
+
+### Upgrade instructions
+
+- No changes required.
+
+## [0.3.0](https://github.com/dropseed/plain/releases/plain-connect@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](https://github.com/dropseed/plain/commit/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](https://github.com/dropseed/plain/commit/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](https://github.com/dropseed/plain/releases/plain-connect@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](https://github.com/dropseed/plain/commit/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](https://github.com/dropseed/plain/releases/plain-connect@0.1.5) (2026-04-13)
+
+### What's changed
+
+- Removed redundant `atexit` shutdown registrations that duplicated the shutdown hooks already registered elsewhere. ([dfb2ce53cd5c](https://github.com/dropseed/plain/commit/dfb2ce53cd5c))
+
+### Upgrade instructions
+
+- No changes required.
+
+## [0.1.4](https://github.com/dropseed/plain/releases/plain-connect@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](https://github.com/dropseed/plain/commit/ab431cb5ffe6))
+
+### Upgrade instructions
+
+- No changes required.
+
+## [0.1.3](https://github.com/dropseed/plain/releases/plain-connect@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](https://github.com/dropseed/plain/commit/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](https://github.com/dropseed/plain/commit/40252d96ce7d))
+
+### Upgrade instructions
+
+- No changes required.
+
+## [0.1.2](https://github.com/dropseed/plain/releases/plain-connect@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](https://github.com/dropseed/plain/commit/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](https://github.com/dropseed/plain/releases/plain-connect@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](https://github.com/dropseed/plain/commit/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](https://github.com/dropseed/plain/releases/plain-connect@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](https://github.com/dropseed/plain/commit/e3971506cb))

plain_connect-0.3.4/plain/connect/README.md

@@ -0,0 +1,83 @@
+# plain.connect
+
+**Connect your Plain app to Plain Cloud via OTLP export.**
+
+- [Overview](#overview)
+- [Settings](#settings)
+- [Sampling](#sampling)
+- [What gets exported](#what-gets-exported)
+- [Observer coexistence](#observer-coexistence)
+- [FAQs](#faqs)
+- [Installation](#installation)
+
+## Overview
+
+You can use plain.connect to export traces, metrics, and logs from your Plain app to Plain Cloud. The framework already instruments itself with OpenTelemetry spans and histograms — plain.connect activates them by providing the OTLP exporters and bridges Python's `logging` module into OTLP log records.
+
+Set one environment variable and your app starts pushing telemetry:
+
+```
+PLAIN_CONNECT_EXPORT_TOKEN=your-token
+```
+
+If `CONNECT_EXPORT_TOKEN` is not set, the package is a no-op — safe to install without configuration.
+
+## Settings
+
+| Setting                     | Default                               | Description                                                 |
+| --------------------------- | ------------------------------------- | ----------------------------------------------------------- |
+| `CONNECT_EXPORT_URL`        | `"https://ingest.plainframework.com"` | OTLP ingest endpoint (override to use a custom endpoint)    |
+| `CONNECT_EXPORT_TOKEN`      | `""`                                  | Auth token for the export endpoint                          |
+| `CONNECT_TRACE_SAMPLE_RATE` | `1.0`                                 | Probability of exporting a trace (0.0–1.0)                  |
+| `CONNECT_EXPORT_LOGS`       | `True`                                | Set to `False` to disable OTLP log export                   |
+| `CONNECT_LOG_LEVEL`         | `"INFO"`                              | Minimum severity exported via OTLP logs (level name or int) |
+
+All settings can be set via `PLAIN_`-prefixed environment variables or in `app/settings.py`.
+
+## Sampling
+
+By default, all traces are exported. To reduce volume, set a sample rate:
+
+```python
+CONNECT_TRACE_SAMPLE_RATE = 0.1  # Export 10% of traces
+```
+
+Metrics are not affected by sampling — histograms aggregate in-process and export periodically regardless of the trace sample rate.
+
+## What gets exported
+
+**Traces** — HTTP request spans and database query spans instrumented by the framework.
+
+**Metrics** — OTel histograms like `db.client.query.duration`, aggregated and pushed every 60 seconds.
+
+**Logs** — Records from the `plain` and `app` loggers, plus anything propagating to the root logger, are bridged into OTLP log records and exported with `trace_id` / `span_id` set from the active span. The minimum severity is controlled by `CONNECT_LOG_LEVEL` (default `INFO`); the root logger's level is widened to that floor when needed so libraries using `getLogger(__name__)` reach the exporter. To prevent feedback loops, two sources are skipped on the export path: the `opentelemetry` namespace, and any record emitted from inside the OTLP exporter's background thread (e.g. urllib3 connection errors raised by the exporter's own HTTP call). Your application's urllib3 logs are exported normally.
+
+## Observer coexistence
+
+If [plain.observer](../../plain-observer/plain/observer/README.md) is also installed, both work simultaneously. plain.connect handles production export while observer provides the local dev toolbar and admin trace viewer. Observer detects the existing TracerProvider and layers its sampler and span processor on top.
+
+## FAQs
+
+#### Do I need plain.observer to use plain.connect?
+
+No. plain.connect works independently. Observer is for local dev tooling; plain.connect is for production export.
+
+#### What happens if the export endpoint is unreachable?
+
+The OTLP exporters batch and retry automatically. If the endpoint is down, telemetry is dropped after retries — it does not block your application.
+
+#### Does this add latency to requests?
+
+No. Trace spans are exported in a background thread via `BatchSpanProcessor`. Metrics are flushed periodically by a background thread. Neither blocks request handling.
+
+## Installation
+
+```python
+# app/settings.py
+INSTALLED_PACKAGES = [
+    "plain.connect",
+    # ...
+]
+```
+
+Place `plain.connect` **before** `plain.observer` in `INSTALLED_PACKAGES` so it sets up the TracerProvider first.

plain_connect-0.3.4/plain/connect/__init__.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+__version__ = version("plain.connect")

plain_connect-0.3.4/plain/connect/config.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import logging
+import threading
+
+from opentelemetry import _logs, metrics, trace
+from opentelemetry._logs._internal import ProxyLoggerProvider
+from opentelemetry.exporter.otlp.proto.http import Compression
+from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.sdk.metrics import Counter, Histogram, MeterProvider, UpDownCounter
+from opentelemetry.sdk.metrics.export import (
+    AggregationTemporality,
+    PeriodicExportingMetricReader,
+)
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider, sampling
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.semconv.attributes import service_attributes
+
+from plain.packages import PackageConfig, register_config
+from plain.runtime import settings
+
+
+class _ExporterLoopFilter(logging.Filter):
+    """Block records that would feed back into OTLP export under failure.
+
+    Two sources to suppress:
+
+    1. The OpenTelemetry SDK's own namespace — its `failed to export`
+       warnings would re-queue indefinitely.
+    2. Anything emitted from inside an OTel SDK exporter thread (e.g.
+       urllib3 connection errors raised by the OTLP HTTP exporter). The
+       SDK names every exporter thread with an `Otel` prefix —
+       `OtelBatch{Span,Log}RecordProcessor` for traces/logs, and
+       `OtelPeriodicExportingMetricReader` for metrics — so matching on
+       that prefix catches all three. Scoping to the thread, not the
+       urllib3 namespace, lets user-code urllib3 logs flow through.
+
+    See `opentelemetry/sdk/_shared_internal/__init__.py` (BatchProcessor)
+    and `opentelemetry/sdk/metrics/export/__init__.py`
+    (PeriodicExportingMetricReader) for the thread names.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        name = record.name
+        if name == "opentelemetry" or name.startswith("opentelemetry."):
+            return False
+        if threading.current_thread().name.startswith("Otel"):
+            return False
+        return True
+
+
+@register_config
+class Config(PackageConfig):
+    package_label = "plainconnect"
+
+    def ready(self) -> None:
+        if not settings.CONNECT_EXPORT_ENABLED or not settings.CONNECT_EXPORT_TOKEN:
+            return
+
+        # Don't capture per-batch OTLP export failures as Sentry events. The OTel
+        # 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 Sentry SDK's own self-protection for `sentry_sdk.errors` and
+        # `urllib3.connectionpool` in sentry_sdk/integrations/logging.py.
+        try:
+            import sentry_sdk.integrations.logging as _sentry_log  # ty: ignore[unresolved-import]
+        except ImportError:
+            pass
+        else:
+            for name in (
+                "opentelemetry.exporter.otlp.proto.http.trace_exporter",
+                "opentelemetry.exporter.otlp.proto.http.metric_exporter",
+                "opentelemetry.exporter.otlp.proto.http._log_exporter",
+                "opentelemetry.sdk._shared_internal",
+                "opentelemetry.sdk._logs._internal.export",
+                "opentelemetry.sdk.metrics._internal.export",
+            ):
+                _sentry_log.ignore_logger(name)
+
+        resource = Resource.create(
+            {
+                service_attributes.SERVICE_NAME: settings.NAME,
+                service_attributes.SERVICE_VERSION: settings.VERSION,
+            }
+        )
+
+        export_url = str(settings.CONNECT_EXPORT_URL).rstrip("/")
+        headers = {"Authorization": f"Bearer {settings.CONNECT_EXPORT_TOKEN}"}
+
+        # Traces
+        current_provider = trace.get_tracer_provider()
+        if current_provider and not isinstance(
+            current_provider, trace.ProxyTracerProvider
+        ):
+            raise RuntimeError(
+                "A tracer provider already exists."
+                " plain.connect must be listed before plain.observer in INSTALLED_PACKAGES."
+            )
+
+        span_exporter = OTLPSpanExporter(
+            endpoint=f"{export_url}/v1/traces",
+            headers=headers,
+            timeout=30,
+            compression=Compression.Gzip,
+        )
+        sampler = sampling.TraceIdRatioBased(settings.CONNECT_TRACE_SAMPLE_RATE)
+        tracer_provider = TracerProvider(sampler=sampler, resource=resource)
+        tracer_provider.add_span_processor(BatchSpanProcessor(span_exporter))
+        trace.set_tracer_provider(tracer_provider)
+
+        # Metrics — use delta temporality so each export contains only the
+        # increment since the last export, not a running total.  This makes
+        # server-side aggregation (sum/avg in ClickHouse) straightforward.
+        metric_exporter = OTLPMetricExporter(
+            endpoint=f"{export_url}/v1/metrics",
+            headers=headers,
+            timeout=30,
+            compression=Compression.Gzip,
+            preferred_temporality={
+                Counter: AggregationTemporality.DELTA,
+                Histogram: AggregationTemporality.DELTA,
+                UpDownCounter: AggregationTemporality.DELTA,
+            },
+        )
+        reader = PeriodicExportingMetricReader(metric_exporter)
+        meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
+        metrics.set_meter_provider(meter_provider)
+
+        # Logs
+        if settings.CONNECT_EXPORT_LOGS:
+            current_logger_provider = _logs.get_logger_provider()
+            if current_logger_provider and not isinstance(
+                current_logger_provider, ProxyLoggerProvider
+            ):
+                raise RuntimeError(
+                    "A logger provider already exists."
+                    " plain.connect must be listed before plain.observer in INSTALLED_PACKAGES."
+                )
+
+            # Accept either a level name ("INFO") or an int (20).
+            raw_level = settings.CONNECT_LOG_LEVEL
+            if isinstance(raw_level, str):
+                log_level = logging.getLevelName(raw_level.upper())
+                if not isinstance(log_level, int):
+                    raise ValueError(
+                        f"CONNECT_LOG_LEVEL={raw_level!r} is not a valid logging level."
+                    )
+            else:
+                log_level = int(raw_level)
+
+            log_exporter = OTLPLogExporter(
+                endpoint=f"{export_url}/v1/logs",
+                headers=headers,
+                timeout=30,
+                compression=Compression.Gzip,
+            )
+            logger_provider = LoggerProvider(resource=resource)
+            logger_provider.add_log_record_processor(
+                BatchLogRecordProcessor(log_exporter)
+            )
+            _logs.set_logger_provider(logger_provider)
+
+            handler = LoggingHandler(level=log_level, logger_provider=logger_provider)
+            # Filter on the handler (not the loggers) so OTLP exporter and
+            # HTTP-client diagnostics still reach the app's console/file
+            # handlers — we only stop them from being re-exported, which
+            # would loop under failure.
+            handler.addFilter(_ExporterLoopFilter())
+
+            # Plain's `configure_logging` sets `plain` and `app` to
+            # propagate=False, so attaching only to root would miss them.
+            # Attach to root for everything else (user `getLogger(__name__)`,
+            # third-party libs).
+            for name in ("", "plain", "app"):
+                logging.getLogger(name).addHandler(handler)
+
+            # Root defaults to WARNING. A library that uses
+            # `logging.getLogger(__name__)` without setting its own level
+            # inherits root's effective level — so INFO/DEBUG records get
+            # dropped before the OTLP handler runs. Widen root just enough
+            # to let CONNECT_LOG_LEVEL through; never narrow it.
+            # NOTSET (0) on root already means "all messages processed",
+            # so leave it alone in that case.
+            root = logging.getLogger()
+            if root.level != logging.NOTSET and root.level > log_level:
+                root.setLevel(log_level)

plain_connect-0.3.4/plain/connect/default_settings.py

@@ -0,0 +1,10 @@
+from plain.runtime import Secret
+
+CONNECT_EXPORT_ENABLED: bool = True  # Set to False to disable all OTEL reporting
+CONNECT_EXPORT_URL: str = "https://ingest.plainframework.com"
+CONNECT_EXPORT_TOKEN: Secret[str] = ""  # Auth token for the export endpoint
+CONNECT_TRACE_SAMPLE_RATE: float = 1.0  # 0.0–1.0, probability of exporting a trace
+CONNECT_EXPORT_LOGS: bool = True  # Set to False to disable OTLP log export
+# Minimum severity exported via OTLP logs. Accepts a level name ("INFO",
+# "DEBUG", ...) or the integer level value.
+CONNECT_LOG_LEVEL: str = "INFO"

plain_connect-0.3.4/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "plain.connect"
+version = "0.3.4"
+description = "Connect your Plain app to Plain Cloud via OTLP export."
+authors = [{ name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev" }]
+license = "BSD-3-Clause"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+  "plain>=0.113.0,<1.0.0",
+  "opentelemetry-sdk>=1.34.1",
+  "opentelemetry-exporter-otlp-proto-http>=1.34.1",
+]
+
+[dependency-groups]
+dev = ["plain.pytest<1.0.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["plain"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"