Azure · xiangyan99 · Mar 27, 2026
@@ -21,6 +21,7 @@
   - [Known uses of token request parameters](#known-uses-of-token-request-parameters)
   - [BearerTokenCredentialPolicy and AsyncBearerTokenCredentialPolicy](#bearertokencredentialpolicy-and-asyncbearertokencredentialpolicy)
 - [Long-running operation (LRO) customization](#long-running-operation-lro-customization)
+- [Environment Variables](#environment-variables)
 
 ## Pipeline
 
@@ -209,10 +210,11 @@ synchronous_transport = RequestsTransport(use_env_settings=True)
 
 If "use_env_settings" is set to True(by default), the transport will look for environment variables
 
-- HTTP_PROXY
-- HTTPS_PROXY
+- `HTTP_PROXY`
+- `HTTPS_PROXY`
+- `NO_PROXY`
 
-and use their values to configure the proxy settings.
+and use their values to configure the proxy settings. See the [Environment Variables](#environment-variables) section for the full list of recognized environment variables.
 
 - Use ProxyPolicy
 
@@ -740,6 +742,64 @@ from azure.core.pipeline.policies import BearerTokenCredentialPolicy
 authentication_policy = BearerTokenCredentialPolicy(credential, scopes, enable_cae=True)
 ```
 
+## Environment Variables
+
+The following environment variables are recognized by `azure-core`. They are resolved through the `azure.core.settings` module with the following priority order (highest to lowest):
+
+1. Immediate values (passed directly when retrieving the setting)
+2. Previously user-set values (assigned programmatically via `settings.<name> = value`)
+3. Environment variables (from `os.environ`)
+4. System settings (OS-level registries or hooks)
+5. Implicit defaults
+
+### SDK Configuration
+
+| Variable | Description | Accepted Values | Default |
+| --- | --- | --- | --- |
+| `AZURE_LOG_LEVEL` | Logging level for all Azure SDK clients. | `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG` (case-insensitive) | `INFO` |
+| `AZURE_TRACING_ENABLED` | Enable/disable distributed tracing. | `true`/`false`, `yes`/`no`, `1`/`0`, `on`/`off` (case-insensitive) | Auto-detected based on `AZURE_SDK_TRACING_IMPLEMENTATION` |
+| `AZURE_SDK_TRACING_IMPLEMENTATION` | Tracing implementation to use. Requires the corresponding plugin package (`azure-core-tracing-opentelemetry` or `azure-core-tracing-opencensus`). | `opentelemetry`, `opencensus` | None |
+| `AZURE_SDK_CLOUD_CONF` | Azure cloud environment. | `AZURE_PUBLIC_CLOUD`, `AZURE_CHINA_CLOUD`, `AZURE_US_GOVERNMENT` | `AZURE_PUBLIC_CLOUD` |
+
+These settings can also be read or set programmatically:
+
+```python
+from azure.core.settings import settings
+import logging
+
+# Read the current value (resolves using the priority order above)
+current_level = settings.log_level()
+
+# Set a value programmatically (takes priority over environment variable)
+settings.log_level = logging.DEBUG
+```
+
+### HTTP Pipeline
+
+| Variable | Description | Used By | Default |
+| --- | --- | --- | --- |
+| `AZURE_HTTP_USER_AGENT` | Additional string appended to the `User-Agent` header. Only used when `user_agent_use_env=True` (the default). | `UserAgentPolicy` | None |
+| `AZURE_SDK_LOGGING_MULTIRECORD` | When set to any truthy value, HTTP request and response details are logged as separate log records instead of a single combined record. | `HttpLoggingPolicy` | Disabled |
+
+### Network & Proxy
+
+These standard proxy environment variables are honored by the underlying HTTP transport libraries (`requests` and `aiohttp`) when the transport is created with `use_env_settings=True` (the default).
+
+| Variable | Description | Example |
+| --- | --- | --- |
+| `HTTP_PROXY` | Proxy URL for HTTP requests. | `http://proxy.example.com:8080` |
+| `HTTPS_PROXY` | Proxy URL for HTTPS requests. | `http://user:password@proxy.example.com:8080` |
+| `NO_PROXY` | Comma-separated list of hosts that should bypass the proxy. | `localhost,127.0.0.1,.internal.corp` |
+
+To disable reading proxy settings from the environment:
+
+```python
+from azure.core.pipeline.transport import RequestsTransport
+transport = RequestsTransport(use_env_settings=False)
+```
+
+See the [Proxy Settings](#proxy-settings) section for more details.
+
 ## Long-running operation (LRO) customization
 
 See [doc/dev/customize_long_running_operation.md](https://github.com/Azure/azure-sdk-for-python/blob/main/doc/dev/customize_long_running_operation.md) for more information.

@@ -0,0 +1,174 @@
+# Azure Core - Environment Variables Reference
+
+This document lists all environment variables recognized by `azure-core`.
+
+## SDK Configuration
+
+### `AZURE_LOG_LEVEL`
+
+Controls the logging level for all Azure SDK clients.
+
+| | |
+|---|---|
+| **Used by** | `azure.core.settings.Settings.log_level` |
+| **Default** | `INFO` |
+| **Accepted values** | `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG` (case-insensitive) |
+
+**Example:**
+
+```bash
+export AZURE_LOG_LEVEL=DEBUG
+```
+
+### `AZURE_TRACING_ENABLED`
+
+Enables or disables distributed tracing across Azure SDK clients.
+
+| | |
+|---|---|
+| **Used by** | `azure.core.settings.Settings.tracing_enabled` |
+| **Default** | Auto-detected based on whether `AZURE_SDK_TRACING_IMPLEMENTATION` is set |
+| **Accepted values** | `true`, `yes`, `1`, `on` to enable; `false`, `no`, `0`, `off` to disable (case-insensitive) |
+
+When not set, tracing is automatically enabled if a tracing implementation is configured (via `AZURE_SDK_TRACING_IMPLEMENTATION`), and disabled otherwise.
+
+**Example:**
+
+```bash
+export AZURE_TRACING_ENABLED=true
+```
+
+### `AZURE_SDK_TRACING_IMPLEMENTATION`
+
+Specifies which distributed tracing implementation the SDK should use.
+
+| | |
+|---|---|
+| **Used by** | `azure.core.settings.Settings.tracing_implementation` |
+| **Default** | None |
+| **Accepted values** | `opentelemetry`, `opencensus` |
+
+The corresponding tracing plugin package must be installed:
+
+- `opentelemetry` — requires `azure-core-tracing-opentelemetry`
+- `opencensus` — requires `azure-core-tracing-opencensus`
+
+**Example:**
+
+```bash
+export AZURE_SDK_TRACING_IMPLEMENTATION=opentelemetry
+```
+
+### `AZURE_SDK_CLOUD_CONF`
+
+Sets the Azure cloud environment used by SDK clients.
+
+| | |
+|---|---|
+| **Used by** | `azure.core.settings.Settings.azure_cloud` |
+| **Default** | `AZURE_PUBLIC_CLOUD` |
+| **Accepted values** | `AZURE_PUBLIC_CLOUD`, `AZURE_CHINA_CLOUD`, `AZURE_US_GOVERNMENT` |
+
+**Example:**
+
+```bash
+export AZURE_SDK_CLOUD_CONF=AZURE_CHINA_CLOUD
+```
+
+## HTTP Pipeline
+
+### `AZURE_HTTP_USER_AGENT`
+
+Appends a custom string to the `User-Agent` header sent with every HTTP request.
+
+| | |
+|---|---|
+| **Used by** | `azure.core.pipeline.policies.UserAgentPolicy` |
+| **Default** | None |
+| **Accepted values** | Any string |
+
+The value is appended to the end of the SDK-generated User-Agent string. This variable is only read when `user_agent_use_env=True` (the default).
+
+**Example:**
+
+```bash
+export AZURE_HTTP_USER_AGENT="my-app/1.0"
+```
+
+### `AZURE_SDK_LOGGING_MULTIRECORD`
+
+Controls the HTTP logging format used by `HttpLoggingPolicy`.
+
+| | |
+|---|---|
+| **Used by** | `azure.core.pipeline.policies.HttpLoggingPolicy` |
+| **Default** | Disabled (single-record format) |
+| **Accepted values** | Any truthy value to enable |
+
+When set, HTTP request and response details are logged as separate log records instead of a single combined record. This can make log output easier to parse in structured logging systems.
+
+**Example:**
+
+```bash
+export AZURE_SDK_LOGGING_MULTIRECORD=1
+```
+
+## Network & Proxy
+
+These standard proxy environment variables are honored by the underlying HTTP transport libraries (`requests` and `aiohttp`) when the transport is created with `use_env_settings=True` (the default).
+
+### `HTTP_PROXY`
+
+HTTP proxy URL for requests made over HTTP.
+
+| | |
+|---|---|
+| **Used by** | `RequestsTransport`, `AioHttpTransport` (via `session.trust_env`) |
+| **Default** | None |
+| **Accepted values** | `http://[user:password@]host:port` |
+
+### `HTTPS_PROXY`
+
+HTTP proxy URL for requests made over HTTPS.
+
+| | |
+|---|---|
+| **Used by** | `RequestsTransport`, `AioHttpTransport` (via `session.trust_env`) |
+| **Default** | None |
+| **Accepted values** | `http://[user:password@]host:port` |
+
+### `NO_PROXY`
+
+Comma-separated list of hostnames or IP addresses that should bypass the proxy.
+
+| | |
+|---|---|
+| **Used by** | `RequestsTransport`, `AioHttpTransport` (via `session.trust_env`) |
+| **Default** | None |
+| **Accepted values** | Comma-separated hostnames, e.g. `localhost,127.0.0.1,.example.com` |
+
+**Example:**
+
+```bash
+export HTTP_PROXY=http://proxy.example.com:8080
+export HTTPS_PROXY=http://proxy.example.com:8080
+export NO_PROXY=localhost,127.0.0.1,.internal.corp
+```
+
+To disable reading proxy settings from the environment, create the transport with `use_env_settings=False`:
+
+```python
+from azure.core.pipeline.transport import RequestsTransport
+
+transport = RequestsTransport(use_env_settings=False)
+```
+
+## Settings Priority
+
+Environment variables are just one source of configuration. The `azure.core.settings` module resolves values in the following priority order (highest to lowest):
+
+1. **Immediate values** — passed directly when retrieving the setting
+2. **User-set values** — assigned programmatically via `settings.<name> = value`
+3. **Environment variables** — read from `os.environ`
+4. **System settings** — obtained from OS-level registries or hooks
+5. **Implicit defaults** — defined by the setting itself
@@ -190,6 +190,11 @@ class UserAgentPolicy(SansIOHTTPPolicy[HTTPRequestType, HTTPResponseType]):
     :keyword str sdk_moniker: If specified, the user agent string will be
         azsdk-python-[sdk_moniker] Python/[python_version] ([platform_version])
 
+    Environment variables:
+
+    * ``AZURE_HTTP_USER_AGENT`` - If set and ``user_agent_use_env`` is True (the default),
+      the value is appended to the User-Agent header string sent with each request.
+
     .. admonition:: Example:
 
         .. literalinclude:: ../samples/test_example_sansio.py
@@ -389,6 +394,11 @@ class HttpLoggingPolicy(
 
     :param logger: The logger to use for logging. Default to azure.core.pipeline.policies.http_logging_policy.
     :type logger: logging.Logger
+
+    Environment variables:
+
+    * ``AZURE_SDK_LOGGING_MULTIRECORD`` - If set to any truthy value, HTTP request and response
+      details are logged as separate log records instead of a single combined record.
     """
 
     DEFAULT_HEADERS_ALLOWLIST: Set[str] = set(

@@ -127,6 +127,12 @@ class AioHttpTransport(AsyncHttpTransport):
     :keyword bool session_owner: Session owner. Defaults True.
     :keyword bool use_env_settings: Uses proxy settings from environment. Defaults to True.
 
+    Environment variables (read when ``use_env_settings`` is True, the default):
+
+    * ``HTTP_PROXY`` - Proxy URL for HTTP requests.
+    * ``HTTPS_PROXY`` - Proxy URL for HTTPS requests.
+    * ``NO_PROXY`` - Comma-separated list of hosts that should bypass the proxy.
+
     .. admonition:: Example:
 
         .. literalinclude:: ../samples/test_example_async.py

@@ -249,6 +249,12 @@ class RequestsTransport(HttpTransport):
     :keyword bool session_owner: Decide if the session provided by user is owned by this transport. Default to True.
     :keyword bool use_env_settings: Uses proxy settings from environment. Defaults to True.
 
+    Environment variables (read when ``use_env_settings`` is True, the default):
+
+    * ``HTTP_PROXY`` - Proxy URL for HTTP requests.
+    * ``HTTPS_PROXY`` - Proxy URL for HTTPS requests.
+    * ``NO_PROXY`` - Comma-separated list of hosts that should bypass the proxy.
+
     .. admonition:: Example:
 
         .. literalinclude:: ../samples/test_example_sync.py

@@ -427,6 +427,21 @@ class Settings:
     :type tracing_enabled: PrioritizedSetting
     :cvar tracing_implementation: The tracing implementation to use (AZURE_SDK_TRACING_IMPLEMENTATION)
     :type tracing_implementation: PrioritizedSetting
+    :cvar azure_cloud: The Azure cloud environment to use (AZURE_SDK_CLOUD_CONF)
+    :type azure_cloud: PrioritizedSetting
+
+    The following environment variables are used by the settings:
+
+    * ``AZURE_LOG_LEVEL`` - Logging level. Accepted values: ``CRITICAL``, ``ERROR``, ``WARNING``,
+      ``INFO``, ``DEBUG`` (case-insensitive). Default: ``INFO``.
+    * ``AZURE_TRACING_ENABLED`` - Enable/disable tracing. Accepted values: ``true``/``false``,
+      ``yes``/``no``, ``1``/``0``, ``on``/``off`` (case-insensitive). Default: auto-detected
+      based on whether a tracing implementation is configured.
+    * ``AZURE_SDK_TRACING_IMPLEMENTATION`` - Tracing implementation. Accepted values:
+      ``opentelemetry``, ``opencensus``. Default: None.
+    * ``AZURE_SDK_CLOUD_CONF`` - Azure cloud environment. Accepted values:
+      ``AZURE_PUBLIC_CLOUD``, ``AZURE_CHINA_CLOUD``, ``AZURE_US_GOVERNMENT``.
+      Default: ``AZURE_PUBLIC_CLOUD``.
 
     :Example: