# google/orbit architecture

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

- Interactive diagram: https://gitdiagram.com/google/orbit
- Repository: https://github.com/google/orbit

## Overview

##### Main components
- Frontend (UI)
- OrbitQt: Qt-based windows, dialogs, user workflows (SessionSetup, Symbols tab, Capture tab, Source/Disassembly views)
- OrbitGl: OpenGL renderer for time graphs, tracks, call-trees
- Backend services (gRPC)
- OrbitService (OrbitGrpcServer + OrbitServiceImpl): central gRPC server exposing CaptureControl, ProcessService, TracepointService, CrashManager, etc.
- CaptureService: standalone process on Linux or Windows that receives instrumentation events, schedules, and forwards to client
- ProducerSideService: injected server into target process to collect instrumented function entry/exit events
- Pipeline
- ProducerSideChannel: IPC between injected instrumentation and CaptureService
- CaptureEventProducer: lock-free buffer producers inside target (API, Vulkan, ETW on Windows, perf_event on Linux)
- CaptureEventProcessor: on service side, process raw events (GPU, memory, thread scheduling, callstack samples)
- Post-processing: ClientData/DataManager, Mizar/MizarData for combining sampling vs instrumentation, building metrics
- Data storage & transport
- CaptureFile module: serializes/deserializes complete capture to `.orbit` files
- ClientModel: sampling data serialization for UI
- Symbol resolution & code view
- SymbolProvider(s): local ELF/DWARF/PDB parsing, remote Microsoft Symbol Server via HTTP (HttpDownloadManager)
- ClientSymbols: persistent cache manager (QSettings-based)
- CodeReport, CodeViewer, SyntaxHighlighter: generate and display annotated source and disassembly
- Deployment & remote profiling
- OrbitSsh & OrbitSshQt: SSH session management, file copy, remote command execution
- SessionSetup / ServiceDeployManager: start OrbitService and remote CaptureService on Linux target (via ssh or Docker)
- Utilities & third-party
- Abseil, gRPC, protobuf, Capstone, LZMA, LZ4, Catch2, GoogleTest, imgui, Vulkan headers, PresentMon

##### Relationships and data flows
1. UI ↔ OrbitService (gRPC calls over in-process or TCP)
2. OrbitService ↔ CaptureService (gRPC over local loopback or remote)
3. CaptureService ↔ ProducerSideService (IPC channel for event stream)
4. ProducerSideService → in-target instrumentation APIs (OrbitApi via APILoader, Vulkan layer, ETW/Krabs)
5. CaptureService → ClientData/DataManager → OrbitService → UI (event batch, metrics updates)
6. UI → HttpDownloadManager → Microsoft symbol server
7. UI → OrbitSshQt / OrbitSsh → remote target for deployment

##### Architectural patterns
- Microservices via gRPC: each service has its own process and clearly defined protobuf interfaces
- Plugin layers / dynamic instrumentation: APILoader + Vulkan layer intercept calls in-process
- Lock-free producers and modular event processors for high-throughput tracing
- MVC in UI: OrbitQt controllers invoke models (ClientModel, CaptureFileInfo, ClientData) and render via OrbitGl

