Structlog

https://www.structlog.org/en/stable
Admin
Structlog is a production-ready, flexible, and fast structured logging solution for Python that...
Tokens:164,341
Snippets:1,231
Trust Score:8.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example log entry output

Source: https://www.structlog.org/en/stable/performance.html

A sample JSON log entry produced by the example configuration, showing the event, level, and timestamp fields.

```json
{"event":"hello","level":"info","timestamp":"2023-11-02T08:03:38.298565Z"}

```

--------------------------------

### Setup structlog with KeyValueRenderer for doctest

Source: https://www.structlog.org/en/stable/_sources/recipes.md

Configures structlog to use KeyValueRenderer as the only processor, used in the test setup for the example.

```python
import structlog
structlog.configure(
    processors=[structlog.processors.KeyValueRenderer()],
)
```

--------------------------------

### format_exc_info example

Source: https://www.structlog.org/en/stable/api.html

Shows how to use structlog.processors.format_exc_info to convert an exc_info key into an exception string. The example raises a ValueError and calls format_exc_info with exc_info set to True, producing a traceback string in the 'exception' key.

```python
>>> from structlog.processors import format_exc_info
>>> try:
...     raise ValueError
... except ValueError:
...     format_exc_info(None, "", {"exc_info": True})
{'exception': 'Traceback (most recent call last):...'
```

--------------------------------

### PrintLogger usage example

Source: https://www.structlog.org/en/stable/_modules/structlog/_output.html

Shows how to instantiate PrintLogger and call its info method, which prints the message to stdout. This is useful for testing and examples because logging is finicky in doctests.

```python
>>> from structlog import PrintLogger
>>> PrintLogger().info("hello")
hello
```

--------------------------------

### ReturnLogger usage example

Source: https://www.structlog.org/en/stable/api.html

Shows how to use structlog.testing.ReturnLogger to return the arguments it is called with. The example logs a single argument and multiple arguments, demonstrating the return values.

```python
>>> from structlog import ReturnLogger
>>> ReturnLogger().info("hello")
'hello'
>>> ReturnLogger().info("hello", when="again")
(('hello',), {'when': 'again'})
```

--------------------------------

### get_logger usage example

Source: https://www.structlog.org/en/stable/api.html

Shows how to create a logger with initial values and log a message. The output uses the KeyValueRenderer for brevity; the default configuration produces different output.

```python
>>> from structlog import get_logger
>>> log = get_logger(y=23)
>>> log.info("hello", x=42)
y=23 x=42 event='hello'

```

--------------------------------

### WriteLogger usage example

Source: https://www.structlog.org/en/stable/_modules/structlog/_output.html

Shows how to instantiate WriteLogger and call its info method, which writes the message to stdout. It is a little faster and a little less versatile than PrintLogger.

```python
>>> from structlog import WriteLogger
>>> WriteLogger().info("hello")
hello
```

--------------------------------

### dict_tracebacks example

Source: https://www.structlog.org/en/stable/api.html

Shows how to use structlog.processors.dict_tracebacks to replace an exc_info field with a structured traceback dictionary. The example raises a ValueError and calls dict_tracebacks with exc_info set to True, producing a structured exception entry.

```python
>>> from structlog.processors import dict_tracebacks
>>> try:
...     raise ValueError("onoes")
... except ValueError:
...     dict_tracebacks(None, "", {"exc_info": True})
{'exception': [{'exc_type': 'ValueError', 'exc_value': 'onoes', ..., 'frames': [{'filename': ...'
```

--------------------------------

### Example output of structlog and logging

Source: https://www.structlog.org/en/stable/_sources/standard-library.md

Shows the output of structlog and standard logging after the configuration. structlog logs are formatted as JSON, while standard logging logs are output as plain messages.

```pycon
>>> structlog.get_logger("test").warning("hello")
{"event": "hello", "logger": "test", "level": "warning", "timestamp": "2017-03-06T07:39:09.518720Z"}

>>> logging.getLogger("test").warning("hello")
hello
```

--------------------------------

### Example: Custom SemanticLogger wrapper class

Source: https://www.structlog.org/en/stable/_sources/recipes.md

Demonstrates creating a custom wrapper class by subclassing BoundLoggerBase. The SemanticLogger adds a default status of 'ok' to info calls unless a status is provided, and defines a user_error method. The example shows wrapping a PrintLogger and binding a user before calling user_error, producing the output shown.

