objectstore-client 0.2.3__tar.gz → 0.2.5__tar.gz

{objectstore_client-0.2.3 → objectstore_client-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: objectstore-client
-Version: 0.2.3
+Version: 0.2.5
 Summary: Client SDK for Objectstore, the Sentry object storage platform
 Author: Sentry
 Author-email: Sentry <oss@sentry.io>
@@ -109,7 +109,7 @@ License: # Functional Source License, Version 1.1, Apache 2.0 Future License
          under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
          CONDITIONS OF ANY KIND, either express or implied. See the License for the
          specific language governing permissions and limitations under the License.
-Requires-Dist: sentry-sdk>=2.42.1
+Requires-Dist: sentry-sdk>=2.66.0
 Requires-Dist: urllib3>=2.2.2
 Requires-Dist: zstandard>=0.18.0
 Requires-Dist: filetype>=1.2.0
@@ -375,6 +375,24 @@ attachments = Usecase("attachments")
 
 See the docstrings on `Client`, `Usecase`, and `Session` for full parameter documentation.
 
+### Tracing
+
+When the Sentry SDK is initialized, every method that talks to Objectstore
+automatically emits a span, with no setup required on your side. If you also
+want a span for the underlying HTTP request, Sentry's `StdlibIntegration`
+covers that, it's enabled by default:
+
+```python
+import sentry_sdk
+
+sentry_sdk.init(
+    dsn="...",
+    traces_sample_rate=1.0,
+    # Optional: controls which hosts get `sentry-trace`/`baggage` headers.
+    # trace_propagation_targets=["http://objectstore"],
+)
+```
+
 ## Development
 
 ### Environment Setup

{objectstore_client-0.2.3 → objectstore_client-0.2.5}/README.md

@@ -256,6 +256,24 @@ attachments = Usecase("attachments")
 
 See the docstrings on `Client`, `Usecase`, and `Session` for full parameter documentation.
 
+### Tracing
+
+When the Sentry SDK is initialized, every method that talks to Objectstore
+automatically emits a span, with no setup required on your side. If you also
+want a span for the underlying HTTP request, Sentry's `StdlibIntegration`
+covers that, it's enabled by default:
+
+```python
+import sentry_sdk
+
+sentry_sdk.init(
+    dsn="...",
+    traces_sample_rate=1.0,
+    # Optional: controls which hosts get `sentry-trace`/`baggage` headers.
+    # trace_propagation_targets=["http://objectstore"],
+)
+```
+
 ## Development
 
 ### Environment Setup

{objectstore_client-0.2.3 → objectstore_client-0.2.5}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "objectstore-client"
-version = "0.2.3"
+version = "0.2.5"
 description = "Client SDK for Objectstore, the Sentry object storage platform"
 readme = "README.md"
 authors = [{ name = "Sentry", email = "oss@sentry.io" }]
 license = { file = "LICENSE.md" }
 requires-python = ">=3.11"
 dependencies = [
-    "sentry-sdk>=2.42.1",
+    "sentry-sdk>=2.66.0",
     "urllib3>=2.2.2",
     "zstandard>=0.18.0",
     "filetype>=1.2.0",

{objectstore_client-0.2.3 → objectstore_client-0.2.5}/src/objectstore_client/client.py

@@ -5,6 +5,7 @@ import warnings
 from collections.abc import Mapping, Sequence
 from dataclasses import asdict, dataclass
 from datetime import UTC, datetime, timedelta
+from importlib.metadata import version
 from io import BytesIO
 from typing import IO, Any, Literal, NamedTuple, cast
 from urllib.parse import urlparse
@@ -34,10 +35,14 @@ from objectstore_client.metrics import (
 )
 from objectstore_client.multipart import MultipartUpload
 from objectstore_client.scope import Scope
+from objectstore_client.tracing import storage_span
 
 # Query parameter carrying a JWT, mirroring the `x-os-auth` header.
 PARAM_AUTH = "os_auth"
 
+# Identifies this library to the server, mirroring the Rust client's user agent.
+USER_AGENT = f"objectstore-client/{version('objectstore-client')}"
+
 
 class GetResponse(NamedTuple):
     metadata: Metadata
@@ -100,8 +105,13 @@ class Client:
             "http://objectstore:8888"). metrics_backend: Optional metrics backend for
             tracking storage operations. Defaults to ``NoOpMetricsBackend`` if not
             provided.
-        propagate_traces: Whether to propagate Sentry trace headers in requests to
-            objectstore. Defaults to ``False``.
+        propagate_traces: **Deprecated.** Use Sentry's ``StdlibIntegration``
+            instead; it propagates traces on the underlying HTTP request
+            regardless of this flag, unless the host application's Sentry SDK
+            is configured to opt out.
+
+            This only controls headers this client adds itself. Defaults to
+            ``False``.
         retries: Number of connection retries for failed requests.
             Defaults to ``3`` if not specified. **Note:** only connection failures are
             retried, not read failures (as compression streams cannot be rewound).
@@ -122,7 +132,9 @@ class Client:
 
         connection_kwargs: Additional keyword arguments to pass to the underlying
             urllib3 connection pool (e.g., custom headers, SSL settings, advanced
-            timeouts).
+            timeouts). By default, requests carry a ``User-Agent`` header of
+            ``objectstore-client/{version}``; pass a ``headers`` mapping with a
+            ``User-Agent`` key here to override it.
         token: A ``SecretKey`` that signs a fresh JWT for each request
             using an EdDSA keypair, or a static pre-signed JWT string used
             as-is for every request. Use a ``SecretKey`` for internal
