# inspector-apm/inspector-laravel architecture

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

- Interactive diagram: https://gitdiagram.com/inspector-apm/inspector-laravel
- Repository: https://github.com/inspector-apm/inspector-laravel

## Overview

##### Project type and purpose
- This is a Laravel package (“inspector-laravel”) that instruments a Laravel or Lumen application for code‐execution monitoring (APM).
- It plugs into the host app via service providers, middleware, event listeners, and a CLI command to capture request traces, DB queries, job executions, exceptions, outgoing HTTP calls, email sends, Redis calls, etc., then ships that data to the external Inspector ingestion API.

##### File structure
- Top‐level:
- config/inspector.php – user config and ingestion key
- src/InspectorServiceProvider.php – registers all instrumentation providers
- src/Providers/* – each service provider hooks into one type of event (DB, jobs, exceptions, email, HTTP client, Redis, notifications, gates, stacktraces)
- src/Middleware/WebRequestMonitoring.php – wraps each HTTP request
- src/Commands/TestCommand.php – `php artisan inspector:test` CLI
- src/OutOfMemoryBootstrapper.php – listens early for memory limits
- src/Facades/Inspector.php – user‐friendly facade
- src/Filters.php – drop/allow rules
- Tests exercise configuration, middleware, providers, helpers.

##### Key insights from README
- Must register the service provider (Laravel auto or manual for Lumen).
- Must attach WebRequestMonitoring middleware to web and api groups.
- The CLI command verifies connectivity.
- All captured events are forwarded to Inspector’s cloud endpoints over HTTP.

##### Components
a. Main components
1. Host Laravel Application
2. Inspector Laravel Package
- Configuration Loader
- InspectorServiceProvider
- Instrumentation Providers
- Middleware
- Facade & Filters
- CLI Command
3. External Inspector Ingestion API (cloud)
4. Underlying Laravel subsystems: HTTP Kernel, Queue Worker, Event Dispatcher, DB, Mailer, HTTP Client, Redis, Notification, Gate, Exception Handler
b. Relationships & Data Flows
- On app bootstrap, InspectorServiceProvider registers instrumentation providers.
- HTTP Request → Kernel → WebRequestMonitoring middleware → start trace → passes through app → end trace → Inspector client dispatches telemetry.
- DB queries, Job starts/completes, exceptions, outgoing HTTP/email/Redis calls → listeners in respective Providers → send spans.
- CLI (`inspector:test`) uses Facade → dispatches a test event.
- All spans are batched or streamed to Inspector Ingestion API.
c. Architectural patterns
- Inversion of Control / Service Provider pattern for extension
- Middleware pipeline for request tracing
- Observer/Event listener pattern for capturing domain events
- Facade for a simple developer API
d. Key technologies
- PHP 7.2+, Laravel ≥5.5 or Lumen
- Composer for package management
- REST/HTTP client (Guzzle or built-in) for ingestion
- Laravel Service Container, Event Dispatcher, Middleware
- PHPUnit for tests

##### Detail
- That InspectorServiceProvider is the “entry point” registering all providers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Host Laravel App"
        Kernel["HTTP Kernel"]:::laravel
        Queue["Queue Worker"]:::laravel
        Dispatcher["Event Dispatcher"]:::laravel
        DB["Database"]:::laravel
        Mailer["Mailer"]:::laravel
        HTTPClient["HTTP Client"]:::laravel
        Redis["Redis"]:::laravel
        Notification["Notification"]:::laravel
        Gate["Gate"]:::laravel
        ExceptionHandler["Exception Handler"]:::laravel
        ViewEngine["View Engine"]:::laravel
    end

    subgraph "Inspector Package"
        Config["Configuration Loader"]:::inspector
        SP["InspectorServiceProvider"]:::inspector

        subgraph "Instrumentation Providers"
            CommandProv["CommandServiceProvider"]:::inspector
            DBProv["DatabaseQueryServiceProvider"]:::inspector
            JobProv["JobServiceProvider"]:::inspector
            ExProv["ExceptionsServiceProvider"]:::inspector
            EmailProv["EmailServiceProvider"]:::inspector
            HTTPProv["HttpClientServiceProvider"]:::inspector
            RedisProv["RedisServiceProvider"]:::inspector
            NotifProv["NotificationServiceProvider"]:::inspector
            GateProv["GateServiceProvider"]:::inspector
            StackProv["FetchesStackTrace"]:::inspector
        end

        subgraph "Middleware"
            WebMid["WebRequestMonitoring"]:::inspector
            OctaneMid["InspectorOctaneMiddleware"]:::inspector
        end

        Facade["Facade"]:::inspector
        Filters["Filters"]:::inspector
        CLI["Inspector CLI Command"]:::inspector
        OOM["OutOfMemoryBootstrapper"]:::inspector
        Client["Core Inspector Client"]:::inspector
        ViewDec["ViewEngineDecorator"]:::inspector
        Helpers["Global Helpers"]:::inspector
    end

    External["External Inspector Ingestion API"]:::external

    Config -.-> SP
    SP --> CommandProv
    SP --> DBProv
    SP --> JobProv
    SP --> ExProv
    SP --> EmailProv
    SP --> HTTPProv
    SP --> RedisProv
    SP --> NotifProv
    SP --> GateProv
    SP --> StackProv

    Kernel -->|"HTTP Request"| WebMid
    Kernel -->|"HTTP Request (Octane)"| OctaneMid
    WebMid -->|"Trace Data"| Client
    OctaneMid -->|"Trace Data"| Client

    DB -->|"DB Query"| DBProv -->|"DB Query Span"| Client
    Queue -->|"Job Event"| JobProv -->|"Job Span"| Client
    Dispatcher -->|"Exception Event"| ExProv -->|"Exception Span"| Client
    Mailer -->|"Email Send"| EmailProv -->|"Email Span"| Client
    HTTPClient -->|"HTTP Call"| HTTPProv -->|"HTTP Call Span"| Client
    Redis -->|"Redis Call"| RedisProv -->|"Redis Call Span"| Client
    Notification -->|"Notification Event"| NotifProv -->|"Notification Span"| Client
    Gate -->|"Authorization Check"| GateProv -->|"Gate Span"| Client
    Dispatcher -->|"Stacktrace Request"| StackProv -->|"Stacktrace"| Client
    ViewEngine -->|"Render View"| ViewDec -->|"View Render Span"| Client

    CLI -->|"Test Command"| Facade -->|"Test Span"| Client
    Filters -->|"Rule Check"| Client
    OOM -->|"OOM Event"| Client

    Client -->|"Telemetry Data"| External

    click Config "https://github.com/inspector-apm/inspector-laravel/blob/master/config/inspector.php"
    click SP "https://github.com/inspector-apm/inspector-laravel/blob/master/src/InspectorServiceProvider.php"
    click CommandProv "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Providers/CommandServiceProvider.php"
    click DBProv "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Providers/DatabaseQueryServiceProvider.php"
    click JobProv "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Providers/JobServiceProvider.php"
    click ExProv "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Providers/ExceptionsServiceProvider.php"
    click EmailProv "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Providers/EmailServiceProvider.php"
    click HTTPProv "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Providers/HttpClientServiceProvider.php"
    click RedisProv "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Providers/RedisServiceProvider.php"
    click NotifProv "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Providers/NotificationServiceProvider.php"
    click GateProv "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Providers/GateServiceProvider.php"
    click StackProv "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Providers/FetchesStackTrace.php"
    click WebMid "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Middleware/WebRequestMonitoring.php"
    click OctaneMid "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Middleware/InspectorOctaneMiddleware.php"
    click CLI "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Commands/TestCommand.php"
    click Facade "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Facades/Inspector.php"
    click Filters "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Filters.php"
    click OOM "https://github.com/inspector-apm/inspector-laravel/blob/master/src/OutOfMemoryBootstrapper.php"
    click Client "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Inspector.php"
    click ViewDec "https://github.com/inspector-apm/inspector-laravel/blob/master/src/Views/ViewEngineDecorator.php"
    click Helpers "https://github.com/inspector-apm/inspector-laravel/blob/master/src/helpers.php"

    classDef laravel fill:#D0E8FF,stroke:#008FCC,stroke-width:1px
    classDef inspector fill:#DFF5E1,stroke:#28A745,stroke-width:1px
    classDef external fill:#FFE8C5,stroke:#FF8C00,stroke-width:1px
```