```python
>>> from structlog import BoundLoggerBase, PrintLogger, wrap_logger
>>> class SemanticLogger(BoundLoggerBase):
...    def info(self, event, **kw):
...        if not "status" in kw:
...            return self._proxy_to_logger("info", event, status="ok", **kw)
...        else:
...            return self._proxy_to_logger("info", event, **kw)
...
...    def user_error(self, event, **kw):
...        self.info(event, status="user_error", **kw)
>>> log = wrap_logger(PrintLogger(), wrapper_class=SemanticLogger)
>>> log = log.bind(user="fprefect")
>>> log.user_error("user.forgot_towel")
user='fprefect' status='user_error' event='user.forgot_towel'
```

--------------------------------

### Basic logging configuration with basicConfig

Source: https://www.structlog.org/en/stable/standard-library.html

Configures the standard library logging to send messages of level INFO and above to standard out without special formatting. This is the minimal setup needed when using structlog with logging.

```python
import logging
import sys

logging.basicConfig(
    format="%(message)s",
    stream=sys.stdout,
    level=logging.INFO,
)

```

--------------------------------

### ReprWrapper example showing repr output

Source: https://www.structlog.org/en/stable/_modules/structlog/twisted.html

Demonstrates the difference between repr of a plain string and a ReprWrapper. ReprWrapper returns the string itself as its repr, which is needed for twisted.python.log.err that calls repr on _stuff.

```python
>>> repr("foo")
"'foo'"
>>> repr(ReprWrapper("foo"))
'foo'
```

--------------------------------

### Using plainJSONStdOutLogger with twistd

Source: https://www.structlog.org/en/stable/_sources/twisted.md

Shows how to use structlog.twisted.plainJSONStdOutLogger as the logger for twistd to get pure JSON log output without timestamps or system fields. The output lines are shown as examples.

```console
$ twistd -n --logger structlog.twisted.plainJSONStdOutLogger web
```

```console
{"event": "Log opened.", "system": "-"}
{"event": "twistd 13.1.0 (python 2.7.3) starting up.", "system": "-"}
{"event": "reactor class: twisted...EPollReactor.", "system": "-"}
{"event": "Site starting on 8080", "system": "-"}
{"event": "Starting factory <twisted.web.server.Site ...>", ...}
```

--------------------------------

### Type-annotated logger with structlog.get_logger()

Source: https://www.structlog.org/en/stable/_sources/typing.md

Use this snippet to get a logger with static type hints by annotating the return of structlog.get_logger() as structlog.stdlib.BoundLogger. The example shows that calling logger.info() is accepted, while logger.msg() triggers a Mypy error because BoundLogger has no attribute 'msg'.

```python
import structlog

logger: structlog.stdlib.BoundLogger = structlog.get_logger()
logger.info("hi")  # <- ok
logger.msg("hi")   # <- Mypy: 'error: "BoundLogger" has no attribute "msg"'

```

--------------------------------

### Fine-grained log-level filtering with CallsiteParameterAdder

Source: https://www.structlog.org/en/stable/_sources/recipes.md

This recipe shows how to filter out log entries from a specific function by adding CallsiteParameterAdder to the processor chain and using a custom processor that raises DropEvent. The example includes the logger setup, the filter processor, and the resulting output.

```python
logger = structlog.get_logger()

def f():
    logger.info("f called")

def g():
    logger.info("g called")

f()
g()
```

```python
def filter_f(_, __, event_dict):
    if event_dict.get("func_name") == "f":
        raise structlog.DropEvent

    return event_dict

structlog.configure(
    processors=[
        structlog.processors.CallsiteParameterAdder(
            [structlog.processors.CallsiteParameter.FUNC_NAME]
        ),
        filter_f,  # <-- your processor!
        structlog.processors.KeyValueRenderer(),
    ]
)
```

```text
event='g called' func_name='g'
```

--------------------------------

### Configure ConsoleRenderer with explicit columns

Source: https://www.structlog.org/en/stable/_sources/console-output.md

Configure ConsoleRenderer with explicit columns using structlog.dev.Column and KeyValueColumnFormatter. Pass the columns parameter to ConsoleRenderer; all other output-related parameters are ignored. The example defines formatters for timestamp, event, and a default for all other keys, then installs the renderer by replacing the last processor in structlog.configure.

