# google/perfetto architecture

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

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

## Overview

Perfetto is a system-tracing and trace-analysis suite. Its principal workflow is to configure tracing, collect userspace and OS events through SDKs, probes, and tracing daemons, then inspect the resulting trace in the browser UI or analyze it with SQL. The graph also includes trace-processor storage and execution layers. The README documents the product capabilities; sampled source excerpts expose some implementation details, but not enough to verify every runtime connection.

Main entry points: [`src/trace_processor/perfetto_sql/engine/pipeline_module.cc`](https://github.com/google/perfetto/blob/main/src/trace_processor/perfetto_sql/engine/pipeline_module.cc) (SQL execution), [`src/trace_processor/storage/trace_storage.h`](https://github.com/google/perfetto/blob/main/src/trace_processor/storage/trace_storage.h) (Trace storage), [`src/trace_processor/trace_processor_storage_impl.cc`](https://github.com/google/perfetto/blob/main/src/trace_processor/trace_processor_storage_impl.cc) (Trace processor), [`src/traced/service/main.cc`](https://github.com/google/perfetto/blob/main/src/traced/service/main.cc) (Tracing daemon)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Tracing capture"]
  node_sdk["Tracing SDK<br/>[tracing.h]"]
  node_probes["OS probes"]
  node_daemon["Tracing daemon<br/>[main.cc]"]
  node_service["Tracing service"]
  node_tracefile["Unified trace"]
end

subgraph group_processing["Trace processing"]
  node_importers["Trace importers"]
  node_processor["Trace processor"]
  node_storage[("Trace storage<br/>[trace_storage.h]")]
  node_stringpool["String pool<br/>[string_pool.h]"]
  node_stats["Trace statistics<br/>[stats.h]"]
  node_storageapi["Storage API"]
  node_storageplugin["Storage tables<br/>[storage_tables.cc]"]
end

subgraph group_analysis["Analysis and UI"]
  node_sqlengine["SQL execution<br/>[pipeline_module.cc]"]
  node_execpipeline["Execution pipeline<br/>[pipeline.cc]"]
  node_traceui["Browser trace UI<br/>[engine.ts]"]
  node_dataexplorer["Data Explorer"]
  node_bigtrace["Bigtrace client"]
  node_uiresult["UI query results<br/>[engine.ts]"]
end

subgraph group_foundation["Runtime foundations"]
  node_base["Base utilities<br/>[status.h]"]
  node_buildconfig["Build config<br/>[build_config.h]"]
  node_logging["Logging<br/>[logging.h]"]
  node_fileutils["File utilities<br/>[file_utils.h]"]
  node_hashmap["Hash map<br/>[flat_hash_map.h]"]
  node_stringview["String views<br/>[string_view.h]"]
  node_tracebasics["Trace data types<br/>[basic_types.h]"]
end

node_developer(("Developer"))
node_sqluser(("Analysis user"))

node_developer -->|"instruments apps"| node_sdk
node_developer -->|"configures tracing"| node_daemon
node_sdk -.->|"submits events"| node_service
node_probes -->|"captures system events"| node_daemon
node_daemon -->|"collects tracing"| node_service
node_service -->|"records trace"| node_tracefile
node_tracefile -.->|"loads trace"| node_importers
node_processor -->|"uses importers"| node_importers
node_processor -.->|"updates storage"| node_storage
node_storage -->|"interns strings"| node_stringpool
node_storageplugin -->|"registers tables"| node_storage
node_processor -.->|"implements storage"| node_storageapi
node_tracefile -->|"queries trace"| node_sqlengine
node_sqluser -->|"runs SQL"| node_sqlengine
node_sqlengine -->|"executes pipeline"| node_execpipeline
node_sqluser -->|"explores trace"| node_traceui
node_traceui -->|"visualizes trace"| node_tracefile
node_dataexplorer -->|"executes queries"| node_traceui
node_bigtrace -.->|"queries remotely"| node_tracefile
node_sqlengine -.->|"queries tables"| node_storage

click node_sdk "https://github.com/google/perfetto/blob/main/include/perfetto/tracing.h"
click node_probes "https://github.com/google/perfetto/tree/main/src/traced/probes"
click node_daemon "https://github.com/google/perfetto/blob/main/src/traced/service/main.cc"
click node_service "https://github.com/google/perfetto/blob/main/src/tracing/service/tracing_service_session.cc"
click node_importers "https://github.com/google/perfetto/tree/main/src/trace_processor/importers"
click node_processor "https://github.com/google/perfetto/blob/main/src/trace_processor/trace_processor_storage_impl.cc"
click node_storage "https://github.com/google/perfetto/blob/main/src/trace_processor/storage/trace_storage.h"
click node_stringpool "https://github.com/google/perfetto/blob/main/src/trace_processor/containers/string_pool.h"
click node_stats "https://github.com/google/perfetto/blob/main/src/trace_processor/storage/stats.h"
click node_storageapi "https://github.com/google/perfetto/blob/main/include/perfetto/trace_processor/trace_processor_storage.h"
click node_storageplugin "https://github.com/google/perfetto/blob/main/src/trace_processor/plugins/storage_tables/storage_tables.cc"
click node_sqlengine "https://github.com/google/perfetto/blob/main/src/trace_processor/perfetto_sql/engine/pipeline_module.cc"
click node_execpipeline "https://github.com/google/perfetto/blob/main/src/trace_processor/core/exec/pipeline.cc"
click node_traceui "https://github.com/google/perfetto/blob/main/ui/src/trace_processor/engine.ts"
click node_dataexplorer "https://github.com/google/perfetto/blob/main/ui/src/plugins/dev.perfetto.DataExplorer/query_builder/query_execution_service.ts"
click node_bigtrace "https://github.com/google/perfetto/blob/main/ui/src/bigtrace/query/bigtrace_query_client.ts"
click node_base "https://github.com/google/perfetto/blob/main/include/perfetto/base/status.h"
click node_buildconfig "https://github.com/google/perfetto/blob/main/include/perfetto/base/build_config.h"
click node_logging "https://github.com/google/perfetto/blob/main/include/perfetto/base/logging.h"
click node_fileutils "https://github.com/google/perfetto/blob/main/include/perfetto/ext/base/file_utils.h"
click node_hashmap "https://github.com/google/perfetto/blob/main/include/perfetto/ext/base/flat_hash_map.h"
click node_stringview "https://github.com/google/perfetto/blob/main/include/perfetto/ext/base/string_view.h"
click node_tracebasics "https://github.com/google/perfetto/blob/main/include/perfetto/trace_processor/basic_types.h"
click node_uiresult "https://github.com/google/perfetto/blob/main/ui/src/trace_processor/engine.ts"

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_sdk,node_probes,node_daemon,node_service,node_tracefile,node_sqluser toneBlue
class node_importers,node_processor,node_storage,node_stringpool,node_stats,node_storageapi,node_storageplugin toneAmber
class node_sqlengine,node_execpipeline,node_traceui,node_dataexplorer,node_bigtrace,node_uiresult toneMint
class node_base,node_buildconfig,node_logging,node_fileutils,node_hashmap,node_stringview,node_tracebasics toneRose
class node_developer toneIndigo
```

## Components

### Tracing capture

- [Tracing SDK](https://github.com/google/perfetto/blob/main/include/perfetto/tracing.h): `include/perfetto/tracing.h`
- [OS probes](https://github.com/google/perfetto/tree/main/src/traced/probes): `src/traced/probes`
- [Tracing daemon](https://github.com/google/perfetto/blob/main/src/traced/service/main.cc): `src/traced/service/main.cc`
- [Tracing service](https://github.com/google/perfetto/blob/main/src/tracing/service/tracing_service_session.cc): `src/tracing/service/tracing_service_session.cc`
- **Unified trace**

### Trace processing

- [Trace importers](https://github.com/google/perfetto/tree/main/src/trace_processor/importers): `src/trace_processor/importers`
- [Trace processor](https://github.com/google/perfetto/blob/main/src/trace_processor/trace_processor_storage_impl.cc): `src/trace_processor/trace_processor_storage_impl.cc`
- [Trace storage](https://github.com/google/perfetto/blob/main/src/trace_processor/storage/trace_storage.h): `src/trace_processor/storage/trace_storage.h`
- [String pool](https://github.com/google/perfetto/blob/main/src/trace_processor/containers/string_pool.h): `src/trace_processor/containers/string_pool.h`
- [Trace statistics](https://github.com/google/perfetto/blob/main/src/trace_processor/storage/stats.h): `src/trace_processor/storage/stats.h`
- [Storage API](https://github.com/google/perfetto/blob/main/include/perfetto/trace_processor/trace_processor_storage.h): `include/perfetto/trace_processor/trace_processor_storage.h`
- [Storage tables](https://github.com/google/perfetto/blob/main/src/trace_processor/plugins/storage_tables/storage_tables.cc): `src/trace_processor/plugins/storage_tables/storage_tables.cc`

### Analysis and UI

- [SQL execution](https://github.com/google/perfetto/blob/main/src/trace_processor/perfetto_sql/engine/pipeline_module.cc): `src/trace_processor/perfetto_sql/engine/pipeline_module.cc`
- [Execution pipeline](https://github.com/google/perfetto/blob/main/src/trace_processor/core/exec/pipeline.cc): `src/trace_processor/core/exec/pipeline.cc`
- [Browser trace UI](https://github.com/google/perfetto/blob/main/ui/src/trace_processor/engine.ts): `ui/src/trace_processor/engine.ts`
- [Data Explorer](https://github.com/google/perfetto/blob/main/ui/src/plugins/dev.perfetto.DataExplorer/query_builder/query_execution_service.ts): `ui/src/plugins/dev.perfetto.DataExplorer/query_builder/query_execution_service.ts`
- [Bigtrace client](https://github.com/google/perfetto/blob/main/ui/src/bigtrace/query/bigtrace_query_client.ts): `ui/src/bigtrace/query/bigtrace_query_client.ts`
- [UI query results](https://github.com/google/perfetto/blob/main/ui/src/trace_processor/engine.ts): `ui/src/trace_processor/engine.ts`

### Runtime foundations

- [Base utilities](https://github.com/google/perfetto/blob/main/include/perfetto/base/status.h): `include/perfetto/base/status.h`
- [Build config](https://github.com/google/perfetto/blob/main/include/perfetto/base/build_config.h): `include/perfetto/base/build_config.h`
- [Logging](https://github.com/google/perfetto/blob/main/include/perfetto/base/logging.h): `include/perfetto/base/logging.h`
- [File utilities](https://github.com/google/perfetto/blob/main/include/perfetto/ext/base/file_utils.h): `include/perfetto/ext/base/file_utils.h`
- [Hash map](https://github.com/google/perfetto/blob/main/include/perfetto/ext/base/flat_hash_map.h): `include/perfetto/ext/base/flat_hash_map.h`
- [String views](https://github.com/google/perfetto/blob/main/include/perfetto/ext/base/string_view.h): `include/perfetto/ext/base/string_view.h`
- [Trace data types](https://github.com/google/perfetto/blob/main/include/perfetto/trace_processor/basic_types.h): `include/perfetto/trace_processor/basic_types.h`

### Other components

- **Developer**
- **Analysis user**

## Connections

- Developer → Tracing SDK: instruments apps (evidence: `README.md`)
- Developer → Tracing daemon: configures tracing (evidence: `README.md`)
- Tracing SDK → Tracing service: submits events
- OS probes → Tracing daemon: captures system events (evidence: `README.md`)
- Tracing daemon → Tracing service: collects tracing (evidence: `README.md`)
- Tracing service → Unified trace: records trace (evidence: `README.md`)
- Unified trace → Trace importers: loads trace
- Trace processor → Trace importers: uses importers (evidence: `src/trace_processor/trace_processor_storage_impl.cc`)
- Trace processor → Trace storage: updates storage (evidence: `src/trace_processor/trace_processor_storage_impl.cc`)
- Trace storage → String pool: interns strings (evidence: `src/trace_processor/storage/trace_storage.h`)
- Storage tables → Trace storage: registers tables (evidence: `src/trace_processor/plugins/storage_tables/storage_tables.cc`)
- Trace processor → Storage API: implements storage
- Unified trace → SQL execution: queries trace (evidence: `README.md`)
- Analysis user → SQL execution: runs SQL (evidence: `README.md`)
- SQL execution → Execution pipeline: executes pipeline (evidence: `src/trace_processor/perfetto_sql/engine/pipeline_module.cc`)
- Analysis user → Browser trace UI: explores trace (evidence: `README.md`)
- Browser trace UI → Unified trace: visualizes trace (evidence: `README.md`)
- Data Explorer → Browser trace UI: executes queries (evidence: `ui/src/plugins/dev.perfetto.DataExplorer/query_builder/query_execution_service.ts`)
- Bigtrace client → Unified trace: queries remotely
- SQL execution → Trace storage: queries tables
