# benfred/py-spy architecture

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

- Interactive diagram: https://gitdiagram.com/benfred/py-spy
- Repository: https://github.com/benfred/py-spy

## Overview

##### Main Components

a) Core Components:
- Sampler Engine (src/sampler.rs)
- Python Process Interface (src/python_process_info.rs)
- Memory Reading Layer
- Python Interpreter State Handler (src/python_interpreters.rs)
- Output Formatters (flamegraph.rs, speedscope.rs, console_viewer.rs)

b) Supporting Components:
- Python Version Bindings (src/python_bindings/*)
- Configuration Handler (src/config.rs)
- Platform-specific Memory Access Implementations

**┌─────────────────────────────────────────┐**
- Command Interface            │
- (record, top, dump commands)        │
- ┤
- Sampling Engine              │
- (sampling coordination, timing)     │
- ┤
- Memory Access Layer            │
- (process_vm_readv, vm_read, etc.)     │
- ┤
- Python Interface Layer            │
- (interpreter state, thread tracking)   │
- ┤
- Output Formatters              │
- (flamegraph, speedscope, console)     │
- ┘

##### Key Relationships

- How the Python Interface Layer interacts with different Python version bindings
- Data flow from sampling to output generation
- External system interactions (OS-specific memory reading calls)

##### Implementation Details to Highlight

- Non-blocking sampling capability
- GIL state detection
- Native extension profiling support
- Subprocess monitoring
- Thread state tracking

##### Notes

- Clear separation between the profiler and target Python process
- Where system calls and memory access occur
- Non-intrusive nature of the profiling mechanism

- Zero overhead sampling
- Process separation
- Cross-platform support
- Multiple Python version compatibility
- Various output format support

## Diagram (Mermaid)

```mermaid
graph TB
    %% Main Layers
    subgraph CLI["Command Interface Layer"]
        CMD["Command Handler"]
        CFG["Configuration"]
        click CFG "https://github.com/benfred/py-spy/blob/master/src/config.rs"
    end

    subgraph Core["Core Profiling Layer"]
        Sampler["Sampling Engine"]
        ProcInfo["Process Info Handler"]
        Timer["Timer Service"]
        PythonSpy["Core Profiler"]
        
        click Sampler "https://github.com/benfred/py-spy/blob/master/src/sampler.rs"
        click ProcInfo "https://github.com/benfred/py-spy/blob/master/src/python_process_info.rs"
        click Timer "https://github.com/benfred/py-spy/blob/master/src/timer.rs"
        click PythonSpy "https://github.com/benfred/py-spy/blob/master/src/python_spy.rs"
    end

    subgraph Memory["Memory Access Layer"]
        MemAccess["Memory Reader"]
        CoreDump["Core Dump Handler"]
        NativeStack["Native Stack Tracer"]
        
        click CoreDump "https://github.com/benfred/py-spy/blob/master/src/coredump.rs"
        click NativeStack "https://github.com/benfred/py-spy/blob/master/src/native_stack_trace.rs"
    end

    subgraph Python["Python Interface Layer"]
        InterpState["Interpreter State"]
        ThreadHandler["Thread Handler"]
        StackTrace["Stack Tracer"]
        DataAccess["Data Access"]
        CythonSupport["Cython Support"]
        
        click InterpState "https://github.com/benfred/py-spy/blob/master/src/python_interpreters.rs"
        click ThreadHandler "https://github.com/benfred/py-spy/blob/master/src/python_threading.rs"
        click StackTrace "https://github.com/benfred/py-spy/blob/master/src/stack_trace.rs"
        click DataAccess "https://github.com/benfred/py-spy/blob/master/src/python_data_access.rs"
        click CythonSupport "https://github.com/benfred/py-spy/blob/master/src/cython.rs"
    end

    subgraph Bindings["Python Version Bindings"]
        VersionDetect["Version Detection"]
        PythonBindings["Version-Specific Bindings"]
        
        click PythonBindings "https://github.com/benfred/py-spy/tree/master/src/python_bindings/"
    end

    subgraph Output["Output Formatters"]
        Flamegraph["Flamegraph"]
        Speedscope["Speedscope"]
        Console["Console Viewer"]
        ChromeTrace["Chrome Trace"]
        
        click Flamegraph "https://github.com/benfred/py-spy/blob/master/src/flamegraph.rs"
        click Speedscope "https://github.com/benfred/py-spy/blob/master/src/speedscope.rs"
        click Console "https://github.com/benfred/py-spy/blob/master/src/console_viewer.rs"
        click ChromeTrace "https://github.com/benfred/py-spy/blob/master/src/chrometrace.rs"
    end

    %% Relationships
    CMD --> CFG
    CFG --> PythonSpy
    
    PythonSpy --> Sampler
    Sampler --> Timer
    Sampler --> ProcInfo
    
    ProcInfo --> MemAccess
    MemAccess --> CoreDump
    MemAccess --> NativeStack
    
    Sampler --> InterpState
    InterpState --> ThreadHandler
    ThreadHandler --> StackTrace
    StackTrace --> DataAccess
    DataAccess --> CythonSupport
    
    InterpState --> VersionDetect
    VersionDetect --> PythonBindings
    
    PythonSpy --> Output
    Output --> Flamegraph
    Output --> Speedscope
    Output --> Console
    Output --> ChromeTrace

    %% Styling
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:1px
    classDef core fill:#dae8fc,stroke:#6c8ebf
    classDef memory fill:#d5e8d4,stroke:#82b366
    classDef python fill:#ffe6cc,stroke:#d79b00
    classDef output fill:#fff2cc,stroke:#d6b656
    classDef bindings fill:#e1d5e7,stroke:#9673a6
    
    class Sampler,ProcInfo,Timer,PythonSpy core
    class MemAccess,CoreDump,NativeStack memory
    class InterpState,ThreadHandler,StackTrace,DataAccess,CythonSupport python
    class Flamegraph,Speedscope,Console,ChromeTrace output
    class VersionDetect,PythonBindings bindings
```