@@ -140,6 +152,14 @@ class Client:
         connection_kwargs: Mapping[str, Any] | None = None,
         token: TokenProvider | None = None,
     ):
+        if propagate_traces:
+            warnings.warn(
+                "`propagate_traces` is deprecated; Sentry's `StdlibIntegration` "
+                "already propagates traces on the underlying HTTP request",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         connection_kwargs_to_use = asdict(_ConnectionDefaults())
 
         if retries:
@@ -158,6 +178,10 @@ class Client:
         if connection_kwargs:
             connection_kwargs_to_use = {**connection_kwargs_to_use, **connection_kwargs}
 
+        headers = urllib3.HTTPHeaderDict({"User-Agent": USER_AGENT})
+        headers.update(connection_kwargs_to_use.get("headers") or {})
+        connection_kwargs_to_use["headers"] = headers
+
         self._pool = urllib3.connectionpool.connection_from_url(
             base_url, **connection_kwargs_to_use
         )
@@ -248,12 +272,29 @@ class Session:
         """
         if not isinstance(self._token, SecretKey):
             raise ValueError("no secret key configured on this session")
-        return self._token.token_for_scope(
-            self._usecase.name,
-            self._scope,
-            permissions,
-            expiry_seconds,
+
+        resolved_expiry = (
+            expiry_seconds if expiry_seconds is not None else self._token.expiry_seconds
         )
+        resolved_permissions = (
+            permissions if permissions is not None else self._token.permissions
+        )
+        with storage_span(
+            "mint_token",
+            self._usecase,
+            self._scope,
+            expiry_seconds=resolved_expiry,
+        ) as span:
+            token = self._token.token_for_scope(
+                self._usecase.name,
+                self._scope,
+                permissions,
+                expiry_seconds,
+            )
+            span.set_attribute(
+                "objectstore.permissions", [str(p) for p in resolved_permissions]
+            )
+            return token
 
     def _auth_token(self) -> str | None:
         """Returns a token for internal auth headers."""
@@ -391,9 +432,12 @@ class Session:
         if key == "":
             key = None
 
-        with measure_storage_operation(
-            self._metrics_backend, "put", self._usecase.name
-        ) as metric_emitter:
+        with (
+            storage_span("put", self._usecase, self._scope) as span,
+            measure_storage_operation(
+                self._metrics_backend, "put", self._usecase.name
+            ) as metrics,
+        ):
             retries = None  # by default use the pool's value, set by the Client
             if compress_with != "none":
                 # For on-the-fly compression, don't attempt read retries,
@@ -419,9 +463,21 @@ class Session:
             # Must do this after streaming `body` as that's what is responsible
             # for advancing the seek position in both streams
             if precompressed is None:
-                metric_emitter.record_uncompressed_size(original_body.tell())
+                metrics.record_uncompressed_size(original_body.tell())
             if encoding != "none":
-                metric_emitter.record_compressed_size(body.tell(), encoding)
+                metrics.record_compressed_size(body.tell(), encoding)
+
+            # Set after the response, since the key may be server-generated.
+            span.set_attribute("objectstore.key", res["key"])
+            span.set_attribute("objectstore.compression", encoding)
+            if metrics.uncompressed_size is not None:
+                span.set_attribute(
+                    "objectstore.uncompressed_size", metrics.uncompressed_size
+                )
+            if metrics.compressed_size is not None:
+                span.set_attribute(
+                    "objectstore.compressed_size", metrics.compressed_size
+                )
             return res["key"]
 
     def get(
@@ -446,38 +502,49 @@ class Session:
         """
 
         headers = self._make_headers()
-        with measure_storage_operation(
-            self._metrics_backend, "get", self._usecase.name
-        ):
-            response = self._pool.request(
-                "GET",
-                self._make_url(key),
-                preload_content=False,
-                decode_content=False,
-                headers=headers,
-            )
-            if response.status == 404:
-                response.read()  # drain body so urllib3 returns the connection
-                return None
-            raise_for_status(response)
-        # OR: should I use `response.stream()`?
-        stream = cast(IO[bytes], response)
-        metadata = Metadata.from_headers(response.headers)
-
-        encoding_accepted = accept_encoding is not None and (
-            "*" in accept_encoding or metadata.compression in accept_encoding
-        )
-        if metadata.compression and decompress and not encoding_accepted:
-            if metadata.compression != "zstd":
-                raise NotImplementedError(
-                    "Transparent decoding of anything but `zstd` is not implemented yet"
+        with storage_span("get", self._usecase, self._scope, key=key) as span:
+            with measure_storage_operation(
+                self._metrics_backend, "get", self._usecase.name
+            ):
+                response = self._pool.request(
+                    "GET",
+                    self._make_url(key),
+                    preload_content=False,
+                    decode_content=False,
+                    headers=headers,
                 )
+                if response.status == 404:
+                    response.read()  # drain body so urllib3 returns the connection
+                    span.set_attribute("objectstore.found", False)
+                    return None
+                raise_for_status(response)
+                span.set_attribute("objectstore.found", True)
+
+            # OR: should I use `response.stream()`?
+            stream = cast(IO[bytes], response)
+            metadata = Metadata.from_headers(response.headers)
+            span.set_attribute(
+                "objectstore.compression", metadata.compression or "none"
+            )
 
-            metadata.compression = None
-            dctx = zstandard.ZstdDecompressor()
-            stream = dctx.stream_reader(stream, read_across_frames=True)
-
-        return GetResponse(metadata, stream)
+            encoding_accepted = accept_encoding is not None and (
+                "*" in accept_encoding or metadata.compression in accept_encoding
+            )
+            decompressed = False
+            if metadata.compression and decompress and not encoding_accepted:
+                if metadata.compression != "zstd":
+                    raise NotImplementedError(
+                        "Transparent decoding of anything but `zstd` is not "
+                        "implemented yet"
+                    )
+
+                metadata.compression = None
+                dctx = zstandard.ZstdDecompressor()
+                stream = dctx.stream_reader(stream, read_across_frames=True)
+                decompressed = True
+
+            span.set_attribute("objectstore.decompressed", decompressed)
+            return GetResponse(metadata, stream)
 
     def object_url(self, key: str, token_validity: timedelta | None = None) -> str:
         """
@@ -548,22 +615,32 @@ class Session:
             )
         duration_secs = math.ceil(duration.total_seconds())
 
-        # `_make_url` already percent-encodes the path identically to the wire.
-        encoded_path = self._make_url(key)
-        timestamp = datetime.now(tz=UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
-        encoded_query = utils.encode_query(
-            f"{presign.PARAM_KID}={self._token.kid}"
-            f"&{presign.PARAM_TIMESTAMP}={timestamp}"
-            f"&{presign.PARAM_DURATION}={duration_secs}"
-        )
+        with storage_span(
+            "presign",
+            self._usecase,
+            self._scope,
+            key=key,
+            method=method,
+            duration_seconds=duration_secs,
+        ):
+            # `_make_url` already percent-encodes the path identically to the wire.
+            encoded_path = self._make_url(key)
+            timestamp = datetime.now(tz=UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+            encoded_query = utils.encode_query(
+                f"{presign.PARAM_KID}={self._token.kid}"
+                f"&{presign.PARAM_TIMESTAMP}={timestamp}"
+                f"&{presign.PARAM_DURATION}={duration_secs}"
+            )
 
-        canonical = presign.build_canonical_form(method, encoded_path, encoded_query)
-        signature = self._token.signature_for_canonical_form(canonical)
+            canonical = presign.build_canonical_form(
+                method, encoded_path, encoded_query
+            )
+            signature = self._token.signature_for_canonical_form(canonical)
 
-        return (
-            f"{self._base_url()}"
-            f"{encoded_path}?{encoded_query}&{presign.PARAM_SIG}={signature}"
-        )
+            return (
+                f"{self._base_url()}"
+                f"{encoded_path}?{encoded_query}&{presign.PARAM_SIG}={signature}"
+            )
 
     def head(self, key: str) -> Metadata | None:
         """
@@ -575,8 +652,11 @@ class Session:
         and therefore bumps its expiration.
         """
         headers = self._make_headers()
-        with measure_storage_operation(
-            self._metrics_backend, "head", self._usecase.name
+        with (
+            storage_span("head", self._usecase, self._scope, key=key) as span,
+            measure_storage_operation(
+                self._metrics_backend, "head", self._usecase.name
+            ),
         ):
             response = self._pool.request(
                 "HEAD",
@@ -585,8 +665,10 @@ class Session:
                 preload_content=True,
             )
             if response.status == 404:
+                span.set_attribute("objectstore.found", False)
                 return None
             raise_for_status(response)
+            span.set_attribute("objectstore.found", True)
             return Metadata.from_headers(response.headers)
 
     def delete(self, key: str) -> None:
@@ -595,8 +677,11 @@ class Session:
         """
 
         headers = self._make_headers()
-        with measure_storage_operation(
-            self._metrics_backend, "delete", self._usecase.name
+        with (
+            storage_span("delete", self._usecase, self._scope, key=key),
+            measure_storage_operation(
+                self._metrics_backend, "delete", self._usecase.name
+            ),
         ):
             response = self._pool.request(
                 "DELETE",
@@ -657,8 +742,13 @@ class Session:
         if key == "":
             key = None
 
-        with measure_storage_operation(
-            self._metrics_backend, "multipart.initiate", self._usecase.name
+        with (
+            storage_span(
+                "multipart.initiate", self._usecase, self._scope, key=key
+            ) as span,
+            measure_storage_operation(
+                self._metrics_backend, "multipart.initiate", self._usecase.name
+            ),
         ):
             response = self._pool.request(
                 "POST" if not key else "PUT",
@@ -669,6 +759,9 @@ class Session:
             )
             raise_for_status(response)
             res = response.json()
+            # Set after the response, since the key may be server-generated.
+            span.set_attribute("objectstore.key", res["key"])
+            span.set_attribute("objectstore.upload_id", res["upload_id"])
             return MultipartUpload(self, res["key"], res["upload_id"])
 
     def resume_multipart_upload(self, key: str, upload_id: str) -> MultipartUpload:

{objectstore_client-0.2.3 → objectstore_client-0.2.5}/src/objectstore_client/multipart.py

@@ -11,6 +11,7 @@ from urllib.parse import urlencode
 
 from objectstore_client.errors import RequestError, raise_for_status
 from objectstore_client.metrics import measure_storage_operation
+from objectstore_client.tracing import storage_span
 
 if TYPE_CHECKING:
     from objectstore_client.client import Session
@@ -118,11 +119,22 @@ class MultipartUpload:
         )
         url = self._session._make_multipart_url("parts", self._key, query)
 
-        with measure_storage_operation(
-            self._session._metrics_backend,
-            "multipart.put_part",
-            self._session._usecase.name,
-        ) as metric_emitter:
+        with (
+            storage_span(
+                "multipart.put_part",
+                self._session._usecase,
+                self._session._scope,
+                key=self._key,
+                upload_id=self._upload_id,
+                part_number=part_number,
+                size=content_length,
+            ),
+            measure_storage_operation(
+                self._session._metrics_backend,
+                "multipart.put_part",
+                self._session._usecase.name,
+            ) as metric_emitter,
+        ):
             response = self._session._pool.request(
                 "PUT",
                 url,
@@ -141,57 +153,73 @@ class MultipartUpload:
         all_parts: list[PartInfo] = []
         marker: int | None = None
 
-        while True:
-            params: dict[str, str] = {"upload_id": self._upload_id}
-            if marker is not None:
-                params["part_number_marker"] = str(marker)
+        with storage_span(
+            "multipart.list_parts",
+            self._session._usecase,
+            self._session._scope,
+            key=self._key,
+            upload_id=self._upload_id,
+        ) as span:
+            while True:
+                params: dict[str, str] = {"upload_id": self._upload_id}
+                if marker is not None:
+                    params["part_number_marker"] = str(marker)
+
+                query = urlencode(params)
+                url = self._session._make_multipart_url("parts", self._key, query)
+                headers = self._session._make_headers()
+
+                response = self._session._pool.request(
+                    "GET",
+                    url,
+                    headers=headers,
+                    preload_content=True,
+                )
+                raise_for_status(response)
+                data = response.json()
+
+                for p in data["parts"]:
+                    all_parts.append(
+                        PartInfo(
+                            part_number=p["part_number"],
+                            etag=p["etag"],
+                            last_modified=datetime.fromisoformat(p["last_modified"]),
+                            size=p["size"],
+                        )
+                    )
+
+                if not data["is_truncated"]:
+                    span.set_attribute("objectstore.part_count", len(all_parts))
+                    return all_parts
+
+                marker = data.get("next_part_number_marker")
+                if marker is None:
+                    raise RequestError(
+                        "Server returned is_truncated=true but no "
+                        "next_part_number_marker",
+                        status=200,
+                        response=str(data),
+                    )
 
-            query = urlencode(params)
-            url = self._session._make_multipart_url("parts", self._key, query)
+    def abort(self) -> None:
+        """Aborts this multipart upload, cleaning up server-side state."""
+        with storage_span(
+            "multipart.abort",
+            self._session._usecase,
+            self._session._scope,
+            key=self._key,
+            upload_id=self._upload_id,
+        ):
+            query = urlencode({"upload_id": self._upload_id})
+            url = self._session._make_multipart_url(None, self._key, query)
             headers = self._session._make_headers()
 
             response = self._session._pool.request(
-                "GET",
+                "DELETE",
                 url,
                 headers=headers,
-                preload_content=True,
             )
             raise_for_status(response)
-            data = response.json()
-
-            for p in data["parts"]:
-                all_parts.append(
-                    PartInfo(
-                        part_number=p["part_number"],
-                        etag=p["etag"],
-                        last_modified=datetime.fromisoformat(p["last_modified"]),
-                        size=p["size"],
-                    )
-                )
-
-            if not data["is_truncated"]:
-                return all_parts
-
-            marker = data.get("next_part_number_marker")
-            if marker is None:
-                raise RequestError(
-                    "Server returned is_truncated=true but no next_part_number_marker",
-                    status=200,
-                    response=str(data),
-                )
-
-    def abort(self) -> None:
-        """Aborts this multipart upload, cleaning up server-side state."""
-        query = urlencode({"upload_id": self._upload_id})
-        url = self._session._make_multipart_url(None, self._key, query)
-        headers = self._session._make_headers()
-
-        response = self._session._pool.request(
-            "DELETE",
-            url,
-            headers=headers,
-        )
-        raise_for_status(response)
 
     def complete(self, parts: Sequence[CompletePart | PartInfo]) -> str:
         """Completes the multipart upload, assembling all parts into the final object.
@@ -216,10 +244,20 @@ class MultipartUpload:
             }
         ).encode("utf-8")
 
-        with measure_storage_operation(
-            self._session._metrics_backend,
-            "multipart.complete",
-            self._session._usecase.name,
+        with (
+            storage_span(
+                "multipart.complete",
+                self._session._usecase,
+                self._session._scope,
+                key=self._key,
+                upload_id=self._upload_id,
+                part_count=len(sorted_parts),
+            ),
+            measure_storage_operation(
+                self._session._metrics_backend,
+                "multipart.complete",
+                self._session._usecase.name,
+            ),
         ):
             response = self._session._pool.request(
                 "POST",

objectstore_client-0.2.5/src/objectstore_client/tracing.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+import sentry_sdk
+from sentry_sdk.traces import StreamedSpan
+
+from objectstore_client.scope import Scope
+
+if TYPE_CHECKING:
+    from sentry_sdk._types import Attributes
+
+    from objectstore_client.client import Usecase
+
+# Origin recorded on every span this module creates, per Sentry's span-origin
+# convention (`auto.<integration>.<library>`).
+SPAN_ORIGIN = "auto.objectstore.client"
+
+SpanAttributeValue = str | int | float | bool | list[str] | list[int] | list[float]
+
+
+@contextmanager
+def storage_span(
+    operation: str,
+    usecase: Usecase,
+    scope: Scope,
+    **attributes: SpanAttributeValue | None,
+) -> Generator[StreamedSpan]:
+    """
+    Starts a span for a single Objectstore operation.
+
+    ``operation`` is the same literal already passed to
+    ``measure_storage_operation``, so the span's ``op``
+    (``objectstore.<operation>``), its name, and the ``storage.<operation>.*``
+    metrics all derive from one source. Keyword arguments become
+    ``objectstore.<key>`` span attributes, with ``None`` values dropped so
+    call sites can pass optionals inline; attributes that are only known after
+    the request completes can be set on the yielded span instead.
+    """
+    op = f"objectstore.{operation}"
+    name = f"{op} {usecase.name}"
+    span_attributes: Attributes = {
+        "sentry.op": op,
+        "sentry.origin": SPAN_ORIGIN,
+        "objectstore.usecase": usecase.name,
+    }
+    for scope_key, scope_value in scope.dict().items():
+        span_attributes[f"objectstore.scopes.{scope_key}"] = scope_value
+    for attribute_key, attribute_value in attributes.items():
+        if attribute_value is not None:
+            span_attributes[f"objectstore.{attribute_key}"] = attribute_value
+
+    with sentry_sdk.traces.start_span(name=name, attributes=span_attributes) as span:
+        yield span