# tarun-227/ebpf-stall-fingerprinting architecture

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

- Interactive diagram: https://gitdiagram.com/tarun-227/ebpf-stall-fingerprinting
- Repository: https://github.com/tarun-227/ebpf-stall-fingerprinting

## Overview

This repository is a Linux eBPF research tool for explaining application-operation stalls. Its main workflow runs marked workloads under the tracer, turns kernel events and per-operation ground truth into time breakdowns and features, then classifies operations as I/O-, scheduler-, CPU-dominated, or indeterminate. Separate analysis covers injected-delay fidelity and tracing overhead; processed results also feed report assets. The workflow and several connections are documented in the README; unsampled subsystems are included only where their purpose is documented, without asserting unverified call paths.

Main entry points: [`code/src/collector/stalltrace.c`](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/collector/stalltrace.c) (Stalltrace collector), [`supplementary/experimental_results`](https://github.com/tarun-227/ebpf-stall-fingerprinting/tree/main/supplementary/experimental_results) (Processed results), [`code/src/workloads/stallbench.c`](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/workloads/stallbench.c) (Stallbench workloads), [`code/src/ebpf/stalltrace.bpf.c`](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/ebpf/stalltrace.bpf.c) (Kernel probes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_instrumentation["Workload tracing"]
  node_stallbench["Stallbench workloads<br/>[stallbench.c]"]
  node_collector["Stalltrace collector<br/>[stalltrace.c]"]
  node_ebpf["Kernel probes<br/>[stalltrace.bpf.c]"]
  node_event_schema["Event schema<br/>[stalltrace.h]"]
  node_trace_output["Trace and run data<br/>[stalltrace.c]"]
end

subgraph group_analysis["Timeline analysis"]
  node_breakdown["Timeline breakdown<br/>[breakdown.py]"]
  node_features["Operation features<br/>[features.py]"]
end

subgraph group_classification["Classification"]
  node_label_trace["Live trace labeling<br/>[label_trace.py]"]
  node_models["Rules and trees<br/>[models.py]"]
end

subgraph group_evaluation["Evaluation outputs"]
  node_evaluate["Classifier evaluation<br/>[evaluate.py]"]
  node_delay["Delay analysis<br/>[delay_analysis.py]"]
  node_overhead["Overhead analysis<br/>[overhead.py]"]
  node_assets["Report assets<br/>[make_assets.py]"]
  node_results["Processed results"]
end

node_user(("Experimenter"))
node_target(("Traced target"))
node_kernel(("Linux kernel"))

node_user -->|"runs workload"| node_stallbench
node_user -->|"starts tracing"| node_collector
node_target -->|"runs under"| node_collector
node_stallbench -->|"marks operations"| node_collector
node_stallbench -->|"records ground truth"| node_trace_output
node_collector -->|"loads programs"| node_ebpf
node_ebpf -->|"hooks kernel events"| node_kernel
node_ebpf -->|"emits records"| node_event_schema
node_collector -->|"decodes records"| node_event_schema
node_collector -->|"writes events"| node_trace_output
node_trace_output -->|"provides trace and truth"| node_breakdown
node_breakdown -->|"provides breakdown rows"| node_features
node_features -->|"supplies feature table"| node_evaluate
node_evaluate -->|"builds classifiers"| node_models
node_trace_output -->|"provides trace"| node_label_trace
node_label_trace -->|"uses timelines"| node_breakdown
node_label_trace -->|"applies rules"| node_models
node_features -->|"supplies feature table"| node_delay
node_evaluate -.->|"produces metrics"| node_results
node_delay -.->|"reports delay fidelity"| node_results
node_overhead -.->|"reports tracing cost"| node_results
node_results -->|"feeds report assets"| node_assets

click node_stallbench "https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/workloads/stallbench.c"
click node_collector "https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/collector/stalltrace.c"
click node_ebpf "https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/ebpf/stalltrace.bpf.c"
click node_event_schema "https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/ebpf/stalltrace.h"
click node_trace_output "https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/collector/stalltrace.c"
click node_breakdown "https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/correlation/breakdown.py"
click node_features "https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/classifier/features.py"
click node_label_trace "https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/label_trace.py"
click node_models "https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/classifier/models.py"
click node_evaluate "https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/classifier/evaluate.py"
click node_delay "https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/classifier/delay_analysis.py"
click node_overhead "https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/classifier/overhead.py"
click node_assets "https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/report/make_assets.py"
click node_results "https://github.com/tarun-227/ebpf-stall-fingerprinting/tree/main/supplementary/experimental_results"

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_stallbench,node_collector,node_ebpf,node_event_schema,node_trace_output toneBlue
class node_breakdown,node_features toneAmber
class node_label_trace,node_models toneMint
class node_evaluate,node_delay,node_overhead,node_assets,node_results toneRose
class node_user,node_target,node_kernel toneIndigo
```

## Components

### Workload tracing

- [Stallbench workloads](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/workloads/stallbench.c): `code/src/workloads/stallbench.c`
- [Stalltrace collector](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/collector/stalltrace.c): `code/src/collector/stalltrace.c`
- [Kernel probes](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/ebpf/stalltrace.bpf.c): `code/src/ebpf/stalltrace.bpf.c`
- [Event schema](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/ebpf/stalltrace.h): `code/src/ebpf/stalltrace.h`
- [Trace and run data](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/collector/stalltrace.c): `code/src/collector/stalltrace.c`

### Timeline analysis

- [Timeline breakdown](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/correlation/breakdown.py): `code/src/correlation/breakdown.py`
- [Operation features](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/classifier/features.py): `code/src/classifier/features.py`

### Classification

- [Live trace labeling](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/label_trace.py): `code/src/label_trace.py`
- [Rules and trees](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/classifier/models.py): `code/src/classifier/models.py`

### Evaluation outputs

- [Classifier evaluation](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/classifier/evaluate.py): `code/src/classifier/evaluate.py`
- [Delay analysis](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/classifier/delay_analysis.py): `code/src/classifier/delay_analysis.py`
- [Overhead analysis](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/classifier/overhead.py): `code/src/classifier/overhead.py`
- [Report assets](https://github.com/tarun-227/ebpf-stall-fingerprinting/blob/main/code/src/report/make_assets.py): `code/src/report/make_assets.py`
- [Processed results](https://github.com/tarun-227/ebpf-stall-fingerprinting/tree/main/supplementary/experimental_results): `supplementary/experimental_results`

### Other components

- **Experimenter**
- **Traced target**
- **Linux kernel**

## Connections

- Experimenter → Stallbench workloads: runs workload (evidence: `README.md`)
- Experimenter → Stalltrace collector: starts tracing (evidence: `README.md`)
- Traced target → Stalltrace collector: runs under (evidence: `README.md`)
- Stallbench workloads → Stalltrace collector: marks operations (evidence: `README.md`)
- Stallbench workloads → Trace and run data: records ground truth (evidence: `README.md`)
- Stalltrace collector → Kernel probes: loads programs (evidence: `README.md`)
- Kernel probes → Linux kernel: hooks kernel events (evidence: `README.md`)
- Kernel probes → Event schema: emits records (evidence: `code/src/ebpf/stalltrace.bpf.c`)
- Stalltrace collector → Event schema: decodes records (evidence: `code/src/collector/stalltrace.c`)
- Stalltrace collector → Trace and run data: writes events (evidence: `README.md`)
- Trace and run data → Timeline breakdown: provides trace and truth (evidence: `README.md`)
- Timeline breakdown → Operation features: provides breakdown rows (evidence: `code/src/classifier/features.py`)
- Operation features → Classifier evaluation: supplies feature table (evidence: `code/src/classifier/evaluate.py`)
- Classifier evaluation → Rules and trees: builds classifiers (evidence: `code/src/classifier/evaluate.py`)
- Trace and run data → Live trace labeling: provides trace (evidence: `code/src/label_trace.py`)
- Live trace labeling → Timeline breakdown: uses timelines (evidence: `code/src/label_trace.py`)
- Live trace labeling → Rules and trees: applies rules (evidence: `code/src/label_trace.py`)
- Operation features → Delay analysis: supplies feature table (evidence: `code/src/classifier/delay_analysis.py`)
- Classifier evaluation → Processed results: produces metrics (evidence: `README.md`)
- Delay analysis → Processed results: reports delay fidelity (evidence: `README.md`)
- Overhead analysis → Processed results: reports tracing cost (evidence: `README.md`)
- Processed results → Report assets: feeds report assets (evidence: `code/src/report/make_assets.py`)