```python
import structlog
import colorama

cr = structlog.dev.ConsoleRenderer(
    columns=[
        # Render the timestamp without the key name in yellow.
        structlog.dev.Column(
            "timestamp",
            structlog.dev.KeyValueColumnFormatter(
                key_style=None,
                value_style=colorama.Fore.YELLOW,
                reset_style=colorama.Style.RESET_ALL,
                value_repr=str,
            ),
        ),
        # Render the event without the key name in bright magenta.
        structlog.dev.Column(
            "event",
            structlog.dev.KeyValueColumnFormatter(
                key_style=None,
                value_style=colorama.Style.BRIGHT + colorama.Fore.MAGENTA,
                reset_style=colorama.Style.RESET_ALL,
                value_repr=str,
            ),
        ),
        # Default formatter for all keys not explicitly mentioned. The key is
        # cyan, the value is green.
        structlog.dev.Column(
            "",
            structlog.dev.KeyValueColumnFormatter(
                key_style=colorama.Fore.CYAN,
                value_style=colorama.Fore.GREEN,
                reset_style=colorama.Style.RESET_ALL,
                value_repr=str,
            ),
        ),
    ]
)

structlog.configure(processors=structlog.get_config()["processors"][:-1]+[cr])
```

--------------------------------

### Install structlog with pip

Source: https://www.structlog.org/en/stable/_sources/getting-started.md

Install structlog from PyPI using pip. This is the standard installation command.

```console
$ python -m pip install structlog
```

--------------------------------

### Inspect configuration with is_configured() and get_config()

Source: https://www.structlog.org/en/stable/configuration.html

Check configuration state with is_configured() and retrieve the current configuration with get_config(). The output shows the default state (False), the effect of configure(), and the resulting logger_factory value.

```python
>>> structlog.is_configured()
False
>>> structlog.configure(logger_factory=structlog.stdlib.LoggerFactory())
>>> structlog.is_configured()
True
>>> cfg = structlog.get_config()
>>> cfg["logger_factory"]
<class 'structlog.stdlib.LoggerFactory'>

```

--------------------------------

### Configure processor chain and show call chain

Source: https://www.structlog.org/en/stable/_sources/processors.md

Shows how to configure a processor chain and the resulting call chain when logging with bound context and an event.

```python
structlog.configure(processors=[f1, f2, f3])
log = structlog.get_logger().bind(x=42)
```

```python
wrapped_logger.info(
   f3(wrapped_logger, "info",
      f2(wrapped_logger, "info",
         f1(wrapped_logger, "info", {"event": "some_event", "x": 42, "y": 23})
      )
   )
)
```

--------------------------------

### EventAdapter.__init__

Source: https://www.structlog.org/en/stable/_modules/structlog/twisted.html

Initializes EventAdapter with an optional dictRenderer, defaulting to the last built-in processor. Must be the last processor in the chain to support log.msg() and log.err() behaviors.

```python
def __init__(
        self,
        dictRenderer: (
            Callable[[WrappedLogger, str, EventDict], str] | None
        ) = None,
    ) -> None:
        self._dictRenderer = dictRenderer or _BUILTIN_DEFAULT_PROCESSORS[-1]
```

--------------------------------

### ExceptionRenderer.__init__

Source: https://www.structlog.org/en/stable/_modules/structlog/processors.html

Initializes an ExceptionRenderer with an exception formatter.

```APIDOC
## ExceptionRenderer.__init__

### Description
Initializes an ExceptionRenderer instance. The exception_formatter is used to format exceptions from the exc_info field.

### Method
Constructor

### Parameters
- **exception_formatter** (ExceptionTransformer) - Optional - A callable that formats the exception. Defaults to _format_exception.

### Request Example
```python
renderer = ExceptionRenderer(exception_formatter=my_formatter)
```
```

--------------------------------

### EventAdapter example: handling a failure with log.err

Source: https://www.structlog.org/en/stable/_sources/twisted.md

Shows how to use structlog.twisted.EventAdapter with an existing Twisted application. The example defines an onError function that traps a MoonExploded failure and calls log.err with a _why argument. This works as expected when EventAdapter is placed at the end of the processing chain.

```python
def onError(fail):
   failure = fail.trap(MoonExploded)
   log.err(failure, _why="event-that-happened")
```

--------------------------------

### Tracebacks.__init__ method

Source: https://www.structlog.org/en/stable/_modules/structlog/tracebacks.html

Initializes the Tracebacks instance with options for showing locals, limiting local variable length and string length, hiding dunder/sunder locals, suppressing modules, limiting frame count, and using rich. Validates that locals_max_length and locals_max_string are non-negative and max_frames is at least 2. Converts suppress entries to absolute paths.

```python
    def __init__(
        self,
        *,
        show_locals: bool = SHOW_LOCALS,
        locals_max_length: int = LOCALS_MAX_LENGTH,
        locals_max_string: int = LOCALS_MAX_STRING,
        locals_hide_dunder: bool = True,
        locals_hide_sunder: bool = False,
        suppress: Iterable[str | ModuleType] = (),
        max_frames: int = MAX_FRAMES,
        use_rich: bool = True,
    ) -> None:
        if locals_max_length is not None and locals_max_length < 0:
            msg = f'"locals_max_length" must be >= 0: {locals_max_length}'
            raise ValueError(msg)
        if locals_max_string is not None and locals_max_string < 0:
            msg = f'"locals_max_string" must be >= 0: {locals_max_string}'
            raise ValueError(msg)
        if max_frames < 2:
            msg = f'"max_frames" must be >= 2: {max_frames}'
            raise ValueError(msg)
        self.show_locals = show_locals
        self.locals_max_length = locals_max_length
        self.locals_max_string = locals_max_string
        self.locals_hide_dunder = locals_hide_dunder
        self.locals_hide_sunder = locals_hide_sunder
        self.suppress: Sequence[str] = []
        for suppress_entity in suppress:
            if not isinstance(suppress_entity, str):
                if suppress_entity.__file__ is None:
                    msg = (
                        f'"suppress" item {suppress_entity!r} must be a '
                        f"module with '__file__' attribute"
                    )
                    raise ValueError(msg)
                path = os.path.dirname(suppress_entity.__file__)
            else:
                path = suppress_entity
            path = os.path.normpath(os.path.abspath(path))
            self.suppress.append(path)
        self.max_frames = max_frames
        self.use_rich = use_rich
```

--------------------------------

### ConsoleRenderer.columns

Source: https://www.structlog.org/en/stable/api.html

Property to get or set the columns configuration for the console renderer.

```APIDOC
## [PROPERTY] ConsoleRenderer.columns

### Description
The columns configuration for this console renderer. Setting this will update the renderer's styles immediately and reset level styles to the defaults according to the new color setting.

### Property
`columns`

### Type
list[Column]

### Parameters
- **value** (list[Column]) - Required - A list of Column objects defining both the order and format of the key-value pairs in the output. Must contain a column with key='' that defines the default formatter.

### Raises
- **ValueError** - If there's not exactly one default column formatter.

### Notes
Added in version 25.5.0.
```

--------------------------------

### ConsoleRenderer.__init__

Source: https://www.structlog.org/en/stable/_modules/structlog/dev.html

Initializes a ConsoleRenderer instance with configurable options for padding, colors, exception formatting, sorting, and column selection.

```APIDOC
## ConsoleRenderer.__init__

### Description
Initializes a ConsoleRenderer instance with configurable options for padding, colors, exception formatting, sorting, and column selection.

### Method
Constructor

### Parameters
#### Constructor Parameters
- **pad_event_to** (int) - Optional - The width to pad the event field to. Defaults to `_EVENT_WIDTH`.
- **colors** (bool) - Optional - Whether to use colors. Defaults to `_has_colors`.
- **force_colors** (bool) - Optional - Force color output even if not supported. Defaults to `False`.
- **repr_native_str** (bool) - Optional - Whether to use `repr` for native strings. Defaults to `False`.
- **level_styles** (dict[str, str] | None) - Optional - Custom styles for log levels. Defaults to `None`.
- **exception_formatter** (ExceptionRenderer) - Optional - Custom exception formatter. Defaults to `default_exception_formatter`.
- **sort_keys** (bool) - Optional - Whether to sort keys in output. Defaults to `True`.
- **event_key** (str) - Optional - The key for the event field. Defaults to `"event"`.
- **timestamp_key** (str) - Optional - The key for the timestamp field. Defaults to `"timestamp"`.
- **columns** (list[Column] | None) - Optional - Custom columns for output. Defaults to `None`.
- **pad_level** (bool) - Optional - Whether to pad the level field. Defaults to `True`.
- **pad_event** (int | None) - Optional - Deprecated, use `pad_event_to` instead. Defaults to `None`.

### Notes
- If `pad_event` is provided, it overrides `pad_event_to` and raises a `DeprecationWarning`.
- If `columns` is provided, many other arguments are ignored and warnings are issued.
- If `exception_formatter` is the default and colors are disabled, a monochrome formatter is used.

### Example
```python
renderer = ConsoleRenderer(
    pad_event_to=40,
    colors=True,
    sort_keys=False,
    event_key="message",
    timestamp_key="time",
)
```
```

