0
# Configuration and Settings
1

2
Azure Core provides a comprehensive global configuration system that manages Azure SDK settings with a clear precedence hierarchy, environment variable support, and programmatic configuration options. The settings system enables consistent behavior across all Azure SDK components.
3

4
## Global Settings Instance
5

6
```python { .api }
7
from azure.core.settings import settings
8

9
# Global settings singleton
10
settings.log_level = logging.DEBUG
11
settings.tracing_enabled = True
12
settings.tracing_implementation = "opentelemetry"
13
settings.azure_cloud = AzureClouds.AZURE_US_GOVERNMENT
14
```
15

16
## Configuration Priority
17

18
Settings follow a 5-level precedence system (highest to lowest priority):
19

20
1. **Immediate values**: Values passed directly to setting calls
21
2. **User-set values**: Values set programmatically via assignment
22
3. **Environment variables**: OS environment variables
23
4. **System settings**: System-wide configurations 
24
5. **Default values**: Built-in default values
25

26
## Available Settings
27

28
### Log Level
29

30
Controls logging level for Azure SDK operations.
31

32
```python { .api }
33
import logging
34
from azure.core.settings import settings
35

36
# Programmatic configuration
37
settings.log_level = logging.DEBUG
38
settings.log_level = logging.INFO
39
settings.log_level = logging.WARNING
40
settings.log_level = logging.ERROR
41
settings.log_level = logging.CRITICAL
42

43
# Get current log level
44
current_level = settings.log_level()
45

46
# Use immediate value (highest priority)
47
temp_level = settings.log_level(logging.WARNING)
48
```
49

50
**Environment Variable**: `AZURE_LOG_LEVEL`
51
**Default**: `logging.INFO` (20)
52
**Supported Values**:
53
- Integers: Any valid logging level
54
- Strings: "CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG" (case-insensitive)
55

56
**Environment Variable Usage**:
57
```bash
58
export AZURE_LOG_LEVEL=DEBUG
59
export AZURE_LOG_LEVEL=20
60
```
61

62
### Tracing Enabled
63

64
Controls whether distributed tracing is enabled across Azure SDK operations.
65

66
```python { .api }
67
from azure.core.settings import settings
68

69
# Enable/disable tracing
70
settings.tracing_enabled = True
71
settings.tracing_enabled = False
72

73
# Auto-enable when implementation is set
74
settings.tracing_implementation = "opentelemetry"
75
# tracing_enabled automatically becomes True
76

77
# Check current status
78
is_enabled = settings.tracing_enabled()
79
```
80

81
**Environment Variable**: `AZURE_TRACING_ENABLED`
82
**Default**: `None` (auto-determined based on tracing implementation)
83
**Supported Values**:
84
- Boolean: `True`, `False`
85
- Strings: "yes", "1", "on", "true" → `True`; "no", "0", "off", "false" → `False`
86

87
**Environment Variable Usage**:
88
```bash
89
export AZURE_TRACING_ENABLED=true
90
export AZURE_TRACING_ENABLED=1
91
export AZURE_TRACING_ENABLED=yes
92
```
93

94
### Tracing Implementation
95

96
Specifies which distributed tracing implementation to use.
97

98
```python { .api }
99
from azure.core.settings import settings
100
from azure.core.tracing.ext.opentelemetry_span import OpenTelemetrySpan
101

102
# String-based configuration
103
settings.tracing_implementation = "opentelemetry"
104
settings.tracing_implementation = "opencensus"
105

106
# Direct class assignment
107
settings.tracing_implementation = OpenTelemetrySpan
108

109
# Get current implementation
110
impl = settings.tracing_implementation()
111
```
112

113
**Environment Variable**: `AZURE_SDK_TRACING_IMPLEMENTATION`
114
**Default**: `None`
115
**Supported Values**:
116
- `None`: No tracing implementation
117
- String: "opentelemetry", "opencensus" (case-insensitive)
118
- Type: Any `AbstractSpan` subclass
119

120
**Environment Variable Usage**:
121
```bash
122
export AZURE_SDK_TRACING_IMPLEMENTATION=opentelemetry
123
```
124

125
### Azure Cloud
126

127
Specifies which Azure cloud environment to use for default endpoints and configurations.
128

