# iovisor/bcc architecture

> Architecture diagram of the GitHub repository iovisor/bcc, 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/iovisor/bcc
- Repository: https://github.com/iovisor/bcc

## Overview

BCC is a toolkit for authoring and running eBPF tracing and manipulation programs, with Python and Lua front ends and a broad suite of tracing tools. The main workflow is a user invoking a tool or API, which compiles and loads instrumentation, attaches it to kernel or user probes, and reads event or map data for presentation. The graph includes major tool families and internal compiler, probe, map, and event layers. Some subsystem links are documented rather than verified in sampled implementation, so those are dashed.

Main entry points: [`src/python/bcc/__init__.py`](https://github.com/iovisor/bcc/blob/master/src/python/bcc/__init__.py) (Python BPF API), [`src/python/bcc/libbcc.py`](https://github.com/iovisor/bcc/blob/master/src/python/bcc/libbcc.py) (Native bindings), [`src/cc/bpf_module.h`](https://github.com/iovisor/bcc/blob/master/src/cc/bpf_module.h) (BPF module runtime), [`src/python/bcc/utils.py`](https://github.com/iovisor/bcc/blob/master/src/python/bcc/utils.py) (Python utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tools["Tracing tools"]
  node_trace_tools["Tracing tools<br/>[trace.py]"]
  node_argdist["Argument analysis<br/>[argdist.py]"]
  node_tool_families["System tool families"]
  node_standalone_tools["libbpf tools"]
end

subgraph group_frontend["Language frontends"]
  node_python_api["Python BPF API<br/>[__init__.py]"]
  node_lua_frontend["Lua frontend<br/>[main.c]"]
  node_usdt_api["USDT interface<br/>[usdt.py]"]
  node_python_helpers["Python utilities<br/>[utils.py]"]
  node_python_tables["Python map access<br/>[table.py]"]
  node_syscall_helpers["Syscall helpers<br/>[syscall.py]"]
  node_disassembler["Disassembler<br/>[disassembler.py]"]
  node_containers["Container helpers<br/>[containers.py]"]
end

subgraph group_engine["Compiler and runtime"]
  node_native_bridge["Native bindings<br/>[libbcc.py]"]
  node_compiler_loader["Compiler and loader<br/>[loader.cc]"]
  node_module_runtime["BPF module runtime<br/>[bpf_module.h]"]
  node_rw_engine["Read-write engine"]
  node_exceptions["Exception types<br/>[bcc_exception.h]"]
  node_table_desc["Map descriptions<br/>[table_desc.h]"]
  node_table_storage["Map metadata storage<br/>[table_storage.h]"]
  node_perf_events["Perf event handling<br/>[perf.py]"]
end

subgraph group_instrumentation["Instrumentation and data"]
  node_probe_runtime["Probe and map runtime<br/>[libbpf.h]"]
  node_trace_helpers["Tracing helpers<br/>[trace_helpers.h]"]
  node_klockstat["Lock statistics tool<br/>[klockstat.c]"]
  node_perf_data["Perf event data<br/>[perf_reader.c]"]
  node_map_store[("Kernel BPF maps<br/>[table.py]")]
end

node_user(("Operator"))
node_kernel{{"Linux kernel"}}

node_user -->|"invokes"| node_trace_tools
node_user -->|"invokes"| node_argdist
node_user -->|"invokes"| node_tool_families
node_user -.->|"invokes"| node_standalone_tools
node_trace_tools -->|"uses"| node_python_api
node_argdist -->|"imports"| node_python_api
node_tool_families -.->|"uses"| node_python_api
node_python_api -->|"imports"| node_native_bridge
node_python_api -->|"imports"| node_python_tables
node_python_api -->|"imports"| node_perf_events
node_python_api -->|"imports"| node_usdt_api
node_python_api -->|"imports"| node_disassembler
node_python_api -->|"imports"| node_python_helpers
node_python_api -.->|"loads through"| node_compiler_loader
node_lua_frontend -.->|"uses"| node_compiler_loader
node_native_bridge -->|"binds"| node_probe_runtime
node_python_tables -->|"calls"| node_native_bridge
node_python_tables -.->|"accesses"| node_map_store
node_perf_events -.->|"uses"| node_perf_data
node_usdt_api -->|"calls"| node_native_bridge
node_python_helpers -->|"calls"| node_native_bridge
node_python_helpers -.->|"supports"| node_syscall_helpers
node_module_runtime -->|"includes"| node_exceptions
node_module_runtime -->|"uses"| node_table_storage
node_table_storage -->|"uses"| node_table_desc
node_rw_engine -->|"implements"| node_module_runtime
node_rw_engine -->|"uses"| node_table_storage
node_compiler_loader -.->|"loads"| node_module_runtime
node_probe_runtime -.->|"attaches probes"| node_kernel
node_kernel -.->|"updates"| node_map_store
node_kernel -.->|"emits events"| node_perf_data
node_standalone_tools -.->|"includes"| node_klockstat
node_klockstat -->|"uses"| node_trace_helpers
node_klockstat -.->|"traces locks"| node_kernel

click node_trace_tools "https://github.com/iovisor/bcc/blob/master/tools/trace.py"
click node_argdist "https://github.com/iovisor/bcc/blob/master/tools/argdist.py"
click node_tool_families "https://github.com/iovisor/bcc/tree/master/tools"
click node_standalone_tools "https://github.com/iovisor/bcc/tree/master/libbpf-tools"
click node_python_api "https://github.com/iovisor/bcc/blob/master/src/python/bcc/__init__.py"
click node_lua_frontend "https://github.com/iovisor/bcc/blob/master/src/lua/src/main.c"
click node_usdt_api "https://github.com/iovisor/bcc/blob/master/src/python/bcc/usdt.py"
click node_python_helpers "https://github.com/iovisor/bcc/blob/master/src/python/bcc/utils.py"
click node_native_bridge "https://github.com/iovisor/bcc/blob/master/src/python/bcc/libbcc.py"
click node_compiler_loader "https://github.com/iovisor/bcc/blob/master/src/cc/frontends/clang/loader.cc"
click node_module_runtime "https://github.com/iovisor/bcc/blob/master/src/cc/bpf_module.h"
click node_rw_engine "https://github.com/iovisor/bcc/blob/master/src/cc/bpf_module_rw_engine.cc"
click node_exceptions "https://github.com/iovisor/bcc/blob/master/src/cc/bcc_exception.h"
click node_table_desc "https://github.com/iovisor/bcc/blob/master/src/cc/table_desc.h"
click node_table_storage "https://github.com/iovisor/bcc/blob/master/src/cc/table_storage.h"
click node_python_tables "https://github.com/iovisor/bcc/blob/master/src/python/bcc/table.py"
click node_perf_events "https://github.com/iovisor/bcc/blob/master/src/python/bcc/perf.py"
click node_syscall_helpers "https://github.com/iovisor/bcc/blob/master/src/python/bcc/syscall.py"
click node_disassembler "https://github.com/iovisor/bcc/blob/master/src/python/bcc/disassembler.py"
click node_containers "https://github.com/iovisor/bcc/blob/master/src/python/bcc/containers.py"
click node_probe_runtime "https://github.com/iovisor/bcc/blob/master/src/cc/libbpf.h"
click node_trace_helpers "https://github.com/iovisor/bcc/blob/master/libbpf-tools/trace_helpers.h"
click node_klockstat "https://github.com/iovisor/bcc/blob/master/libbpf-tools/klockstat.c"
click node_perf_data "https://github.com/iovisor/bcc/blob/master/src/cc/perf_reader.c"
click node_map_store "https://github.com/iovisor/bcc/blob/master/src/python/bcc/table.py"

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_trace_tools,node_argdist,node_tool_families,node_standalone_tools toneBlue
class node_python_api,node_lua_frontend,node_usdt_api,node_python_helpers,node_python_tables,node_syscall_helpers,node_disassembler,node_containers toneAmber
class node_native_bridge,node_compiler_loader,node_module_runtime,node_rw_engine,node_exceptions,node_table_desc,node_table_storage,node_perf_events toneMint
class node_probe_runtime,node_trace_helpers,node_klockstat,node_perf_data,node_map_store toneRose
class node_user,node_kernel toneIndigo
```

## Components

### Tracing tools

- [Tracing tools](https://github.com/iovisor/bcc/blob/master/tools/trace.py): `tools/trace.py`
- [Argument analysis](https://github.com/iovisor/bcc/blob/master/tools/argdist.py): `tools/argdist.py`
- [System tool families](https://github.com/iovisor/bcc/tree/master/tools): `tools`
- [libbpf tools](https://github.com/iovisor/bcc/tree/master/libbpf-tools): `libbpf-tools`

### Language frontends

- [Python BPF API](https://github.com/iovisor/bcc/blob/master/src/python/bcc/__init__.py): `src/python/bcc/__init__.py`
- [Lua frontend](https://github.com/iovisor/bcc/blob/master/src/lua/src/main.c): `src/lua/src/main.c`
- [USDT interface](https://github.com/iovisor/bcc/blob/master/src/python/bcc/usdt.py): `src/python/bcc/usdt.py`
- [Python utilities](https://github.com/iovisor/bcc/blob/master/src/python/bcc/utils.py): `src/python/bcc/utils.py`
- [Python map access](https://github.com/iovisor/bcc/blob/master/src/python/bcc/table.py): `src/python/bcc/table.py`
- [Syscall helpers](https://github.com/iovisor/bcc/blob/master/src/python/bcc/syscall.py): `src/python/bcc/syscall.py`
- [Disassembler](https://github.com/iovisor/bcc/blob/master/src/python/bcc/disassembler.py): `src/python/bcc/disassembler.py`
- [Container helpers](https://github.com/iovisor/bcc/blob/master/src/python/bcc/containers.py): `src/python/bcc/containers.py`

### Compiler and runtime

- [Native bindings](https://github.com/iovisor/bcc/blob/master/src/python/bcc/libbcc.py): `src/python/bcc/libbcc.py`
- [Compiler and loader](https://github.com/iovisor/bcc/blob/master/src/cc/frontends/clang/loader.cc): `src/cc/frontends/clang/loader.cc`
- [BPF module runtime](https://github.com/iovisor/bcc/blob/master/src/cc/bpf_module.h): `src/cc/bpf_module.h`
- [Read-write engine](https://github.com/iovisor/bcc/blob/master/src/cc/bpf_module_rw_engine.cc): `src/cc/bpf_module_rw_engine.cc`
- [Exception types](https://github.com/iovisor/bcc/blob/master/src/cc/bcc_exception.h): `src/cc/bcc_exception.h`
- [Map descriptions](https://github.com/iovisor/bcc/blob/master/src/cc/table_desc.h): `src/cc/table_desc.h`
- [Map metadata storage](https://github.com/iovisor/bcc/blob/master/src/cc/table_storage.h): `src/cc/table_storage.h`
- [Perf event handling](https://github.com/iovisor/bcc/blob/master/src/python/bcc/perf.py): `src/python/bcc/perf.py`

### Instrumentation and data

- [Probe and map runtime](https://github.com/iovisor/bcc/blob/master/src/cc/libbpf.h): `src/cc/libbpf.h`
- [Tracing helpers](https://github.com/iovisor/bcc/blob/master/libbpf-tools/trace_helpers.h): `libbpf-tools/trace_helpers.h`
- [Lock statistics tool](https://github.com/iovisor/bcc/blob/master/libbpf-tools/klockstat.c): `libbpf-tools/klockstat.c`
- [Perf event data](https://github.com/iovisor/bcc/blob/master/src/cc/perf_reader.c): `src/cc/perf_reader.c`
- [Kernel BPF maps](https://github.com/iovisor/bcc/blob/master/src/python/bcc/table.py): `src/python/bcc/table.py`

### Other components

- **Operator**
- **Linux kernel**

## Connections

- Operator → Tracing tools: invokes (evidence: `README.md`)
- Operator → Argument analysis: invokes (evidence: `README.md`)
- Operator → System tool families: invokes (evidence: `README.md`)
- Operator → libbpf tools: invokes
- Tracing tools → Python BPF API: uses (evidence: `tools/trace.py`)
- Argument analysis → Python BPF API: imports (evidence: `tools/argdist.py`)
- System tool families → Python BPF API: uses (evidence: `tools/trace.py`)
- Python BPF API → Native bindings: imports (evidence: `src/python/bcc/__init__.py`)
- Python BPF API → Python map access: imports (evidence: `src/python/bcc/__init__.py`)
- Python BPF API → Perf event handling: imports (evidence: `src/python/bcc/__init__.py`)
- Python BPF API → USDT interface: imports (evidence: `src/python/bcc/__init__.py`)
- Python BPF API → Disassembler: imports (evidence: `src/python/bcc/__init__.py`)
- Python BPF API → Python utilities: imports (evidence: `src/python/bcc/__init__.py`)
- Python BPF API → Compiler and loader: loads through
- Lua frontend → Compiler and loader: uses
- Native bindings → Probe and map runtime: binds (evidence: `src/cc/libbpf.h`)
- Python map access → Native bindings: calls (evidence: `src/python/bcc/table.py`)
- Python map access → Kernel BPF maps: accesses (evidence: `src/python/bcc/table.py`)
- Perf event handling → Perf event data: uses
- USDT interface → Native bindings: calls (evidence: `src/python/bcc/usdt.py`)
- Python utilities → Native bindings: calls (evidence: `src/python/bcc/utils.py`)
- Python utilities → Syscall helpers: supports
- BPF module runtime → Exception types: includes (evidence: `src/cc/bpf_module.h`)
- BPF module runtime → Map metadata storage: uses (evidence: `src/cc/bpf_module.h`)
- Map metadata storage → Map descriptions: uses (evidence: `src/cc/table_storage.h`)
- Read-write engine → BPF module runtime: implements (evidence: `src/cc/bpf_module_rw_engine.cc`)
- Read-write engine → Map metadata storage: uses (evidence: `src/cc/bpf_module_rw_engine.cc`)
- Compiler and loader → BPF module runtime: loads
- Probe and map runtime → Linux kernel: attaches probes
- Linux kernel → Kernel BPF maps: updates
- Linux kernel → Perf event data: emits events
- libbpf tools → Lock statistics tool: includes (evidence: `libbpf-tools/klockstat.c`)
- Lock statistics tool → Tracing helpers: uses (evidence: `libbpf-tools/klockstat.c`)
- Lock statistics tool → Linux kernel: traces locks
