0
# Configuration and Setup
1

2
Global configuration system for structlog that controls how loggers are created, how log events are processed, and how the overall logging pipeline behaves. Configuration is typically done once at application startup and affects all subsequent logger creation.
3

4
## Capabilities
5

6
### Global Configuration
7

8
Configure structlog's global defaults including processors, wrapper classes, context classes, and logger factories.
9

10
```python { .api }
11
def configure(
12
    processors=None,
13
    wrapper_class=None,
14
    context_class=None,
15
    logger_factory=None,
16
    cache_logger_on_first_use=None
17
) -> None:
18
    """
19
    Configure structlog's global defaults.
20

21
    Args:
22
        processors (list, optional): List of processor functions/classes to apply to all log events
23
        wrapper_class (type, optional): Class to wrap loggers (default: BoundLogger)
24
        context_class (type, optional): Class for context storage (default: dict)
25
        logger_factory (callable, optional): Factory function for creating loggers
26
        cache_logger_on_first_use (bool, optional): Whether to cache loggers after first use
27
    """
28
```
29

30
### Conditional Configuration
31

32
Configure structlog only if it hasn't been configured already, useful for libraries that want to set defaults without overriding user configuration.
33

34
```python { .api }
35
def configure_once(
36
    processors=None,
37
    wrapper_class=None,
38
    context_class=None,
39
    logger_factory=None,
40
    cache_logger_on_first_use=None
41
) -> None:
42
    """
43
    Configure structlog only if not already configured.
44

45
    Args:
46
        Same as configure()
47
    """
48
```
49

50
### Configuration Inspection
51

52
Get the current configuration state and check whether structlog has been configured.
53

54
```python { .api }
55
def get_config() -> dict[str, Any]:
56
    """
57
    Get current structlog configuration as a dictionary.
58

59
    Returns:
60
        dict: Current configuration with keys for processors, wrapper_class, 
61
              context_class, logger_factory, cache_logger_on_first_use
62
    """
63

64
def is_configured() -> bool:
65
    """
66
    Check if structlog has been configured.
67

68
    Returns:
69
        bool: True if configure() has been called, False otherwise
70
    """
71
```
72

73
### Configuration Reset
74

75
Reset structlog to its built-in defaults, clearing any previous configuration.
76

77
```python { .api }
78
def reset_defaults() -> None:
79
    """
80
    Reset structlog to built-in defaults.
81
    
82
    This clears any previous configuration and restores the original
83
    default processors, wrapper class, and other settings.
84
    """
85
```
86

87
## Usage Examples
88

89
### Basic Configuration
90

91
```python
92
import structlog
93

94
# Simple configuration with console output
95
structlog.configure(
96
    processors=[
97
        structlog.processors.TimeStamper(fmt="iso"),
98
        structlog.dev.ConsoleRenderer()
99
    ],
100
    wrapper_class=structlog.stdlib.BoundLogger,
101
    logger_factory=structlog.stdlib.LoggerFactory(),
102
    cache_logger_on_first_use=True,
103
)
104
```
105

106
### Production Configuration
107

108
```python
109
import structlog
110
import logging
111

112
# Configure Python logging first
113
logging.basicConfig(
114
    level=logging.INFO,
115
    format="%(message)s",
116
)
117

118
# Configure structlog for JSON output
119
structlog.configure(
120
    processors=[
121
        structlog.processors.TimeStamper(fmt="iso"),
122
        structlog.processors.add_log_level,
123
        structlog.processors.JSONRenderer()
124
    ],
125
    wrapper_class=structlog.stdlib.BoundLogger,
126
    logger_factory=structlog.stdlib.LoggerFactory(),
127
    context_class=dict,
128
    cache_logger_on_first_use=True,
129
)
130
```
131

132
### Development Configuration
133

134
```python
135
import structlog
136

137
# Configuration optimized for development
138
structlog.configure(
139
    processors=[
140
        structlog.processors.TimeStamper(fmt="iso"),
141
        structlog.dev.ConsoleRenderer(
142
            colors=True,
143
            exception_formatter=structlog.dev.rich_traceback
144
        )
145
    ],
146
    wrapper_class=structlog.stdlib.BoundLogger,
147
    logger_factory=structlog.stdlib.LoggerFactory(),
148
    cache_logger_on_first_use=True,
149
)
150
```
151

152
### Conditional Configuration for Libraries
153

154
```python
155
import structlog
156

157
# Library code that sets defaults without overriding user config
158
def setup_logging():
159
    structlog.configure_once(
160
        processors=[
161
            structlog.processors.TimeStamper(),
162
            structlog.processors.JSONRenderer()
163
        ],
164
        wrapper_class=structlog.stdlib.BoundLogger,
165
        logger_factory=structlog.stdlib.LoggerFactory(),
166
    )
167
```
168

169
### Configuration Inspection
170

171
```python
172
import structlog
173

174
# Check if configured
175
if not structlog.is_configured():
176
    # Set up default configuration
177
    structlog.configure(...)
178

179
# Get current configuration
180
config = structlog.get_config()
181
print(f"Processors: {config['processors']}")
182
print(f"Wrapper class: {config['wrapper_class']}")
183
```