Enable overriding undocumented telemetry identifier with PIP_TELEMETRY_USER_AGENT_ID

docs/html/user_guide.rst

@@ -46,7 +46,7 @@ directly from distribution files.
 
 
 The most common scenario is to install from `PyPI`_ using :ref:`Requirement
-Specifiers`
+Specifiers`.
 
 .. tab:: Unix/macOS
 
@@ -66,6 +66,16 @@ Specifiers`
 
 For more information and examples, see the :ref:`pip install` reference.
 
+.. note::
+
+   Pip generates a ``User-Agent`` string that includes the running version of Python and pip, along
+   with further identifying info about the libc and Linux distribution. This string is sent with
+   every HTTP(S) request pip makes to a remote host.
+
+   Setting ``PIP_TELEMETRY_USER_AGENT_ID`` in the
+   process environment to any value will instead use exactly that string for the
+   ``User-Agent`` header. This value is printed as part of the output of :doc:`cli/pip_debug`.
+
 .. _PyPI: https://pypi.org/
 
 .. _`0-basic-authentication-credentials`:

news/13560.feature.rst

@@ -0,0 +1 @@
+Introduces ``PIP_TELEMETRY_USER_AGENT_ID``, an environment variable which completely overrides the value used to form pip's ``User-Agent`` header.

src/pip/_internal/commands/debug.py

@@ -18,6 +18,7 @@
 from pip._internal.cli.status_codes import SUCCESS
 from pip._internal.configuration import Configuration
 from pip._internal.metadata import get_environment
+from pip._internal.network.session import Telemetry
 from pip._internal.utils.compat import open_text_resource
 from pip._internal.utils.logging import indent_log
 from pip._internal.utils.misc import get_pip_version
@@ -190,6 +191,7 @@ def run(self, options: Values, args: list[str]) -> int:
         show_value("sys.platform", sys.platform)
         show_sys_implementation()
 
+        show_value("User-Agent header", Telemetry.user_agent_id())
         show_value("'cert' config value", ca_bundle_info(self.parser.config))
         show_value("REQUESTS_CA_BUNDLE", os.environ.get("REQUESTS_CA_BUNDLE"))
         show_value("CURL_CA_BUNDLE", os.environ.get("CURL_CA_BUNDLE"))