Metadata-Version: 2.5
Name: sdk-garden-python
Version: 0.1.0
Summary: Lightweight SDK observability client for Python — stdlib only, non-blocking
Project-URL: Homepage, https://sdkgarden.dev
Project-URL: Repository, https://github.com/tjb/SDKGarden
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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

```bash
pip install sdk-garden-python
```

## Quick Start

```python
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:

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

Track errors with automatic PII scrubbing:

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

## Configuration

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | `str` | required | Your SDK Garden API key (`sgk_...`) |
| `sdk_name` | `str` | required | Name of your SDK (e.g. `"my-payments-sdk"`) |
| `sdk_version` | `str` | required | Version of your SDK (e.g. `"1.2.3"`) |
| `endpoint` | `str` | `https://ingest.sdkgarden.dev/track` | Ingest endpoint URL |
| `debug` | `bool` | `False` | Print `[SDK Garden]` debug lines to stdout |
| `disabled` | `bool` | `False` | Disable all tracking (no thread spawned, no network calls) |
| `batch_size` | `int` | `10` | Maximum events per HTTP POST |
| `flush_interval` | `float` | `5.0` | Seconds between flush cycles |
| `started_at` | `float` | import time | `time.time()` when your SDK began initializing; reported as `time_to_init_ms` for the dashboard's init timing |

## 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](https://github.com/tjb/SDKGarden): 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