--------------------------------

### structlog.dev.ConsoleRenderer.get_default_level_styles()

Source: https://www.structlog.org/en/stable/genindex.html

Static method to get the default level styles for the ConsoleRenderer.

```APIDOC
## get_default_level_styles()

### Description
Static method to get the default level styles for the ConsoleRenderer.

### Method
get_default_level_styles

### Parameters
None

### Response
Returns a dictionary of level styles.
```

--------------------------------

### ProcessorFormatter.__init__

Source: https://www.structlog.org/en/stable/_modules/structlog/stdlib.html

Initializes a ProcessorFormatter instance with configurable processors, foreign pre-chain, and options for handling exc_info, stack_info, and foreign log record arguments.

```APIDOC
## ProcessorFormatter.__init__

### Description
Initializes a ProcessorFormatter instance with configurable processors, foreign pre-chain, and options for handling exc_info, stack_info, and foreign log record arguments.

### Method
Constructor

### Parameters
#### Parameters
- **processor** (Processor | None) - Optional - A single structlog processor used for rendering the event dictionary before passing it off to logging. Must return a str. Deprecated in favor of processors.
- **processors** (Sequence[Processor] | None) - Optional - A sequence of structlog processors used for rendering the event dictionary. Default is ().
- **foreign_pre_chain** (Sequence[Processor] | None) - Optional - A sequence of processors applied to foreign log records before the main processor chain.
- **keep_exc_info** (bool) - Optional - If True, keep exc_info on the LogRecord. Default is False.
- **keep_stack_info** (bool) - Optional - If True, keep stack_info on the LogRecord. Default is False.
- **logger** (logging.Logger | None) - Optional - Logger to push through the structlog processor chain. Default is None.
- **pass_foreign_args** (bool) - Optional - If True, pass a foreign log record's args attribute to the event_dict under positional_args key. Default is False.
- **use_get_message** (bool) - Optional - If True, use record.getMessage to get a fully rendered log message, otherwise use str(record.msg). Default is True.
- **args** (Any) - Optional - Additional positional arguments passed to the parent class.
- **kwargs** (Any) - Optional - Additional keyword arguments. The 'fmt' keyword is popped and used as the format string.

### Raises
- **TypeError** - If both or neither processor and processors are passed.

### Example
```python
formatter = ProcessorFormatter(
    processors=[structlog.stdlib.ProcessorFormatter.wrap_for_formatter],
    foreign_pre_chain=[structlog.processors.format_exc_info],
    keep_exc_info=False,
    keep_stack_info=False,
    logger=None,
    pass_foreign_args=False,
    use_get_message=True,
)
```
```

--------------------------------

### structlog.dev.ConsoleRenderer.get_default_column_styles()

Source: https://www.structlog.org/en/stable/genindex.html

Class method to get the default column styles for the ConsoleRenderer.

```APIDOC
## get_default_column_styles()

### Description
Class method to get the default column styles for the ConsoleRenderer.

### Method
get_default_column_styles

### Parameters
None

### Response
Returns a dictionary of column styles.
```

--------------------------------

### ConsoleRenderer.__init__

Source: https://www.structlog.org/en/stable/_modules/structlog/dev.html

Initializes a ConsoleRenderer instance with configurable options for column layout, padding, colors, exception formatting, and key names.

