Advanced Filtering
Relevant source files
The following files were used as context for generating this wiki page:
Advanced Filtering in pmm-dump allows users to selectively export metrics and Query Analytics (QAN) data from a PMM Server. By using specific flags, users can restrict the scope of a dump to certain timeframes, specific database instances, or granular metric selectors. This ensures that the generated dump files are focused and manageable in size, specifically aiding Percona engineers in troubleshooting localized issues.
The filtering logic is divided between two primary data sources: VictoriaMetrics for core metrics and ClickHouse for QAN data. Users can apply filters based on high-level entities like Grafana dashboards or low-level expressions like Prometheus-style label selectors.
Sources: README.md:3-5, cmd/pmm-dump/main.go:88-100
Filtering Architecture
The filtering process occurs during the export command execution. The tool parses CLI flags to build selectors for different storage backends.
The diagram above shows how user-provided filters are aggregated and passed to the respective data sources to influence the data extraction process.
Sources: cmd/pmm-dump/main.go:174-210, pkg/victoriametrics/source.go:44-55
Core Metric Filtering (VictoriaMetrics)
VictoriaMetrics filtering primarily relies on time-series selectors. These are Prometheus-compatible label matching expressions used to identify specific metrics.
Dashboard-Based Filtering
Users can specify one or more dashboard names using the --dashboard flag. pmm-dump retrieves the underlying metric selectors used by those dashboards to automatically filter the exported data.
Sources: cmd/pmm-dump/main.go:197-200, README.md:120-123
Manual Selectors
The --ts-selector flag allows for direct input of VictoriaMetrics selectors. If no dashboards are specified but instances are, the tool automatically generates selectors using the service_name label.
| Filter Type | Flag | Backend Implementation | Example |
|---|---|---|---|
| Time Range | --start-ts, --end-ts | start and end URL parameters | 2006-01-02T15:04:05Z |
| Labels | --ts-selector | match[] URL parameter | {service_name="mongo"} |
| Service | --instance | Generated {service_name="..."} | mongo |
Sources: README.md:73-81, pkg/victoriametrics/source.go:47-55
QAN Filtering (ClickHouse)
Query Analytics data stored in ClickHouse is filtered using SQL-like WHERE statements.
WHERE Clause Filtering
The --where flag allows users to pass a raw ClickHouse WHERE clause. This is useful for filtering by specific database types, query attributes, or service IDs.
Sources: cmd/pmm-dump/main.go:94, internal/test/e2e/qan_test.go:76-80
Instance Filtering for QAN
The --instance flag is cross-functional. When used, it generates a WHERE statement for ClickHouse in the format service_name='<name>'. If multiple instances are provided, they are joined with an OR operator.
// Example logic from main.go:212-219
if *where == "" && len(*instances) > 0 {
for i, serviceName := range *instances {
if i != 0 {
*where += " OR "
}
*where += fmt.Sprintf("service_name='%s'", serviceName)
}
}
Sources: cmd/pmm-dump/main.go:212-219, internal/test/e2e/qan_test.go:88-92
Time-Based Filtering
All exports are subject to time-based filtering. If no timeframe is specified, the tool defaults to the last 4 hours.
The sequence shows how the overall time range is subdivided into manageable chunks before being requested from the metrics source.
Sources: cmd/pmm-dump/main.go:146-163, pkg/victoriametrics/source.go:303-324
Load-Based Export Throttling
While not a direct "data filter," pmm-dump includes an advanced mechanism to filter when the export happens based on system load. This prevents the export process from overwhelming the PMM Server.
| Threshold | Description | Default Max | Default Critical |
|---|---|---|---|
CPU | PMM Server CPU load (%) | 70 | 90 |
RAM | PMM Server RAM usage (%) | 80 | 90 |
MYRAM | Local pmm-dump RAM usage (%) | 10 | 30 |
Users can bypass these checks using the --ignore-load flag or customize them using --max-load and --critical-load.
Sources: README.md:143-155, cmd/pmm-dump/main.go:102-106
Summary of Filtering Logic
Advanced Filtering is achieved by translating high-level CLI arguments into specific API queries for PMM's internal components. VictoriaMetrics handles label-based series selection, while ClickHouse handles row-based SQL filtering. Both are constrained by the mandatory timeframe processing that ensures dumps are chronologically precise.
Sources: cmd/pmm-dump/main.go:202-225, pkg/victoriametrics/source.go:44-55