vercel-internal-telemetry 0.7.0__tar.gz

vercel_internal_telemetry-0.7.0/.gitignore

@@ -0,0 +1,130 @@
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstallerhave
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+.benchmarks/
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+.ruff_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Scrapy
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# PDM
+pdm.lock
+.pdm.toml
+
+# Hatch
+.hatch/
+
+# pyright/mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# pyre
+.pyre/
+
+# pytype
+.pytype/
+
+# Caches
+__pypackages__/
+
+# Editor/project files
+.DS_Store
+.idea/
+.vscode/
+.zed/
+*.swp
+*.swo
+
+# Virtual environments
+.env
+.venv
+.venv.*
+env/
+venv/
+**/.env
+**/.venv
+**/.venv.*
+**/env/
+**/venv/
+ENV/
+env.bak/
+venv.bak/
+
+# dotenv anywhere
+**/.env
+**/.env.*
+**/*.env
+
+.claude

vercel_internal_telemetry-0.7.0/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.

vercel_internal_telemetry-0.7.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,4 @@
+# Internal Telemetry
+
+`vercel.internal.telemetry` provides shared internal telemetry helpers for
+Vercel Python packages.

vercel_internal_telemetry-0.7.0/_vercel_hatch_build.py

@@ -0,0 +1,116 @@
+"""Hatch metadata hook for publish-time workspace dependency bounds."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+from typing import Any
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+from packaging.requirements import Requirement
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python < 3.11
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+class WorkspaceDependenciesMetadataHook(MetadataHookInterface):
+    """Generate package dependencies from the repo-owned dependency table."""
+
+    def update(self, metadata: dict[str, Any]) -> None:
+        """Populate dynamic dependencies for Hatchling metadata generation."""
+        pyproject = _load_pyproject(Path(self.root))
+        release = pyproject.get("tool", {}).get("vercel", {}).get("release", {})
+        dependency_table = release.get("dependencies", {})
+        workspace_sources = pyproject.get("tool", {}).get("uv", {}).get("sources", {})
+        workspace_names = {
+            name for name, source in workspace_sources.items() if source.get("workspace") is True
+        }
+        workspace_root = _find_workspace_root(Path(self.root))
+
+        metadata["dependencies"] = [
+            _rewrite_dependency(requirement, workspace_names, workspace_root)
+            for requirement in dependency_table.get("dependencies", [])
+        ]
+
+
+def _load_pyproject(path: Path) -> dict[str, Any]:
+    with (path / "pyproject.toml").open("rb") as fp:
+        return tomllib.load(fp)
+
+
+def _find_workspace_root(start: Path) -> Path | None:
+    for path in [start, *start.parents]:
+        pyproject = path / "pyproject.toml"
+        if not pyproject.exists():
+            continue
+        data = _load_pyproject(path)
+        if "workspace" in data.get("tool", {}).get("uv", {}):
+            return path
+    return None
+
+
+def _rewrite_dependency(
+    requirement: str,
+    workspace_names: set[str],
+    workspace_root: Path | None,
+) -> str:
+    parsed = Requirement(requirement)
+    normalized = parsed.name.lower().replace("_", "-")
+    if normalized not in workspace_names or workspace_root is None:
+        return requirement
+    return _with_lower_bound(parsed, _read_workspace_version(workspace_root, normalized))
+
+
+def _with_lower_bound(requirement: Requirement, version: str) -> str:
+    extras = f"[{','.join(sorted(requirement.extras))}]" if requirement.extras else ""
+    specifiers = [
+        str(specifier) for specifier in requirement.specifier if specifier.operator != ">="
+    ]
+    specifier_text = ",".join([f">={version}", *specifiers])
+    marker = f" ; {requirement.marker}" if requirement.marker else ""
+    return f"{requirement.name}{extras}{specifier_text}{marker}"
+
+
+def _read_workspace_version(workspace_root: Path, package_name: str) -> str:
+    for pattern in ("src/*/pyproject.toml", "integrations/*/pyproject.toml"):
+        for pyproject_path in workspace_root.glob(pattern):
+            version = _version_from_pyproject(pyproject_path, package_name)
+            if version is not None:
+                return version
+    raise RuntimeError(f"unknown workspace dependency {package_name!r}")
+
+
+def _version_from_pyproject(pyproject_path: Path, package_name: str) -> str | None:
+    data = _load_pyproject(pyproject_path.parent)
+    if data.get("project", {}).get("name") != package_name:
+        return None
+    version_path = pyproject_path.parent / data["tool"]["hatch"]["version"]["path"]
+    module = ast.parse(version_path.read_text(encoding="utf-8"), filename=str(version_path))
+    for node in module.body:
+        value = _version_value(node)
+        if value is None:
+            continue
+        if isinstance(value, ast.Constant) and isinstance(value.value, str):
+            return value.value
+    raise RuntimeError(f"could not find __version__ in {version_path}")
+
+
+def _version_value(node: ast.stmt) -> ast.expr | None:
+    if isinstance(node, ast.Assign) and any(
+        isinstance(target, ast.Name) and target.id == "__version__" for target in node.targets
+    ):
+        return node.value
+    if (
+        isinstance(node, ast.AnnAssign)
+        and isinstance(node.target, ast.Name)
+        and node.target.id == "__version__"
+    ):
+        return node.value
+    return None
+
+
+def get_metadata_hook() -> type[MetadataHookInterface]:
+    """Return the hook class used by Hatchling's custom hook loader."""
+    return WorkspaceDependenciesMetadataHook

vercel_internal_telemetry-0.7.0/hatch_build.py

@@ -0,0 +1,29 @@
+"""Load the shared Vercel Hatch metadata hook."""
+
+from __future__ import annotations
+
+from importlib.util import module_from_spec, spec_from_file_location
+from pathlib import Path
+from types import ModuleType
+
+from hatchling.metadata.plugin.interface import MetadataHookInterface
+
+
+def get_metadata_hook() -> type[MetadataHookInterface]:
+    """Return the shared workspace dependency metadata hook."""
+    return _load_shared_hook().get_metadata_hook()
+
+
+def _load_shared_hook() -> ModuleType:
+    root = Path(__file__).resolve().parent
+    candidates = [root / "../../scripts/hatch_build.py", root / "_vercel_hatch_build.py"]
+    for candidate in candidates:
+        path = candidate.resolve()
+        if path.exists():
+            spec = spec_from_file_location("_vercel_hatch_build", path)
+            if spec is None or spec.loader is None:
+                raise RuntimeError(f"could not load Hatch hook from {path}")
+            module = module_from_spec(spec)
+            spec.loader.exec_module(module)
+            return module
+    raise RuntimeError("could not find shared Vercel Hatch metadata hook")

vercel_internal_telemetry-0.7.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling>=1.27.0,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vercel-internal-telemetry"
+dynamic = ["version", "dependencies"]
+description = "Internal telemetry helpers for Vercel Python packages"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE", "LICENSE.*"]
+
+[tool.hatch.metadata.hooks.custom]
+path = "hatch_build.py"
+
+[tool.vercel.release.dependencies]
+dependencies = [
+    "httpx>=0.27.0,<1",
+    "vercel-oidc>=0.6.0",
+]
+
+[tool.uv.sources]
+vercel-oidc = { workspace = true }
+
+[tool.hatch.version]
+path = "vercel/internal/telemetry/version.py"
+
+[tool.hatch.build.targets.sdist]
+force-include = { "../../scripts/hatch_build.py" = "/_vercel_hatch_build.py" }
+include = [
+    "/vercel/internal/telemetry/**/*.py",
+    "/vercel/internal/telemetry/py.typed",
+    "/README.md",
+    "/pyproject.toml",
+    "/hatch_build.py",
+    "/LICENSE",
+]
+exclude = [
+    "/**/__pycache__",
+]
+
+[tool.hatch.build.targets.wheel]
+dev-mode-dirs = ["."]
+only-include = [
+    "/vercel/internal/telemetry",
+]
+exclude = [
+    "/**/__pycache__",
+]
+
+[tool.poe]
+include = "../../scripts/poe/poe.toml"
+verbosity = -1
+
+[tool.poe.tasks.typecheck]
+cmd = "$MYPY"
+
+[tool.poe.tasks.test]
+cmd = "python -c \"pass\""

vercel_internal_telemetry-0.7.0/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-0.7.0/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-0.7.0/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-0.7.0/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-0.7.0/vercel/internal/telemetry/version.py

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