```APIDOC
## ConsoleRenderer.__init__

### Description
Initializes a ConsoleRenderer instance with configurable options for column layout, padding, colors, exception formatting, and key names.

### Method
Constructor

### Parameters
#### Constructor Parameters
- **columns** (list of Column) - Optional - A list of Column objects defining the order and format of key-value pairs. Must contain a column with key='' for the default formatter.
- **pad_event_to** (int) - Optional - Pad the event to this many characters. Ignored if columns are passed.
- **colors** (bool) - Optional - Use colors for nicer output. True by default. On Windows only if Colorama is installed. Ignored if columns are passed.
- **force_colors** (bool) - Optional - Force colors even for non-tty destinations. Only meaningful on Windows. Ignored if columns are passed.
- **repr_native_str** (bool) - Optional - When True, repr is also applied to str values. The event key is never repr-ed. Ignored if columns are passed.
- **level_styles** (dict) - Optional - A dict from level names to terminal sequence styles. Default can be obtained via get_default_level_styles. Ignored if columns are passed.
- **exception_formatter** (callable) - Optional - A callable to render exc_infos. Defaults to Rich traceback if Rich is installed, otherwise plain_traceback.
- **sort_keys** (bool) - Optional - Whether to sort keys when formatting. True by default. Ignored if columns are passed.
- **event_key** (str) - Optional - The key to look for the main log message. Needed when renamed. Ignored if columns are passed.
- **timestamp_key** (str) - Optional - The key to look for timestamp. Needed when renamed. Ignored if columns are passed.
- **pad_level** (bool) - Optional - Whether to pad log level with blanks to the longest amongst all level labels.

### Raises
- **ValueError** - If there's not exactly one default column formatter.

### Notes
Requires Colorama if colors is True on Windows.
```

--------------------------------

### ConsoleRenderer.exception_formatter

Source: https://www.structlog.org/en/stable/api.html

Property to get or set the exception formatter used by the console renderer.

```APIDOC
## [PROPERTY] ConsoleRenderer.exception_formatter

### Description
The exception formatter used by this console renderer.

### Property
`exception_formatter`

### Type
Callable[[TextIO, tuple[type[BaseException], BaseException, TracebackType | None]], None]

### Notes
Added in version 25.5.0.
```

--------------------------------

### ConsoleRenderer.event_key

Source: https://www.structlog.org/en/stable/api.html

Property to get or set the key used for the main log message.

```APIDOC
## [PROPERTY] ConsoleRenderer.event_key

### Description
The key to look for the main log message. Setting this will rebuild columns to reflect the change.

### Property
`event_key`

### Type
str

### Notes
Added in version 25.5.0.
```

--------------------------------

### Basic key-value logging with structlog

Source: https://www.structlog.org/en/stable/_sources/why.md

Shows the simplest way to log an event with key-value pairs using structlog's get_logger(). The output is a formatted log entry with the event name and key-value pairs.

```pycon
>>> from structlog import get_logger
>>> log = get_logger()
>>> log.info("key_value_logging", out_of_the_box=True, effort=0)
2020-11-18 09:17:09 [info     ] key_value_logging    effort=0 out_of_the_box=True
```

--------------------------------

### structlog.dev.plain_traceback

Source: https://www.structlog.org/en/stable/_sources/exceptions.md

Renders a plain traceback, used as the default exception formatter when Rich is not installed.

```APIDOC
## structlog.dev.plain_traceback

### Description
Renders a plain traceback. It is the default exception formatter for ConsoleRenderer when Rich is not installed.

### Method
N/A (function)

### Endpoint
N/A

### Parameters
- **exc_info** (tuple) - Required - The exception info tuple as returned by `sys.exc_info()`.

### Request Example
N/A

### Response
#### Success Response
- **string** (str) - The formatted plain traceback string.

#### Response Example
N/A
```

--------------------------------

### Example JSON output from structlog and logging

Source: https://www.structlog.org/en/stable/standard-library.html

Shows the JSON output produced by the previous configuration for both structlog and logging log entries. The structlog entry includes logger and level fields, while the logging entry only includes the message.

```python
>>> structlog.get_logger("test").warning("hello")
{"message": "hello", "logger": "test", "level": "warning"}

>>> logging.getLogger("test").warning("hello")
{"message": "hello"}

```

--------------------------------

### Wrap a custom logger with structlog.wrap_logger

Source: https://www.structlog.org/en/stable/_sources/bound-loggers.md

Shows how to wrap a custom logger with structlog.wrap_logger without global configuration. The example defines a CustomPrintLogger and a processor, then demonstrates binding, unbinding, and equality checks on the resulting bound loggers.

