sagemaker-core 1.0.62__py3-none-any.whl → 2.3.1__py3-none-any.whl

sagemaker/core/debugger/profiler_config.py

@@ -0,0 +1,190 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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.
+"""Configuration for collecting system and framework metrics in SageMaker training jobs."""
+from __future__ import absolute_import
+
+import logging
+from typing import Optional, Union
+
+from sagemaker.core.debugger.framework_profile import FrameworkProfile
+from sagemaker.core.debugger.profiler import Profiler
+from sagemaker.core.helper.pipeline_variable import PipelineVariable
+from sagemaker.core.deprecations import deprecation_warn_base
+
+logger = logging.getLogger(__name__)
+
+
+class ProfilerConfig(object):
+    """Configuration for collecting system and framework metrics of SageMaker training jobs.
+
+    SageMaker Debugger collects system and framework profiling
+    information of training jobs and identify performance bottlenecks.
+
+    """
+
+    def __init__(
+        self,
+        s3_output_path: Optional[Union[str, PipelineVariable]] = None,
+        system_monitor_interval_millis: Optional[Union[int, PipelineVariable]] = None,
+        framework_profile_params: Optional[FrameworkProfile] = None,
+        profile_params: Optional[Profiler] = None,
+        disable_profiler: Optional[Union[str, PipelineVariable]] = False,
+    ):
+        """Initialize a ``ProfilerConfig`` instance.
+
+        Pass the output of this class
+        to the ``profiler_config`` parameter of the generic :class:`~sagemaker.estimator.Estimator`
+        class and SageMaker Framework estimators.
+
+        Args:
+            s3_output_path (str or PipelineVariable): The location in Amazon S3 to store
+                the output.
+                The default Debugger output path for profiling data is created under the
+                default output path of the :class:`~sagemaker.estimator.Estimator` class.
+                For example,
+                s3://sagemaker-<region>-<12digit_account_id>/<training-job-name>/profiler-output/.
+            system_monitor_interval_millis (int or PipelineVariable): The time interval in
+                milliseconds to collect system metrics. Available values are 100, 200, 500,
+                1000 (1 second), 5000 (5 seconds), and 60000 (1 minute) milliseconds.
+                The default is 500 milliseconds.
+            framework_profile_params (:class:`~sagemaker.debugger.FrameworkProfile`):
+                (Deprecated) A parameter object for framework metrics profiling. Configure it using
+                the :class:`~sagemaker.debugger.FrameworkProfile` class.
+                To use the default framework profile parameters, pass ``FrameworkProfile()``.
+                For more information about the default values,
+                see :class:`~sagemaker.debugger.FrameworkProfile`.
+            disable_profiler (bool): Switch the basic monitoring on or off using this parameter.
+                The default is ``False``.
+            profile_params (dict or an object of :class:`sagemaker.Profiler`): Pass this parameter
+                to activate SageMaker Profiler using the :class:`sagemaker.Profiler` class.
+
+        **Basic profiling using SageMaker Debugger**
+
+        By default, if you submit training jobs using SageMaker Python SDK's estimator classes,
+        SageMaker runs basic profiling automatically.
+        The following example shows the basic profiling configuration
+        that you can utilize to update the time interval for collecting system resource utilization.
+
+        .. code:: python
+
+            import sagemaker
+            from sagemaker.pytorch import PyTorch
+            from sagemaker.debugger import ProfilerConfig
+
+            profiler_config = ProfilerConfig(
+                system_monitor_interval_millis = 500
+            )
+
+            estimator = PyTorch(
+                framework_version="2.0.0",
+                ... # Set up other essential parameters for the estimator class
+                profiler_config=profiler_config
+            )
+
+        For a complete instruction on activating and using SageMaker Debugger, see
+        `Monitor AWS compute resource utilization in Amazon SageMaker Studio
+        <https://docs.aws.amazon.com/sagemaker/latest/dg/train-debugger.html>`_.
+
+        **Deep profiling using SageMaker Profiler**
+
+        The following example shows an example configration for activating
+        SageMaker Profiler.
+
+        .. code:: python
+
+            import sagemaker
+            from sagemaker.pytorch import PyTorch
+            from sagemaker import ProfilerConfig, Profiler
+
+            profiler_config = ProfilerConfig(
+                profiler_params = Profiler(cpu_profiling_duration=3600)
+            )
+
+            estimator = PyTorch(
+                framework_version="2.0.0",
+                ... # Set up other essential parameters for the estimator class
+                profiler_config=profiler_config
+            )
+
+        For a complete instruction on activating and using SageMaker Profiler, see
+        `Use Amazon SageMaker Profiler to profile activities on AWS compute resources
+        <https://docs.aws.amazon.com/sagemaker/latest/dg/train-profile-computational-performance.html>`_.
+
+        """
+        assert framework_profile_params is None or isinstance(
+            framework_profile_params, FrameworkProfile
+        ), "framework_profile_params must be of type FrameworkProfile if specified."
+
+        assert profile_params is None or isinstance(
+            profile_params, Profiler
+        ), "profile_params must be of type Profiler if specified."
+
+        if profile_params and framework_profile_params:
+            raise ValueError("Profiler will not work when Framework Profiler is ON")
+
+        self.s3_output_path = s3_output_path
+        self.system_monitor_interval_millis = system_monitor_interval_millis
+        self.framework_profile_params = framework_profile_params
+        self.profile_params = profile_params
+        self.disable_profiler = disable_profiler
+
+        if self.framework_profile_params is not None:
+            deprecation_warn_base(
+                "Framework profiling will be deprecated from tensorflow 2.12 and pytorch 2.0"
+            )
+
+    def _to_request_dict(self):
+        """Generate a request dictionary using the parameters provided when initializing the object.
+
+        Returns:
+            dict: An portion of an API request as a dictionary.
+
+        """
+        profiler_config_request = {}
+
+        if (
+            self.s3_output_path is not None
+            and self.disable_profiler is not None
+            and self.disable_profiler is False
+        ):
+            profiler_config_request["S3OutputPath"] = self.s3_output_path
+
+        profiler_config_request["DisableProfiler"] = self.disable_profiler
+
+        if self.system_monitor_interval_millis is not None:
+            profiler_config_request["ProfilingIntervalInMilliseconds"] = (
+                self.system_monitor_interval_millis
+            )
+
+        if self.framework_profile_params is not None:
+            profiler_config_request["ProfilingParameters"] = (
+                self.framework_profile_params.profiling_parameters
+            )
+
+        if self.profile_params is not None:
+            profiler_config_request["ProfilingParameters"] = (
+                self.profile_params.profiling_parameters
+            )
+
+        return profiler_config_request
+
+    @classmethod
+    def _to_profiler_disabled_request_dict(cls):
+        """Generate a request dictionary for updating the training job to disable profiler.
+
+        Returns:
+            dict: An portion of an API request as a dictionary.
+
+        """
+        profiler_config_request = {"DisableProfiler": True}
+        return profiler_config_request

