# hynek/structlog architecture

> Architecture diagram of the GitHub repository hynek/structlog, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hynek/structlog
- Repository: https://github.com/hynek/structlog

## Overview

##### Main Components

a) Core Logger Components:
- Base Logger System (based on _base.py)
- Configuration System (_config.py)
- Type System (types.py, typing.py)

b) Integration Layers:
- Standard Library Integration (stdlib.py)
- Twisted Framework Integration (twisted.py)
- Context Variables Support (contextvars.py)
- Thread Local Storage (threadlocal.py)

c) Processing Pipeline:
- Processors Module (processors.py)
- Exception Handling (exceptions.py)
- Output Formatting (_output.py)

##### Architectural Flow

**[Application Code]**
- ↓
**[Logger Interface]**
- ↓
**[Bound Logger] → [Context Management]**
- ↓
**[Processor Pipeline]**
- ↓
**[Output Formatters] → [Various Outputs]**
- Console
- JSON
- logfmt
- Custom formats

##### Key Design Elements

a) Input Layer:
- How log entries start as simple dictionaries
- Binding points for contextual data

b) Processing Chain:
- Processor pipeline architecture
- How processors transform the log data
- Where custom processors can be inserted

c) Output Layer:
- Different output formatter options
- Integration points with other logging systems

##### Implementation Details to Highlight

- Chain-of-responsibility pattern in the processor pipeline
- Where type hints and validation occur
- Async-compatible components
- Performance-critical paths

##### Notes Section

Notes about:
- Performance considerations
- Thread safety mechanisms
- Integration capabilities
- Customization points

Remember to indicate that the system is designed to be both standalone and integrated with existing logging systems, as this is a key feature of structlog's flexibility.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Legend
        L1[Core Components]:::core
        L2[Integration Layer]:::integration
        L3[Processing Components]:::processing
        L4[Output Components]:::output
        L5[Context Management]:::context
    end

    subgraph "Application Layer"
        APP[Application Code]
    end

    subgraph "Core Logger Layer"
        BL["Base Logger System"]:::core
        CF["Configuration System"]:::core
        TS["Type System"]:::core
    end
    click BL "https://github.com/hynek/structlog/blob/main/src/structlog/_base.py"
    click CF "https://github.com/hynek/structlog/blob/main/src/structlog/_config.py"
    click TS "https://github.com/hynek/structlog/blob/main/src/structlog/types.py"

    subgraph "Context Management"
        CV["Context Variables"]:::context
        TL["Thread Local Storage"]:::context
        GC["Greenlet Context"]:::context
    end
    click CV "https://github.com/hynek/structlog/blob/main/src/structlog/contextvars.py"
    click TL "https://github.com/hynek/structlog/blob/main/src/structlog/threadlocal.py"
    click GC "https://github.com/hynek/structlog/blob/main/src/structlog/_greenlets.py"

    subgraph "Integration Layer"
        STD["Standard Library Integration"]:::integration
        TW["Twisted Framework"]:::integration
    end
    click STD "https://github.com/hynek/structlog/blob/main/src/structlog/stdlib.py"
    click TW "https://github.com/hynek/structlog/blob/main/src/structlog/twisted.py"

    subgraph "Processing Pipeline"
        PR["Processors"]:::processing
        EH["Exception Handler"]:::processing
        TB["Traceback Handler"]:::processing
        DT["Development Tools"]:::processing
        TS["Testing Support"]:::processing
    end
    click PR "https://github.com/hynek/structlog/blob/main/src/structlog/processors.py"
    click EH "https://github.com/hynek/structlog/blob/main/src/structlog/exceptions.py"
    click TB "https://github.com/hynek/structlog/blob/main/src/structlog/tracebacks.py"
    click DT "https://github.com/hynek/structlog/blob/main/src/structlog/dev.py"
    click TS "https://github.com/hynek/structlog/blob/main/src/structlog/testing.py"

    subgraph "Output Layer"
        OF["Output Formatter"]:::output
        Console["Console Output"]:::output
        JSON["JSON Format"]:::output
        LogFMT["LogFMT Format"]:::output
        Custom["Custom Formats"]:::output
    end
    click OF "https://github.com/hynek/structlog/blob/main/src/structlog/_output.py"

    %% Connections
    APP --> BL
    BL --> CF
    BL --> TS
    
    BL --> CV
    BL --> TL
    BL --> GC
    
    BL --> PR
    PR --> EH
    PR --> TB
    PR --> DT
    PR --> TS
    
    PR --> OF
    OF --> Console
    OF --> JSON
    OF --> LogFMT
    OF --> Custom
    
    BL --> STD
    BL --> TW

    %% Styles
    classDef core fill:#a8d1f0,stroke:#333,stroke-width:2px
    classDef integration fill:#90EE90,stroke:#333,stroke-width:2px
    classDef processing fill:#FFB347,stroke:#333,stroke-width:2px
    classDef output fill:#DDA0DD,stroke:#333,stroke-width:2px
    classDef context fill:#F0E68C,stroke:#333,stroke-width:2px
```
