vercel-internal-telemetry 0.7.0__py3-none-any.whl

vercel/internal/telemetry/__init__.py

@@ -0,0 +1,6 @@
+"""Internal telemetry functionality for Vercel Python packages."""
+
+from vercel.internal.telemetry.client import TelemetryClient
+from vercel.internal.telemetry.tracker import track
+
+__all__ = ["TelemetryClient", "track"]

vercel/internal/telemetry/client.py

@@ -0,0 +1,179 @@
+"""Telemetry client for tracking SDK usage."""
+
+import atexit
+import os
+import time
+import uuid
+from typing import Any
+
+import httpx
+
+from vercel.internal.telemetry.credentials import extract_credentials
+
+_TELEMETRY_ENABLED = os.getenv("VERCEL_TELEMETRY_DISABLED") != "1"
+_TELEMETRY_BRIDGE_URL = os.getenv(
+    "VERCEL_TELEMETRY_BRIDGE_URL",
+    "https://telemetry.vercel.com/api/vercel-py/v1/events",
+)
+
+
+class TelemetryClient:
+    """Client for sending telemetry events."""
+
+    def __init__(self, session_id: str | None = None):
+        """Initialize telemetry client.
+
+        Args:
+            session_id: Unique session ID. If not provided, generates a new one.
+        """
+        self.session_id = session_id or str(uuid.uuid4())
+        self._events: list[dict[str, Any]] = []
+        self._enabled = _TELEMETRY_ENABLED
+        # Register flush at exit so telemetry events are sent before program termination
+        atexit.register(self._flush_at_exit)
+
+    def track(
+        self,
+        event: str,
+        *,
+        user_id: str | None = None,
+        team_id: str | None = None,
+        project_id: str | None = None,
+        token: str | None = None,
+        **fields: Any,
+    ) -> None:
+        """
+        Track a generic telemetry event.
+
+        This is the single entry point for tracking all telemetry events.
+        Use the @telemetry decorator or track() function from tracker module
+        instead of calling this directly.
+
+        Args:
+            event: The event/action being tracked (e.g., 'blob_put', 'cache_get')
+            user_id: Optional user ID
+            team_id: Optional team ID
+            project_id: Optional project ID
+            token: Optional token to extract credentials from
+            **fields: Additional event fields (whitelisted by schema)
+        """
+        if not self._enabled:
+            return
+
+        # Extract credentials if not explicitly provided
+        extracted_user_id, extracted_team_id, extracted_project_id = extract_credentials(
+            token=token,
+            team_id=team_id,
+            project_id=project_id,
+            user_id=user_id,
+        )
+
+        # Use explicitly provided values, fall back to extracted
+        final_user_id = user_id or extracted_user_id
+        final_team_id = team_id or extracted_team_id
+        final_project_id = project_id or extracted_project_id
+
+        # Whitelist fields allowed by the generic schema for vercel_py
+        allowed_keys = {
+            "access",
+            "content_type",
+            "size_bytes",
+            "multipart",
+            "count",
+            "ttl_seconds",
+            "has_tags",
+            "hit",
+            "target",
+            "force_new",
+        }
+        event_fields: dict[str, Any] = {}
+        for k, v in fields.items():
+            if k in allowed_keys:
+                if isinstance(v, float) and v.is_integer():
+                    event_fields[k] = int(v)
+                else:
+                    event_fields[k] = v
+
+        event_data: dict[str, Any] = {
+            "id": str(uuid.uuid4()),
+            "event_time": int(time.time() * 1000),
+            "session_id": self.session_id,
+            "action": event,
+        }
+
+        if final_user_id:
+            event_data["user_id"] = final_user_id
+        if final_team_id:
+            event_data["team_id"] = final_team_id
+        if final_project_id:
+            event_data["project_id"] = final_project_id
+
+        # Merge whitelisted fields
+        event_data.update(event_fields)
+        self._events.append(event_data)
+
+    def flush(self) -> None:
+        """Flush all accumulated events to the telemetry bridge.
+
+        This is a synchronous method that can be safely called from atexit
+        handlers or from within existing event loops.
+        """
+        if not self._enabled or not self._events:
+            return
+
+        # Batch events by action type for efficient sending
+        batch: dict[str, list] = {}
+        for event in self._events:
+            action = event.get("action", "unknown")
+            if action not in batch:
+                batch[action] = []
+            batch[action].append(event)
+
+        if not batch:
+            return
+
+        try:
+            headers = {
+                "x-vercel-py-session-id": self.session_id,
+                "Content-Type": "application/json",
+            }
+
+            # Group all events under "generic" key since we're using generic schema
+            payload = {"generic": [event for events in batch.values() for event in events]}
+
+            with httpx.Client(timeout=30.0) as client:
+                response = client.post(
+                    _TELEMETRY_BRIDGE_URL,
+                    headers=headers,
+                    json=payload,
+                )
+
+                if response.status_code == 204:
+                    if _TELEMETRY_DEBUG():
+                        print(f"Telemetry events tracked: {len(self._events)} events")
+                    # Clear events only on successful delivery
+                    self._events.clear()
+                else:
+                    if _TELEMETRY_DEBUG():
+                        print(f"Failed to send telemetry: {response.status_code}")
+
+        except Exception as e:
+            if _TELEMETRY_DEBUG():
+                print(f"Telemetry error: {e}")
+
+    def reset(self) -> None:
+        """Clear accumulated events."""
+        self._events.clear()
+
+    def _flush_at_exit(self) -> None:
+        """Flush events at program exit (called by atexit)."""
+        try:
+            self.flush()
+        except Exception:
+            # Silently fail - don't interrupt program exit
+            pass
+
+
+def _TELEMETRY_DEBUG() -> bool:
+    """Check if telemetry debugging is enabled."""
+    return os.getenv("VERCEL_TELEMETRY_DEBUG") == "1"

