sdk-garden-python 0.1.1__tar.gz → 0.2.0__tar.gz

{sdk_garden_python-0.1.1 → sdk_garden_python-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sdk-garden-python
-Version: 0.1.1
+Version: 0.2.0
 Summary: Lightweight SDK observability client for Python — stdlib only, non-blocking
 Project-URL: Homepage, https://sdkgarden.com
 Project-URL: Repository, https://github.com/tjb/SDKGarden
@@ -59,14 +59,35 @@ except Exception as e:
 | `batch_size` | `int` | `10` | Maximum events per HTTP POST, from 1 to 100 |
 | `flush_interval` | `float` | `5.0` | Seconds between flush cycles, from 0.1 to 86400 (a full batch is sent sooner) |
 | `started_at` | `float` | import time | `time.time()` when your SDK began initializing; reported as `time_to_init_ms` for the dashboard's init timing |
+| `methods` | iterable of `str` | `None` | Public methods of your SDK that are not wrapped with `track_method()`, so the dashboard's API Surface panel can show them when nobody calls them |
+| `customer_id` / `customer_name` | `str` | `None` | The app or customer account this client runs for (see [Customers](#customers)) |
+
+### API surface
+
+Every name passed to `track_method()` is declared as part of your SDK's API surface, once per client (in the `sdk_initialized` event, or in one `api_surface` event for methods decorated after `start()`). The dashboard lists those methods next to the ones people call, so the methods nobody uses show up with zero calls. Add methods you don't decorate with the `methods` parameter. Up to 500 names are declared.
+
+### Customers
+
+Tell SDK Garden which of your customers a client belongs to, and the dashboard's Customers page shows who is on an old version, who still calls a deprecated method and who hits errors, so you know who to contact.
+
+```python
+# When your SDK knows which account it runs for, for example after resolving its API key:
+sg.set_customer(account.id, name=account.display_name)
+
+# Or when creating the client, if you already know it:
+sg = SdkGarden(api_key="sgk_...", sdk_name="my-sdk", sdk_version="1.0.0", customer_id="acct_123").start()
+```
+
+Use an ID from your own system, such as an account, project or app ID, and optionally a display name. Nothing is attributed unless you set one. Don't pass email addresses or other personal data: an ID that contains an email address is ignored, and so is a name that contains one. IDs are cut to 128 characters and names to 200. `set_customer(None)` stops attributing.
 
 ## 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`.
+- **`sdk_initialized`** (sent by `start()`): Python implementation and version, `time_to_init_ms`, and the names of your SDK's methods (see [API surface](#api-surface)).
 - **`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.
+- **If you set a customer**, every event carries its ID and name (see [Customers](#customers)).
 
 Never sent: argument or return values, request or response bodies, stack traces or environment variables. Error messages go out as they are apart from email addresses, so anything your SDK puts in an exception message, such as a hostname, a URL or an ID, goes with it. Nothing is sent when `disabled=True`.
 

{sdk_garden_python-0.1.1 → sdk_garden_python-0.2.0}/README.md

@@ -49,14 +49,35 @@ except Exception as e:
 | `batch_size` | `int` | `10` | Maximum events per HTTP POST, from 1 to 100 |
 | `flush_interval` | `float` | `5.0` | Seconds between flush cycles, from 0.1 to 86400 (a full batch is sent sooner) |
 | `started_at` | `float` | import time | `time.time()` when your SDK began initializing; reported as `time_to_init_ms` for the dashboard's init timing |
+| `methods` | iterable of `str` | `None` | Public methods of your SDK that are not wrapped with `track_method()`, so the dashboard's API Surface panel can show them when nobody calls them |
+| `customer_id` / `customer_name` | `str` | `None` | The app or customer account this client runs for (see [Customers](#customers)) |
+
+### API surface
+
+Every name passed to `track_method()` is declared as part of your SDK's API surface, once per client (in the `sdk_initialized` event, or in one `api_surface` event for methods decorated after `start()`). The dashboard lists those methods next to the ones people call, so the methods nobody uses show up with zero calls. Add methods you don't decorate with the `methods` parameter. Up to 500 names are declared.
+
+### Customers
+
+Tell SDK Garden which of your customers a client belongs to, and the dashboard's Customers page shows who is on an old version, who still calls a deprecated method and who hits errors, so you know who to contact.
+
+```python
+# When your SDK knows which account it runs for, for example after resolving its API key:
+sg.set_customer(account.id, name=account.display_name)
+
+# Or when creating the client, if you already know it:
+sg = SdkGarden(api_key="sgk_...", sdk_name="my-sdk", sdk_version="1.0.0", customer_id="acct_123").start()
+```
+
+Use an ID from your own system, such as an account, project or app ID, and optionally a display name. Nothing is attributed unless you set one. Don't pass email addresses or other personal data: an ID that contains an email address is ignored, and so is a name that contains one. IDs are cut to 128 characters and names to 200. `set_customer(None)` stops attributing.
 
 ## 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`.
+- **`sdk_initialized`** (sent by `start()`): Python implementation and version, `time_to_init_ms`, and the names of your SDK's methods (see [API surface](#api-surface)).
 - **`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.
+- **If you set a customer**, every event carries its ID and name (see [Customers](#customers)).
 
 Never sent: argument or return values, request or response bodies, stack traces or environment variables. Error messages go out as they are apart from email addresses, so anything your SDK puts in an exception message, such as a hostname, a URL or an ID, goes with it. Nothing is sent when `disabled=True`.
 

{sdk_garden_python-0.1.1 → sdk_garden_python-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sdk-garden-python"
-version = "0.1.1"
+version = "0.2.0"
 description = "Lightweight SDK observability client for Python — stdlib only, non-blocking"
 readme = "README.md"
 requires-python = ">=3.8"

{sdk_garden_python-0.1.1 → sdk_garden_python-0.2.0}/sdk_garden/client.py

@@ -31,7 +31,7 @@ import urllib.error
 import urllib.request
 import uuid
 import weakref
-from typing import Any, Callable, Dict, List, Optional, Set, TypeVar
+from typing import Any, Callable, Dict, Iterable, List, Optional, Set, TypeVar
 
 F = TypeVar("F", bound=Callable[..., Any])
 
@@ -80,6 +80,23 @@ _MAX_EMAIL_LENGTH = 254
 #: The ingest endpoint stores event names of at most this many characters.
 _MAX_EVENT_NAME_LENGTH = 100
 
+#: Longest customer ID and name sent, in characters (the server's column sizes).
+_MAX_CUSTOMER_ID_LENGTH = 128
+_MAX_CUSTOMER_NAME_LENGTH = 200
+
+#: Control characters, removed from customer IDs and names.
+_CONTROL_CHARS = re.compile("[\x00-\x1f\x7f-\x9f]")
+
+#: Most method names one API surface declaration carries.
+_MAX_SURFACE_METHODS = 500
+
+#: Longest method name the endpoint stores.
+_MAX_METHOD_NAME_LENGTH = 255
+
+#: Most characters of method names in one declaration, so its event stays
+#: well under _MAX_EVENT_BYTES.
+_MAX_SURFACE_CHARS = 32 * 1024
+
 #: Characters the ingest endpoint cannot store: NUL and surrogates.
 _UNSTORABLE_CHARS = re.compile("[\x00\ud800-\udfff]")
 
@@ -234,6 +251,52 @@ def _sanitize_json(serialized: str) -> str:
     return _JSON_ESCAPE.sub(replace, serialized)
 
 
+def _is_method_name(name: Any) -> bool:
+    """Whether name can be stored as a method name."""
+    return isinstance(name, str) and name.strip() != "" and len(name) <= _MAX_METHOD_NAME_LENGTH
+
+
+def _surface_list(names: Iterable[Any]) -> List[str]:
+    """Up to _MAX_SURFACE_METHODS distinct method names, at most
+    _MAX_SURFACE_CHARS in all, in the order given."""
+    out: List[str] = []
+    seen: Set[str] = set()
+    chars = 0
+    for name in names:
+        if len(out) >= _MAX_SURFACE_METHODS:
+            break
+        if not _is_method_name(name) or name in seen:
+            continue
+        if chars + len(name) > _MAX_SURFACE_CHARS:
+            break
+        out.append(name)
+        seen.add(name)
+        chars += len(name)
+    return out
+
+
+def _customer_field(value: Any, max_length: int) -> str:
+    """A customer field trimmed, without control characters, cut to max_length."""
+    if not isinstance(value, str):
+        return ""
+    return _CONTROL_CHARS.sub("", value).strip()[:max_length].strip()
+
+
+def _clean_customer(customer_id: Any, name: Any) -> Optional[Dict[str, str]]:
+    """The customer to send, or None.
+
+    An ID that contains an email address is refused, and a name that contains
+    one is left out: attribution must not carry personal data.
+    """
+    cid = _customer_field(customer_id, _MAX_CUSTOMER_ID_LENGTH)
+    if not cid or _PII_PATTERN.search(cid):
+        return None
+    cname = _customer_field(name, _MAX_CUSTOMER_NAME_LENGTH)
+    if cname and not _PII_PATTERN.search(cname):
+        return {"id": cid, "name": cname}
+    return {"id": cid}
+
+
 def _scrub_error_message(message: str) -> str:
     """The part of an error message the endpoint can keep, with email
     addresses redacted. Only the first _MAX_ERROR_MESSAGE_BYTES characters
@@ -286,12 +349,22 @@ class SdkGarden:
         batch_size: int = _BATCH_SIZE,
         flush_interval: float = _FLUSH_INTERVAL,
         started_at: Optional[float] = None,
+        methods: Optional[Iterable[str]] = None,
+        customer_id: Optional[str] = None,
+        customer_name: Optional[str] = None,
     ) -> None:
         """Create a client. Nothing is sent until ``start()``.
 
         ``started_at`` is when your SDK began initializing, as ``time.time()``;
         ``start()`` reports the difference as ``time_to_init_ms``. Defaults to
         when sdk_garden was imported.
+
+        ``methods`` names public methods of your SDK that are not wrapped with
+        ``track_method()``. ``start()`` sends them with every name passed to
+        ``track_method()``, so the dashboard can list the methods nobody calls.
+
+        ``customer_id`` and ``customer_name`` attribute the session to one of
+        your customers from the start; see ``set_customer()``.
         """
         self._api_key = api_key
         self._sdk_name = sdk_name
@@ -303,6 +376,29 @@ class SdkGarden:
         self._flush_interval = _clamp_flush_interval(flush_interval)
         self._started_at = _start_time(started_at)
 
+        #: The customer added to every event, if set (see set_customer()).
+        #: Replaced whole, never changed in place, so readers need no lock.
+        self._customer: Optional[Dict[str, str]] = None
+        if customer_id is not None:
+            self._customer = _clean_customer(customer_id, customer_name)
+            if self._customer is None:
+                self._log("ignored a customer id that is empty or contains an email address")
+
+        #: Method names from ``methods`` and track_method(), in order.
+        self._registered: List[str] = []
+        try:
+            self._registered = _surface_list(methods or ())
+        except Exception:
+            pass  # Not an iterable of names: declare only what track_method() registers.
+
+        #: Names registered after start() that the flush thread has yet to
+        #: declare in an api_surface event. Guarded by _surface_lock.
+        self._undeclared: List[str] = []
+        self._surface_lock = threading.RLock()
+
+        #: True once start() has declared the methods registered so far.
+        self._surface_sent = False
+
         #: True once start() has sent sdk_initialized for this session.
         self._init_sent = False
 
@@ -380,16 +476,36 @@ class SdkGarden:
             if not self._init_sent:
                 self.track(
                     "sdk_initialized",
-                    {
-                        "environment": self._get_environment(),
-                        "time_to_init_ms": self._time_to_init_ms(),
-                    },
+                    self._init_properties(),
                 )
                 self._init_sent = True
             _register_live(self)
         self._ensure_thread()
         return self
 
+    def set_customer(self, customer_id: Optional[str], name: Optional[str] = None) -> None:
+        """Attribute events tracked from now on to one of your customers.
+
+        Pass an ID from your own system, such as an account, project or app ID,
+        and optionally a display name. The dashboard then shows which
+        customers are on old versions, still call deprecated methods or hit
+        errors. ``set_customer(None)`` stops attributing.
+
+        Never pass an email address or other personal data: an ID containing
+        one is ignored, and so is a name containing one. IDs are cut to 128
+        characters and names to 200. Never raises.
+        """
+        try:
+            if customer_id is None:
+                self._customer = None
+                return
+            customer = _clean_customer(customer_id, name)
+            if customer is None:
+                self._log("ignored a customer id that is empty or contains an email address")
+            self._customer = customer
+        except Exception:
+            pass  # Instrumentation must never raise into the host.
+
     def track(
         self,
         event_name: str,
@@ -413,16 +529,20 @@ class SdkGarden:
             # start() already reported it; a manual call (as older docs
             # suggested) would double-count the session.
             return
+        event: Dict[str, Any] = {
+            "event": event_name,
+            "sdk": {"name": self._sdk_name, "version": self._sdk_version},
+            "session_id": self._session_id,
+            "timestamp": int(time.time() * 1000),
+            "properties": properties or {},
+            "meta": {},
+        }
+        customer = self._customer
+        if customer is not None:
+            event["customer"] = customer
         try:
             serialized = json.dumps(
-                {
-                    "event": event_name,
-                    "sdk": {"name": self._sdk_name, "version": self._sdk_version},
-                    "session_id": self._session_id,
-                    "timestamp": int(time.time() * 1000),
-                    "properties": properties or {},
-                    "meta": {},
-                },
+                event,
                 default=str,
                 allow_nan=False,
             )
@@ -464,6 +584,8 @@ class SdkGarden:
 
             return _noop_decorator  # type: ignore[return-value]
 
+        self._register(method_name)
+
         def decorator(fn: F) -> F:
             if inspect.iscoroutinefunction(fn):
                 @functools.wraps(fn)
@@ -712,6 +834,43 @@ class SdkGarden:
         except RuntimeError:
             pass  # One is already pending
 
+    def _init_properties(self) -> Dict[str, Any]:
+        """Properties of the sdk_initialized event, with the API surface
+        registered so far."""
+        properties: Dict[str, Any] = {
+            "environment": self._get_environment(),
+            "time_to_init_ms": self._time_to_init_ms(),
+        }
+        with self._surface_lock:
+            surface = _surface_list(self._registered)
+            self._undeclared = []
+            self._surface_sent = True
+        if surface:
+            properties["api_surface"] = surface
+        return properties
+
+    def _register(self, method_name: str) -> None:
+        """Remember a method passed to track_method(). One registered after
+        start() is declared by the flush thread in an api_surface event, with
+        any others registered by then (see _declare_undeclared)."""
+        if not _is_method_name(method_name):
+            return
+        with self._surface_lock:
+            if method_name in self._registered or len(self._registered) >= _MAX_SURFACE_METHODS:
+                return
+            self._registered.append(method_name)
+            if self._surface_sent:
+                self._undeclared.append(method_name)
+
+    def _declare_undeclared(self) -> None:
+        """Queue an api_surface event for the methods registered since the
+        last declaration. Runs on the flush thread."""
+        with self._surface_lock:
+            names, self._undeclared = self._undeclared, []
+        surface = _surface_list(names)
+        if surface:
+            self.track("api_surface", {"api_surface": surface})
+
     def _time_to_init_ms(self) -> int:
         """Milliseconds since the host SDK began initializing (see started_at)."""
         try:
@@ -754,6 +913,10 @@ class SdkGarden:
     def _drain(self) -> None:
         """Send what is queued now, a batch at a time. Stops at the first
         failed request: the rest waits for the next cycle."""
+        try:
+            self._declare_undeclared()
+        except Exception:
+            pass  # Declaring methods must never stop events from being sent.
         remaining = len(self._queue)
         while remaining > 0:
             events = self._take_batch(min(remaining, self._batch_size))

{sdk_garden_python-0.1.1 → sdk_garden_python-0.2.0}/tests/test_client.py

@@ -1109,3 +1109,129 @@ class TestSignalHandlers:
         proc, _elapsed = run_script(INTERVAL_UNDER_SIGNALS_SCRIPT, timeout=20)
         assert proc.returncode == 0, proc.stderr
         assert float(proc.stdout) < 1.0  # worst delay from track() to send, in seconds
+
+
+# ---------------------------------------------------------------------------
+# class TestAPISurface
+# ---------------------------------------------------------------------------
+
+class TestAPISurface:
+    def test_start_declares_registered_methods_and_methods_param(self, urlopen):
+        sg = make_sg(flush_interval=3600, methods=["webhooks.verify", "charges.create", "", 42, "x" * 256])
+
+        @sg.track_method("charges.create")
+        def create():
+            return 1
+
+        @sg.track_method("refunds.create")
+        def refund():
+            return 1
+
+        sg.start()
+        sg.flush()
+        init = [e for batch in sent_batches(urlopen) for e in batch if e["event"] == "sdk_initialized"][0]
+        assert init["properties"]["api_surface"] == ["webhooks.verify", "charges.create", "refunds.create"]
+        assert "api_surface" not in sent_events(urlopen)
+
+    def test_no_api_surface_when_nothing_is_registered(self, urlopen):
+        sg = make_started()
+        sg.flush()
+        assert "api_surface" not in sent_batches(urlopen)[0][0]["properties"]
+
+    def test_methods_registered_after_start_are_declared_together(self, urlopen):
+        sg = make_started()
+        for name in ["a", "b", "a"]:
+            sg.track_method(name)(lambda: 1)
+        sg.flush()
+        declared = [e for batch in sent_batches(urlopen) for e in batch if e["event"] == "api_surface"]
+        assert len(declared) == 1
+        assert declared[0]["properties"]["api_surface"] == ["a", "b"]
+        sg.flush()
+        assert sent_events(urlopen).count("api_surface") == 1
+
+    def test_a_disabled_client_registers_nothing(self):
+        sg = make_sg(disabled=True)
+        sg.track_method("a")(lambda: 1)
+        assert sg._registered == []
+
+    def test_the_declaration_stays_small_enough_to_send(self, urlopen):
+        names = ["method_%d_%s" % (i, "x" * 200) for i in range(600)]
+        sg = make_sg(flush_interval=3600, methods=names).start()
+        sg.flush()
+        init = sent_batches(urlopen)[0][0]
+        assert len(init["properties"]["api_surface"]) > 100
+        assert len(json.dumps(init)) < 40 * 1024
+
+    def test_methods_that_are_not_a_list_never_break_the_client(self, urlopen):
+        sg = make_sg(flush_interval=3600, methods=7).start()
+        sg.flush()
+        assert sent_events(urlopen) == ["sdk_initialized"]
+
+
+# ---------------------------------------------------------------------------
+# class TestCustomer
+# ---------------------------------------------------------------------------
+
+def queued_events(sg):
+    return [json.loads(e) for e in sg._queue]
+
+
+class TestCustomer:
+    def test_no_customer_by_default(self):
+        sg = make_sg()
+        sg.track("custom_event")
+        assert "customer" not in queued_events(sg)[0]
+
+    def test_constructor_customer_on_every_event(self):
+        sg = make_sg(customer_id="acct_123", customer_name="Acme Corp")
+        sg.track("custom_event")
+        sg.track_error(ValueError("boom"))
+        for event in queued_events(sg):
+            assert event["customer"] == {"id": "acct_123", "name": "Acme Corp"}
+
+    def test_set_customer_applies_to_later_events_and_none_stops(self):
+        sg = make_sg()
+        sg.track("before")
+        sg.set_customer(" acct_9\n")
+        sg.track("during")
+        sg.set_customer(None)
+        sg.track("after")
+        by_name = {e["event"]: e for e in queued_events(sg)}
+        assert "customer" not in by_name["before"]
+        assert by_name["during"]["customer"] == {"id": "acct_9"}
+        assert "customer" not in by_name["after"]
+
+    def test_wrapped_calls_carry_customer(self):
+        sg = make_sg()
+        sg.set_customer("acct_1")
+
+        @sg.track_method("charge")
+        def charge():
+            return 1
+
+        charge()
+        events = [e for e in queued_events(sg) if e["event"].startswith("method_")]
+        assert len(events) == 2
+        assert all(e["customer"] == {"id": "acct_1"} for e in events)
+
+    def test_email_id_ignored_and_email_name_left_out(self):
+        sg = make_sg()
+        sg.set_customer("jane@acme.com", "Acme")
+        sg.track("email_id")
+        sg.set_customer("acct_2", "Jane <jane@acme.com>")
+        sg.track("email_name")
+        by_name = {e["event"]: e for e in queued_events(sg)}
+        assert "customer" not in by_name["email_id"]
+        assert by_name["email_name"]["customer"] == {"id": "acct_2"}
+
+    def test_invalid_values_never_raise_and_long_values_are_cut(self):
+        sg = make_sg(customer_id="")
+        sg.set_customer(42)
+        sg.set_customer(object(), name=["x"])
+        sg.track("invalid")
+        sg.set_customer("a" * 300, "n" * 300)
+        sg.track("long")
+        by_name = {e["event"]: e for e in queued_events(sg)}
+        assert "customer" not in by_name["invalid"]
+        assert len(by_name["long"]["customer"]["id"]) == 128
+        assert len(by_name["long"]["customer"]["name"]) == 200