sagemaker/core/debugger/profiler_constants.py

@@ -0,0 +1,40 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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.
+"""Utils file that contains constants for the profiler."""
+from __future__ import absolute_import  # noqa: F401
+
+BASE_FOLDER_DEFAULT = "/opt/ml/output/profiler"
+MAX_FILE_SIZE_DEFAULT = 10485760  # default 10MB
+CLOSE_FILE_INTERVAL_DEFAULT = 60  # default 60 seconds
+FILE_OPEN_FAIL_THRESHOLD_DEFAULT = 50
+
+DETAILED_PROFILING_CONFIG_NAME = "DetailedProfilingConfig"
+DATALOADER_PROFILING_CONFIG_NAME = "DataloaderProfilingConfig"
+PYTHON_PROFILING_CONFIG_NAME = "PythonProfilingConfig"
+HOROVOD_PROFILING_CONFIG_NAME = "HorovodProfilingConfig"
+SMDATAPARALLEL_PROFILING_CONFIG_NAME = "SMDataParallelProfilingConfig"
+
+DETAILED_PROFILING_START_STEP_DEFAULT = 5
+DATALOADER_PROFILING_START_STEP_DEFAULT = 7
+PYTHON_PROFILING_START_STEP_DEFAULT = 9
+HOROVOD_PROFILING_START_STEP_DEFAULT = 13
+SMDATAPARALLEL_PROFILING_START_STEP_DEFAULT = 15
+PROFILING_NUM_STEPS_DEFAULT = 1
+START_STEP_DEFAULT = 0
+PYTHON_PROFILING_NUM_STEPS_DEFAULT = 3
+
+# These options are used in detail profiler (NOT framework profile)
+CPU_PROFILING_DURATION = 3600
+FILE_ROTATION_INTERVAL_DEFAULT = 600  # 600 secs
+DETAIL_PROF_PROCESSING_DEFAULT_INSTANCE_TYPE = "ml.m5.4xlarge"
+DETAIL_PROF_PROCESSING_DEFAULT_VOLUME_SIZE = 128

