---
title: Monitor the performance upgrade preview
description: Use system tables and query telemetry to monitor file status, query execution, and overall performance when using InfluxDB 3 Enterprise performance upgrades.
url: https://docs.influxdata.com/influxdb3/enterprise/performance-preview/monitor/
estimated_tokens: 3556
product: InfluxDB 3 Enterprise
version: enterprise
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb3/enterprise/performance-preview/monitor/
date: '2026-06-25T15:51:16+00:00'
lastmod: '2026-06-25T15:51:16+00:00'
---

#### Performance preview beta

The performance upgrade preview is available to InfluxDB 3 Enterprise Trial
and Commercial users as a beta. These features are subject to breaking changes
and **should not be used for production workloads**.

InfluxDB 3 Enterprise provides system tables and a query telemetry endpoint to
monitor file status, query execution, and overall performance when using the
performance upgrade preview.

## System tables

The upgraded storage engine exposes internal state through system tables that
you can query with SQL.

### system.pt\_ingest\_wal

View WAL files and their shards:

```sql
SELECT * FROM system.pt_ingest_wal;
```

Example output:

|wal\_file\_id| shard\_start\_time |shard\_duration\_seconds|     min\_time      |     max\_time      |row\_count|size\_bytes|is\_merged|
|-------------|--------------------|------------------------|--------------------|--------------------|----------|-----------|----------|
|      1      |2024-01-01T00:00:00Z|         86400          |2024-01-01T00:00:00Z|2024-01-01T00:10:00Z|  50000   |  2456789  |  false   |
|      2      |2024-01-01T00:00:00Z|         86400          |2024-01-01T00:10:00Z|2024-01-01T00:20:00Z|  48000   |  2345678  |  false   |

> [!Note]
> **InfluxDB 3.10**: The `system.pt_ingest_wal` schema was updated to replace`partition_id`, `database_id`, and `table_id` with `shard_start_time`,`shard_duration_seconds`, and `is_merged`.

Use this table to monitor:

* **WAL accumulation**: Track the number and size of unmerged WAL files
* **Shard distribution**: See how data is distributed across shards
* **Time coverage**: Verify data time ranges
* **Merge status**: Identify WAL files where `is_merged` is `false`

#### Monitor WAL backlog

Check for WAL accumulation that may indicate merging is falling behind:

```sql
SELECT
  COUNT(*) as wal_file_count,
  SUM(size_bytes) / 1024 / 1024 as total_size_mb,
  MIN(min_time) as oldest_data,
  MAX(max_time) as newest_data
FROM system.pt_ingest_wal;
```

### system.pt\_ingest\_files

View Gen0 files with metadata:

```sql
SELECT * FROM system.pt_ingest_files;
```

Example output:

|file\_id|generation|     min\_time      |     max\_time      |row\_count|size\_bytes|has\_bloom\_filter|
|--------|----------|--------------------|--------------------|----------|-----------|------------------|
|   1    |    0     |2024-01-01T00:00:00Z|2024-01-01T01:00:00Z|  500000  | 45678901  |       true       |
|   2    |    0     |2024-01-01T01:00:00Z|2024-01-01T02:00:00Z|  480000  | 43567890  |       true       |

Use this table to monitor:

* **File counts per generation**: Track compaction progress
* **File sizes**: Verify files are within configured limits
* **Time ranges**: Identify Gen0 files that span multiple compaction windows

#### Monitor file distribution

Check file distribution and compaction status:

```sql
SELECT
  generation,
  COUNT(*) as file_count,
  SUM(row_count) as total_rows,
  SUM(size_bytes) / 1024 / 1024 as total_size_mb,
  AVG(size_bytes) / 1024 / 1024 as avg_file_size_mb
FROM system.pt_ingest_files
GROUP BY generation
ORDER BY generation;
```

### Compaction tables

The following system tables expose the state of the pacha-tree compaction
subsystem.

#### system.pt\_compaction\_active\_jobs

View currently running compaction jobs:

```sql
SELECT * FROM system.pt_compaction_active_jobs;
```

Key columns:

|      Column      |                    Description                     |
|------------------|----------------------------------------------------|
|    `plan_id`     |               Unique job identifier                |
|   `plan_type`    |          Job type (for example, `L0toL1`)          |
|     `state`      |Current job state (for example, `running`, `queued`)|
|    `shard_id`    |               Shard being compacted                |
|  `total_slices`  |            Total work units in the job             |
|`completed_slices`|            Work units completed so far             |

#### system.pt\_compaction\_ingest\_nodes

View per-ingest-node compaction lag:

```sql
SELECT * FROM system.pt_compaction_ingest_nodes;
```

Key columns:

|         Column          |                           Description                            |
|-------------------------|------------------------------------------------------------------|
|        `node_id`        |                      Ingest node identifier                      |
|    `compaction_lag`     |       How far behind the compactor is on this node’s data        |
|       `seen_lag`        |Lag between latest observed snapshot and latest compacted snapshot|
|`deferred_snapshot_count`|     Number of snapshots deferred due to compaction failures      |

