State Change

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.

Plugin metadata

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.

Required parameters

Data write trigger parameters

Notification parameters

Advanced parameters

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 InfluxDB 3.

Example TOML configuration files provided:

• state_change_config_scheduler.toml - for scheduled triggers
• state_change_config_data_writes.toml - for data write triggers

For more information on using TOML configuration files, see the Using TOML Configuration Files section in the influxdb3_plugins/README.md.

Channel-specific configuration

Notification channels require additional parameters based on the sender type (same as the influxdata/notifier plugin).

Example 1: Scheduled field change monitoring

Monitor field changes over a time window and alert when thresholds are exceeded:

# Write test data with changing values (7 writes = 6 changes)
influxdb3 write \
  --database sensors \
  "temperature,location=office value=22.5"
influxdb3 write \
  --database sensors \
  "temperature,location=office value=25.0"
influxdb3 write \
  --database sensors \
  "temperature,location=office value=22.8"
influxdb3 write \
  --database sensors \
  "temperature,location=office value=26.5"
influxdb3 write \
  --database sensors \
  "temperature,location=office value=23.0"
influxdb3 write \
  --database sensors \
  "temperature,location=office value=27.2"
influxdb3 write \
  --database sensors \
  "temperature,location=office value=24.0"

# Create and enable the trigger
influxdb3 create trigger \
  --database sensors \
  --path "gh:influxdata/state_change/state_change_check_plugin.py" \
  --trigger-spec "every:15m" \
  --trigger-arguments "measurement=temperature,field_change_count=value:5,window=1h,senders=slack,slack_webhook_url=$SLACK_WEBHOOK_URL" \
  temp_change_monitor

influxdb3 enable trigger --database sensors temp_change_monitor

Set SLACK_WEBHOOK_URL to your Slack incoming webhook URL.

Expected output

When the field changes more than 5 times within 1 hour, a notification is sent: “Temperature sensor value changed 6 times in 1h for tags location=office”

Example 2: Advanced scheduled field change monitoring

Monitor field changes over a time window and alert when thresholds are exceeded:

influxdb3 create trigger \
  --database sensors \
  --path "gh:influxdata/state_change/state_change_check_plugin.py" \
  --trigger-spec "every:15m" \
  --trigger-arguments "measurement=temperature,field_change_count=value:5,window=1h,senders=slack,slack_webhook_url=$SLACK_WEBHOOK_URL,notification_text=Temperature sensor $field changed $changes times in $window for tags $tags" \
  temp_change_monitor

Set SLACK_WEBHOOK_URL to your Slack incoming webhook URL.

Real-time threshold detection

Monitor data writes for threshold conditions:

influxdb3 create trigger \
  --database monitoring \
  --path "gh:influxdata/state_change/state_change_check_plugin.py" \
  --trigger-spec "all_tables" \
  --trigger-arguments "measurement=system_metrics,field_thresholds=cpu_usage:80:5@memory_usage:90:10min,senders=discord,discord_webhook_url=$DISCORD_WEBHOOK_URL" \
  system_threshold_monitor

Set DISCORD_WEBHOOK_URL to your Discord incoming webhook URL.

Multi-condition monitoring

Monitor multiple fields with different threshold types:

influxdb3 create trigger \
  --database application \
  --path "gh:influxdata/state_change/state_change_check_plugin.py" \
  --trigger-spec "all_tables" \
  --trigger-arguments "measurement=app_health,field_thresholds=error_rate:0.05:3@response_time:500:30s@status:down:1,senders=slack.sms,slack_webhook_url=$SLACK_WEBHOOK_URL,twilio_from_number=+1234567890,twilio_to_number=+0987654321" \
  app_health_monitor

Set SLACK_WEBHOOK_URL to your Slack incoming webhook URL.