# percona/percona-toolkit architecture

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

- Interactive diagram: https://gitdiagram.com/percona/percona-toolkit
- Repository: https://github.com/percona/percona-toolkit

## Overview

Percona Toolkit is a collection of command-line tools for database and system diagnostics. The tree shows separate Go workflows rather than one shared application: operators invoke a tool, it gathers or analyzes data from a database, log, or Kubernetes cluster, and emits a report or collected bundle. The graph preserves those distinct products and their visible internal layers. Several subsystems are represented from filenames and README-level capabilities; where sampled source did not establish call wiring, links are omitted.

Main entry points: [`src/go/pt-galera-log-explainer/main.go`](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-galera-log-explainer/main.go) (Log explainer), [`src/go/pt-k8s-debug-collector/dumper/dumper.go`](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-k8s-debug-collector/dumper/dumper.go) (Cluster dumper), [`src/go/pt-secure-collect/main.go`](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-secure-collect/main.go) (Secure collect CLI), [`src/go/pt-mongodb-query-digest/main.go`](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-query-digest/main.go) (Query digest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mongodb["MongoDB diagnostics"]
  node_mongo_summary["Mongo summary<br/>[main.go]"]
  node_mongo_templates["Report templates<br/>[clusterwide.go]"]
  node_mongo_server[("MongoDB server")]
  node_query_digest["Query digest<br/>[main.go]"]
  node_query_profiler["Query profiler<br/>[profiler.go]"]
  node_query_stats["Query statistics<br/>[stats.go]"]
  node_query_filters["Query filters<br/>[filters.go]"]
  node_index_check["Index checker<br/>[main.go]"]
  node_index_analysis["Index analysis<br/>[unused.go]"]
  node_index_templates["Index reports<br/>[unused.go]"]
end

subgraph group_postgres["PostgreSQL summary"]
  node_pg_summary["PostgreSQL summary<br/>[main.go]"]
  node_pg_collector["PG information collector<br/>[pginfo.go]"]
  node_pg_models["PG query models"]
  node_postgres_db[("PostgreSQL server")]
end

subgraph group_galera["Galera analysis"]
  node_galera_tool["Log explainer<br/>[main.go]"]
  node_galera_patterns["Log patterns<br/>[regex.go]"]
  node_galera_translation["Event translation<br/>[translate.go]"]
  node_galera_display["Timeline display<br/>[timelinecli.go]"]
  node_galera_logs["Galera logs"]
end

subgraph group_kubernetes["Kubernetes collection"]
  node_k8s_tool["Debug collector<br/>[main.go]"]
  node_k8s_dumper["Cluster dumper<br/>[dumper.go]"]
  node_k8s_resources["Resource collection<br/>[resources.go]"]
  node_k8s_logs["Pod log collection<br/>[logs.go]"]
  node_k8s_cluster[("Kubernetes cluster")]
  node_k8s_archive["Cluster archive<br/>[tar.go]"]
end

subgraph group_secure["Secure collection"]
  node_secure_tool["Secure collect CLI<br/>[main.go]"]
  node_secure_collect["Data collection<br/>[collect.go]"]
  node_secure_sanitize["Data sanitization<br/>[sanitize.go]"]
  node_secure_encrypt["File encryption<br/>[encrypt.go]"]
  node_secure_bundle["Support bundle"]
end

node_operator(("Operator"))

node_operator -->|"invokes"| node_mongo_summary
node_mongo_summary -->|"queries"| node_mongo_server
node_mongo_summary -->|"renders with"| node_mongo_templates
node_operator -->|"invokes"| node_query_digest
node_query_digest -->|"profiles"| node_mongo_server
node_query_digest -->|"applies"| node_query_filters
node_query_digest -->|"starts"| node_query_profiler
node_query_profiler -->|"records"| node_query_stats
node_operator -->|"invokes"| node_index_check
node_index_check -->|"checks"| node_mongo_server
node_index_check -->|"calls"| node_index_analysis
node_index_check -->|"renders with"| node_index_templates
node_operator -->|"invokes"| node_pg_summary
node_pg_summary -->|"queries"| node_postgres_db
node_pg_summary -->|"creates and collects"| node_pg_collector
node_pg_collector -->|"uses queries"| node_pg_models
node_operator -->|"invokes"| node_galera_tool
node_galera_tool -->|"reads"| node_galera_logs
node_galera_tool -->|"configures"| node_galera_patterns
node_galera_tool -->|"configures"| node_galera_translation
node_galera_tool -->|"dispatches"| node_galera_display
node_operator -->|"invokes"| node_k8s_tool
node_k8s_tool -->|"creates and runs"| node_k8s_dumper
node_k8s_dumper -->|"collects"| node_k8s_resources
node_k8s_dumper -->|"collects"| node_k8s_logs
node_k8s_dumper -->|"accesses"| node_k8s_cluster
node_k8s_dumper -->|"writes"| node_k8s_archive
node_operator -->|"invokes"| node_secure_tool
node_secure_tool -->|"dispatches"| node_secure_collect
node_secure_tool -->|"dispatches"| node_secure_sanitize
node_secure_tool -->|"dispatches"| node_secure_encrypt
node_secure_tool -->|"produces"| node_secure_bundle

click node_mongo_summary "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-summary/main.go"
click node_mongo_templates "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-summary/templates/clusterwide.go"
click node_query_digest "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-query-digest/main.go"
click node_query_profiler "https://github.com/percona/percona-toolkit/blob/3.x/src/go/mongolib/profiler/profiler.go"
click node_query_stats "https://github.com/percona/percona-toolkit/blob/3.x/src/go/mongolib/stats/stats.go"
click node_query_filters "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-query-digest/filter/filters.go"
click node_index_check "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-index-check/main.go"
click node_index_analysis "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-index-check/indexes/unused.go"
click node_index_templates "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-index-check/templates/unused.go"
click node_pg_summary "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-pg-summary/main.go"
click node_pg_collector "https://github.com/percona/percona-toolkit/blob/3.x/src/go/lib/pginfo/pginfo.go"
click node_pg_models "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-pg-summary/models/connectedclients.xo.go"
click node_galera_tool "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-galera-log-explainer/main.go"
click node_galera_patterns "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-galera-log-explainer/regex/regex.go"
click node_galera_translation "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-galera-log-explainer/translate/translate.go"
click node_galera_display "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-galera-log-explainer/display/timelinecli.go"
click node_k8s_tool "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-k8s-debug-collector/main.go"
click node_k8s_dumper "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-k8s-debug-collector/dumper/dumper.go"
click node_k8s_resources "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-k8s-debug-collector/dumper/resources.go"
click node_k8s_logs "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-k8s-debug-collector/dumper/logs.go"
click node_k8s_archive "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-k8s-debug-collector/dumper/tar.go"
click node_secure_tool "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-secure-collect/main.go"
click node_secure_collect "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-secure-collect/collect.go"
click node_secure_sanitize "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-secure-collect/sanitize.go"
click node_secure_encrypt "https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-secure-collect/encrypt.go"

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_mongo_summary,node_mongo_templates,node_mongo_server,node_query_digest,node_query_profiler,node_query_stats,node_query_filters,node_index_check,node_index_analysis,node_index_templates toneBlue
class node_pg_summary,node_pg_collector,node_pg_models,node_postgres_db toneAmber
class node_galera_tool,node_galera_patterns,node_galera_translation,node_galera_display,node_galera_logs toneMint
class node_k8s_tool,node_k8s_dumper,node_k8s_resources,node_k8s_logs,node_k8s_cluster,node_k8s_archive toneRose
class node_secure_tool,node_secure_collect,node_secure_sanitize,node_secure_encrypt,node_secure_bundle,node_operator toneIndigo
```

## Components

### MongoDB diagnostics

- [Mongo summary](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-summary/main.go): `src/go/pt-mongodb-summary/main.go`
- [Report templates](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-summary/templates/clusterwide.go): `src/go/pt-mongodb-summary/templates/clusterwide.go`
- **MongoDB server**
- [Query digest](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-query-digest/main.go): `src/go/pt-mongodb-query-digest/main.go`
- [Query profiler](https://github.com/percona/percona-toolkit/blob/3.x/src/go/mongolib/profiler/profiler.go): `src/go/mongolib/profiler/profiler.go`
- [Query statistics](https://github.com/percona/percona-toolkit/blob/3.x/src/go/mongolib/stats/stats.go): `src/go/mongolib/stats/stats.go`
- [Query filters](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-query-digest/filter/filters.go): `src/go/pt-mongodb-query-digest/filter/filters.go`
- [Index checker](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-index-check/main.go): `src/go/pt-mongodb-index-check/main.go`
- [Index analysis](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-index-check/indexes/unused.go): `src/go/pt-mongodb-index-check/indexes/unused.go`
- [Index reports](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-mongodb-index-check/templates/unused.go): `src/go/pt-mongodb-index-check/templates/unused.go`

### PostgreSQL summary

- [PostgreSQL summary](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-pg-summary/main.go): `src/go/pt-pg-summary/main.go`
- [PG information collector](https://github.com/percona/percona-toolkit/blob/3.x/src/go/lib/pginfo/pginfo.go): `src/go/lib/pginfo/pginfo.go`
- [PG query models](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-pg-summary/models/connectedclients.xo.go): `src/go/pt-pg-summary/models/connectedclients.xo.go`
- **PostgreSQL server**

### Galera analysis

- [Log explainer](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-galera-log-explainer/main.go): `src/go/pt-galera-log-explainer/main.go`
- [Log patterns](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-galera-log-explainer/regex/regex.go): `src/go/pt-galera-log-explainer/regex/regex.go`
- [Event translation](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-galera-log-explainer/translate/translate.go): `src/go/pt-galera-log-explainer/translate/translate.go`
- [Timeline display](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-galera-log-explainer/display/timelinecli.go): `src/go/pt-galera-log-explainer/display/timelinecli.go`
- **Galera logs**

### Kubernetes collection

- [Debug collector](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-k8s-debug-collector/main.go): `src/go/pt-k8s-debug-collector/main.go`
- [Cluster dumper](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-k8s-debug-collector/dumper/dumper.go): `src/go/pt-k8s-debug-collector/dumper/dumper.go`
- [Resource collection](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-k8s-debug-collector/dumper/resources.go): `src/go/pt-k8s-debug-collector/dumper/resources.go`
- [Pod log collection](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-k8s-debug-collector/dumper/logs.go): `src/go/pt-k8s-debug-collector/dumper/logs.go`
- **Kubernetes cluster**
- [Cluster archive](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-k8s-debug-collector/dumper/tar.go): `src/go/pt-k8s-debug-collector/dumper/tar.go`

### Secure collection

- [Secure collect CLI](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-secure-collect/main.go): `src/go/pt-secure-collect/main.go`
- [Data collection](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-secure-collect/collect.go): `src/go/pt-secure-collect/collect.go`
- [Data sanitization](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-secure-collect/sanitize.go): `src/go/pt-secure-collect/sanitize.go`
- [File encryption](https://github.com/percona/percona-toolkit/blob/3.x/src/go/pt-secure-collect/encrypt.go): `src/go/pt-secure-collect/encrypt.go`
- **Support bundle**

### Other components

- **Operator**

## Connections

- Operator → Mongo summary: invokes
- Mongo summary → MongoDB server: queries
- Mongo summary → Report templates: renders with
- Operator → Query digest: invokes
- Query digest → MongoDB server: profiles
- Query digest → Query filters: applies
- Query digest → Query profiler: starts
- Query profiler → Query statistics: records
- Operator → Index checker: invokes
- Index checker → MongoDB server: checks
- Index checker → Index analysis: calls
- Index checker → Index reports: renders with
- Operator → PostgreSQL summary: invokes
- PostgreSQL summary → PostgreSQL server: queries
- PostgreSQL summary → PG information collector: creates and collects
- PG information collector → PG query models: uses queries
- Operator → Log explainer: invokes
- Log explainer → Galera logs: reads
- Log explainer → Log patterns: configures
- Log explainer → Event translation: configures
- Log explainer → Timeline display: dispatches
- Operator → Debug collector: invokes
- Debug collector → Cluster dumper: creates and runs
- Cluster dumper → Resource collection: collects
- Cluster dumper → Pod log collection: collects
- Cluster dumper → Kubernetes cluster: accesses
- Cluster dumper → Cluster archive: writes
- Operator → Secure collect CLI: invokes
- Secure collect CLI → Data collection: dispatches
- Secure collect CLI → Data sanitization: dispatches
- Secure collect CLI → File encryption: dispatches
- Secure collect CLI → Support bundle: produces