0
# Core Configuration
1

2
Base formatter class and configuration system that provides extensive customization options for JSON log output. All formatter implementations inherit from BaseJsonFormatter.
3

4
## Core Imports
5

6
```python
7
from pythonjsonlogger.core import BaseJsonFormatter, str_to_object, merge_record_extra, RESERVED_ATTRS
8
```
9

10
For type checking:
11

12
```python
13
from typing import Optional, Union, Dict, Any, List, Sequence, Container
14
import logging
15
```
16

17
## Capabilities
18

19
### BaseJsonFormatter Class
20

21
Abstract base class providing core JSON logging functionality and configuration options.
22

23
```python { .api }
24
class BaseJsonFormatter(logging.Formatter):
25
    def __init__(
26
        self,
27
        fmt: Optional[str] = None,
28
        datefmt: Optional[str] = None,
29
        style: str = "%",
30
        validate: bool = True,
31
        *,
32
        prefix: str = "",
33
        rename_fields: Optional[Dict[str, str]] = None,
34
        rename_fields_keep_missing: bool = False,
35
        static_fields: Optional[Dict[str, Any]] = None,
36
        reserved_attrs: Optional[Sequence[str]] = None,
37
        timestamp: Union[bool, str] = False,
38
        defaults: Optional[Dict[str, Any]] = None,
39
        exc_info_as_array: bool = False,
40
        stack_info_as_array: bool = False,
41
    ) -> None:
42
        """
43
        Base JSON formatter initialization with extensive configuration options.
44

45
        Standard logging parameters:
46
        - fmt: string representing fields to log
47
        - datefmt: format to use when formatting asctime field  
48
        - style: how to extract log fields from fmt (%, {, $)
49
        - validate: validate fmt against style
50

51
        JSON-specific parameters:
52
        - prefix: string prefix added to formatted output
53
        - rename_fields: dict to rename field names in output
54
        - rename_fields_keep_missing: include missing fields when renaming
55
        - static_fields: dict of fields with static values added to all logs
56
        - reserved_attrs: list of fields to skip when outputting JSON
57
        - timestamp: add timestamp field (True, False, or custom key name)
58
        - defaults: dict of default fields added before all other fields
59
        - exc_info_as_array: break exc_info into array of lines
60
        - stack_info_as_array: break stack_info into array of lines
61
        """
62

63
    def format(self, record: logging.LogRecord) -> str:
64
        """
65
        Format a log record and serialize to JSON.
66

67
        Parameters:
68
        - record: the log record to format
69

70
        Returns:
71
        JSON string representation of the log record
72
        """
73

74
    def parse(self) -> List[str]:
75
        """
76
        Parse format string looking for field substitutions.
77

78
        Supports %, {}, and $ style format strings.
79

80
        Returns:
81
        List of field names to be extracted and serialized
82
        """
83

84
    def serialize_log_record(self, log_record: LogRecord) -> str:
85
        """
86
        Return final representation of the log record.
87

88
        Applies prefix and calls jsonify_log_record.
89

90
        Parameters:
91
        - log_record: the log record dictionary
92

93
        Returns:
94
        Final formatted string
95
        """
96

97
    def add_fields(
98
        self,
99
        log_record: Dict[str, Any],
100
        record: logging.LogRecord,
101
        message_dict: Dict[str, Any],
102
    ) -> None:
103
        """
104
        Extract fields from a LogRecord for logging.
105

106
        Can be overridden to implement custom field extraction logic.
107

108
        Parameters:
109
        - log_record: dictionary that will be logged
110
        - record: the original LogRecord to extract data from
111
        - message_dict: dictionary logged instead of a message
112
        """
113

114
    def jsonify_log_record(self, log_record: LogRecord) -> str:
115
        """
116
        Convert log record into JSON string.
117

118
        Abstract method that must be implemented by subclasses.
119

120
        Parameters:
121
        - log_record: the data to serialize
122

123
        Returns:
124
        JSON string representation
125
        """
126

127
    def process_log_record(self, log_record: LogRecord) -> LogRecord:
128
        """
129
        Custom processing hook for log records.
130

131
        Can be overridden to modify log records before serialization.
132

133
        Parameters:
134
        - log_record: incoming log data
135

136
        Returns:
137
        Processed log record
138
        """
139

140
    def formatException(self, ei) -> Union[str, list[str]]:
141
        """
142
        Format and return exception information.
143

144
        Parameters:
145
        - ei: exception info tuple
146

147
        Returns:
148
        Formatted exception as string or list of strings if exc_info_as_array is True
149
        """
150

151
    def formatStack(self, stack_info) -> Union[str, list[str]]:
152
        """
153
        Format and return stack information.
154

155
        Parameters:
156
        - stack_info: stack info string
157

158
        Returns:
159
        Formatted stack as string or list of strings if stack_info_as_array is True
160
        """
161
```
162

163
### Core Utility Functions
164

165
Utility functions for string-to-object conversion and log record merging.
166

167
```python { .api }
168
def str_to_object(obj: Any) -> Any:
169
    """
170
    Import strings to an object, leaving non-strings as-is.
171

172
    Converts module.function strings to actual callable objects.
173

174
    Parameters:
175
    - obj: the object or string to process
176

177
    Returns:
178
    Imported object if string, otherwise original object
179
    """
180

181
def merge_record_extra(
182
    record: logging.LogRecord,
183
    target: Dict,
184
    reserved: Container[str], 
185
    rename_fields: Optional[Dict[str, str]] = None,
186
) -> Dict:
187
    """
188
    Merge extra attributes from LogRecord into target dictionary.
189

190
    Parameters:
191
    - record: logging.LogRecord instance
192
    - target: dictionary to update
193
    - reserved: container with reserved keys to skip
194
    - rename_fields: optional dict for renaming field names
195

196
    Returns:
197
    Updated target dictionary
198
    """
199
```
200

