plain.cloud 0.1.0__py3-none-any.whl

plain/cloud/CHANGELOG.md

@@ -0,0 +1,7 @@
+# plain-cloud changelog
+
+## [0.1.0](https://github.com/dropseed/plain/releases/plain-cloud@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/cloud/README.md

@@ -0,0 +1,80 @@
+# plain.cloud
+
+**Production observability via OTLP export to Plain Cloud.**
+
+- [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.cloud to export traces and metrics from your Plain app to Plain Cloud. The framework already instruments itself with OpenTelemetry spans and histograms — plain.cloud activates them by providing the OTLP exporters.
+
+Set two environment variables and your app starts pushing telemetry:
+
+```
+PLAIN_CLOUD_EXPORT_URL=https://ingest.plaincloud.com
+PLAIN_CLOUD_EXPORT_TOKEN=your-token
+```
+
+If `CLOUD_EXPORT_URL` is not set, the package is a no-op — safe to install without configuration.
+
+## Settings
+
+| Setting                   | Default | Description                                                 |
+| ------------------------- | ------- | ----------------------------------------------------------- |
+| `CLOUD_EXPORT_URL`        | `""`    | OTLP ingest endpoint (e.g. `https://ingest.plaincloud.com`) |
+| `CLOUD_EXPORT_TOKEN`      | `""`    | Auth token for the export endpoint                          |
+| `CLOUD_TRACE_SAMPLE_RATE` | `1.0`   | Probability of exporting a trace (0.0–1.0)                  |
+
+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
+CLOUD_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.
+
+## Observer coexistence
+
+If [plain.observer](../../plain-observer/plain/observer/README.md) is also installed, both work simultaneously. plain.cloud 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.cloud?
+
+No. plain.cloud works independently. Observer is for local dev tooling; plain.cloud 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.cloud",
+    # ...
+]
+```
+
+Place `plain.cloud` **before** `plain.observer` in `INSTALLED_PACKAGES` so it sets up the TracerProvider first.

plain/cloud/config.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import atexit
+
+from opentelemetry import metrics, trace
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.metrics.export import 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
+
+
+@register_config
+class Config(PackageConfig):
+    package_label = "plaincloud"
+
+    def ready(self) -> None:
+        if not settings.CLOUD_EXPORT_URL:
+            return
+
+        resource = Resource.create(
+            {
+                service_attributes.SERVICE_NAME: settings.NAME,
+                service_attributes.SERVICE_VERSION: settings.VERSION,
+            }
+        )
+
+        export_url = str(settings.CLOUD_EXPORT_URL).rstrip("/")
+        headers = {"Authorization": f"Bearer {settings.CLOUD_EXPORT_TOKEN}"}
+
+        # Traces
+        span_exporter = OTLPSpanExporter(
+            endpoint=f"{export_url}/v1/traces",
+            headers=headers,
+        )
+        sampler = sampling.TraceIdRatioBased(settings.CLOUD_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
+        metric_exporter = OTLPMetricExporter(
+            endpoint=f"{export_url}/v1/metrics",
+            headers=headers,
+        )
+        reader = PeriodicExportingMetricReader(metric_exporter)
+        meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
+        metrics.set_meter_provider(meter_provider)
+
+        atexit.register(tracer_provider.shutdown)
+        atexit.register(meter_provider.shutdown)

plain/cloud/default_settings.py

@@ -0,0 +1,5 @@
+from plain.runtime import Secret
+
+CLOUD_EXPORT_URL: str = ""  # e.g. "https://ingest.plaincloud.com"
+CLOUD_EXPORT_TOKEN: Secret[str] = ""  # Auth token for the export endpoint
+CLOUD_TRACE_SAMPLE_RATE: float = 1.0  # 0.0–1.0, probability of exporting a trace

plain_cloud-0.1.0.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: plain.cloud
+Version: 0.1.0
+Summary: Production observability via OTLP export to Plain Cloud.
+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.cloud
+
+**Production observability via OTLP export to Plain Cloud.**
+
+- [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.cloud to export traces and metrics from your Plain app to Plain Cloud. The framework already instruments itself with OpenTelemetry spans and histograms — plain.cloud activates them by providing the OTLP exporters.
+
+Set two environment variables and your app starts pushing telemetry:
+
+```
+PLAIN_CLOUD_EXPORT_URL=https://ingest.plaincloud.com
+PLAIN_CLOUD_EXPORT_TOKEN=your-token
+```
+
+If `CLOUD_EXPORT_URL` is not set, the package is a no-op — safe to install without configuration.
+
+## Settings
+
+| Setting                   | Default | Description                                                 |
+| ------------------------- | ------- | ----------------------------------------------------------- |
+| `CLOUD_EXPORT_URL`        | `""`    | OTLP ingest endpoint (e.g. `https://ingest.plaincloud.com`) |
+| `CLOUD_EXPORT_TOKEN`      | `""`    | Auth token for the export endpoint                          |
+| `CLOUD_TRACE_SAMPLE_RATE` | `1.0`   | Probability of exporting a trace (0.0–1.0)                  |
+
+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
+CLOUD_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.
+
+## Observer coexistence
+
+If [plain.observer](../../plain-observer/plain/observer/README.md) is also installed, both work simultaneously. plain.cloud 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.cloud?
+
+No. plain.cloud works independently. Observer is for local dev tooling; plain.cloud 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.cloud",
+    # ...
+]
+```
+
+Place `plain.cloud` **before** `plain.observer` in `INSTALLED_PACKAGES` so it sets up the TracerProvider first.

plain_cloud-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+plain/cloud/CHANGELOG.md,sha256=KlweN6yIHqtFlAg7IpXjl-g1uUoza9EiYuvaSN-eOvM,615
+plain/cloud/README.md,sha256=_4ZZxysW5qoxKo9Bxvte7Q3u4u296E3cl44DFMq_-ZE,3086
+plain/cloud/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+plain/cloud/config.py,sha256=Cw0Q8toyHem9myPgBLcuYuZsFJdk-CSdrrrk5pD0K1s,2124
+plain/cloud/default_settings.py,sha256=3cAKENWSZZVuc3T33HAbntrgch-0_w6UreI4keDwnGI,260
+plain_cloud-0.1.0.dist-info/METADATA,sha256=9pVfz2fKxHqezJNcpdVa6f-FnOgEzn9XzNW-F6JiGxI,3524
+plain_cloud-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+plain_cloud-0.1.0.dist-info/licenses/LICENSE,sha256=mgqZwn7Asoev1K7qXKiLuQ6jHBTT8yWRwbbED407z_w,1500
+plain_cloud-0.1.0.dist-info/RECORD,,

plain_cloud-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

plain_cloud-0.1.0.dist-info/licenses/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.