Skip to main content
Version: Nightly

Maintenance events

Metasrv records GC and Remote WAL pruning events in distributed deployments. Standalone and Metasrv both record table reconciliation events.

GC events​

Each row with a non-NULL gc_report records the files processed for one Region:

SELECT timestamp, procedure_id, procedure_state,
region_id, table_id, region_number,
json_to_string(gc_report) AS gc_report
FROM greptime_private.events
WHERE type = 'batch_gc'
AND gc_report IS NOT NULL
AND timestamp >= now() - INTERVAL '1' hour
ORDER BY timestamp DESC
LIMIT 3;

deleted_files lists deleted SST/Parquet file IDs. deleted_indexes lists deleted index file IDs and their index_version. need_retry is true when the Region needs another GC run.

For example:

{
"deleted_files": ["580653aa-252b-415b-aaf9-ce65e9d78249"],
"deleted_indexes": [
{"file_id":"580653aa-252b-415b-aaf9-ce65e9d78249","index_version":0}
],
"need_retry": false
}

Scheduled GC does not emit a Submitted row. A manual Submitted row contains the configuration. If no Region needs cleanup or retry, no Done row is written. payload is JSON null on a report row.

Remote WAL pruning​

SELECT timestamp, type, topic_name, prunable_entry_id, latest_offset,
procedure_state,
json_get_string(procedure_trigger, 'type') AS trigger_type,
json_to_string(payload) AS payload
FROM greptime_private.events
WHERE type = 'wal_prune'
AND timestamp >= now() - INTERVAL '1' hour
ORDER BY timestamp DESC
LIMIT 3;
+-------------------------------+-----------+-------------------------+-------------------+---------------+-----------------+--------------+--------------------------------------+
| timestamp | type | topic_name | prunable_entry_id | latest_offset | procedure_state | trigger_type | payload |
+-------------------------------+-----------+-------------------------+-------------------+---------------+-----------------+--------------+--------------------------------------+
| 2026-08-10 11:23:28.495676149 | wal_prune | greptimedb_wal_topic_20 | 248376 | 248381 | Done | Succeeded | {"logical_delete":false,"version":1} |
| 2026-08-10 10:53:28.478381545 | wal_prune | greptimedb_wal_topic_20 | 248375 | 248376 | Done | Succeeded | {"logical_delete":false,"version":1} |
| 2026-08-10 10:23:28.486761751 | wal_prune | greptimedb_wal_topic_20 | 248371 | 248375 | Done | Succeeded | {"logical_delete":false,"version":1} |
+-------------------------------+-----------+-------------------------+-------------------+---------------+-----------------+--------------+--------------------------------------+

prunable_entry_id is the pruning boundary for topic_name. It is the smallest boundary reported by Regions that use the topic, so none of those Regions needs entries before it. On a non-Succeeded row, it is only the attempted boundary.

When present, latest_offset is the Kafka latest offset observed during this attempt. It is an exclusive upper bound: the offset after the last record, not the offset of the last record.

The recorder omits Submitted and Recovered rows. A successful run writes Done; Retrying is not terminal, and a run can also write Failed or Poisoned.

Table reconciliation​

Table reconciliation records one event type for each scope:

Event typeRecorded forPopulated locator columns
reconcile_catalogADMIN reconcile_catalog()catalog_name
reconcile_databaseA databasecatalog_name, schema_name
reconcile_tableA physical tablecatalog_name, schema_name, table_name, table_id
reconcile_logical_tablesThe logical tables of one physical table, one row per logical tablecatalog_name, schema_name, table_name, table_id, physical_table_id

Reconciling a catalog starts a child procedure for each database, which in turn starts child procedures for its tables. Each child procedure records its own events.

SELECT timestamp, type, schema_name, table_name, procedure_id, procedure_state,
json_get_string(procedure_trigger, 'type') AS trigger_type,
json_to_string(payload) AS payload
FROM greptime_private.events
WHERE type IN ('reconcile_catalog', 'reconcile_database',
'reconcile_table', 'reconcile_logical_tables')
AND timestamp >= now() - INTERVAL '1' hour
ORDER BY timestamp;

The Submitted row records the request, and the terminal row records the result. payload is JSON null on other rows. Both payloads contain version.

Event typeSubmitted payloadTerminal payload
reconcile_catalogresolve_strategy, fail_fast, parallelismcomplete, processed_database_count, succeeded_database_count, failed_database_count
reconcile_databaseresolve_strategy, fail_fast, parallelism, is_subprocedurecomplete, processed_table_count, succeeded_table_count, failed_table_count, succeeded_subprocedure_count, failed_subprocedure_count
reconcile_tableresolve_strategy, is_subprocedurecomplete, metadata_state, resolution_strategy_applied, resolved_column_count, scanned_region_count, updated_region_count, table_info_updated, last_completed_phase
reconcile_logical_tableslogical_table_count, is_subprocedurecomplete, processed_table_count, metadata_consistent_table_count, metadata_inconsistent_table_count, create_table_count, update_table_info_count
  • resolve_strategy is use_latest, use_metasrv, or abort_on_conflict.
  • is_subprocedure is true when a parent reconciliation started the procedure.
  • complete is true only when the procedure succeeded.
  • metadata_state is consistent or inconsistent.
  • last_completed_phase is start, resolve_column_metadata, reconcile_regions, or update_table_info.
  • metadata_state, resolution_strategy_applied, resolved_column_count, and last_completed_phase are JSON null until the task reaches the step that sets them, for example when it fails early.
  • For reconcile_logical_tables, processed_table_count is the number of logical tables in the request, including tables whose reconciliation did not finish. create_table_count is the number of tables identified for creation.

The terminal payload is a best-effort summary, not a complete execution history. It is kept in memory and reset when a procedure recovers after a restart, so a recovered task can succeed with zero counts and null state and phase fields. Use procedure_state to decide whether a task succeeded.