sdk-garden-python

Lightweight SDK observability client for Python — stdlib only, non-blocking

Add SDK Garden telemetry to your Python SDK in minutes. Events are sent on a background daemon thread — your users never see a delay or an exception from the instrumentation layer.

Install

pip install sdk-garden-python

Quick Start

from sdk_garden import SdkGarden

sg = SdkGarden(api_key="YOUR_API_KEY", sdk_name="my-sdk", sdk_version="1.0.0").start()

@sg.track_method("process_payment")
def process_payment(amount):
    ...

Track arbitrary events:

sg.track("feature_used", properties={"feature": "streaming"})

Track errors with automatic PII scrubbing:

try:
    process_payment(100)
except Exception as e:
    sg.track_error(e)

Configuration

What gets sent

Each event carries your SDK's name and version, an event type, a random session ID created per client instance, and a timestamp. Depending on the event:

• sdk_initialized (sent by start()): Python implementation and version, and time_to_init_ms.
• method_called / method_success: method name, duration, and the number of positional arguments.
• sdk_error: error type and message (email addresses are redacted) plus the method and duration.

Never sent: argument or return values, request or response bodies, stack traces, hostnames, environment variables or user identifiers. Nothing is sent when disabled=True.

Telling your users

Copy this into your SDK's README or privacy docs so your users know what's collected (edit the names to match):

Telemetry. This SDK reports anonymous usage data to its maintainers through SDK Garden: the SDK version, runtime version, which SDK methods are called, how long they take, and error types. It never sends your data, request contents or personal information. To opt out, set YOUR_SDK_TELEMETRY_DISABLED=1 (wire this environment variable to disabled=True in your SDK).

Behaviour Guarantees

All network errors are caught and discarded. Your program will never see an exception from sdk-garden-python.

Runs on a daemon thread — your program exits normally even if events are queued. When the process exits the daemon thread is killed automatically; any unsent events in the buffer are dropped. This is intentional — sdk-garden-python prioritises zero impact on your SDK over delivery guarantees.

Pass disabled=True in test environments to suppress all network calls. When disabled, start() returns immediately without spawning a thread, and track() / track_method() / track_error() are all no-ops.

HTTP requests use a 2-second timeout. Slow or unreachable ingest endpoints are silently abandoned after 2 seconds.

Queue overflow is silent. The internal queue holds a maximum of 100 events. If your SDK generates events faster than the flush thread can drain them, new events are discarded without raising an exception.

Notes

• start() must be called before events are flushed. Calling track() before start() is safe — events are queued and will be flushed once start() is called.
• track_method() returns a decorator. The decorated function behaves identically to the original; timing and error telemetry are captured transparently.
• Error messages passed to track_error() are PII-scrubbed: email addresses matching the standard user@example.com pattern are replaced with [REDACTED] before the event is enqueued.

License

MIT