vercel/internal/telemetry/credentials.py

@@ -0,0 +1,68 @@
+"""Utilities for extracting credentials (user_id, team_id, project_id) from various sources."""
+
+import os
+
+from vercel.oidc import decode_oidc_payload
+from vercel.oidc.utils import find_project_info
+
+
+def extract_credentials(
+    *,
+    token: str | None = None,
+    team_id: str | None = None,
+    project_id: str | None = None,
+    user_id: str | None = None,
+) -> tuple[str | None, str | None, str | None]:
+    """
+    Extract user_id, team_id, and project_id from various sources.
+
+    Priority order:
+    1. Explicitly provided parameters
+    2. Environment variables (VERCEL_PROJECT_ID, VERCEL_TEAM_ID)
+    3. OIDC token payload (if available)
+    4. .vercel/project.json (for local dev)
+
+    Returns:
+        Tuple of (user_id, team_id, project_id). Each may be None if not found.
+    """
+    # Start with explicitly provided values
+    resolved_user_id = user_id
+    resolved_team_id = team_id
+    resolved_project_id = project_id
+
+    # Check environment variables
+    if not resolved_project_id:
+        resolved_project_id = os.getenv("VERCEL_PROJECT_ID")
+    if not resolved_team_id:
+        resolved_team_id = os.getenv("VERCEL_TEAM_ID")
+
+    # Try to extract from OIDC token if available
+    if token:
+        try:
+            payload = decode_oidc_payload(token)
+            if not resolved_project_id:
+                resolved_project_id = payload.get("project_id")
+            if not resolved_team_id:
+                # OIDC tokens may have owner_id as team_id
+                resolved_team_id = payload.get("owner_id") or payload.get("team_id")
+        except Exception:
+            # Silently fail - OIDC may not be available or token may be invalid
+            pass
+
+    # Try to extract from .vercel/project.json for local dev
+    if not resolved_project_id or not resolved_team_id:
+        try:
+            project_info = find_project_info()
+            if not resolved_project_id and project_info.get("projectId"):
+                resolved_project_id = project_info["projectId"]
+            if not resolved_team_id and project_info.get("teamId"):
+                resolved_team_id = project_info["teamId"]
+        except Exception:
+            # Silently fail - .vercel directory may not exist (production context)
+            pass
+
+    # Note: user_id typically requires API call to determine from token
+    # For now, we leave it as None unless explicitly provided
+    # This is acceptable as user_id may not always be available in all contexts
+
+    return (resolved_user_id, resolved_team_id, resolved_project_id)

vercel/internal/telemetry/tracker.py

