getstream 4.0.0__tar.gz → 4.2.0__tar.gz

{getstream-4.0.0 → getstream-4.2.0}/CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.2.0] - 2026-07-24
+
 ### Added
 
 - Standardized error hierarchy ([CHA-2958](https://linear.app/stream/issue/CHA-2958)).
@@ -45,7 +47,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - `request_timeout: float` (seconds): default `30.0` (was `6.0`; see Behavior changes)
 
   These tune the underlying `httpx.Limits` and `httpx.Timeout`. The existing `http_client=` and `transport=` kwargs continue to act as escape hatches; when `http_client` is set, none of the four new kwargs apply. Env-var fallbacks for the new kwargs: `STREAM_MAX_CONNS_PER_HOST`, `STREAM_IDLE_TIMEOUT`, `STREAM_CONNECT_TIMEOUT`, `STREAM_REQUEST_TIMEOUT`.
-- INFO log on client construction (logger `getstream`) lists the effective pool config and whether a user-supplied `http_client` is in use.
+
+- Structured logging ([CHA-2957](https://linear.app/stream/issue/CHA-2957)).
+  New `logger: logging.Logger | None` and `log_bodies: bool = False` kwargs on
+  `Stream(...)` and `AsyncStream(...)`. Off by default: nothing is emitted
+  unless a logger is passed. Four events, each carrying structured fields via
+  the stdlib logging `extra={}` mechanism:
+    - `client.initialized` (INFO, once at construction): SDK name/version,
+      resolved pool knobs, `gzip_enabled`, `user_http_client`, `log_bodies`.
+      Replaces the old plain-text pool-config INFO line.
+    - `http.request.sent` (DEBUG, before each request): method, path,
+      redacted query, `stream.endpoint_name`.
+    - `http.response.received` (DEBUG, after any response including
+      4xx/5xx): status code, response size, `duration_ms`. HTTP error
+      status codes are data, not failures.
+    - `http.request.failed` (ERROR, transport failure only, no HTTP
+      response received): `error.type` (`connection_reset` / `timeout` /
+      `dns_failure` / `tls_handshake_failed` / `unknown`), `error.message`.
+  Query values for `api_key`/`api_secret`/`token` and top-level JSON body
+  keys `api_secret`/`token`/`password` are always redacted; no opt-out.
+  Bodies are never logged by default; `log_bodies=True` adds redacted
+  request/response bodies and emits one WARNING at construction.
 
 - Webhook handling spec helpers (CHA-2961): `UnknownEvent` dataclass for
   forward-compat; `gunzip_payload`, `decode_sqs_payload`, `decode_sns_payload`

{getstream-4.0.0 → getstream-4.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: getstream
-Version: 4.0.0
+Version: 4.2.0
 Summary: GetStream Python SDK - Build scalable activity feeds, chat, and video calling applications
 Author-email: sachaarbonel <sacha.arbonel@hotmail.fr>, tbarbugli <tbarbugli@gmail.com>
 License-File: LICENSE.md
@@ -151,6 +151,31 @@ response: StreamResponse[StartClosedCaptionsResponse] = call.start_closed_captio
 response.data  # Gives the StartClosedCaptionsResponse model
 ```
 
+### Logging
+
+The SDK emits structured log events (`client.initialized`, `http.request.sent`, `http.response.received`, `http.request.failed`) through the stdlib `logging` module. By default nothing is printed: pass a `logging.Logger` to see them.
+
+```python
+import logging
+
+logging.basicConfig(level=logging.DEBUG)
+client = Stream(api_key="key", api_secret="secret", logger=logging.getLogger("myapp.stream"))
+```
+
+Each event carries structured fields via the standard `extra={}` mechanism (for example `http.response.status_code`, `duration_ms`, `stream.endpoint_name`). Query and body values for known secret keys (`api_key`, `api_secret`, `token`, `password`) are always redacted. Request/response bodies are omitted by default; pass `log_bodies=True` to include them (still redacted, and this emits one WARNING at construction since bodies can contain other sensitive data).
+
+### Retries
+
+By default the client makes exactly one attempt per request and surfaces errors unchanged. Pass a `RetryConfig` to opt in to auto-retry:
+
+```python
+from getstream import Stream, RetryConfig
+
+client = Stream(api_key=..., api_secret=..., retry=RetryConfig(enabled=True, max_attempts=3, max_backoff=30.0))
+```
+
+Only idempotent `GET`/`HEAD` requests are retried, and only on HTTP 429 (unless the backend marked it unrecoverable) or a transport-level failure (timeout, connection reset, DNS, TLS). A 429's `Retry-After` header is honored (clamped to `max_backoff`); otherwise the delay uses full jitter over an exponential backoff. A retried failure logs `http.request.failed` at DEBUG; a final, non-retried failure logs it at ERROR (or not at all for a final 429, since that's already covered by `http.response.received`).
+
 ### App configuration
 
 ```python

{getstream-4.0.0 → getstream-4.2.0}/README.md

@@ -99,6 +99,31 @@ response: StreamResponse[StartClosedCaptionsResponse] = call.start_closed_captio
 response.data  # Gives the StartClosedCaptionsResponse model
 ```
 
+### Logging
+
+The SDK emits structured log events (`client.initialized`, `http.request.sent`, `http.response.received`, `http.request.failed`) through the stdlib `logging` module. By default nothing is printed: pass a `logging.Logger` to see them.
+
+```python
+import logging
+
+logging.basicConfig(level=logging.DEBUG)
+client = Stream(api_key="key", api_secret="secret", logger=logging.getLogger("myapp.stream"))
+```
+
+Each event carries structured fields via the standard `extra={}` mechanism (for example `http.response.status_code`, `duration_ms`, `stream.endpoint_name`). Query and body values for known secret keys (`api_key`, `api_secret`, `token`, `password`) are always redacted. Request/response bodies are omitted by default; pass `log_bodies=True` to include them (still redacted, and this emits one WARNING at construction since bodies can contain other sensitive data).
+
+### Retries
+
+By default the client makes exactly one attempt per request and surfaces errors unchanged. Pass a `RetryConfig` to opt in to auto-retry:
+
+```python
+from getstream import Stream, RetryConfig
+
+client = Stream(api_key=..., api_secret=..., retry=RetryConfig(enabled=True, max_attempts=3, max_backoff=30.0))
+```
+
+Only idempotent `GET`/`HEAD` requests are retried, and only on HTTP 429 (unless the backend marked it unrecoverable) or a transport-level failure (timeout, connection reset, DNS, TLS). A 429's `Retry-After` header is honored (clamped to `max_backoff`); otherwise the delay uses full jitter over an exponential backoff. A retried failure logs `http.request.failed` at DEBUG; a final, non-retried failure logs it at ERROR (or not at all for a final 429, since that's already covered by `http.response.received`).
+
 ### App configuration
 
 ```python

getstream-4.2.0/getstream/__init__.py

@@ -0,0 +1,16 @@
+import logging
+
+from getstream.config import RetryConfig  # noqa: F401
+from getstream.exceptions import (  # noqa: F401
+    StreamApiException,
+    StreamException,
+    StreamRateLimitException,
+    StreamTaskException,
+    StreamTransportException,
+)
+from getstream.stream import Stream  # noqa: F401
+from getstream.stream import AsyncStream  # noqa: F401
+
+# No-op until the caller attaches a handler: the SDK never configures the
+# logger's level or output, it only emits at each event's documented level.
+logging.getLogger("getstream").addHandler(logging.NullHandler())

{getstream-4.0.0 → getstream-4.2.0}/getstream/base.py

@@ -2,6 +2,7 @@ import json
 import logging
 import mimetypes
 import os
+import random
 import time
 import uuid
 import warnings
@@ -10,13 +11,17 @@ from typing import Any, Dict, List, Optional, Tuple, Type, cast, get_origin
 
 from getstream.exceptions import (
     StreamApiException,
+    StreamRateLimitException,
+    StreamTransportException,
     build_api_exception,
     wrap_transport_error,
 )
+from getstream.logging_utils import redact_json_body, redact_query
 from getstream.stream_response import StreamResponse
 from getstream.generic import T
 import httpx
 from getstream.config import BaseConfig
+from getstream.version import VERSION
 from urllib.parse import quote
 from abc import ABC
 from getstream.common.telemetry import (
@@ -42,6 +47,34 @@ DEFAULT_CONNECT_TIMEOUT = 10.0
 logger = logging.getLogger("getstream")
 
 
+# ── Retry policy (CHA-2959) ───────────────────────────────────────────
+def _retry_eligible(retry, exc, method: str, attempt: int) -> bool:
+    """Whether ``exc`` from the given 0-indexed ``attempt`` should be retried
+    under ``retry`` (a ``RetryConfig`` or ``None``). Only GET/HEAD, only HTTP
+    429 (unless marked unrecoverable) or a transport error, and only while
+    attempts remain."""
+    if retry is None or not retry.enabled:
+        return False
+    if method.upper() not in ("GET", "HEAD"):
+        return False
+    if attempt + 1 >= retry.max_attempts:
+        return False
+    if isinstance(exc, StreamRateLimitException):
+        return not bool(getattr(exc, "unrecoverable", False))
+    return isinstance(exc, StreamTransportException)
+
+
+def _retry_delay(retry, exc, attempt: int) -> float:
+    """Seconds to sleep before the next attempt: honors the server's
+    ``Retry-After`` when present (clamped to ``max_backoff``), else full
+    jitter over an exponential ceiling (``attempt`` is 0-indexed)."""
+    retry_after = getattr(exc, "retry_after", None)
+    if retry_after is not None and retry_after.total_seconds() > 0:
+        return min(retry_after.total_seconds(), retry.max_backoff)
+    ceil = min(retry.max_backoff, float(2**attempt))
+    return random.uniform(0.0, ceil) if ceil > 0 else 0.0
+
+
 def _resolve_pool_knobs(obj):
     """Pull the 3 pool knobs off ``obj`` if BaseStream has set them, else fall back to spec defaults. Top-level ``Stream``/``AsyncStream`` sets them on ``self`` before calling ``super().__init__()``, so a directly instantiated sub-client (or test fixture) still gets sane values.
 
@@ -59,22 +92,46 @@ def _resolve_pool_knobs(obj):
     )
 
 
-def _log_pool_config(cfg, *, user_http_client: bool) -> None:
-    if user_http_client:
-        logger.info(
-            "getstream connection pool: user_http_client=True (5 knobs not applied)"
-        )
-    else:
-        logger.info(
-            "getstream connection pool: "
-            "max_conns_per_host=%s idle_timeout=%ss "
-            "connect_timeout=%ss request_timeout=%ss "
-            "user_http_client=False",
-            cfg.max_conns_per_host,
-            cfg.idle_timeout,
-            cfg.connect_timeout,
-            cfg.timeout,
-        )
+def _resolve_logger(obj) -> logging.Logger:
+    """The caller's injected logger (``Stream``/``AsyncStream``'s ``logger=``
+    kwarg, plumbed onto ``obj.log`` the same way as the pool knobs), or the
+    shared module logger when none was passed."""
+    return getattr(obj, "log", None) or logger
+
+
+def _log_client_initialized(cfg, *, user_http_client: bool) -> None:
+    """Emit the one-shot ``client.initialized`` event, replacing the old
+    plain-text pool-config INFO line with the structured logging schema."""
+    _resolve_logger(cfg).info(
+        "client.initialized",
+        extra={
+            "stream.sdk.name": "stream-py",
+            "stream.sdk.version": VERSION,
+            "stream.client.max_conns_per_host": cfg.max_conns_per_host,
+            "stream.client.idle_timeout_seconds": cfg.idle_timeout,
+            "stream.client.connect_timeout_seconds": cfg.connect_timeout,
+            "stream.client.request_timeout_seconds": cfg.timeout,
+            "stream.client.gzip_enabled": not user_http_client,
+            "stream.client.user_http_client": user_http_client,
+            "stream.client.log_bodies": bool(getattr(cfg, "log_bodies", False)),
+        },
+    )
+
+
+def _response_body_for_log(response: httpx.Response):
+    """Redact a response body for the ``http.response.body`` log field.
+    JSON bodies get the shallow key redaction; anything else (or anything
+    that fails to parse as JSON) is passed through as text."""
+    # Media types are case-insensitive; match application/json and any
+    # structured +json type (e.g. application/problem+json) so their bodies
+    # are redacted, not logged as raw text.
+    content_type = response.headers.get("content-type", "").lower()
+    if "application/json" in content_type or "+json" in content_type:
+        try:
+            return redact_json_body(json.loads(response.text))
+        except (ValueError, TypeError):
+            return response.text
+    return response.text
 
 
 def _read_file_bytes(file_path: str) -> bytes:
@@ -268,7 +325,7 @@ class BaseClient(TelemetryEndpointMixin, BaseConfig, ResponseParserMixin, ABC):
         op = getattr(self, "_operation_name", None)
         return op or current_operation(self._normalize_endpoint_from_path(path)) or ""
 
-    def _request_sync(
+    def _attempt_sync(
         self,
         method: str,
         path: str,
@@ -284,6 +341,18 @@ class BaseClient(TelemetryEndpointMixin, BaseConfig, ResponseParserMixin, ABC):
         url_path, url_full, endpoint, attrs = self._prepare_request(
             method, path, query_params, kwargs
         )
+        log = _resolve_logger(self)
+        log_bodies = bool(getattr(self, "log_bodies", False))
+        sent_extra = {
+            "http.request.method": method,
+            "url.path": path,
+            "url.query": redact_query(query_params) or "",
+            "stream.endpoint_name": endpoint,
+        }
+        if log_bodies:
+            sent_extra["http.request.body"] = redact_json_body(kwargs.get("json"))
+        log.debug("http.request.sent", extra=sent_extra)
+
         start = time.perf_counter()
         # Span name uses logical operation (endpoint) rather than raw HTTP
         with span_request(
@@ -296,6 +365,9 @@ class BaseClient(TelemetryEndpointMixin, BaseConfig, ResponseParserMixin, ABC):
                     url_path, params=query_params, *args, **call_kwargs
                 )
             except httpx.RequestError as err:
+                # No failed-log here: the retry loop (_request_sync) owns
+                # http.request.failed so it can log at DEBUG when retrying
+                # and ERROR only on a final failure.
                 raise wrap_transport_error(err) from err
             duration = parse_duration_from_body(response.content)
             if duration:
@@ -308,6 +380,17 @@ class BaseClient(TelemetryEndpointMixin, BaseConfig, ResponseParserMixin, ABC):
                 pass
 
             duration_ms = (time.perf_counter() - start) * 1000.0
+            received_extra = {
+                "http.request.method": method,
+                "url.path": path,
+                "stream.endpoint_name": endpoint,
+                "http.response.status_code": response.status_code,
+                "http.response.body.size": len(response.content or b""),
+                "duration_ms": int(duration_ms),
+            }
+            if log_bodies:
+                received_extra["http.response.body"] = _response_body_for_log(response)
+            log.debug("http.response.received", extra=received_extra)
             # Metrics should be low-cardinality: exclude url/call_cid/channel_cid
             metric_attrs = metric_attributes(
                 api_key=self.api_key,
@@ -318,6 +401,72 @@ class BaseClient(TelemetryEndpointMixin, BaseConfig, ResponseParserMixin, ABC):
             record_metrics(duration_ms, attributes=metric_attrs)
             return self._parse_response(response, data_type or Dict[str, Any])
 
+    def _request_sync(
+        self,
+        method: str,
+        path: str,
+        *,
+        query_params=None,
+        args=(),
+        kwargs=None,
+        data_type: Optional[Type[T]] = None,
+    ):
+        """Retry loop around ``_attempt_sync``. Disabled (default) retry
+        policy means exactly one attempt, errors surface unchanged. When
+        enabled, retries GET/HEAD on HTTP 429 / transport errors per
+        ``_retry_eligible``/``_retry_delay``, owning the ``http.request.failed``
+        log level so a retried failure logs at DEBUG and only a final
+        transport failure logs at ERROR (a final 429 is already covered by
+        ``http.response.received``)."""
+        retry = getattr(self, "retry", None)
+        log = _resolve_logger(self)
+        endpoint = self._endpoint_name(path)
+        attempt = 0
+        while True:
+            t0 = time.perf_counter()
+            try:
+                return self._attempt_sync(
+                    method,
+                    path,
+                    query_params=query_params,
+                    args=args,
+                    kwargs=kwargs,
+                    data_type=data_type,
+                )
+            except (StreamRateLimitException, StreamTransportException) as exc:
+                duration_ms = int((time.perf_counter() - t0) * 1000)
+                if _retry_eligible(retry, exc, method, attempt):
+                    delay = _retry_delay(retry, exc, attempt)
+                    extra = {
+                        "http.request.method": method,
+                        "url.path": path,
+                        "stream.endpoint_name": endpoint,
+                        "retry.attempt": attempt + 1,
+                        "backoff_seconds": round(delay, 3),
+                        "error.message": str(exc.__cause__ or exc),
+                        "duration_ms": duration_ms,
+                    }
+                    if isinstance(exc, StreamTransportException):
+                        extra["error.type"] = exc.error_type
+                    log.debug("http.request.failed", extra=extra)
+                    time.sleep(delay)
+                    attempt += 1
+                    continue
+                if isinstance(exc, StreamTransportException):
+                    log.error(
+                        "http.request.failed",
+                        extra={
+                            "http.request.method": method,
+                            "url.path": path,
+                            "stream.endpoint_name": endpoint,
+                            "retry.attempt": attempt + 1,
+                            "error.type": exc.error_type,
+                            "error.message": str(exc.__cause__ or exc),
+                            "duration_ms": duration_ms,
+                        },
+                    )
+                raise
+
     def patch(
         self,
         path,
@@ -576,7 +725,7 @@ class AsyncBaseClient(TelemetryEndpointMixin, BaseConfig, ResponseParserMixin, A
         op = getattr(self, "_operation_name", None)
         return op or current_operation(self._normalize_endpoint_from_path(path)) or ""
 
-    async def _request_async(
+    async def _attempt_async(
         self,
         method: str,
         path: str,
@@ -593,6 +742,18 @@ class AsyncBaseClient(TelemetryEndpointMixin, BaseConfig, ResponseParserMixin, A
         url_path, url_full, endpoint, attrs = self._prepare_request(
             method, path, query_params, kwargs
         )
+        log = _resolve_logger(self)
+        log_bodies = bool(getattr(self, "log_bodies", False))
+        sent_extra = {
+            "http.request.method": method,
+            "url.path": path,
+            "url.query": redact_query(query_params) or "",
+            "stream.endpoint_name": endpoint,
+        }
+        if log_bodies:
+            sent_extra["http.request.body"] = redact_json_body(kwargs.get("json"))
+        log.debug("http.request.sent", extra=sent_extra)
+
         start = time.perf_counter()
         with span_request(
             endpoint, attributes=attrs, request_body=kwargs.get("json")
@@ -612,6 +773,9 @@ class AsyncBaseClient(TelemetryEndpointMixin, BaseConfig, ResponseParserMixin, A
                     url_path, params=query_params, *args, **call_kwargs
                 )
             except httpx.RequestError as err:
+                # No failed-log here: the retry loop (_request_async) owns
+                # http.request.failed so it can log at DEBUG when retrying
+                # and ERROR only on a final failure.
                 raise wrap_transport_error(err) from err
             duration = parse_duration_from_body(response.content)
             if duration:
@@ -624,6 +788,19 @@ class AsyncBaseClient(TelemetryEndpointMixin, BaseConfig, ResponseParserMixin, A
                 pass
 
             duration_ms = (time.perf_counter() - start) * 1000.0
+            received_extra = {
+                "http.request.method": method,
+                "url.path": path,
+                "stream.endpoint_name": endpoint,
+                "http.response.status_code": response.status_code,
+                "http.response.body.size": len(response.content or b""),
+                "duration_ms": int(duration_ms),
+            }
+            if log_bodies:
+                received_extra["http.response.body"] = await asyncio.to_thread(
+                    _response_body_for_log, response
+                )
+            log.debug("http.response.received", extra=received_extra)
             # Metrics should be low-cardinality: exclude url/call_cid/channel_cid
             metric_attrs = metric_attributes(
                 api_key=self.api_key,
@@ -636,6 +813,66 @@ class AsyncBaseClient(TelemetryEndpointMixin, BaseConfig, ResponseParserMixin, A
                 self._parse_response, response, data_type or Dict[str, Any]
             )
 
+    async def _request_async(
+        self,
+        method: str,
+        path: str,
+        *,
+        query_params=None,
+        args=(),
+        kwargs=None,
+        data_type: Optional[Type[T]] = None,
+    ):
+        """Async twin of ``BaseClient._request_sync``; see that docstring."""
+        retry = getattr(self, "retry", None)
+        log = _resolve_logger(self)
+        endpoint = self._endpoint_name(path)
+        attempt = 0
+        while True:
+            t0 = time.perf_counter()
+            try:
+                return await self._attempt_async(
+                    method,
+                    path,
+                    query_params=query_params,
+                    args=args,
+                    kwargs=kwargs,
+                    data_type=data_type,
+                )
+            except (StreamRateLimitException, StreamTransportException) as exc:
+                duration_ms = int((time.perf_counter() - t0) * 1000)
+                if _retry_eligible(retry, exc, method, attempt):
+                    delay = _retry_delay(retry, exc, attempt)
+                    extra = {
+                        "http.request.method": method,
+                        "url.path": path,
+                        "stream.endpoint_name": endpoint,
+                        "retry.attempt": attempt + 1,
+                        "backoff_seconds": round(delay, 3),
+                        "error.message": str(exc.__cause__ or exc),
+                        "duration_ms": duration_ms,
+                    }
+                    if isinstance(exc, StreamTransportException):
+                        extra["error.type"] = exc.error_type
+                    log.debug("http.request.failed", extra=extra)
+                    await asyncio.sleep(delay)
+                    attempt += 1
+                    continue
+                if isinstance(exc, StreamTransportException):
+                    log.error(
+                        "http.request.failed",
+                        extra={
+                            "http.request.method": method,
+                            "url.path": path,
+                            "stream.endpoint_name": endpoint,
+                            "retry.attempt": attempt + 1,
+                            "error.type": exc.error_type,
+                            "error.message": str(exc.__cause__ or exc),
+                            "duration_ms": duration_ms,
+                        },
+                    )
+                raise
+
     async def patch(
         self,
         path,

{getstream-4.0.0 → getstream-4.2.0}/getstream/config.py

@@ -1,6 +1,26 @@
+from dataclasses import dataclass
+
 from getstream.version import VERSION
 
 
+@dataclass(frozen=True)
+class RetryConfig:
+    """Opt-in auto-retry policy. Disabled by default: the client performs
+    exactly one attempt and surfaces errors unchanged. When enabled, only
+    GET/HEAD requests failing with HTTP 429 or a transport error are retried,
+    and never when the backend marked the error unrecoverable."""
+
+    enabled: bool = False
+    max_attempts: int = 3
+    max_backoff: float = 30.0
+
+    def __post_init__(self):
+        if self.max_attempts < 1:
+            raise ValueError("max_attempts must be >= 1")
+        if self.max_backoff < 0:
+            raise ValueError("max_backoff must be >= 0")
+
+
 class BaseConfig:
     def __init__(
         self,

getstream-4.2.0/getstream/logging_utils.py

@@ -0,0 +1,21 @@
+"""Redaction helpers for the SDK's structured log events. Secret values are
+replaced with a literal marker; the scan is shallow by design."""
+
+REDACTED = "<redacted>"
+REDACTED_QUERY_PARAMS = {"api_key", "api_secret", "token"}
+REDACTED_BODY_KEYS = {"api_secret", "token", "password"}
+
+
+def redact_query(params):
+    if not params:
+        return params
+    return {
+        k: (REDACTED if k.lower() in REDACTED_QUERY_PARAMS else v)
+        for k, v in dict(params).items()
+    }
+
+
+def redact_json_body(body):
+    if not isinstance(body, dict):
+        return body
+    return {k: (REDACTED if k in REDACTED_BODY_KEYS else v) for k, v in body.items()}

{getstream-4.0.0 → getstream-4.2.0}/getstream/stream.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from contextlib import AsyncExitStack
 from functools import cached_property
+import logging
 import time
 from typing import List, Optional
 from uuid import uuid4
@@ -10,8 +11,9 @@ import httpx
 import jwt
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
-from getstream.base import _log_pool_config
+from getstream.base import _log_client_initialized, _resolve_logger
 from getstream.common import telemetry
+from getstream.config import RetryConfig
 from getstream.chat.client import ChatClient
 from getstream.chat.async_client import ChatClient as AsyncChatClient
 from getstream.common.async_client import CommonClient as AsyncCommonClient
@@ -92,6 +94,9 @@ class BaseStream:
         max_conns_per_host: Optional[int] = None,
         idle_timeout: Optional[float] = None,
         connect_timeout: Optional[float] = None,
+        logger: Optional[logging.Logger] = None,
+        log_bodies: bool = False,
+        retry: Optional[RetryConfig] = None,
     ):
         """Build a Stream client.
 
@@ -114,6 +119,9 @@ class BaseStream:
             max_conns_per_host: Max concurrent TCP connections per host. Default 5. Ignored when ``http_client`` is set.
             idle_timeout: Idle connection lifetime in seconds. Default 55.0 (sits 5s under the typical 60s LB idle timeout). Ignored when ``http_client`` is set.
             connect_timeout: TCP + TLS handshake timeout in seconds. Default 10.0. Ignored when ``http_client`` is set.
+            logger: Optional stdlib ``logging.Logger`` for the SDK's structured log events (``client.initialized``, ``http.request.sent``, ``http.response.received``, ``http.request.failed``). Defaults to ``logging.getLogger("getstream")``, which is a no-op until the caller attaches a handler.
+            log_bodies: When ``True``, adds redacted request/response bodies to the request/response log events. Off by default. Emits one WARNING at construction when enabled.
+            retry: Optional ``RetryConfig`` enabling auto-retry of GET/HEAD requests on HTTP 429 or transport errors. Disabled by default (a single attempt; errors surface unchanged).
 
         Raises:
             ValueError: If both ``transport`` and ``http_client`` are set; if neither ``api_secret`` nor ``token`` can be resolved; if both are provided; if either is the empty string; if ``api_key`` is missing; or if ``request_timeout`` is not a positive number.
@@ -189,6 +197,18 @@ class BaseStream:
         self._transport = transport
         self._http_client = http_client
         self.token = token or self._create_token()
+        # log / log_bodies are read by BaseClient via getattr(self, ...), same
+        # plumbing as the pool knobs below: the intermediate generated REST
+        # clients (CommonRestClient etc.) do not forward these kwargs, so they
+        # must be set on self before super().__init__() and copied onto
+        # sub-clients in _apply_shared_client.
+        self.log = logger
+        self.log_bodies = log_bodies
+        # retry: same getattr(self, ...) plumbing as the pool knobs and log/
+        # log_bodies above, since the intermediate generated REST clients do
+        # not forward this kwarg either. Read by BaseClient/AsyncBaseClient's
+        # request loop and copied onto sub-clients in _apply_shared_client.
+        self.retry = retry
         # Pool knobs are read by BaseClient via getattr(self, ...) since the intermediate generated REST clients (CommonRestClient etc.) do not forward these kwargs. self.max_conns_per_host / idle_timeout / connect_timeout were set above before super().__init__().
         super().__init__(
             self.api_key, self.base_url, self.token, self.timeout, self.user_agent
@@ -203,9 +223,17 @@ class BaseStream:
         # the parent's client avoids that and keeps one pool per Stream.
         self._shared_client = self.client
 
-        # Emit the pool-config INFO line exactly once per Stream, reflecting the
-        # resolved knobs on the top-level client. Sub-clients no longer log.
-        _log_pool_config(self, user_http_client=http_client is not None)
+        # Emit the client.initialized event exactly once per Stream, reflecting
+        # the resolved knobs on the top-level client. Sub-clients no longer log
+        # their own construction.
+        _log_client_initialized(self, user_http_client=http_client is not None)
+        if self.log_bodies:
+            _resolve_logger(self).warning(
+                "HTTP request/response bodies will be logged. Auth headers "
+                "and known-secret fields are still redacted, but other "
+                "sensitive data (messages, PII) may appear in logs. Disable "
+                "for production."
+            )
 
     @property
     def api_secret(self) -> str:
@@ -234,6 +262,12 @@ class BaseStream:
                 sub_client.client.close()
             sub_client.client = self._shared_client
             sub_client._owns_http_client = False
+        # log / log_bodies: same getattr(self, ..., default) plumbing as the
+        # pool knobs, so sub-clients (which issue the actual requests) emit
+        # through the caller's logger instead of silently falling back.
+        sub_client.log = getattr(self, "log", None)
+        sub_client.log_bodies = getattr(self, "log_bodies", False)
+        sub_client.retry = getattr(self, "retry", None)
         return sub_client
 
     def create_token(
@@ -284,6 +318,8 @@ class BaseStream:
             idle_timeout=self.idle_timeout,
             connect_timeout=self.connect_timeout,
             user_agent=self.user_agent,
+            logger=self.log,
+            log_bodies=self.log_bodies,
         )
 
     def create_call_token(
@@ -543,6 +579,8 @@ class Stream(BaseStream, CommonClient):
             connect_timeout=self.connect_timeout,
             base_url=self.base_url,
             user_agent=self.user_agent,
+            logger=self.log,
+            log_bodies=self.log_bodies,
         )
 
     @cached_property