# facebookresearch/dcperf architecture

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

- Interactive diagram: https://gitdiagram.com/facebookresearch/dcperf
- Repository: https://github.com/facebookresearch/dcperf

## Overview

##### Project Type and Purpose
- DCPerf is a CLI-driven, plugin-based performance benchmark suite for datacenter workloads.
- It provides a “driver” (Benchpress) in Python to install, orchestrate, execute, monitor, parse, and report results of various real-world-style benchmarks (Mediawiki, FeedSim, TaoBench, etc.).

##### Main Architectural Components
A. CLI Layer
- Entry point: benchpress_cli.py
- Command definitions under benchpress/cli (commands: list, install, run, report, system_check, etc.)
- Uses Click for dispatching subcommands.
B. Core Framework
- benchpress/lib – implements core abstractions: Job, Factory, Hooks, Parsers, Reporter, Utilities
- benchpress/config – YAML job/benchmark definitions (benchmarks.yml, jobs.yml, toolchain.yml)
- benchpress/logging_config and benchpress/version
C. Plugin Subsystem
- Hooks (benchpress/plugins/hooks) – instrumentation and monitoring plugins (e.g., perf, cpu_limit, memstat)
- Parsers (benchpress/plugins/parsers) – parsers for raw benchmark output into structured metrics
- Each plugin is discovered and instantiated via HookFactory and ParserFactory
D. Benchmark Packages
- packages/… – per-benchmark install/build/run scripts and source (e.g., packages/feedsim, packages/django_workload, packages/tao_bench)
- Each contains shell scripts (install/run/cleanup), patches, templates, and third-party code
E. External Environment
- System shell, Python interpreter, OS packages (dnf/apt), compilers, third-party libraries (folly, FBThrift, Django, Cassandra, etc.)
- GitHub CI workflows and provisioning scripts under .github/

