# amin511/joule-profiler architecture

> Architecture diagram of the GitHub repository amin511/joule-profiler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amin511/joule-profiler
- Repository: https://github.com/amin511/joule-profiler

## Overview

Joule Profiler is a Linux energy and performance profiler. A user invokes the CLI to run a command; the profiler detects phase tokens in its output while the source orchestrator coordinates metric collection, then results are aggregated and rendered as terminal, JSON, or CSV. Metric-source implementations cover CPU, process/system, and GPU measurements. The README documents these capabilities; relationships among some source adapters and the core are not explicit in the sampled excerpts, so those links are shown as unverified where useful.

Main entry points: [`core/src/profiler/mod.rs`](https://github.com/amin511/joule-profiler/blob/main/core/src/profiler/mod.rs) (Command profiler), [`cli/src/output/displayer/mod.rs`](https://github.com/amin511/joule-profiler/blob/main/cli/src/output/displayer/mod.rs) (Output selection), [`cli/src/commands/profile.rs`](https://github.com/amin511/joule-profiler/blob/main/cli/src/commands/profile.rs) (Profile command), [`cli/src/config/mod.rs`](https://github.com/amin511/joule-profiler/blob/main/cli/src/config/mod.rs) (Config loading)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and configuration"]
  node_profile_command["Profile command<br/>[profile.rs]"]
  node_config["Config loading<br/>[mod.rs]"]
  node_config_overrides["CLI overrides<br/>[overrides.rs]"]
  node_config_table["Source config table<br/>[table.rs]"]
end

subgraph group_profiling["Profiling core"]
  node_profiler["Command profiler<br/>[mod.rs]"]
  node_phase["Phase detection<br/>[phase.rs]"]
  node_orchestrator["Source orchestrator<br/>[mod.rs]"]
  node_source_runtime["Source runtime<br/>[runtime.rs]"]
  node_sensor_model["Sensor model<br/>[sensor.rs]"]
  node_metric_units["Metric units<br/>[unit.rs]"]
end

subgraph group_sources["Metric sources"]
  node_rapl_powercap["RAPL powercap<br/>[mod.rs]"]
  node_rapl_perf["RAPL perf<br/>[mod.rs]"]
  node_perf_event["Perf counters<br/>[event.rs]"]
  node_nvml["NVIDIA GPU<br/>[counters.rs]"]
  node_amdsmi["AMD GPU<br/>[counters.rs]"]
  node_cgroup["Cgroup metrics<br/>[cgroup.rs]"]
  node_procfs["Procfs metrics<br/>[snapshot.rs]"]
end

subgraph group_results["Results and output"]
  node_aggregation["Phase aggregation<br/>[phase.rs]"]
  node_sensor_results["Sensor results<br/>[sensor_result.rs]"]
  node_output_dispatch["Output selection<br/>[mod.rs]"]
  node_csv_output["CSV output<br/>[csv.rs]"]
  node_json_output["JSON output<br/>[json.rs]"]
  node_terminal_output["Terminal output<br/>[terminal.rs]"]
end

node_user(("User"))

node_user -->|"runs profile"| node_profile_command
node_profile_command -.->|"loads settings"| node_config
node_config -->|"applies overrides"| node_config_overrides
node_config -.->|"builds source table"| node_config_table
node_profile_command -.->|"profiles command"| node_profiler
node_profiler -->|"detects tokens"| node_phase
node_profiler -->|"coordinates sources"| node_orchestrator
node_orchestrator -.->|"runs sources"| node_source_runtime
node_source_runtime -->|"aggregates metrics"| node_aggregation
node_aggregation -->|"builds results"| node_sensor_results
node_profiler -.->|"collects energy"| node_rapl_powercap
node_profiler -.->|"collects energy"| node_rapl_perf
node_profiler -.->|"collects counters"| node_perf_event
node_profiler -.->|"collects GPU metrics"| node_nvml
node_profiler -.->|"collects GPU metrics"| node_amdsmi
node_profiler -.->|"collects usage"| node_cgroup
node_profiler -.->|"collects usage"| node_procfs
node_profiler -->|"selects format"| node_output_dispatch
node_output_dispatch -->|"renders CSV"| node_csv_output
node_output_dispatch -->|"renders JSON"| node_json_output
node_output_dispatch -->|"renders terminal"| node_terminal_output

click node_profile_command "https://github.com/amin511/joule-profiler/blob/main/cli/src/commands/profile.rs"
click node_config "https://github.com/amin511/joule-profiler/blob/main/cli/src/config/mod.rs"
click node_config_overrides "https://github.com/amin511/joule-profiler/blob/main/cli/src/config/overrides.rs"
click node_config_table "https://github.com/amin511/joule-profiler/blob/main/cli/src/config/table.rs"
click node_profiler "https://github.com/amin511/joule-profiler/blob/main/core/src/profiler/mod.rs"
click node_phase "https://github.com/amin511/joule-profiler/blob/main/core/src/phase.rs"
click node_orchestrator "https://github.com/amin511/joule-profiler/blob/main/core/src/orchestrator/mod.rs"
click node_source_runtime "https://github.com/amin511/joule-profiler/blob/main/core/src/source/runtime.rs"
click node_sensor_model "https://github.com/amin511/joule-profiler/blob/main/core/src/sensor.rs"
click node_metric_units "https://github.com/amin511/joule-profiler/blob/main/core/src/unit.rs"
click node_aggregation "https://github.com/amin511/joule-profiler/blob/main/core/src/aggregate/phase.rs"
click node_sensor_results "https://github.com/amin511/joule-profiler/blob/main/core/src/aggregate/sensor_result.rs"
click node_rapl_powercap "https://github.com/amin511/joule-profiler/blob/main/sources/rapl/src/powercap/mod.rs"
click node_rapl_perf "https://github.com/amin511/joule-profiler/blob/main/sources/rapl/src/perf/mod.rs"
click node_perf_event "https://github.com/amin511/joule-profiler/blob/main/sources/perf_event/src/event.rs"
click node_nvml "https://github.com/amin511/joule-profiler/blob/main/sources/nvml/src/counters.rs"
click node_amdsmi "https://github.com/amin511/joule-profiler/blob/main/sources/amdsmi/src/counters.rs"
click node_cgroup "https://github.com/amin511/joule-profiler/blob/main/sources/cgroup/src/cgroup.rs"
click node_procfs "https://github.com/amin511/joule-profiler/blob/main/sources/procfs/src/snapshot.rs"
click node_output_dispatch "https://github.com/amin511/joule-profiler/blob/main/cli/src/output/displayer/mod.rs"
click node_csv_output "https://github.com/amin511/joule-profiler/blob/main/cli/src/output/formats/csv.rs"
click node_json_output "https://github.com/amin511/joule-profiler/blob/main/cli/src/output/formats/json.rs"
click node_terminal_output "https://github.com/amin511/joule-profiler/blob/main/cli/src/output/formats/terminal.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_profile_command,node_config,node_config_overrides,node_config_table,node_user toneBlue
class node_profiler,node_phase,node_orchestrator,node_source_runtime,node_sensor_model,node_metric_units toneAmber
class node_rapl_powercap,node_rapl_perf,node_perf_event,node_nvml,node_amdsmi,node_cgroup,node_procfs toneMint
class node_aggregation,node_sensor_results,node_output_dispatch,node_csv_output,node_json_output,node_terminal_output toneRose
```

## Components

### CLI and configuration

- [Profile command](https://github.com/amin511/joule-profiler/blob/main/cli/src/commands/profile.rs): `cli/src/commands/profile.rs`
- [Config loading](https://github.com/amin511/joule-profiler/blob/main/cli/src/config/mod.rs): `cli/src/config/mod.rs`
- [CLI overrides](https://github.com/amin511/joule-profiler/blob/main/cli/src/config/overrides.rs): `cli/src/config/overrides.rs`
- [Source config table](https://github.com/amin511/joule-profiler/blob/main/cli/src/config/table.rs): `cli/src/config/table.rs`

### Profiling core

- [Command profiler](https://github.com/amin511/joule-profiler/blob/main/core/src/profiler/mod.rs): `core/src/profiler/mod.rs`
- [Phase detection](https://github.com/amin511/joule-profiler/blob/main/core/src/phase.rs): `core/src/phase.rs`
- [Source orchestrator](https://github.com/amin511/joule-profiler/blob/main/core/src/orchestrator/mod.rs): `core/src/orchestrator/mod.rs`
- [Source runtime](https://github.com/amin511/joule-profiler/blob/main/core/src/source/runtime.rs): `core/src/source/runtime.rs`
- [Sensor model](https://github.com/amin511/joule-profiler/blob/main/core/src/sensor.rs): `core/src/sensor.rs`
- [Metric units](https://github.com/amin511/joule-profiler/blob/main/core/src/unit.rs): `core/src/unit.rs`

### Metric sources

- [RAPL powercap](https://github.com/amin511/joule-profiler/blob/main/sources/rapl/src/powercap/mod.rs): `sources/rapl/src/powercap/mod.rs`
- [RAPL perf](https://github.com/amin511/joule-profiler/blob/main/sources/rapl/src/perf/mod.rs): `sources/rapl/src/perf/mod.rs`
- [Perf counters](https://github.com/amin511/joule-profiler/blob/main/sources/perf_event/src/event.rs): `sources/perf_event/src/event.rs`
- [NVIDIA GPU](https://github.com/amin511/joule-profiler/blob/main/sources/nvml/src/counters.rs): `sources/nvml/src/counters.rs`
- [AMD GPU](https://github.com/amin511/joule-profiler/blob/main/sources/amdsmi/src/counters.rs): `sources/amdsmi/src/counters.rs`
- [Cgroup metrics](https://github.com/amin511/joule-profiler/blob/main/sources/cgroup/src/cgroup.rs): `sources/cgroup/src/cgroup.rs`
- [Procfs metrics](https://github.com/amin511/joule-profiler/blob/main/sources/procfs/src/snapshot.rs): `sources/procfs/src/snapshot.rs`

### Results and output

- [Phase aggregation](https://github.com/amin511/joule-profiler/blob/main/core/src/aggregate/phase.rs): `core/src/aggregate/phase.rs`
- [Sensor results](https://github.com/amin511/joule-profiler/blob/main/core/src/aggregate/sensor_result.rs): `core/src/aggregate/sensor_result.rs`
- [Output selection](https://github.com/amin511/joule-profiler/blob/main/cli/src/output/displayer/mod.rs): `cli/src/output/displayer/mod.rs`
- [CSV output](https://github.com/amin511/joule-profiler/blob/main/cli/src/output/formats/csv.rs): `cli/src/output/formats/csv.rs`
- [JSON output](https://github.com/amin511/joule-profiler/blob/main/cli/src/output/formats/json.rs): `cli/src/output/formats/json.rs`
- [Terminal output](https://github.com/amin511/joule-profiler/blob/main/cli/src/output/formats/terminal.rs): `cli/src/output/formats/terminal.rs`

### Other components

- **User**

## Connections

- User → Profile command: runs profile (evidence: `README.md`)
- Profile command → Config loading: loads settings
- Config loading → CLI overrides: applies overrides (evidence: `cli/src/config/mod.rs`)
- Config loading → Source config table: builds source table (evidence: `cli/src/config/mod.rs`)
- Profile command → Command profiler: profiles command
- Command profiler → Phase detection: detects tokens (evidence: `core/src/profiler/mod.rs`)
- Command profiler → Source orchestrator: coordinates sources (evidence: `core/src/profiler/mod.rs`)
- Source orchestrator → Source runtime: runs sources
- Source runtime → Phase aggregation: aggregates metrics (evidence: `core/src/source/runtime.rs`)
- Phase aggregation → Sensor results: builds results (evidence: `core/src/aggregate/sensor_result.rs`)
- Command profiler → RAPL powercap: collects energy
- Command profiler → RAPL perf: collects energy
- Command profiler → Perf counters: collects counters
- Command profiler → NVIDIA GPU: collects GPU metrics
- Command profiler → AMD GPU: collects GPU metrics
- Command profiler → Cgroup metrics: collects usage
- Command profiler → Procfs metrics: collects usage
- Command profiler → Output selection: selects format
- Output selection → CSV output: renders CSV (evidence: `cli/src/output/displayer/mod.rs`)
- Output selection → JSON output: renders JSON (evidence: `cli/src/output/displayer/mod.rs`)
- Output selection → Terminal output: renders terminal (evidence: `cli/src/output/displayer/mod.rs`)