@@ -0,0 +1,292 @@
+"""Telemetry tracking helpers for SDK operations."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import threading
+from collections.abc import Callable, Mapping, Sequence
+from typing import TYPE_CHECKING, Any, Literal, TypeVar
+
+if TYPE_CHECKING:
+    from vercel.internal.telemetry.client import TelemetryClient
+
+# Singleton telemetry client instance with thread-safe initialization
+_telemetry_client = None
+_telemetry_client_lock = threading.Lock()
+
+T = TypeVar("T", bound=Callable[..., Any])
+
+
+def get_client() -> TelemetryClient | None:
+    """Get or create the telemetry client singleton (thread-safe).
+
+    Returns:
+        TelemetryClient instance, or None if initialization fails.
+    """
+    global _telemetry_client
+    # Fast path without lock
+    client = _telemetry_client
+    if client is not None:
+        return client
+    # Slow path with double-checked locking
+    with _telemetry_client_lock:
+        client = _telemetry_client
+        if client is None:
+            try:
+                from vercel.internal.telemetry.client import TelemetryClient
+
+                _telemetry_client = TelemetryClient()
+            except Exception:
+                _telemetry_client = None
+        return _telemetry_client
+
+
+def track(event: str, **attrs: Any) -> None:
+    """Track a telemetry event.
+
+    This is the main entry point for tracking telemetry events.
+    All attributes are passed through to the client's track method,
+    which handles credential extraction and field whitelisting.
+
+    Args:
+        event: The event/action being tracked (e.g., 'blob_put', 'cache_get')
+        **attrs: Additional event attributes (e.g., user_id, team_id, token, etc.)
+    """
+    client = get_client()
+    if client is None:
+        return
+    try:
+        client.track(event, **attrs)
+    except Exception:
+        # Silently fail - don't impact user's operation
+        pass
+
+
+def with_telemetry(
+    action: str,
+    extract_metadata: Callable[..., dict[str, Any]] | None = None,
+    extract_token: Callable[..., str | None] | None = None,
+    extract_team_id: Callable[..., str | None] | None = None,
+    extract_project_id: Callable[..., str | None] | None = None,
+) -> Callable[[T], T]:
+    """
+    Create a decorator that automatically tracks telemetry for a function.
+
+    Usage:
+        @with_telemetry(
+            action="blob_put",
+            extract_metadata=lambda self, path, size=None: {"size": size}
+        )
+        def put(self, path, size=None):
+            ...
+
+    Args:
+        action: The action name to track
+        extract_metadata: Optional function to extract metadata from function call
+        extract_token: Optional function to extract token from function call
+        extract_team_id: Optional function to extract team_id from function call
+        extract_project_id: Optional function to extract project_id from function call
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(func: T) -> T:
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            # Execute the original function
+            result = func(*args, **kwargs)
+
+            # Extract metadata and credentials
+            metadata = None
+            token = None
+            team_id = None
+            project_id = None
+
+            if extract_metadata:
+                try:
+                    metadata = extract_metadata(*args, **kwargs)
+                except Exception:
+                    pass
+
+            if extract_token:
+                try:
+                    token = extract_token(*args, **kwargs)
+                except Exception:
+                    pass
+
+            if extract_team_id:
+                try:
+                    team_id = extract_team_id(*args, **kwargs)
+                except Exception:
+                    pass
+
+            if extract_project_id:
+                try:
+                    project_id = extract_project_id(*args, **kwargs)
+                except Exception:
+                    pass
+
+            # Track the event
+            track(
+                action,
+                token=token,
+                team_id=team_id,
+                project_id=project_id,
+                **(metadata or {}),
+            )
+
+            return result
+
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            # Execute the original function
+            result = await func(*args, **kwargs)
+
+            # Extract metadata and credentials (same as sync)
+            metadata = None
+            token = None
+            team_id = None
+            project_id = None
+
+            if extract_metadata:
+                try:
+                    metadata = extract_metadata(*args, **kwargs)
+                except Exception:
+                    pass
+
+            if extract_token:
+                try:
+                    token = extract_token(*args, **kwargs)
+                except Exception:
+                    pass
+
+            if extract_team_id:
+                try:
+                    team_id = extract_team_id(*args, **kwargs)
+                except Exception:
+                    pass
+
+            if extract_project_id:
+                try:
+                    project_id = extract_project_id(*args, **kwargs)
+                except Exception:
+                    pass
+
+            # Track the event
+            track(
+                action,
+                token=token,
+                team_id=team_id,
+                project_id=project_id,
+                **(metadata or {}),
+            )
+
+            return result
+
+        # Return appropriate wrapper based on whether function is async
+        import inspect
+
+        if inspect.iscoroutinefunction(func):
+            return async_wrapper  # type: ignore
+        else:
+            return sync_wrapper  # type: ignore
+
+    return decorator
+
+
+def telemetry(
+    event: str,
+    capture: Sequence[str] | None = None,
+    derive: Mapping[str, Callable[[tuple, dict, Any], Any]] | None = None,
+    when: Literal["before", "after"] = "after",
+) -> Callable[[T], T]:
+    """Decorator to emit telemetry around a function call.
+
+    Args:
+        event: The event name to track
+        capture: List of parameter names to capture from args/kwargs.
+            Names are resolved against the function signature so positional calls
+            are handled correctly.
+        derive: Mapping of output field -> lambda(args, kwargs, result).
+            The callable receives (args, kwargs, result) and should return
+            the value for that field.
+        when: Emit "before" the call, or "after" the call (default: "after").
+
+    Returns:
+        Decorator function
+
+    Example:
+        @telemetry(
+            event="blob_delete",
+            capture=["token"],
+            derive={"count": lambda args, kwargs, rv: len(kwargs.get("urls", []))},
+            when="after",
+        )
+        def delete(urls: list[str], *, token: str | None = None) -> None:
+            ...
+    """
+
+    def decorator(func: T) -> T:
+        is_coro = inspect.iscoroutinefunction(func)
+        sig = inspect.signature(func)
+
+        def _emit(ev: str, args: tuple, kwargs: dict, result: Any) -> None:
+            try:
+                attrs: dict[str, Any] = {}
+                # Bind parameters for positional resolution
+                try:
+                    bound = sig.bind_partial(*args, **kwargs)
+                    params: dict[str, Any] = dict(bound.arguments)  # name -> value
+                except Exception:
+                    params = {}
+
+                # Capture selected params by name
+                if capture:
+                    for name in capture:
+                        if name in kwargs:
+                            attrs[name] = kwargs[name]
+                        elif name in params:
+                            attrs[name] = params[name]
+                        # else: silently skip if not provided
+
+                # Derived attributes
+                if derive:
+                    for field, getter in derive.items():
+                        try:
+                            attrs[field] = getter(args, kwargs, result)
+                        except Exception:
+                            # ignore individual derivation errors
+                            pass
+
+                track(ev, **attrs)
+            except Exception:
+                # Silently fail - don't impact user's operation
+                pass
+
+        @functools.wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            if when == "before":
+                _emit(event, args, kwargs, None)
+            result = await func(*args, **kwargs)
+            if when == "after":
+                _emit(event, args, kwargs, result)
+            return result
+
+        @functools.wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            if when == "before":
+                _emit(event, args, kwargs, None)
+            result = func(*args, **kwargs)
+            if when == "after":
+                _emit(event, args, kwargs, result)
+            return result
+
+        return async_wrapper if is_coro else sync_wrapper  # type: ignore
+
+    return decorator
+
+
+# Specific wrapper functions are intentionally removed;
+# use generic `track(event, **attrs)` or the `telemetry` decorator instead.