##### Technologies
- gRPC / protobuf for inter-service RPC
- Qt for UI, OpenGL for rendering
- absl::flat_hash_map, concurrentqueue, outcome for low-level utilities
- JSON config for Vulkan layer, LZMA for compression
- CMake + Conan for builds, Docker / SSH for remote deployment

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        OrbitQt["OrbitQt UI"]:::ui
        OrbitGl["OrbitGl Renderer"]:::ui
    end

    %% Backend Services
    subgraph "Backend Services"
        direction TB
        OrbitService["OrbitService (gRPC server)"]:::service
        CaptureServiceLinux["Linux CaptureService"]:::service
        CaptureServiceWindows["Windows CaptureService"]:::service
        ProducerSideService["ProducerSideService"]:::instrument
    end

    %% Capture Pipeline
    subgraph "Capture Pipeline"
        direction TB
        ProducerSideChannel["ProducerSideChannel (IPC)"]:::instrument
        CaptureEventProducer["CaptureEventProducer"]:::instrument
        CaptureEventProcessor["CaptureEventProcessor"]:::service
    end

    %% Data Storage & Processing
    subgraph "Data Storage & Processing"
        direction TB
        CaptureFile["CaptureFile (.orbit)"]:::storage
        ClientModel["ClientModel"]:::storage
        ClientData["ClientData/DataManager"]:::storage
        MizarData["Mizar/MizarData"]:::storage
    end

    %% Symbols & Code View
    subgraph "Symbols & Code View"
        direction TB
        SymbolProvider["SymbolProvider (ELF/DWARF/PDB)"]:::storage
        RemoteSymbolProvider["RemoteSymbolProvider"]:::storage
        ClientSymbols["ClientSymbols Cache"]:::storage
        HttpDownloadManager["HttpDownloadManager"]:::storage
        CodeReport["CodeReport"]:::storage
        CodeViewer["CodeViewer"]:::storage
        SyntaxHighlighter["SyntaxHighlighter"]:::storage
    end

    %% Deployment
    subgraph "Deployment"
        direction TB
        OrbitSsh["OrbitSsh"]:::storage
        OrbitSshQt["OrbitSshQt"]:::storage
        SessionSetup["SessionSetup"]:::storage
        ServiceDeployManager["ServiceDeployManager"]:::storage
    end

    %% Additional Services
    subgraph "Additional Services"
        direction TB
        ProcessService["ProcessService"]:::service
        TracepointService["TracepointService"]:::service
        CrashManager["CrashManager"]:::service
        CaptureServiceBase["CaptureServiceBase"]:::service
    end

    %% External
    subgraph "External"
        direction TB
        MS_SymbolServer["Microsoft Symbol Server"]:::external
        TargetProcess["Target Process"]:::external
    end

    %% Relationships
    OrbitQt -->|"gRPC calls"| OrbitService
    OrbitService -->|"gRPC"| CaptureServiceLinux
    OrbitService -->|"gRPC"| CaptureServiceWindows
    CaptureServiceLinux ---|“IPC stream”| ProducerSideChannel
    CaptureServiceWindows ---|“IPC stream”| ProducerSideChannel
    ProducerSideService ---|“inject & IPC”| ProducerSideChannel
    TargetProcess -->|“instrumented API calls”| ProducerSideService
    ProducerSideService -->|“events”| CaptureEventProducer
    CaptureEventProducer ---|“lock-free buffer”| ProducerSideChannel
    ProducerSideChannel -->|“raw events”| CaptureEventProcessor
    CaptureEventProcessor -->|“processed events”| ClientData
    ClientData -->|“data batches”| OrbitService
    OrbitService -->|“updates”| OrbitQt
    OrbitQt -->|“serialize”| ClientModel
    CaptureServiceLinux -->|“save/load”| CaptureFile
    OrbitQt -->|“HTTP”| HttpDownloadManager
    HttpDownloadManager -->|“download PDBs”| MS_SymbolServer
    HttpDownloadManager -->|“fetch symbols”| RemoteSymbolProvider
    SymbolProvider -->|“local parse”| ClientSymbols
    OrbitQt -->|“view code”| CodeViewer
    CodeViewer -->|“report gen”| CodeReport
    CodeReport -->|“highlight”| SyntaxHighlighter
    OrbitQt -->|“SSH”| OrbitSshQt
    OrbitSshQt -->|“session mgmt”| OrbitSsh
    OrbitSsh -->|“deploy”| SessionSetup
    SessionSetup -->|“deploy”| ServiceDeployManager
    ServiceDeployManager -->|“start”| CaptureServiceLinux
    ProcessService -->|“enum/process”| OrbitService
    TracepointService -->|“tracepoint”| OrbitService
    CrashManager -->|“crash events”| OrbitService
    CaptureServiceBase -->|“common utils”| CaptureServiceLinux
    CaptureServiceBase -->|“common utils”| CaptureServiceWindows

    %% Click Events
    click OrbitQt "https://github.com/google/orbit/tree/main/src/OrbitQt/"
    click OrbitGl "https://github.com/google/orbit/tree/main/src/OrbitGl/"
    click OrbitService "https://github.com/google/orbit/blob/main/src/Service/OrbitGrpcServer.cpp"
    click OrbitService "https://github.com/google/orbit/blob/main/src/Service/OrbitService.cpp"
    click CaptureServiceLinux "https://github.com/google/orbit/tree/main/src/LinuxCaptureService/"
    click CaptureServiceWindows "https://github.com/google/orbit/tree/main/src/WindowsCaptureService/"
    click ProducerSideService "https://github.com/google/orbit/tree/main/src/ProducerSideService/"
    click ProducerSideChannel "https://github.com/google/orbit/tree/main/src/ProducerSideChannel/"
    click CaptureEventProducer "https://github.com/google/orbit/tree/main/src/CaptureEventProducer/"
    click CaptureEventProcessor "https://github.com/google/orbit/blob/main/src/CaptureClient/CaptureEventProcessor.cpp"
    click CaptureFile "https://github.com/google/orbit/tree/main/src/CaptureFile/"
    click ClientModel "https://github.com/google/orbit/tree/main/src/ClientModel/"
    click ClientData "https://github.com/google/orbit/tree/main/src/ClientData/"
    click MizarData "https://github.com/google/orbit/tree/main/src/Mizar/"
    click MizarData "https://github.com/google/orbit/tree/main/src/MizarData/"
    click SymbolProvider "https://github.com/google/orbit/tree/main/src/SymbolProvider/"
    click RemoteSymbolProvider "https://github.com/google/orbit/tree/main/src/RemoteSymbolProvider/"
    click ClientSymbols "https://github.com/google/orbit/tree/main/src/ClientSymbols/"
    click HttpDownloadManager "https://github.com/google/orbit/blob/main/src/Http/HttpDownloadManager.cpp"
    click CodeReport "https://github.com/google/orbit/tree/main/src/CodeReport/"
    click CodeViewer "https://github.com/google/orbit/tree/main/src/CodeViewer/"
    click SyntaxHighlighter "https://github.com/google/orbit/tree/main/src/SyntaxHighlighter/"
    click OrbitSsh "https://github.com/google/orbit/tree/main/src/OrbitSsh/"
    click OrbitSshQt "https://github.com/google/orbit/tree/main/src/OrbitSshQt/"
    click SessionSetup "https://github.com/google/orbit/blob/main/src/SessionSetup/SessionSetupDialog.cpp"
    click ServiceDeployManager "https://github.com/google/orbit/blob/main/src/SessionSetup/ServiceDeployManager.cpp"
    click ProcessService "https://github.com/google/orbit/blob/main/src/ProcessService/ProcessServiceImpl.cpp"
    click TracepointService "https://github.com/google/orbit/blob/main/src/TracepointService/TracepointServiceImpl.cpp"
    click CrashManager "https://github.com/google/orbit/blob/main/src/ClientServices/CrashManager.cpp"
    click CaptureServiceBase "https://github.com/google/orbit/tree/main/src/CaptureServiceBase/"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef service fill:#90EE90,stroke:#333,stroke-width:1px
    classDef instrument fill:#FFA500,stroke:#333,stroke-width:1px
    classDef storage fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
