prefect 3.6.15__py3-none-any.whl → 3.6.16.dev2__py3-none-any.whl

prefect/__init__.py

@@ -130,6 +130,26 @@ def _initialize_plugins() -> None:
 # Initialize plugins on import if enabled
 _initialize_plugins()
 
+
+def _initialize_sdk_analytics() -> None:
+    """
+    Initialize SDK analytics for telemetry.
+
+    This runs automatically when Prefect is imported. Errors are silently
+    ignored to ensure analytics never impacts normal Prefect operation.
+    """
+    try:
+        from prefect._internal.analytics import initialize_analytics
+
+        initialize_analytics()
+    except Exception:
+        # Never let analytics initialization impact Prefect
+        pass
+
+
+# Initialize SDK analytics on import
+_initialize_sdk_analytics()
+
 _public_api: dict[str, tuple[Optional[str], str]] = {
     "allow_failure": (__spec__.parent, ".main"),
     "apause_flow_run": (__spec__.parent, ".main"),

prefect/_build_info.py

@@ -1,5 +1,5 @@
 # Generated by versioningit
-__version__ = "3.6.15"
-__build_date__ = "2026-01-30 00:27:37.852288+00:00"
-__git_commit__ = "757a089bbd323e73c4437f77de86030f406f6734"
+__version__ = "3.6.16.dev2"
+__build_date__ = "2026-01-30 21:51:06.104489+00:00"
+__git_commit__ = "17574a7bfd5d441988acf1b86b1aa618e06af271"
 __dirty__ = False

prefect/_internal/analytics/__init__.py

@@ -0,0 +1,80 @@
+"""
+Internal implementation for SDK Analytics.
+
+This module contains internal functions that should not be used directly.
+Use the public API from prefect.analytics instead.
+"""
+
+from prefect._internal.analytics.emit import (
+    _is_interactive_terminal,
+    emit_integration_event,
+    emit_sdk_event,
+)
+from prefect._internal.analytics.enabled import is_telemetry_enabled
+from prefect._internal.analytics.milestones import (
+    _mark_existing_user_milestones,
+    try_mark_milestone,
+)
+from prefect._internal.analytics.notice import maybe_show_telemetry_notice
+
+# Track initialization state
+_telemetry_initialized = False
+
+
+def initialize_analytics() -> None:
+    """
+    Initialize SDK analytics on Prefect import.
+
+    This function:
+    1. Checks if telemetry is enabled (quick local checks only - non-blocking)
+    2. Detects existing users and pre-marks their milestones (no events emitted)
+    3. For new users: shows the first-run notice and emits first_sdk_import
+
+    Onboarding events are only emitted in interactive terminals to avoid
+    tracking deployed flow runs (e.g., Kubernetes jobs) as new users.
+
+    Called automatically when Prefect is imported.
+    """
+    global _telemetry_initialized
+
+    if _telemetry_initialized:
+        return
+
+    _telemetry_initialized = True
+
+    # Quick local checks only - no network calls
+    if not is_telemetry_enabled():
+        return
+
+    # Only emit onboarding events in interactive terminals
+    # This prevents deployed flow runs from being counted as new users
+    if not _is_interactive_terminal():
+        return
+
+    try:
+        # Check for existing users and pre-mark their milestones
+        # This must happen BEFORE any events are emitted
+        is_existing_user = _mark_existing_user_milestones()
+
+        # Don't emit onboarding events for existing users
+        if is_existing_user:
+            return
+
+        # Show first-run notice (only in interactive terminals)
+        maybe_show_telemetry_notice()
+
+        # Emit first_sdk_import event for new users only (tracked as a milestone
+        # so it is only emitted once per installation)
+        try_mark_milestone("first_sdk_import")
+    except Exception:
+        pass  # Silently ignore initialization errors
+
+
+__all__ = [
+    "initialize_analytics",
+    "is_telemetry_enabled",
+    "emit_sdk_event",
+    "emit_integration_event",
+    "try_mark_milestone",
+    "_is_interactive_terminal",
+]

prefect/_internal/analytics/_config.py

@@ -0,0 +1,2 @@
+# Generated at build time - DO NOT EDIT
+AMPLITUDE_API_KEY = "c97dd2acbf306ab7bf54aca0aeb7ffa1"

prefect/_internal/analytics/ci_detection.py

@@ -0,0 +1,39 @@
+"""
+CI environment detection for SDK telemetry.
+
+Telemetry is automatically disabled in CI environments.
+"""
+
+import os
+
+# Common CI environment variables
+CI_ENV_VARS = frozenset(
+    {
+        "CI",
+        "GITHUB_ACTIONS",
+        "GITLAB_CI",
+        "JENKINS_URL",
+        "TRAVIS",
+        "CIRCLECI",
+        "BUILDKITE",
+        "TF_BUILD",  # Azure DevOps
+        "CODEBUILD_BUILD_ID",  # AWS CodeBuild
+        "BITBUCKET_COMMIT",
+        "TEAMCITY_VERSION",
+        "DRONE",
+        "SEMAPHORE",
+        "APPVEYOR",
+        "BUDDY",
+        "CI_NAME",  # Generic CI indicator
+    }
+)
+
+
+def is_ci_environment() -> bool:
+    """
+    Check if the current environment is a CI environment.
+
+    Returns:
+        True if any known CI environment variable is set
+    """
+    return any(os.environ.get(var) for var in CI_ENV_VARS)

prefect/_internal/analytics/client.py

@@ -0,0 +1,132 @@
+"""
+Amplitude client wrapper for SDK telemetry.
+
+Provides fire-and-forget event tracking with silent failure handling.
+"""
+
+import atexit
+import logging
+import platform
+from typing import Any
+
+from amplitude import Amplitude, BaseEvent, Config
+
+import prefect
+
+# Amplitude API key for SDK telemetry
+# This is a write-only key that can only send events, not read data
+try:
+    from prefect._internal.analytics._config import AMPLITUDE_API_KEY
+except ImportError:
+    AMPLITUDE_API_KEY = "YOUR_AMPLITUDE_API_KEY_HERE"
+
+# Module-level client instance
+_amplitude_client: Amplitude | None = None
+_initialized = False
+
+
+def _get_event_properties() -> dict[str, str]:
+    """Get common event properties included with all events."""
+    return {
+        "prefect_version": prefect.__version__,
+        "python_version": platform.python_version(),
+        "platform": platform.system(),
+        "architecture": platform.machine(),
+    }
+
+
+def _initialize_client() -> bool:
+    """
+    Initialize the Amplitude client.
+
+    Returns:
+        True if initialization succeeded, False otherwise
+    """
+    global _amplitude_client, _initialized
+
+    if _initialized:
+        return _amplitude_client is not None
+
+    _initialized = True
+
+    if AMPLITUDE_API_KEY == "YOUR_AMPLITUDE_API_KEY_HERE":
+        # API key not configured - telemetry disabled
+        return False
+
+    try:
+        # Create a silent logger for Amplitude to prevent SDK errors from reaching users
+        amplitude_logger = logging.getLogger("amplitude")
+        amplitude_logger.setLevel(logging.CRITICAL)
+
+        config = Config(
+            # Flush events after a short delay to avoid blocking
+            flush_interval_millis=10000,  # 10 seconds
+            flush_queue_size=10,
+            # Minimize network overhead
+            min_id_length=1,
+        )
+
+        _amplitude_client = Amplitude(AMPLITUDE_API_KEY, config)
+
+        # Register shutdown handler to flush remaining events
+        atexit.register(_shutdown_client)
+
+        return True
+    except Exception:
+        return False
+
+
+def _shutdown_client() -> None:
+    """Shutdown the Amplitude client, flushing any remaining events."""
+    global _amplitude_client
+
+    if _amplitude_client is not None:
+        try:
+            _amplitude_client.shutdown()
+        except Exception:
+            pass
+        _amplitude_client = None
+
+
+def track_event(
+    event_name: str,
+    device_id: str,
+    extra_properties: dict[str, Any] | None = None,
+) -> bool:
+    """
+    Track an event with Amplitude.
+
+    Args:
+        event_name: The name of the event to track
+        device_id: The anonymous device identifier
+        extra_properties: Additional event properties
+
+    Returns:
+        True if the event was tracked, False otherwise
+    """
+    properties = _get_event_properties()
+    if extra_properties:
+        properties.update(extra_properties)
+
+    if not _initialize_client():
+        return False
+
+    try:
+        event = BaseEvent(
+            event_type=event_name,
+            device_id=device_id,
+            event_properties=properties,
+        )
+        _amplitude_client.track(event)
+        return True
+    except Exception:
+        return False
+
+
+def flush() -> None:
+    """Flush any pending events immediately."""
+    if _amplitude_client is not None:
+        try:
+            _amplitude_client.flush()
+        except Exception:
+            pass

prefect/_internal/analytics/device_id.py

@@ -0,0 +1,55 @@
+"""
+Device ID generation and persistence for SDK telemetry.
+
+The device ID is an anonymous identifier used to correlate events
+from the same installation without identifying the user.
+"""
+
+import os
+from pathlib import Path
+from uuid import uuid4
+
+from prefect.settings import get_current_settings
+
+
+def _get_device_id_path() -> Path:
+    """Get the path to the device ID file."""
+    settings = get_current_settings()
+    return settings.home / ".sdk_telemetry" / "device_id"
+
+
+def get_or_create_device_id() -> str:
+    """
+    Get the existing device ID or create a new one.
+
+    The device ID is stored in $PREFECT_HOME/.sdk_telemetry/device_id
+
+    Returns:
+        A UUID string identifying this installation
+    """
+    device_id_path = _get_device_id_path()
+
+    # Try to read existing device ID
+    if device_id_path.exists():
+        try:
+            device_id = device_id_path.read_text().strip()
+            if device_id:
+                return device_id
+        except Exception:
+            pass
+
+    # Generate new device ID
+    device_id = str(uuid4())
+
+    # Persist device ID
+    try:
+        device_id_path.parent.mkdir(parents=True, exist_ok=True)
+        device_id_path.write_text(device_id)
+        # Set restrictive permissions (owner read/write only)
+        os.chmod(device_id_path, 0o600)
+    except Exception:
+        # If we can't persist, still return the generated ID
+        # (it will be regenerated next time)
+        pass
+
+    return device_id

prefect/_internal/analytics/emit.py

@@ -0,0 +1,90 @@
+"""
+Event emission for SDK analytics.
+"""
+
+import sys
+from typing import Any
+
+from prefect._internal.analytics.device_id import get_or_create_device_id
+from prefect._internal.analytics.events import SDKEvent
+from prefect._internal.analytics.service import AnalyticsEvent, AnalyticsService
+
+
+def _is_interactive_terminal() -> bool:
+    """Check if we're running in an interactive terminal."""
+    try:
+        return sys.stdout.isatty() or sys.stderr.isatty()
+    except Exception:
+        return False
+
+
+def emit_sdk_event(
+    event_name: SDKEvent,
+    extra_properties: dict[str, Any] | None = None,
+) -> bool:
+    """
+    Emit an SDK telemetry event.
+
+    This is an internal function for tracking SDK events.
+    Events are queued for processing in a background thread (non-blocking).
+
+    Args:
+        event_name: The name of the event to track
+        extra_properties: Additional event properties
+
+    Returns:
+        True if the event was queued, False otherwise
+    """
+    try:
+        device_id = get_or_create_device_id()
+        event = AnalyticsEvent(
+            event_name=event_name,
+            device_id=device_id,
+            extra_properties=extra_properties,
+        )
+        AnalyticsService.instance().enqueue(event)
+        return True
+    except Exception:
+        return False
+
+
+def emit_integration_event(
+    integration: str,
+    event_name: str,
+    extra_properties: dict[str, Any] | None = None,
+) -> bool:
+    """
+    Emit a telemetry event from an integration library.
+
+    This is exposed via the public API in prefect.analytics for integration
+    libraries (e.g., prefect-aws, prefect-gcp) to emit telemetry events.
+    Events are automatically namespaced with the integration name.
+
+    Args:
+        integration: The integration name (e.g., "prefect-aws", "prefect-gcp")
+        event_name: The event name (e.g., "s3_block_created")
+        extra_properties: Additional event properties
+
+    Returns:
+        True if the event was queued, False otherwise
+    """
+    try:
+        # Namespace the event with the integration name
+        namespaced_event = f"{integration}:{event_name}"
+
+        device_id = get_or_create_device_id()
+
+        # Add integration name to properties
+        properties = {"integration": integration}
+        if extra_properties:
+            properties.update(extra_properties)
+
+        event = AnalyticsEvent(
+            event_name=namespaced_event,
+            device_id=device_id,
+            extra_properties=properties,
+        )
+        AnalyticsService.instance().enqueue(event)
+        return True
+    except Exception:
+        return False

prefect/_internal/analytics/enabled.py

@@ -0,0 +1,33 @@
+"""
+Telemetry enabled check for SDK analytics.
+"""
+
+import os
+
+from prefect._internal.analytics.ci_detection import is_ci_environment
+
+
+def is_telemetry_enabled() -> bool:
+    """
+    Quick non-blocking check of local telemetry settings.
+
+    Telemetry is disabled if:
+    - DO_NOT_TRACK environment variable is set (client-side)
+    - Running in a CI environment
+
+    Note: Server-side analytics check is performed in the background service
+    to avoid blocking the main thread.
+
+    Returns:
+        True if local telemetry checks pass, False otherwise
+    """
+    # Check DO_NOT_TRACK standard (client-side setting)
+    do_not_track = os.environ.get("DO_NOT_TRACK", "").lower()
+    if do_not_track in ("1", "true", "yes"):
+        return False
+
+    # Check CI environment
+    if is_ci_environment():
+        return False
+
+    return True

prefect/_internal/analytics/events.py

@@ -0,0 +1,14 @@
+"""
+Event type definitions for SDK telemetry.
+"""
+
+from typing import Literal
+
+# Quick Start Funnel events
+SDKEvent = Literal[
+    "first_sdk_import",
+    "first_flow_defined",
+    "first_flow_run",
+    "first_deployment_created",
+    "first_schedule_created",
+]

prefect/_internal/analytics/milestones.py

@@ -0,0 +1,177 @@
+"""
+Milestone tracking for SDK telemetry.
+
+Tracks first-* events to avoid duplicate telemetry.
+Milestones are stored in $PREFECT_HOME/.sdk_telemetry/milestones.json
+
+For existing users (detected by presence of Prefect artifacts), all milestones
+are pre-marked as reached to avoid emitting onboarding events on upgrade.
+"""
+
+import json
+from pathlib import Path
+from typing import Literal
+
+from prefect._internal.analytics.emit import _is_interactive_terminal, emit_sdk_event
+from prefect.settings import get_current_settings
+
+MilestoneName = Literal[
+    "first_sdk_import",
+    "first_flow_defined",
+    "first_flow_run",
+    "first_deployment_created",
+    "first_schedule_created",
+]
+
+# All milestone names for pre-marking existing users
+ALL_MILESTONES: list[MilestoneName] = [
+    "first_sdk_import",
+    "first_flow_defined",
+    "first_flow_run",
+    "first_deployment_created",
+    "first_schedule_created",
+]
+
+# Files/directories that indicate an existing Prefect user
+_EXISTING_USER_INDICATORS = [
+    "profiles.toml",  # User has configured profiles
+    ".prefect.db",  # Local server database
+    "prefect.db",  # Alternative database location
+    "storage",  # Result storage directory
+]
+
+
+def _get_telemetry_dir() -> Path:
+    """Get the path to the telemetry directory."""
+    settings = get_current_settings()
+    return settings.home / ".sdk_telemetry"
+
+
+def _get_milestones_path() -> Path:
+    """Get the path to the milestones file."""
+    return _get_telemetry_dir() / "milestones.json"
+
+
+def _read_milestones() -> dict[str, bool]:
+    """Read milestones from disk."""
+    milestones_path = _get_milestones_path()
+    if milestones_path.exists():
+        try:
+            return json.loads(milestones_path.read_text())
+        except Exception:
+            pass
+    return {}
+
+
+def _write_milestones(milestones: dict[str, bool]) -> None:
+    """Write milestones to disk."""
+    milestones_path = _get_milestones_path()
+    try:
+        milestones_path.parent.mkdir(parents=True, exist_ok=True)
+        milestones_path.write_text(json.dumps(milestones, indent=2))
+    except Exception:
+        pass
+
+
+def _is_existing_user() -> bool:
+    """
+    Check if this is an existing Prefect user.
+
+    An existing user is detected by the presence of common Prefect artifacts
+    in PREFECT_HOME that would have been created before telemetry was added.
+
+    Returns:
+        True if existing user indicators are found
+    """
+    settings = get_current_settings()
+    prefect_home = settings.home
+
+    if not prefect_home.exists():
+        return False
+
+    for indicator in _EXISTING_USER_INDICATORS:
+        if (prefect_home / indicator).exists():
+            return True
+
+    return False
+
+
+def _mark_existing_user_milestones() -> bool:
+    """
+    Pre-mark all milestones for existing users.
+
+    This prevents existing users from emitting onboarding events when they
+    upgrade to a version with telemetry.
+
+    Returns:
+        True if milestones were pre-marked (existing user detected)
+    """
+    telemetry_dir = _get_telemetry_dir()
+
+    # If telemetry directory already exists, we've already handled this
+    if telemetry_dir.exists():
+        return False
+
+    # Check if this is an existing user
+    if not _is_existing_user():
+        return False
+
+    # Pre-mark all milestones for existing users
+    milestones = {milestone: True for milestone in ALL_MILESTONES}
+    _write_milestones(milestones)
+    return True
+
+
+def has_reached_milestone(milestone: MilestoneName) -> bool:
+    """
+    Check if a milestone has been reached.
+
+    Args:
+        milestone: The milestone name to check
+
+    Returns:
+        True if the milestone has been recorded
+    """
+    milestones = _read_milestones()
+    return milestones.get(milestone, False)
+
+
+def mark_milestone(milestone: MilestoneName) -> None:
+    """
+    Mark a milestone as reached.
+
+    Args:
+        milestone: The milestone name to mark
+    """
+    milestones = _read_milestones()
+    milestones[milestone] = True
+    _write_milestones(milestones)
+
+
+def try_mark_milestone(milestone: MilestoneName) -> bool:
+    """
+    Try to mark a milestone and emit an event if it's new.
+
+    This is the primary entry point for milestone tracking.
+    It checks if the milestone is new, marks it, and emits the event.
+
+    Events are only emitted in interactive terminals to avoid tracking
+    deployed flow runs (e.g., Kubernetes jobs) as new users.
+
+    Args:
+        milestone: The milestone name to mark
+
+    Returns:
+        True if this was the first time reaching the milestone
+    """
+    # Only emit events in interactive terminals
+    # This prevents deployed flow runs from being counted as new users
+    if not _is_interactive_terminal():
+        return False
+
+    if has_reached_milestone(milestone):
+        return False
+
+    mark_milestone(milestone)
+    emit_sdk_event(milestone)
+    return True