201
## Usage Examples
202

203
### Basic Configuration
204

205
```python
206
import logging
207
from pythonjsonlogger.json import JsonFormatter
208

209
# Basic formatter with field selection
210
formatter = JsonFormatter('%(levelname)s %(name)s %(message)s')
211

212
# Custom format with timestamp
213
formatter = JsonFormatter(
214
    '%(levelname)s %(message)s',
215
    timestamp=True  # Adds "timestamp" field
216
)
217

218
# Custom timestamp field name
219
formatter = JsonFormatter(
220
    '%(levelname)s %(message)s', 
221
    timestamp="log_time"  # Adds "log_time" field
222
)
223
```
224

225
### Field Renaming
226

227
```python
228
from pythonjsonlogger.json import JsonFormatter
229

230
# Rename fields in output
231
formatter = JsonFormatter(
232
    '%(levelname)s %(name)s %(message)s',
233
    rename_fields={
234
        'levelname': 'level',
235
        'name': 'logger',
236
        'message': 'msg'
237
    }
238
)
239

240
# Keep missing fields when renaming (with None values)
241
formatter = JsonFormatter(
242
    '%(levelname)s %(message)s',
243
    rename_fields={'nonexistent': 'missing'},
244
    rename_fields_keep_missing=True
245
)
246
```
247

248
### Static and Default Fields
249

250
```python
251
from pythonjsonlogger.json import JsonFormatter
252

253
# Add static fields to every log record
254
formatter = JsonFormatter(
255
    '%(levelname)s %(message)s',
256
    static_fields={
257
        'service': 'my-app',
258
        'version': '1.0.0',
259
        'environment': 'production'
260
    }
261
)
262

263
# Add default fields that can be overridden
264
formatter = JsonFormatter(
265
    '%(levelname)s %(message)s',
266
    defaults={
267
        'component': 'unknown',
268
        'user_id': None
269
    }
270
)
271
```
272

273
### Custom Reserved Attributes
274

275
```python
276
from pythonjsonlogger.json import JsonFormatter
277
from pythonjsonlogger.core import RESERVED_ATTRS
278

279
# Use custom reserved attributes list
280
custom_reserved = list(RESERVED_ATTRS) + ['custom_field']
281
formatter = JsonFormatter(
282
    '%(levelname)s %(message)s',
283
    reserved_attrs=custom_reserved
284
)
285

286
# Minimal reserved attributes (include more fields)
287
formatter = JsonFormatter(
288
    '%(levelname)s %(message)s',
289
    reserved_attrs=['args', 'msg']  # Only skip these fields
290
)
291
```
292

293
### Exception and Stack Formatting
294

295
```python
296
from pythonjsonlogger.json import JsonFormatter
297

298
# Format exceptions and stack traces as arrays
299
formatter = JsonFormatter(
300
    '%(levelname)s %(message)s',
301
    exc_info_as_array=True,
302
    stack_info_as_array=True
303
)
304

305
# Example output for exception:
306
# {"levelname": "ERROR", "message": "Error occurred", "exc_info": ["Traceback...", "  File...", "ValueError: error"]}
307
```
308

309
### String Prefix
310

311
```python
312
from pythonjsonlogger.json import JsonFormatter
313

314
# Add prefix to all log output
315
formatter = JsonFormatter(
316
    '%(levelname)s %(message)s',
317
    prefix='[JSON] '
318
)
319
# Output: [JSON] {"levelname": "INFO", "message": "test"}
320
```
321

322
### Format String Styles
323

324
```python
325
from pythonjsonlogger.json import JsonFormatter
326

327
# Percent style (default)
328
formatter = JsonFormatter('%(levelname)s %(message)s')
329

330
# Brace style
331
formatter = JsonFormatter('{levelname} {message}', style='{')
332

333
# Dollar style  
334
formatter = JsonFormatter('${levelname} ${message}', style='$')
335

336
# Custom style (requires validate=False)
337
formatter = JsonFormatter('custom_format', style='custom', validate=False)
338
```
339

340
## Configuration Reference
341

342
### Field Processing Order
343
1. **defaults**: Added first, can be overridden
344
2. **required_fields**: From format string parsing
345
3. **static_fields**: Added after defaults, override previous values
346
4. **message_dict**: From logging dict-style calls
347
5. **extra_fields**: From LogRecord.__dict__ (excluding reserved)
348
6. **timestamp**: Added if configured
349

350
### Reserved Attributes
351
Default reserved attributes (from `RESERVED_ATTRS`):
352
- Standard LogRecord fields: name, levelname, levelno, pathname, filename, module, funcName, lineno, created, msecs, relativeCreated, thread, threadName, process, processName, message, exc_info, exc_text, stack_info, args, asctime
353
- Python 3.12+: taskName
354

355
### Format String Processing
356
The formatter parses format strings to identify required fields:
357
- **% style**: `%(field)s` patterns
358
- **{ style**: `{field}` patterns  
359
- **$ style**: `${field}` patterns
360

361
Parsed fields are automatically included in JSON output.