129
```python { .api }
130
from azure.core.settings import settings
131
from azure.core import AzureClouds
132

133
# Enum-based configuration
134
settings.azure_cloud = AzureClouds.AZURE_PUBLIC_CLOUD
135
settings.azure_cloud = AzureClouds.AZURE_CHINA_CLOUD
136
settings.azure_cloud = AzureClouds.AZURE_US_GOVERNMENT
137

138
# String-based configuration
139
settings.azure_cloud = "AZURE_US_GOVERNMENT"
140
settings.azure_cloud = "AZURE_CHINA_CLOUD"
141

142
# Get current cloud
143
cloud = settings.azure_cloud()
144
```
145

146
**Environment Variable**: `AZURE_CLOUD`
147
**Default**: `AzureClouds.AZURE_PUBLIC_CLOUD`
148
**Supported Values**:
149
- `AzureClouds.AZURE_PUBLIC_CLOUD`: Public Azure cloud
150
- `AzureClouds.AZURE_CHINA_CLOUD`: Azure China cloud
151
- `AzureClouds.AZURE_US_GOVERNMENT`: Azure US Government cloud
152

153
**Environment Variable Usage**:
154
```bash
155
export AZURE_CLOUD=AZURE_US_GOVERNMENT
156
export AZURE_CLOUD=AZURE_CHINA_CLOUD
157
```
158

159
## Configuration Snapshots
160

161
### Current Configuration
162

163
Get a snapshot of all current settings with their computed values.
164

165
```python { .api }
166
from azure.core.settings import settings
167

168
# Get current configuration snapshot
169
current_config = settings.current
170

171
# Access individual settings
172
print(f"Log Level: {current_config.log_level}")
173
print(f"Tracing Enabled: {current_config.tracing_enabled}")
174
print(f"Tracing Implementation: {current_config.tracing_implementation}")
175
print(f"Azure Cloud: {current_config.azure_cloud}")
176
```
177

178
### Default Configuration
179

180
Get a snapshot of all default values without environment or user overrides.
181

182
```python { .api }
183
from azure.core.settings import settings
184

185
# Get default configuration snapshot
186
defaults = settings.defaults
187

188
print(f"Default Log Level: {defaults.log_level}")
189
print(f"Default Tracing Enabled: {defaults.tracing_enabled}")
190
print(f"Default Azure Cloud: {defaults.azure_cloud}")
191
```
192

193
### Custom Configuration
194

195
Create a configuration snapshot with specific overrides.
196

197
```python { .api }
198
import logging
199
from azure.core.settings import settings
200
from azure.core import AzureClouds
201

202
# Create custom configuration
203
custom_config = settings.config(
204
    log_level=logging.ERROR,
205
    tracing_enabled=False,
206
    azure_cloud=AzureClouds.AZURE_CHINA_CLOUD
207
)
208

209
# Use custom configuration values
210
print(f"Custom Log Level: {custom_config.log_level}")
211
```
212

213
## Practical Usage Examples
214

215
### Development Environment Setup
216

217
```python
218
import logging
219
from azure.core.settings import settings
220

221
# Development configuration
222
settings.log_level = logging.DEBUG
223
settings.tracing_enabled = True
224
settings.tracing_implementation = "opentelemetry"
225

226
print(f"Development config - Tracing: {settings.tracing_enabled()}")
227
print(f"Development config - Log Level: {settings.log_level()}")
228
```
229

230
### Production Environment Setup
231

232
```bash
233
# Production environment variables
234
export AZURE_LOG_LEVEL=WARNING
235
export AZURE_TRACING_ENABLED=true
236
export AZURE_SDK_TRACING_IMPLEMENTATION=opentelemetry
237
export AZURE_CLOUD=AZURE_PUBLIC_CLOUD
238
```
239

240
### Configuration Validation
241

242
```python
243
from azure.core.settings import settings
244
import logging
245

246
def validate_configuration():
247
    """Validate current Azure SDK configuration"""
248
    config = settings.current
249
    
250
    # Check logging configuration
251
    if config.log_level < logging.WARNING:
252
        print("Warning: Verbose logging enabled - may impact performance")
253
    
254
    # Check tracing configuration
255
    if config.tracing_enabled and not config.tracing_implementation:
256
        print("Error: Tracing enabled but no implementation specified")
257
        return False
258
    
259
    # Check cloud configuration
260
    print(f"Using Azure Cloud: {config.azure_cloud}")
261
    
262
    return True
263

264
# Validate before starting application
265
if validate_configuration():
266
    print("Configuration is valid")
267
```
268

