docs: Clarify that instrumenter is internal-only (#3299)

Adjust docstrings of all non-deprecated functions which take an `instrumenter` parameter to state that `instrumenter` is only meant to be used by the SDK, and that it is deprecated for client code. The docstrings also inform users that `instrumenter` will be removed in the next major release.

Author: szokeasaurusrex

sentry_sdk/api.py

@@ -322,7 +322,8 @@ def start_transaction(
 
     :param transaction: The transaction to start. If omitted, we create and
         start a new transaction.
-    :param instrumenter: This parameter is meant for internal use only.
+    :param instrumenter: This parameter is meant for internal use only. It
+        will be removed in the next major version.
     :param custom_sampling_context: The transaction's custom sampling context.
     :param kwargs: Optional keyword arguments to be passed to the Transaction
         constructor. See :py:class:`sentry_sdk.tracing.Transaction` for

sentry_sdk/scope.py

@@ -987,7 +987,8 @@ def start_transaction(
 
         :param transaction: The transaction to start. If omitted, we create and
             start a new transaction.
-        :param instrumenter: This parameter is meant for internal use only.
+        :param instrumenter: This parameter is meant for internal use only. It
+            will be removed in the next major version.
         :param custom_sampling_context: The transaction's custom sampling context.
         :param kwargs: Optional keyword arguments to be passed to the Transaction
             constructor. See :py:class:`sentry_sdk.tracing.Transaction` for
@@ -1054,6 +1055,10 @@ def start_span(self, instrumenter=INSTRUMENTER.SENTRY, **kwargs):
         one is not already in progress.
 
         For supported `**kwargs` see :py:class:`sentry_sdk.tracing.Span`.
+
+        The instrumenter parameter is deprecated for user code, and it will
+        be removed in the next major version. Going forward, it should only
+        be used by the SDK itself.
         """
         with new_scope():
             kwargs.setdefault("scope", self)

sentry_sdk/tracing.py

@@ -394,6 +394,10 @@ def start_child(self, instrumenter=INSTRUMENTER.SENTRY, **kwargs):
         Takes the same arguments as the initializer of :py:class:`Span`. The
         trace id, sampling decision, transaction pointer, and span recorder are
         inherited from the current span/transaction.
+
+        The instrumenter parameter is deprecated for user code, and it will
+        be removed in the next major version. Going forward, it should only
+        be used by the SDK itself.
         """
         configuration_instrumenter = sentry_sdk.Scope.get_client().options[
             "instrumenter"