Use `compaction_lag` and `deferred_snapshot_count` as the primary health
indicators.
A non-zero `deferred_snapshot_count` means snapshots failed to compact and
are accumulating; check `system.pt_compaction_deferred_snapshots` for details.

#### system.pt\_compaction\_nodes

View compaction node state:

```sql
SELECT * FROM system.pt_compaction_nodes;
```

#### system.pt\_compaction\_run\_sets

View pending compaction work grouped by time window and shard:

```sql
SELECT * FROM system.pt_compaction_run_sets;
```

#### system.pt\_compaction\_deferred\_snapshots

View snapshots that failed to compact:

```sql
SELECT * FROM system.pt_compaction_deferred_snapshots;
```

A growing list here indicates a persistent compaction failure.
Check `error_message` for the root cause.

## Parquet upgrade status

If you [upgraded from Parquet](/influxdb3/enterprise/performance-preview/#upgrade-from-parquet),
use these system tables to monitor migration progress.

### system.upgrade\_parquet\_node

View per-node upgrade status:

```sql
SELECT * FROM system.upgrade_parquet_node;
```

Monitor this table to confirm each node reaches `completed` status.
During the upgrade, nodes progress through detection, conversion, and
finalization stages.

### system.upgrade\_parquet

View per-file migration progress:

```sql
SELECT * FROM system.upgrade_parquet;
```

Use this table to track individual file conversions during the migration.
The status updates on a polling interval (default 5 seconds, configurable with`--pt-upgrade-poll-interval`).

## Query telemetry

The query telemetry endpoint provides detailed execution statistics for
analyzing query performance.

### Enable query telemetry

Query the telemetry endpoint after executing a query:

```bash
curl -X GET "http://localhost:8181/api/v3/query_sql_telemetry" \
  -H "Authorization: Bearer AUTH_TOKEN"
```

Replace `AUTH_TOKEN` with your authentication token.

### Telemetry response

The response includes:

|       Field       |            Description             |
|-------------------|------------------------------------|
|    `query_id`     |  Unique identifier for the query   |
|`execution_time_us`|Total execution time in microseconds|
|     `chunks`      |        Per-chunk statistics        |
|   `cache_stats`   |      Cache hit rates by type       |
|   `file_stats`    |     File-level read statistics     |

### Example telemetry output

```json
{
  "query_id": "q_12345",
  "execution_time_us": 4523,
  "chunks": [
    {
      "chunk_id": "c_1",
      "files_scanned": 3,
      "blocks_processed": 12,
      "rows_read": 24000,
      "rows_returned": 150,
      "bytes_read": 1234567
    }
  ],
  "cache_stats": {
    "gen0_hits": 5,
    "gen0_misses": 1,
    "compacted_hits": 8,
    "compacted_misses": 2
  }
}
```

## Performance analysis

### Query performance metrics

Track these key metrics for query performance:

|          Metric           | Good  |Warning |                           Action                           |
|---------------------------|-------|--------|------------------------------------------------------------|
|      Cache hit rate       | \>80% | \<60%  |Increase `--pt-file-cache-size` or `--pt-file-cache-recency`|
|Rows read vs returned ratio|\<100:1|\>1000:1|               Add more selective predicates                |

### Ingest performance metrics

Monitor these metrics for write performance:

|    Metric     |Healthy|Warning|                  Action                   |
|---------------|-------|-------|-------------------------------------------|
|WAL file count | \<50  | \>100 |   Increase `--pt-wal-flush-concurrency`   |
|Gen0 file count| \<100 | \>200 |Increase `--pt-compactor-input-size-budget`|

### Monitor with SQL

Create a performance summary query:

```sql
-- File generation summary
SELECT
  'Gen0 files' as metric,
  COUNT(*) as count,
  SUM(size_bytes) / 1024 / 1024 as size_mb
FROM system.pt_ingest_files
WHERE generation = 0

UNION ALL

SELECT
  'Compacted files' as metric,
  COUNT(*) as count,
  SUM(size_bytes) / 1024 / 1024 as size_mb
FROM system.pt_ingest_files
WHERE generation > 0

UNION ALL

SELECT
  'WAL files' as metric,
  COUNT(*) as count,
  SUM(size_bytes) / 1024 / 1024 as size_mb
FROM system.pt_ingest_wal;
```

## Troubleshooting

### High WAL file count

**Symptom**: `system.pt_ingest_wal` shows many accumulated files.

**Possible causes**:

* Merge operations falling behind write rate
* Insufficient flush concurrency
* Object storage latency

**Solutions**:

1. Increase flush concurrency:

   ```
   --pt-wal-flush-concurrency 8
   ```

2. Increase WAL flush interval to create larger, fewer files:

   ```
   --pt-wal-flush-interval 5s
   ```

3. Increase the WAL buffer size so each flush produces a larger file:

   ```
   --pt-wal-max-buffer-size 30MB
   ```

4. Check object storage performance and connectivity.

### High cache miss rate

**Symptom**: `cache_stats` shows \>40% miss rate.

**Possible causes**:

* Cache size too small for working set
* Cache recency window too narrow
* Random access patterns across time ranges

**Solutions**:

1. Increase cache size:

   ```
   --pt-file-cache-size 16GB
   ```

2. Extend cache recency window:

   ```
   --pt-file-cache-recency 24h
   ```

3. Extend eviction timeout:

   ```
   --pt-file-cache-evict-after 48h
   ```

### Slow compaction

**Symptom**: Gen0 file count continues to grow.

**Possible causes**:

* Compaction budget too low for write volume
* High write rate overwhelming compaction
* Snapshot size too large, creating oversized Gen0 files

**Solutions**:

1. Increase the compaction input size budget:

   ```
   --pt-compactor-input-size-budget 12GB
   ```

2. Reduce snapshot size to create smaller, more frequent Gen0 files:

   ```
   --pt-snapshot-size 125MB
   ```

3. For distributed deployments, add a dedicated compactor node:

   ```
   influxdb3 serve \
     # ...
     --use-pacha-tree \
     --mode compact
   ```

### Query node lag

**Symptom**: Query nodes return stale data.

**Possible causes**:

* Replication falling behind
* Network latency to object storage
* Insufficient replica concurrency

**Solutions**:

For a full list of replication options, see[Replication (query nodes)](/influxdb3/enterprise/performance-preview/configure/#replication-query-nodes).

1. Increase replication concurrency:

   ```
   --pt-wal-replica-steady-concurrency 8
   ```

2. Reduce the replication polling interval:

   ```
   --pt-wal-replication-interval 100ms
   ```

3. Increase replica queue size:

   ```
   --pt-wal-replica-queue-size 200
   ```

#### Related

* [Performance upgrade preview](/influxdb3/enterprise/performance-preview/)
* [Configure the performance upgrade preview](/influxdb3/enterprise/performance-preview/configure/)
* [Query system data](/influxdb3/enterprise/admin/query-system-data/)

[storage](/influxdb3/enterprise/tags/storage/)[monitoring](/influxdb3/enterprise/tags/monitoring/)[beta](/influxdb3/enterprise/tags/beta/)[preview](/influxdb3/enterprise/tags/preview/)[system tables](/influxdb3/enterprise/tags/system-tables/)
| wal_file_id | shard_start_time | shard_duration_seconds | min_time | max_time | row_count | size_bytes | is_merged |
| --- | --- | --- | --- | --- | --- | --- | --- |
| wal_file_id | shard_start_time | shard_duration_seconds | min_time | max_time | row_count | size_bytes | is_merged |
| 1 | 2024-01-01T00:00:00Z | 86400 | 2024-01-01T00:00:00Z | 2024-01-01T00:10:00Z | 50000 | 2456789 | false |
| 2 | 2024-01-01T00:00:00Z | 86400 | 2024-01-01T00:10:00Z | 2024-01-01T00:20:00Z | 48000 | 2345678 | false |

| file_id | generation | min_time | max_time | row_count | size_bytes | has_bloom_filter |
| --- | --- | --- | --- | --- | --- | --- |
| file_id | generation | min_time | max_time | row_count | size_bytes | has_bloom_filter |
| 1 | 0 | 2024-01-01T00:00:00Z | 2024-01-01T01:00:00Z | 500000 | 45678901 | true |
| 2 | 0 | 2024-01-01T01:00:00Z | 2024-01-01T02:00:00Z | 480000 | 43567890 | true |

| Column | Description |
| --- | --- |
| Column | Description |
| plan_id | Unique job identifier |
| plan_type | Job type (for example,  L0toL1 ) |
| state | Current job state (for example,  running ,  queued ) |
| shard_id | Shard being compacted |
| total_slices | Total work units in the job |
| completed_slices | Work units completed so far |

| Column | Description |
| --- | --- |
| Column | Description |
| node_id | Ingest node identifier |
| compaction_lag | How far behind the compactor is on this node’s data |
| seen_lag | Lag between latest observed snapshot and latest compacted snapshot |
| deferred_snapshot_count | Number of snapshots deferred due to compaction failures |

| Field | Description |
| --- | --- |
| Field | Description |
| query_id | Unique identifier for the query |
| execution_time_us | Total execution time in microseconds |
| chunks | Per-chunk statistics |
| cache_stats | Cache hit rates by type |
| file_stats | File-level read statistics |

| Metric | Good | Warning | Action |
| --- | --- | --- | --- |
| Metric | Good | Warning | Action |
| Cache hit rate | >80% | <60% | Increase  --pt-file-cache-size  or  --pt-file-cache-recency |
| Rows read vs returned ratio | <100:1 | >1000:1 | Add more selective predicates |

| Metric | Healthy | Warning | Action |
| --- | --- | --- | --- |
| Metric | Healthy | Warning | Action |
| WAL file count | <50 | >100 | Increase  --pt-wal-flush-concurrency |
| Gen0 file count | <100 | >200 | Increase  --pt-compactor-input-size-budget |