```python
>>> import structlog
>>> class CustomPrintLogger:
...     def msg(self, message):
...         print(message)
>>> def proc(logger, method_name, event_dict):
...     print("I got called with", event_dict)
...     return repr(event_dict)
>>> log = structlog.wrap_logger(
...     CustomPrintLogger(),
...     wrapper_class=structlog.BoundLogger,
...     processors=[proc],
... )
>>> log2 = log.bind(x=42)
>>> log == log2
False
>>> log.msg("hello world")
I got called with {'event': 'hello world'}
{'event': 'hello world'}
>>> log2.msg("hello world")
I got called with {'x': 42, 'event': 'hello world'}
{'x': 42, 'event': 'hello world'}
>>> log3 = log2.unbind("x")
>>> log == log3
True
>>> log3.msg("nothing bound anymore", foo="but you can structure the event too")
I got called with {'foo': 'but you can structure the event too', 'event': 'nothing bound anymore'}
{'foo': 'but you can structure the event too', 'event': 'nothing bound anymore'}

```

--------------------------------

### repr_native_str property

Source: https://www.structlog.org/en/stable/_modules/structlog/dev.html

Gets or sets whether native strings are passed through repr() in non-event values.

```APIDOC
## repr_native_str property

### Description
Gets or sets whether native strings are passed through repr() in non-event values.

### Property
`repr_native_str` (bool)

### Getter
Returns the current repr_native_str setting.

### Setter
Sets the repr_native_str setting.

### Parameters
- **value** (bool) - Required - The new repr_native_str setting.

### Version History
- Added in version 25.5.0.
```

--------------------------------

### rich_monochrome_traceback

Source: https://www.structlog.org/en/stable/_modules/structlog/dev.html

A pre-configured RichTracebackFormatter instance with color_system=None to disable colors. Used by default if Rich is installed and colors are disabled.

```APIDOC
## rich_monochrome_traceback

### Description
Pretty-print *exc_info* to *sio* using the Rich package w/o colors. To be passed into `ConsoleRenderer`'s `exception_formatter` argument. This is a `RichTracebackFormatter` with default arguments except for `color_system=None`, and used by default if Rich is installed and colors are disabled.

### Type
RichTracebackFormatter instance

### Usage
Pass this object as the `exception_formatter` argument to `ConsoleRenderer`.

### Notes
- Version added: 26.1.0
```

--------------------------------

### Naive logging with repeated context

Source: https://www.structlog.org/en/stable/getting-started.html

Shows a view function that logs events with repeated user_agent and peer_ip key-value pairs. This approach is repetitive and error-prone.

```python
def view(request):
    user_agent = request.get("HTTP_USER_AGENT", "UNKNOWN")
    peer_ip = request.client_addr
    if something:
        log.info("something", user_agent=user_agent, peer_ip=peer_ip)
        return "something"
    elif something_else:
        log.info("something_else", user_agent=user_agent, peer_ip=peer_ip)
        return "something_else"
    else:
        log.info("else", user_agent=user_agent, peer_ip=peer_ip)
        return "else"

```

--------------------------------

### pad_event_to property

Source: https://www.structlog.org/en/stable/_modules/structlog/dev.html

Gets or sets the number of characters to pad the event to. Setting this rebuilds columns to reflect the change.

```APIDOC
## pad_event_to property

### Description
Gets or sets the number of characters to pad the event to. Setting this rebuilds columns to reflect the change.

### Property
`pad_event_to` (int)

### Getter
Returns the current pad_event_to value.

### Setter
Sets the pad_event_to value and rebuilds columns.

### Parameters
- **value** (int) - Required - The new pad_event_to value.

### Behavior
- Rebuilds columns to reflect the change.

### Version History
- Added in version 25.5.0.
```

--------------------------------

### TimeStamper.__init__

Source: https://www.structlog.org/en/stable/_modules/structlog/processors.html

Initializes a TimeStamper with format, UTC flag, and target key.

```APIDOC
## TimeStamper.__init__

### Description
Initializes a TimeStamper instance. The fmt parameter can be a strftime format string, 'iso' for ISO 8601, or None for a UNIX timestamp.

### Method
Constructor

### Parameters
- **fmt** (str | None) - Optional - The timestamp format. Defaults to None (UNIX timestamp).
- **utc** (bool) - Optional - Whether to use UTC time. Defaults to True.
- **key** (str) - Optional - The key in event_dict to store the timestamp. Defaults to 'timestamp'.

### Request Example
```python
stamper = TimeStamper(fmt="iso", utc=True, key="time")
```
```
Tokens:
Raw