269
### Temporary Configuration Override
270

271
```python
272
from azure.core.settings import settings
273
import logging
274

275
def debug_operation():
276
    """Temporarily enable debug logging for this operation"""
277
    # Save current log level
278
    original_level = settings.log_level()
279
    
280
    try:
281
        # Temporarily set debug level
282
        settings.log_level = logging.DEBUG
283
        
284
        # Perform operation with debug logging
285
        perform_complex_operation()
286
        
287
    finally:
288
        # Restore original log level
289
        settings.log_level = original_level
290

291
def immediate_override_example():
292
    """Use immediate value without changing global setting"""
293
    # Use debug level just for this call without changing global setting
294
    current_level = settings.log_level(logging.DEBUG)
295
    
296
    # Global setting remains unchanged
297
    global_level = settings.log_level()
298
    print(f"Immediate: {current_level}, Global: {global_level}")
299
```
300

301
### Settings Reset and Management
302

303
```python
304
from azure.core.settings import settings
305

306
def reset_to_defaults():
307
    """Reset all settings to their default values"""
308
    # Reset individual settings
309
    settings.log_level.unset_value()
310
    settings.tracing_enabled.unset_value()
311
    settings.tracing_implementation.unset_value()
312
    settings.azure_cloud.unset_value()
313

314
def show_configuration_sources():
315
    """Show where each setting value comes from"""
316
    # This would show the precedence for each setting
317
    print("Configuration Sources:")
318
    print(f"Log Level - Current: {settings.log_level()}")
319
    print(f"Log Level - Default: {settings.defaults.log_level}")
320
    print(f"Log Level - Environment: {settings.log_level.env_var}")
321
```
322

323
### Integration with Application Configuration
324

325
```python
326
import os
327
from azure.core.settings import settings
328
from azure.core import AzureClouds
329

330
def configure_from_app_config(app_config: dict):
331
    """Configure Azure SDK from application configuration"""
332
    
333
    # Map application config to Azure settings
334
    log_level_map = {
335
        'debug': logging.DEBUG,
336
        'info': logging.INFO,
337
        'warning': logging.WARNING,
338
        'error': logging.ERROR
339
    }
340
    
341
    # Configure logging
342
    if 'log_level' in app_config:
343
        settings.log_level = log_level_map.get(
344
            app_config['log_level'].lower(), 
345
            logging.INFO
346
        )
347
    
348
    # Configure tracing
349
    if app_config.get('enable_tracing', False):
350
        settings.tracing_enabled = True
351
        settings.tracing_implementation = app_config.get(
352
            'tracing_provider', 
353
            'opentelemetry'
354
        )
355
    
356
    # Configure cloud environment
357
    cloud_map = {
358
        'public': AzureClouds.AZURE_PUBLIC_CLOUD,
359
        'china': AzureClouds.AZURE_CHINA_CLOUD,
360
        'government': AzureClouds.AZURE_US_GOVERNMENT
361
    }
362
    
363
    if 'azure_cloud' in app_config:
364
        settings.azure_cloud = cloud_map.get(
365
            app_config['azure_cloud'].lower(),
366
            AzureClouds.AZURE_PUBLIC_CLOUD
367
        )
368

369
# Example usage
370
app_config = {
371
    'log_level': 'debug',
372
    'enable_tracing': True,
373
    'tracing_provider': 'opentelemetry',
374
    'azure_cloud': 'government'
375
}
376

377
configure_from_app_config(app_config)
378
```
379

380
## Key Features
381

382
**Hierarchical Precedence**: Clear 5-level priority system ensures predictable configuration behavior.
383

384
**Environment Variable Support**: All settings can be configured via environment variables for deployment flexibility.
385

386
**Type Safety**: Automatic type conversion and validation for all configuration values.
387

388
**Configuration Snapshots**: Capture configuration state for debugging and validation.
389

390
**Global Consistency**: Single source of truth for Azure SDK configuration across all components.
391

392
**Runtime Changes**: Settings can be modified at runtime and take effect immediately.
393

394
**Default Restoration**: Settings can be reset to defaults while preserving environment variable behavior.
395

396
The configuration system provides a robust foundation for managing Azure SDK behavior consistently across different deployment environments while supporting both programmatic and environment-based configuration approaches.