sagemaker/core/debugger/utils.py

@@ -0,0 +1,148 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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.
+"""Utils file that contains util functions for the profiler."""
+from __future__ import absolute_import
+
+import re
+from datetime import datetime
+from enum import Enum
+
+
+def _convert_key_and_value(key, value):
+    """Helper function to convert the provided key and value pair (from a dictionary) to a string.
+
+    Args:
+        key (str): The key in the dictionary.
+        value: The value for this key.
+
+    Returns:
+        str: The provided key value pair as a string.
+
+    """
+    updated_key = f'"{key}"' if isinstance(key, str) else key
+    updated_value = f'"{value}"' if isinstance(value, str) else value
+
+    return f"{updated_key}: {updated_value}, "
+
+
+def convert_json_config_to_string(config):
+    """Helper function to convert the dictionary config to a string.
+
+    Calling eval on this string should result in the original dictionary.
+
+    Args:
+        config (dict): The config to be converted to a string.
+
+    Returns:
+        str: The config dictionary formatted as a string.
+
+    """
+    json_string = "{"
+    for key, value in config.items():
+        json_string += _convert_key_and_value(key, value)
+    json_string += "}"
+    return json_string
+
+
+def is_valid_unix_time(unix_time):
+    """Helper function to determine whether the provided UNIX time is valid.
+
+    Args:
+        unix_time (int): The user provided UNIX time.
+
+    Returns:
+        bool: Indicates whether the provided UNIX time was valid or not.
+
+    """
+    try:
+        datetime.fromtimestamp(unix_time)
+        return True
+    except (OverflowError, ValueError):
+        return False
+
+
+def is_valid_regex(regex):
+    """Helper function to determine whether the provided regex is valid.
+
+    Args:
+        regex (str): The user provided regex.
+
+    Returns:
+        bool: Indicates whether the provided regex was valid or not.
+
+    """
+    try:
+        re.compile(regex)
+        return True
+    except (re.error, TypeError):
+        return False
+
+
+class ErrorMessages(Enum):
+    """Enum to store all possible messages during failures in validation of user arguments."""
+
+    INVALID_LOCAL_PATH = "local_path must be a string!"
+    INVALID_FILE_MAX_SIZE = "file_max_size must be an integer greater than 0!"
+    INVALID_FILE_CLOSE_INTERVAL = "file_close_interval must be a float/integer greater than 0!"
+    INVALID_FILE_OPEN_FAIL_THRESHOLD = "file_open_fail threshold must be an integer greater than 0!"
+    INVALID_PROFILE_DEFAULT_STEPS = "profile_default_steps must be a boolean!"
+    INVALID_START_STEP = "start_step must be integer greater or equal to 0!"
+    INVALID_NUM_STEPS = "num_steps must be integer greater than 0!"
+    INVALID_START_UNIX_TIME = "start_unix_time must be valid integer unix time!"
+    INVALID_DURATION = "duration must be float greater than 0!"
+    FOUND_BOTH_STEP_AND_TIME_FIELDS = (
+        "Both step and time fields cannot be specified in the metrics config!"
+    )
+    INVALID_METRICS_REGEX = "metrics_regex is invalid!"
+    INVALID_PYTHON_PROFILER = "python_profiler must be of type PythonProfiler!"
+    INVALID_CPROFILE_TIMER = "cprofile_timer must be of type cProfileTimer"
+
+
+class PythonProfiler(Enum):
+    """Enum to list the Python profiler options for Python profiling.
+
+    .. py:attribute:: CPROFILE
+
+        Use to choose ``"cProfile"``.
+
+    .. py:attribute:: PYINSTRUMENT
+
+        Use to choose ``"Pyinstrument"``.
+
+    """
+
+    CPROFILE = "cprofile"
+    PYINSTRUMENT = "pyinstrument"
+
+
+class cProfileTimer(Enum):
+    """Enum to list the possible cProfile timers for Python profiling.
+
+    .. py:attribute:: TOTAL_TIME
+
+        Use to choose ``"total_time"``.
+
+    .. py:attribute:: CPU_TIME
+
+        Use to choose ``"cpu_time"``.
+
+    .. py:attribute:: OFF_CPU_TIME
+
+        Use to choose ``"off_cpu_time"``.
+
+    """
+
+    TOTAL_TIME = "total_time"
+    CPU_TIME = "cpu_time"
+    OFF_CPU_TIME = "off_cpu_time"
+    DEFAULT = "default"

