Nezha Monitoring V2 Docs

English

简体中文

English

简体中文

Appearance

How to Enable TSDB ​

TSDB is disabled by default. The Dashboard initializes the built-in VictoriaMetrics storage only when tsdb.data_path is configured.

Scope ​

After TSDB is enabled, the server detail page can query historical metric periods such as 1 day, 7 days, and 30 days. When TSDB is disabled, the frontend locks these historical periods.

Service monitoring history still reads from the database when TSDB is disabled. After TSDB is enabled, it reads from TSDB instead.

Configuration ​

Edit the Dashboard configuration file, usually /opt/nezha/dashboard/data/config.yaml, and add or update:

yaml
tsdb:
  data_path: "data/tsdb"
  retention_days: 30
  min_free_disk_space_gb: 1
  max_memory_mb: 256
  write_buffer_size: 512
  write_buffer_flush_interval: 5

data_path can be relative or absolute. Relative paths are resolved from the Dashboard working directory. If this field is empty, TSDB is not enabled.

You can also enable it with an environment variable:

bash
NZ_TSDB_DATAPATH=data/tsdb

Restart the Dashboard after changing the configuration.

Verify ​

Check the Dashboard log after restart:

  • TSDB initialized successfully: TSDB is enabled.
  • TSDB is disabled (tsdb.data_path not configured): data_path is not configured, so TSDB is still disabled.

The frontend also reads tsdb_enabled from the system configuration API. If it is false, historical metric periods on the server detail page stay locked.

Low Disk Space ​

Dashboard handles low disk space with graceful degradation:

  • If storage becomes read-only below min_free_disk_space_gb, new metric writes are paused and discarded while existing history remains queryable. Writes resume automatically once space recovers and storage leaves read-only mode.
  • A disk-full or quota-exhaustion error during writing or flushing pauses writes until Dashboard restarts. Free disk space before restarting.
  • If disk exhaustion prevents TSDB initialization at startup, Dashboard keeps running and attempts to prepare SQLite service-history storage. TSDB is disabled for that process and tsdb_enabled is false. Free space and restart to reopen TSDB.

Look for TSDB writes paused, TSDB writes resumed, and TSDB disk is full in logs to distinguish these cases. Samples discarded during a pause are not queued for backfill, so charts may have gaps. Degradation does not migrate existing TSDB history back to SQLite, and it does not guarantee SQLite can still write when it shares the full disk.

Server online history uses separate database session records. It does not require TSDB and is not governed by TSDB metric retention.

Notes ​

After TSDB is enabled, the Dashboard drops the legacy service_histories database table. Existing service monitoring history is not automatically migrated to TSDB, so back up the database before enabling it.

TSDB uses local disk storage. Make sure the partition for data_path has enough free space, and adjust retention_days, min_free_disk_space_gb, and max_memory_mb according to your server count and retention needs.