content/shared/influxdb3-plugins/plugins-library/official/system-metrics.md
The System Metrics Plugin provides comprehensive system monitoring capabilities for {{% product-name %}}, collecting CPU, memory, disk, and network metrics from the host system. Monitor detailed performance insights including per-core CPU statistics, memory usage breakdowns, disk I/O performance, and network interface statistics. Features configurable metric collection with robust error handling and retry logic for reliable monitoring.
Plugin parameters may be specified as key-value pairs in the --trigger-arguments flag (CLI) or in the trigger_arguments field (API) when creating a trigger. Some plugins support TOML configuration files, which can be specified using the plugin's config_file_path parameter.
If a plugin supports multiple trigger specifications, some parameters may depend on the trigger specification that you use.
This plugin includes a JSON metadata schema in its docstring that defines supported trigger types and configuration parameters. This metadata enables the InfluxDB 3 Explorer UI to display and configure the plugin.
| Parameter | Type | Default | Description |
|---|---|---|---|
hostname | string | localhost | Hostname to tag all metrics with for system identification |
include_cpu | boolean | true | Include comprehensive CPU metrics collection (overall and per-core statistics) |
include_memory | boolean | true | Include memory metrics collection (RAM usage, swap statistics, page faults) |
include_disk | boolean | true | Include disk metrics collection (partition usage, I/O statistics, performance) |
include_network | boolean | true | Include network metrics collection (interface statistics and error counts) |
max_retries | integer | 3 | Maximum retry attempts on failure with graceful error handling |
Note: This plugin has no required parameters. All parameters have sensible defaults.
| Parameter | Type | Default | Description |
|---|---|---|---|
config_file_path | string | none | TOML config file path relative to PLUGIN_DIR (required for TOML configuration) |
To use a TOML configuration file, set the PLUGIN_DIR environment variable and specify the config_file_path in the trigger arguments. This is in addition to the --plugin-dir flag when starting {{% product-name %}}.
system_metrics_config_scheduler.toml
For more information on using TOML configuration files, see the Using TOML Configuration Files section in the influxdb3_plugins/README.md.
psutil (for system metrics collection)Start {{% product-name %}} with the Processing Engine enabled (--plugin-dir /path/to/plugins):
influxdb3 serve \
--node-id node0 \
--object-store file \
--data-dir ~/.influxdb3 \
--plugin-dir ~/.plugins
Install required Python packages:
influxdb3 install package psutil
influxdb3 create trigger \
--database system_monitoring \
--path "gh:influxdata/system_metrics/system_metrics.py" \
--trigger-spec "every:30s" \
system_metrics_trigger
influxdb3 create trigger \
--database system_monitoring \
--path "gh:influxdata/system_metrics/system_metrics.py" \
--trigger-spec "every:1m" \
--trigger-arguments config_file_path=system_metrics_config_scheduler.toml \
system_metrics_config_trigger
influxdb3 create trigger \
--database system_monitoring \
--path "gh:influxdata/system_metrics/system_metrics.py" \
--trigger-spec "every:30s" \
--trigger-arguments hostname=web-server-01,include_disk=false,max_retries=5 \
system_metrics_custom_trigger
# Create trigger for web server monitoring every 15 seconds
influxdb3 create trigger \
--database web_monitoring \
--path "gh:influxdata/system_metrics/system_metrics.py" \
--trigger-spec "every:15s" \
--trigger-arguments hostname=web-server-01,include_network=true \
web_server_metrics
# Focus on CPU and disk metrics for database server
influxdb3 create trigger \
--database db_monitoring \
--path "gh:influxdata/system_metrics/system_metrics.py" \
--trigger-spec "every:30s" \
--trigger-arguments hostname=db-primary,include_disk=true,include_cpu=true,include_network=false \
database_metrics
# Collect all metrics every 10 seconds with higher retry tolerance
influxdb3 create trigger \
--database system_monitoring \
--path "gh:influxdata/system_metrics/system_metrics.py" \
--trigger-spec "every:10s" \
--trigger-arguments hostname=critical-server,max_retries=10 \
high_freq_metrics
This plugin collects system metrics automatically. After the trigger runs, query to view the collected data:
influxdb3 query \
--database system_monitoring \
"SELECT * FROM system_cpu WHERE time >= now() - interval '5 minutes' LIMIT 5"
Expected output
+------+--------+-------+--------+------+--------+-------+--------+-------+-------+------------+------------------+ | host | cpu | user | system | idle | iowait | nice | irq | load1 | load5 | load15 | time | +------+--------+-------+--------+------+--------+-------+--------+-------+-------+------------+------------------+ | srv1 | total | 12.5 | 5.3 | 81.2 | 0.8 | 0.0 | 0.2 | 0.85 | 0.92 | 0.88 | 2024-01-15 10:00 | | srv1 | total | 13.1 | 5.5 | 80.4 | 0.7 | 0.0 | 0.3 | 0.87 | 0.93 | 0.88 | 2024-01-15 10:01 | | srv1 | total | 11.8 | 5.1 | 82.0 | 0.9 | 0.0 | 0.2 | 0.83 | 0.91 | 0.88 | 2024-01-15 10:02 | | srv1 | total | 14.2 | 5.8 | 79.0 | 0.8 | 0.0 | 0.2 | 0.89 | 0.92 | 0.88 | 2024-01-15 10:03 | | srv1 | total | 12.9 | 5.4 | 80.6 | 0.9 | 0.0 | 0.2 | 0.86 | 0.92 | 0.88 | 2024-01-15 10:04 | +------+--------+-------+--------+------+--------+-------+--------+-------+-------+------------+------------------+
process_scheduled_call()The main entry point for scheduled triggers. Collects system metrics based on configuration and writes them to InfluxDB.
def process_scheduled_call(influxdb3_local, call_time, args):
# Parse configuration
config = parse_config(args)
# Collect metrics based on configuration
if config['include_cpu']:
collect_cpu_metrics(influxdb3_local, config['hostname'])
if config['include_memory']:
collect_memory_metrics(influxdb3_local, config['hostname'])
# ... additional metric collections
Overall CPU statistics and metrics:
host, cpu=totaluser, system, idle, iowait, nice, irq, softirq, steal, guest, guest_nice, frequency_current, frequency_min, frequency_max, ctx_switches, interrupts, soft_interrupts, syscalls, load1, load5, load15Per-core CPU statistics:
host, core (core number)usage, user, system, idle, iowait, nice, irq, softirq, steal, guest, guest_nice, frequency_current, frequency_min, frequency_maxSystem memory statistics:
hosttotal, available, used, free, active, inactive, buffers, cached, shared, slab, percentSwap memory statistics:
hosttotal, used, free, percent, sin, soutMemory page fault information (when available):
hostpage_faults, major_faults, minor_faults, rss, vms, dirty, uss, pssDisk partition usage:
host, device, mountpoint, fstypetotal, used, free, percentDisk I/O statistics:
host, devicereads, writes, read_bytes, write_bytes, read_time, write_time, busy_time, read_merged_count, write_merged_countCalculated disk performance metrics:
host, deviceread_bytes_per_sec, write_bytes_per_sec, read_iops, write_iops, avg_read_latency_ms, avg_write_latency_ms, util_percentNetwork interface statistics:
host, interfacebytes_sent, bytes_recv, packets_sent, packets_recv, errin, errout, dropin, dropoutSolution: The plugin will continue collecting other metrics even if some require elevated permissions. Run InfluxDB with appropriate permissions if disk I/O metrics are required.
Solution: Install the psutil package:
influxdb3 install package psutil
Solution: Increase the trigger interval (for example, from every:10s to every:30s). Disable unnecessary metric types. Reduce the number of disk partitions monitored.
Logs are stored in the trigger's database in the system.processing_engine_logs table:
influxdb3 query \
--database YOUR_DATABASE \
"SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'system_metrics_trigger' ORDER BY event_time DESC LIMIT 10"
Check that metrics are being collected:
# List all system metric measurements
influxdb3 query \
--database system_monitoring \
"SHOW MEASUREMENTS WHERE measurement =~ /^system_/"
# Check recent CPU metrics
influxdb3 query \
--database system_monitoring \
"SELECT COUNT(*) FROM system_cpu WHERE time >= now() - interval '1 hour'"
Logs are stored in the _internal database (or the database where the trigger is created) in the system.processing_engine_logs table. To view logs:
influxdb3 query --database _internal "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'your_trigger_name'"
Log columns:
For plugin issues, see the Plugins repository issues page.
The InfluxDB Discord server is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise. For other InfluxDB versions, see the Support and feedback options.