vercel/internal/telemetry/version.py

@@ -0,0 +1 @@
+__version__ = "0.7.0"

vercel_internal_telemetry-0.7.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: vercel-internal-telemetry
+Version: 0.7.0
+Summary: Internal telemetry helpers for Vercel Python packages
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27.0
+Requires-Dist: vercel-oidc>=0.7.0
+Description-Content-Type: text/markdown
+
+# Internal Telemetry
+
+`vercel.internal.telemetry` provides shared internal telemetry helpers for
+Vercel Python packages.

vercel_internal_telemetry-0.7.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+vercel/internal/telemetry/__init__.py,sha256=wlso1BcdmaRrpwKGGbgNyh-zC8xA9g4i7YQNeoeudZA,221
+vercel/internal/telemetry/client.py,sha256=pWzjtSDEAuU7Dd2EQjzRaT-k6Al-pgz_RZsInlLkfIY,5799
+vercel/internal/telemetry/credentials.py,sha256=oOv1yPfdxa4MkwC5tnscNN0cdY3_VI907Kmtcsec0Uk,2540
+vercel/internal/telemetry/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vercel/internal/telemetry/tracker.py,sha256=ARB_lbKiXZeDTl4cdm1erbpYyuevpl6gUFBkZVXn5Sc,9326
+vercel/internal/telemetry/version.py,sha256=RaANGbRu5e-vehwXI1-Qe2ggPPfs1TQaZj072JdbLk4,22
+vercel_internal_telemetry-0.7.0.dist-info/METADATA,sha256=OPk4eHpIf7NT0ZJR3YRIJkA8jUpkbQ4qx70GL_o5RX0,430
+vercel_internal_telemetry-0.7.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+vercel_internal_telemetry-0.7.0.dist-info/licenses/LICENSE,sha256=ZhFC5TwxPSu14bBV9cCjkAFFD_G14nuJ3EvH3ppjUso,1069
+vercel_internal_telemetry-0.7.0.dist-info/RECORD,,

vercel_internal_telemetry-0.7.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vercel_internal_telemetry-0.7.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vercel, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.