##### Relationships and Data Flow
- User invokes benchpress_cli.py → Click dispatches to Command class
- Command loads job definitions from benchpress/config/*.yml
- For install: calls the install script in packages/<job> via subprocess
- For run:
1) Command instantiates Job object (benchpress/lib/job.py)
2) Job object consults HookFactory to attach monitoring hooks
3) Job runs benchmark executables (from packages) under Hook wrappers
4) Raw stdout/log files are fed to ParserFactory
5) Parser produces structured JSON metrics
6) Reporter aggregates metrics, writes results to benchmark_metrics_<run_id>
- For report: Command invokes Reporter to compute per-benchmark and overall DCPerf scores
- system_check and health_check are special Jobs that collect system specs and micro-benchmarks via lib/sys_specs.py and health_check package

##### Architectural Patterns and Principles
- CLI Command Pattern (Click) for pluggable commands
- Plugin Architecture with Factory pattern: HookFactory, ParserFactory, ReporterFactory
- Separation of Concerns:
- CLI layer only parses args & dispatches
- Core library contains business logic
- Plugins encapsulate extensibility (monitoring, parsing)
- Packages isolate benchmark definitions and build scripts
- Config-driven: YAML files define what jobs exist and their roles

##### Technologies and Frameworks
- Python 3.x, Click, PyYAML, Pandas, Tabulate
- Bash shell scripts for environment setup & package installs
- C++ toolchains for FeedSim, TaoBench, VideoTranscodeBench
- Third-party libs: Folly, FBThrift, OpenSSL, Cassandra, Django, HHVM, Memcached, Spark, ffmpeg, etc.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLIEntry["benchpress_cli.py"]:::cli
        CLIMain["benchpress/cli/main.py"]:::cli
        CLICommands["benchpress/cli/commands/"]:::cli
    end

    %% Core Framework
    subgraph "Core Framework"
        direction TB
        LibCore["benchpress/lib/"]:::core
        Job["job.py"]:::core
        HookFactory["hook_factory.py"]:::core
        ParserFactory["parser_factory.py"]:::core
        ReporterFactory["reporter_factory.py"]:::core
        Utils["util.py\nsys_specs.py"]:::core
        Configs["benchmarks.yml\njobs.yml\ntoolchain.yml"]:::core
        Logging["logging_config.py"]:::core
        Version["version.py"]:::core
    end

    %% Plugin Subsystem
    subgraph "Plugin Subsystem"
        direction TB
        Hooks["benchpress/plugins/hooks/"]:::plugins
        Parsers["benchpress/plugins/parsers/"]:::plugins
    end

    %% Benchmark Packages
    subgraph "Benchmark Packages"
        direction TB
        Django["packages/django_workload/"]:::pkg
        FeedSim["packages/feedsim/"]:::pkg
        HealthCheckPkg["packages/health_check/"]:::pkg
        MediaWiki["packages/mediawiki/"]:::pkg
        Spark["packages/spark_standalone/"]:::pkg
        TaoBench["packages/tao_bench/"]:::pkg
        VideoTranscode["packages/video_transcode_bench/"]:::pkg
        WDL["packages/wdl_bench/"]:::pkg
    end

    %% External & CI
    subgraph "External Environment & CI"
        direction TB
        GitHubCI[".github/workflows/"]:::external
        Provision[".github/scripts/"]:::external
        Environment["OS, Shell, Python, DBs, Compilers"]:::external
    end

    %% Connections
    CLIEntry -->|"invokes"| CLIMain
    CLIMain -->|"loads commands"| CLICommands
    CLIMain -->|"dispatch"| Job
    CLIMain -->|"load config"| Configs
    Job -->|"instantiate"| HookFactory
    Job -->|"instantiate"| ParserFactory
    Job -->|"instantiate"| ReporterFactory
    Job -->|"use utils"| Utils
    HookFactory -->|"discovers"| Hooks
    ParserFactory -->|"discovers"| Parsers
    ReporterFactory -->|"aggregates"| ReporterFactory
    Job -->|"invoke install/run"| Django
    Job -->|"invoke install/run"| FeedSim
    Job -->|"invoke install/run"| HealthCheckPkg
    Job -->|"invoke install/run"| MediaWiki
    Job -->|"invoke install/run"| Spark
    Job -->|"invoke install/run"| TaoBench
    Job -->|"invoke install/run"| VideoTranscode
    Job -->|"invoke install/run"| WDL
    Job -->|"health_check via sys_specs"| HealthCheckPkg
    Parsers -->|"produce JSON"| ReporterFactory
    ReporterFactory -->|"write metrics"| Environment
    GitHubCI -->|"runs CLI commands"| CLIEntry
    Provision -->|"setup env"| Environment

    %% Click Events
    click CLIEntry "https://github.com/facebookresearch/dcperf/blob/main/benchpress_cli.py"
    click CLIMain "https://github.com/facebookresearch/dcperf/blob/main/benchpress/cli/main.py"
    click CLICommands "https://github.com/facebookresearch/dcperf/tree/main/benchpress/cli/commands/"
    click LibCore "https://github.com/facebookresearch/dcperf/tree/main/benchpress/lib/"
    click Job "https://github.com/facebookresearch/dcperf/blob/main/benchpress/lib/job.py"
    click HookFactory "https://github.com/facebookresearch/dcperf/blob/main/benchpress/lib/hook_factory.py"
    click ParserFactory "https://github.com/facebookresearch/dcperf/blob/main/benchpress/lib/parser_factory.py"
    click ReporterFactory "https://github.com/facebookresearch/dcperf/blob/main/benchpress/lib/reporter_factory.py"
    click Utils "https://github.com/facebookresearch/dcperf/blob/main/benchpress/lib/util.py"
    click Utils "https://github.com/facebookresearch/dcperf/blob/main/benchpress/lib/sys_specs.py"
    click Configs "https://github.com/facebookresearch/dcperf/blob/main/benchpress/config/benchmarks.yml"
    click Configs "https://github.com/facebookresearch/dcperf/blob/main/benchpress/config/jobs.yml"
    click Configs "https://github.com/facebookresearch/dcperf/blob/main/benchpress/config/toolchain.yml"
    click Logging "https://github.com/facebookresearch/dcperf/blob/main/benchpress/logging_config.py"
    click Version "https://github.com/facebookresearch/dcperf/blob/main/benchpress/version.py"
    click Hooks "https://github.com/facebookresearch/dcperf/tree/main/benchpress/plugins/hooks/"
    click Parsers "https://github.com/facebookresearch/dcperf/tree/main/benchpress/plugins/parsers/"
    click Django "https://github.com/facebookresearch/dcperf/tree/main/packages/django_workload/"
    click FeedSim "https://github.com/facebookresearch/dcperf/tree/main/packages/feedsim/"
    click HealthCheckPkg "https://github.com/facebookresearch/dcperf/tree/main/packages/health_check/"
    click MediaWiki "https://github.com/facebookresearch/dcperf/tree/main/packages/mediawiki/"
    click Spark "https://github.com/facebookresearch/dcperf/tree/main/packages/spark_standalone/"
    click TaoBench "https://github.com/facebookresearch/dcperf/tree/main/packages/tao_bench/"
    click VideoTranscode "https://github.com/facebookresearch/dcperf/tree/main/packages/video_transcode_bench/"
    click WDL "https://github.com/facebookresearch/dcperf/tree/main/packages/wdl_bench/"
    click GitHubCI "https://github.com/facebookresearch/dcperf/tree/main/.github/workflows/"
    click Provision "https://github.com/facebookresearch/dcperf/tree/main/.github/scripts/"

    %% Styles
    classDef cli fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef core fill:#ABEBC6,stroke:#196F3D,color:#1B2631;
    classDef plugins fill:#D2B4DE,stroke:#6C3483,color:#1B2631;
    classDef pkg fill:#E5E7E9,stroke:#566573,color:#1B2631;
    classDef external fill:#F9E79F,stroke:#B9770E,color:#1B2631
```
