diff --git a/sdk/core/azure-core/CLIENT_LIBRARY_DEVELOPER.md b/sdk/core/azure-core/CLIENT_LIBRARY_DEVELOPER.md index aa6db05385af..0fe4b07ec19c 100644 --- a/sdk/core/azure-core/CLIENT_LIBRARY_DEVELOPER.md +++ b/sdk/core/azure-core/CLIENT_LIBRARY_DEVELOPER.md @@ -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. = 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. diff --git a/sdk/core/azure-core/ENVIRONMENT_VARIABLES.md b/sdk/core/azure-core/ENVIRONMENT_VARIABLES.md new file mode 100644 index 000000000000..8c093d5c9aec --- /dev/null +++ b/sdk/core/azure-core/ENVIRONMENT_VARIABLES.md @@ -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. = 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 diff --git a/sdk/core/azure-core/azure/core/pipeline/policies/_universal.py b/sdk/core/azure-core/azure/core/pipeline/policies/_universal.py index 67fc6aef4e69..bd482b84e892 100644 --- a/sdk/core/azure-core/azure/core/pipeline/policies/_universal.py +++ b/sdk/core/azure-core/azure/core/pipeline/policies/_universal.py @@ -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( diff --git a/sdk/core/azure-core/azure/core/pipeline/transport/_aiohttp.py b/sdk/core/azure-core/azure/core/pipeline/transport/_aiohttp.py index 9c653b34d55b..8af2829b7a86 100644 --- a/sdk/core/azure-core/azure/core/pipeline/transport/_aiohttp.py +++ b/sdk/core/azure-core/azure/core/pipeline/transport/_aiohttp.py @@ -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 diff --git a/sdk/core/azure-core/azure/core/pipeline/transport/_requests_basic.py b/sdk/core/azure-core/azure/core/pipeline/transport/_requests_basic.py index 9f102f4b0b20..ef99c0e50b5a 100644 --- a/sdk/core/azure-core/azure/core/pipeline/transport/_requests_basic.py +++ b/sdk/core/azure-core/azure/core/pipeline/transport/_requests_basic.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 diff --git a/sdk/core/azure-core/azure/core/settings.py b/sdk/core/azure-core/azure/core/settings.py index 8ba3ee4a80d3..bb4810ef4dfd 100644 --- a/sdk/core/azure-core/azure/core/settings.py +++ b/sdk/core/azure-core/azure/core/settings.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: