reo-census 0.1.0

Custom telemetry client for Reo (POST JSON to telemetry.reo.dev)

reo-census (Python)

Send custom telemetry events to Reo’s ingestion API. Defaults to https://telemetry.reo.dev/data (same as the npm reo-census tracker).

Install

pip install reo-census

Usage

from reo_census import ReoEventLogger

logger = ReoEventLogger(
    endpoint_url="https://telemetry.reo.dev/data",
    timeout=3.0,
)
# Default: non-blocking — HTTP runs in a background thread; returns True if queued.
ok = logger.log_event({"event": "my_event", "package": "demo", "version": "1.0.0"})

# Wait for the HTTP round-trip (tests, debugging, or short-lived scripts):
ok = logger.log_event({"event": "my_event"}, blocking=True)

Event property values are sent as strings.

• blocking=False (default): returns True if the event was queued, False if opted out, URL rejected, or payload too large. Does not reflect HTTP success.
• blocking=True: returns True only after a successful HTTP 2xx (with retries), False on failure or opt-out.

Short-lived programs (one-shot CLI) should use blocking=True or the process may exit before the daemon thread finishes sending.

Opt-out

Respected when any of these apply:

• PACKAGE_TRACKER_ANALYTICS=false
• DO_NOT_TRACK is 1, true, or yes (case-insensitive)

Endpoint override

Set PACKAGE_TRACKER_ENDPOINT to override the URL (same as the Node tracker). Only http:// and https:// URLs with a host are accepted.

Verbose logging

Set PACKAGE_TRACKER_VERBOSE=true to print send details to stderr.

Security notes

• TLS: Use https:// endpoints in production. The default is HTTPS to telemetry.reo.dev.
• Endpoint control: endpoint_url and PACKAGE_TRACKER_ENDPOINT should only be set by operators or trusted config. Arbitrary schemes (file:, etc.) are rejected.
• Payload size: JSON bodies larger than 256 KiB are not sent (guardrail against accidental huge posts).
• Secrets: Do not put API keys or tokens in log_event properties; verbose mode logs the body to stderr when enabled.