sagemaker/core/deprecations.py

@@ -0,0 +1,254 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You
+# may not use this file except in compliance with the License. A copy of
+# the License is located at
+#
+#     http://aws.amazon.com/apache2.0/
+#
+# or in the "license" file accompanying this file. This file 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.
+"""Module for deprecation abstractions."""
+from __future__ import absolute_import
+
+import logging
+import warnings
+
+logger = logging.getLogger(__name__)
+
+V2_URL = "https://sagemaker.readthedocs.io/en/stable/v2.html"
+
+
+def _warn(msg, sdk_version=None):
+    """Generic warning raiser referencing V2
+
+    Args:
+        phrase: The phrase to include in the warning.
+        sdk_version: the sdk version of removal of support.
+    """
+    _sdk_version = sdk_version if sdk_version is not None else "2"
+    full_msg = f"{msg} in sagemaker>={_sdk_version}.\nSee: {V2_URL} for details."
+    warnings.warn(full_msg, DeprecationWarning, stacklevel=2)
+    logger.warning(full_msg)
+
+
+def removed_warning(phrase, sdk_version=None):
+    """Raise a warning for a no-op in sagemaker>=2
+
+    Args:
+        phrase: the prefix phrase of the warning message.
+        sdk_version: the sdk version of removal of support.
+    """
+    _warn(f"{phrase} is a no-op", sdk_version)
+
+
+def renamed_warning(phrase):
+    """Raise a warning for a rename in sagemaker>=2
+
+    Args:
+        phrase: the prefix phrase of the warning message.
+    """
+    _warn(f"{phrase} has been renamed")
+
+
+def deprecation_warn(name, date, msg=None):
+    """Raise a warning for soon to be deprecated feature in sagemaker>=2
+
+    Args:
+        name (str): Name of the feature
+        date (str): the date when the feature will be deprecated
+        msg (str): the prefix phrase of the warning message.
+    """
+    _warn(f"{name} will be deprecated on {date}.{msg}")
+
+
+def deprecation_warn_base(msg):
+    """Raise a warning for soon to be deprecated feature in sagemaker>=2
+
+    Args:
+        msg (str): the warning message.
+    """
+    _warn(msg)
+
+
+def deprecation_warning(date, msg=None):
+    """Decorator for raising deprecation warning for a feature in sagemaker>=2
+
+    Args:
+        date (str): the date when the feature will be deprecated
+        msg (str): the prefix phrase of the warning message.
+
+    Usage:
+        @deprecation_warning(msg="message", date="date")
+        def sample_function():
+            print("xxxx....")
+
+        @deprecation_warning(msg="message", date="date")
+        class SampleClass():
+            def __init__(self):
+                print("xxxx....")
+
+    """
+
+    def deprecate(obj):
+        def wrapper(*args, **kwargs):
+            deprecation_warn(obj.__name__, date, msg)
+            return obj(*args, **kwargs)
+
+        return wrapper
+
+    return deprecate
+
+
+def renamed_kwargs(old_name, new_name, value, kwargs):
+    """Checks if the deprecated argument is in kwargs
+
+    Raises warning, if present.
+
+    Args:
+        old_name: name of deprecated argument
+        new_name: name of the new argument
+        value: value associated with new name, if supplied
+        kwargs: keyword arguments dict
+
+    Returns:
+        value of the keyword argument, if present
+    """
+    if old_name in kwargs:
+        value = kwargs.get(old_name, value)
+        kwargs[new_name] = value
+        renamed_warning(old_name)
+    return value
+
+
+def removed_arg(name, arg):
+    """Checks if the deprecated argument is populated.
+
+    Raises warning, if not None.
+
+    Args:
+        name: name of deprecated argument
+        arg: the argument to check
+    """
+    if arg is not None:
+        removed_warning(name)
+
+
+def removed_kwargs(name, kwargs):
+    """Checks if the deprecated argument is in kwargs
+
+    Raises warning, if present.
+
+    Args:
+        name: name of deprecated argument
+        kwargs: keyword arguments dict
+    """
+    if name in kwargs:
+        removed_warning(name)
+
+
+def removed_function(name):
+    """A no-op deprecated function factory."""
+
+    def func(*args, **kwargs):  # pylint: disable=W0613
+        removed_warning(f"The function {name}")
+
+    return func
+
+
+def deprecated(sdk_version=None):
+    """Decorator for raising deprecated warning for a feature in sagemaker>=2
+
+    Args:
+        sdk_version (str): the sdk version of removal of support.
+
+    Usage:
+        @deprecated()
+        def sample_function():
+            print("xxxx....")
+
+        @deprecated(sdk_version="2.66")
+        class SampleClass():
+            def __init__(self):
+                print("xxxx....")
+
+    """
+
+    def deprecate(obj):
+        def wrapper(*args, **kwargs):
+            removed_warning(obj.__name__, sdk_version)
+            return obj(*args, **kwargs)
+
+        return wrapper
+
+    return deprecate
+
+
+def deprecated_function(func, name):
+    """Wrap a function with a deprecation warning.
+
+    Args:
+        func: Function to wrap in a deprecation warning.
+        name: The name that has been deprecated.
+
+    Returns:
+        The modified function
+    """
+
+    def deprecate(*args, **kwargs):
+        renamed_warning(f"The {name}")
+        return func(*args, **kwargs)
+
+    return deprecate
+
+
+def deprecated_serialize(instance, name):
+    """Modifies a serializer instance serialize method.
+
+    Args:
+        instance: Instance to modify serialize method.
+        name: The name that has been deprecated.
+
+    Returns:
+        The modified instance
+    """
+    instance.serialize = deprecated_function(instance.serialize, name)
+    return instance
+
+
+def deprecated_deserialize(instance, name):
+    """Modifies a deserializer instance deserialize method.
+
+    Args:
+        instance: Instance to modify deserialize method.
+        name: The name that has been deprecated.
+
+    Returns:
+        The modified instance
+    """
+    instance.deserialize = deprecated_function(instance.deserialize, name)
+    return instance
+
+
+def deprecated_class(cls, name):
+    """Returns a class based on super class with a deprecation warning.
+
+    Args:
+        cls: The class to derive with a deprecation warning on __init__
+        name: The name of the class.
+
+    Returns:
+        The modified class.
+    """
+
+    class DeprecatedClass(cls):
+        """Provides a warning for the class name."""
+
+        def __init__(self, *args, **kwargs):
+            """Provides a warning for the class name."""
+            renamed_warning(f"The class {name}")
+            super(DeprecatedClass, self).__init__(*args, **kwargs)
+
+    return DeprecatedClass

sagemaker/core/deserializers/__init__.py

@@ -0,0 +1,10 @@
+"""Deserializers for SageMaker inference."""
+
+from __future__ import absolute_import
+
+# Re-export from base
+from sagemaker.core.deserializers.base import *  # noqa: F401, F403
+
+# Note: implementations is not imported here to avoid circular imports
+# Import explicitly if needed:
+#   from sagemaker.core.deserializers.implementations import ...