How ReportPlane works

ReportPlane separates configuration from runtime traffic. You configure resources in the console. Applications then send and query data through dedicated runtime endpoints.

Two planes, one contract#

The management plane contains workspaces, projects, models, clients, credentials, destinations, and analytics definitions. Automation uses the public, token-authenticated https://app.reportplane.com/management/v1 API. The browser console uses a separate private session API.

The runtime plane handles high-frequency traffic:

• ingest.reportplane.com accepts data;
• query.reportplane.com executes published analytics;
• dedicated Syslog listeners accept UDP, TCP, or TLS messages.

These planes share the same configuration. Creating or updating a client in the management plane changes what the runtime is allowed to accept.

The write path#

When an application sends an event, ReportPlane follows this path:

1. Identify the ingest client from its credential or transport context.
2. Apply authentication and CIDR rules.
3. Check that the client may access the requested data model.
4. Validate required fields and declared field types.
5. Add controlled system information where needed.
6. Accept the event into a durable local spool.
7. Batch and deliver accepted records to the configured destination.
8. Record usage and operational statistics.

Delivery is intentionally asynchronous. This keeps short warehouse delays away from the application's request path.

The read path#

When a consumer calls /query, ReportPlane:

1. identifies the query client;
2. verifies that the client may access the requested Analytics API;
3. validates the supplied filters against the published allowlist;
4. converts the saved analytics definition into a warehouse-neutral plan;
5. executes the plan using the selected warehouse adapter;
6. returns normalized columns, rows, and result metadata.

SQL is not accepted as an alternative public query language. This keeps every query inside the published analytics contract.

Warehouse portability#

ReportPlane can translate the same supported analytics shape to BigQuery, ClickHouse, Snowflake, and Elasticsearch/OpenSearch. The saved definition describes intent—dimensions, metrics, filters, buckets, order, and limit—rather than vendor-specific SQL.

Not every data operation is silently approximated. For example, arrays of objects are stored losslessly, but analytics over them is rejected until an explicit cross-warehouse explode model exists.

Configuration freshness#

Runtime authorization and configuration are read from a local in-memory snapshot that refreshes from PostgreSQL. A newly created analytics definition or client can therefore take a short time to appear on every runtime instance.

This is expected eventual visibility, not data loss. Retry a new resource after a short delay before treating it as a permanent error.