Add LOG_DEPRECATION_WARNINGS config, update docs

changes/2798.added

@@ -0,0 +1 @@
+Added `LOG_DEPRECATION_WARNINGS` configuration variable and corresponding environment-variable support.

changes/2798.changed

@@ -0,0 +1 @@
+Changed logging of Nautobot deprecation warnings to be silent by default (can be enabled with `DEBUG` or `LOG_DEPRECATION_WARNINGS` settings).

nautobot/core/settings.py

@@ -76,6 +76,10 @@
 GIT_ROOT = os.getenv("NAUTOBOT_GIT_ROOT", os.path.join(NAUTOBOT_ROOT, "git").rstrip("/"))
 HTTP_PROXIES = None
 JOBS_ROOT = os.getenv("NAUTOBOT_JOBS_ROOT", os.path.join(NAUTOBOT_ROOT, "jobs").rstrip("/"))
+
+# Log Nautobot deprecation warnings. Note that this setting is ignored (deprecation logs always enabled) if DEBUG = True
+LOG_DEPRECATION_WARNINGS = is_truthy(os.getenv("NAUTOBOT_LOG_DEPRECATION_WARNINGS", "False"))
+
 MAINTENANCE_MODE = is_truthy(os.getenv("NAUTOBOT_MAINTENANCE_MODE", "False"))
 # Metrics
 METRICS_ENABLED = is_truthy(os.getenv("NAUTOBOT_METRICS_ENABLED", "False"))

nautobot/core/templates/nautobot_config.py.j2

@@ -367,6 +367,10 @@ SECRET_KEY = os.getenv("NAUTOBOT_SECRET_KEY", "{{ secret_key }}")
 #
 # JOBS_ROOT = os.getenv("NAUTOBOT_JOBS_ROOT", os.path.join(NAUTOBOT_ROOT, "jobs").rstrip("/"))
 
+# Log Nautobot deprecation warnings. Note that this setting is ignored (deprecation logs always enabled) if DEBUG = True
+#
+# LOG_DEPRECATION_WARNINGS = is_truthy(os.getenv("NAUTOBOT_LOG_DEPRECATION_WARNINGS", "False"))
+
 # Setting this to True will display a "maintenance mode" banner at the top of every page.
 #
 # MAINTENANCE_MODE = is_truthy(os.getenv("NAUTOBOT_MAINTENANCE_MODE", "False"))

nautobot/docs/configuration/optional-settings.md

@@ -514,6 +514,24 @@ The file path to a directory where [Jobs](../additional-features/jobs.md) can be
 
 ---
 
+## LOG_DEPRECATION_WARNINGS
+
++++ 1.5.2
+
+Default: `False`
+
+Environment Variable: `NAUTOBOT_LOG_DEPRECATION_WARNINGS`
+
+This can be set to `True` to allow deprecation warnings raised by Nautobot to (additionally) be logged as `WARNING` level log messages. (Deprecation warnings are normally silent in Python, but can be enabled globally by [various means](https://docs.python.org/3/library/warnings.html) such as setting the `PYTHONWARNINGS` environment variable. However, doing so can be rather noisy, as it will also include warnings from within Django about various code in various package dependencies of Nautobot's, etc. This configuration setting allows a more targeted enablement of only warnings from within Nautobot itself, which can be useful when vetting various Nautobot apps (plugins) for future-proofness against upcoming changes to Nautobot.)
+
+!!! tip
+    Setting `DEBUG = True` will also cause Nautobot's deprecation warnings to be logged as well.
+
+!!! caution
+    In Nautobot 2.0, deprecation warnings will be logged by default; a future release of Nautobot 1.5.x will also enable default logging of deprecation warnings.
+
+---
+
 ## MAINTENANCE_MODE
 
 Default: `False`

nautobot/docs/release-notes/version-1.5.md

@@ -75,6 +75,15 @@ As a result, the value of this setting now defaults to `False`, disabling databa
 !!! important
     Users with existing `nautobot_config.py` files generated from earlier versions of Nautobot will still have `CACHEOPS_ENABLED = True` unless they modify or regenerate their configuration. If users no longer desire caching, please be sure to explicitly toggle the value of this setting to `False` and restart your Nautobot services.
 
+#### Deprecation warnings silenced by default ([#2798](https://github.com/nautobot/nautobot/pull/2798))
+
++/- 1.5.2
+
+Deprecation warnings raised by Nautobot itself (such as warnings about upcoming breaking changes in a future release) are no longer logged as `WARNING` log messages by default, but can be enabled by setting `DEBUG = True` or `LOG_DEPRECATION_WARNINGS = True` in your configuration. More information is available under [Optional Settings](../configuration/optional-settings.md#log_deprecation_warnings).
+
+!!! caution
+    In Nautobot 2.0, deprecation warnings will again be logged by default; a future release of Nautobot 1.5.x will also re-enable default logging of deprecation warnings.
+
 #### Redesigned List Filtering UI ([#1998](https://github.com/nautobot/nautobot/issues/1998))
 
 Added a dynamic filter form that allows users to filter object tables/lists by any field and lookup expression combination supported by the corresponding FilterSet and API.

nautobot/utilities/deprecation.py

@@ -5,6 +5,9 @@
 import traceback
 import warnings
 
+from django.conf import settings
+
+
 logger = logging.getLogger(__name__)
 
 
@@ -28,21 +31,23 @@ def init_subclass(new_subclass):
                 DeprecationWarning,
                 stacklevel=stacklevel,
             )
-            # Since DeprecationWarnings are silenced by default, also log a traditional warning.
-            # Note: logger.warning() only supports a `stacklevel` parameter in Python 3.8 and later
-            if sys.version_info >= (3, 8):
-                logger.warning(
-                    f"Class {cls.__name__} is deprecated, and will be removed in a future Nautobot release. "
-                    f"Instead of deriving {new_subclass.__name__} from {cls.__name__}, "
-                    f"please migrate your code to inherit from class {replacement_class.__name__} instead.",
-                    stacklevel=stacklevel,
-                )
-            else:
-                logger.warning(
-                    f"Class {cls.__name__} is deprecated, and will be removed in a future Nautobot release. "
-                    f"Instead of deriving {new_subclass.__name__} from {cls.__name__}, "
-                    f"please migrate your code to inherit from class {replacement_class.__name__} instead.",
-                )
+            if settings.LOG_DEPRECATION_WARNINGS or settings.DEBUG:
+                # Since DeprecationWarnings are silenced by default, also log a traditional warning.
+                # Note: logger.warning() only supports a `stacklevel` parameter in Python 3.8 and later
+                if sys.version_info >= (3, 8):
+                    logger.warning(
+                        f"Class {cls.__name__} is deprecated, and will be removed in a future Nautobot release. "
+                        f"Instead of deriving {new_subclass.__name__} from {cls.__name__}, "
+                        f"please migrate your code to inherit from class {replacement_class.__name__} instead.",
+                        stacklevel=stacklevel,
+                    )
+                else:
+                    # TODO: remove this case when we drop Python 3.7 support
+                    logger.warning(
+                        f"Class {cls.__name__} is deprecated, and will be removed in a future Nautobot release. "
+                        f"Instead of deriving {new_subclass.__name__} from {cls.__name__}, "
+                        f"please migrate your code to inherit from class {replacement_class.__name__} instead.",
+                    )
 
         cls.__init_subclass__ = classmethod(init_subclass)
         return cls