Documentation

State change plugin

The State Change Plugin provides comprehensive field monitoring and threshold detection for InfluxDB 3 data streams. Detect field value changes, monitor threshold conditions, and trigger notifications when specified criteria are met. Supports both scheduled batch monitoring and real-time data write monitoring with configurable stability checks and multi-channel alerts.

Configuration

Scheduled trigger parameters

ParameterTypeDefaultDescription
measurementstringrequiredMeasurement to monitor for field changes
field_change_countstringrequiredDot-separated field thresholds (for example, "temp:3.load:2")
sendersstringrequiredDot-separated notification channels
windowstringrequiredTime window for analysis. Format: <number><unit>

Data write trigger parameters

ParameterTypeDefaultDescription
measurementstringrequiredMeasurement to monitor for threshold conditions
field_thresholdsstringrequiredThreshold conditions (for example, "temp:30:10@status:ok:1h")
sendersstringrequiredDot-separated notification channels

Notification parameters

ParameterTypeDefaultDescription
influxdb3_auth_tokenstringenv varInfluxDB 3 API token
notification_textstringtemplateMessage template for scheduled notifications
notification_count_textstringtemplateMessage template for count-based notifications
notification_time_textstringtemplateMessage template for time-based notifications
notification_pathstring“notify”Notification endpoint path
port_overridenumber8181InfluxDB port override

Advanced parameters

ParameterTypeDefaultDescription
state_change_windownumber1Recent values to check for stability
state_change_countnumber1Max changes allowed within stability window
config_file_pathstringnoneTOML config file path relative to PLUGIN_DIR

Channel-specific configuration

Notification channels require additional parameters based on the sender type (same as the Notifier Plugin).

Schema requirements

The plugin assumes that the table schema is already defined in the database, as it relies on this schema to retrieve field and tag names required for processing.

Requires existing schema

By design, the plugin returns an error if the schema doesn’t exist or doesn’t contain the expected columns.

TOML configuration

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

Example TOML configuration files provided:

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

Installation

  1. Start InfluxDB 3 Enterprise with the Processing Engine enabled (--plugin-dir /path/to/plugins)

  2. Install required Python packages:

    • requests (for HTTP requests)
    influxdb3 install package requests

Create scheduled trigger

Create a trigger for periodic field change monitoring:

influxdb3 create trigger \
  --database mydb \
  --plugin-filename state_change_check_plugin.py \
  --trigger-spec "every:10m" \
  --trigger-arguments "measurement=cpu,field_change_count=temp:3.load:2,window=10m,senders=slack,slack_webhook_url=https://hooks.slack.com/services/..." \
  state_change_scheduler

Create data write trigger

Create a trigger for real-time threshold monitoring:

influxdb3 create trigger \
  --database mydb \
  --plugin-filename state_change_check_plugin.py \
  --trigger-spec "all_tables" \
  --trigger-arguments "measurement=cpu,field_thresholds=temp:30:10@status:ok:1h,senders=slack,slack_webhook_url=https://hooks.slack.com/services/..." \
  state_change_datawrite

Enable triggers

influxdb3 enable trigger --database mydb state_change_scheduler
influxdb3 enable trigger --database mydb state_change_datawrite

Examples

Scheduled field change monitoring

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

influxdb3 create trigger \
  --database sensors \
  --plugin-filename 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=https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX,notification_text=Temperature sensor $field changed $changes times in $window for tags $tags" \
  temp_change_monitor

Real-time threshold detection

Monitor data writes for threshold conditions:

influxdb3 create trigger \
  --database monitoring \
  --plugin-filename 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=https://discord.com/api/webhooks/..." \
  system_threshold_monitor

Multi-condition monitoring

Monitor multiple fields with different threshold types:

influxdb3 create trigger \
  --database application \
  --plugin-filename 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=https://hooks.slack.com/services/...,twilio_from_number=+1234567890,twilio_to_number=+0987654321" \
  app_health_monitor

Features

  • Dual monitoring modes: Scheduled batch monitoring and real-time data write monitoring
  • Flexible thresholds: Support for count-based and duration-based conditions
  • Stability checks: Configurable state change detection to reduce noise
  • Multi-channel alerts: Integration with Slack, Discord, HTTP, SMS, and WhatsApp
  • Template notifications: Customizable message templates with dynamic variables
  • Caching optimization: Measurement and tag name caching for improved performance
  • Environment variable support: Credential management via environment variables

Troubleshooting

Common issues

No notifications triggered

  • Verify notification channel configuration (webhook URLs, credentials)
  • Check threshold values are appropriate for your data
  • Ensure the Notifier Plugin is installed and configured
  • Review plugin logs for error messages

Too many notifications

  • Adjust state_change_window and state_change_count for stability filtering
  • Increase threshold values to reduce sensitivity
  • Consider longer monitoring windows for scheduled triggers

Authentication errors

  • Set INFLUXDB3_AUTH_TOKEN environment variable
  • Verify token has appropriate database permissions
  • Check Twilio credentials for SMS/WhatsApp notifications

Field threshold formats

Count-based thresholds

  • Format: field_name:"value":count
  • Example: temp:"30.5":10 (10 occurrences of temperature = 30.5)

Time-based thresholds

  • Format: field_name:"value":duration
  • Example: status:"error":5min (status = error for 5 minutes)
  • Supported units: s, min, h, d, w

Multiple conditions

  • Separate with @: temp:"30":5@humidity:"high":10min

Message template variables

Scheduled notifications

  • $table: Measurement name
  • $field: Field name
  • $changes: Number of changes detected
  • $window: Time window
  • $tags: Tag values

Data write notifications

  • $table: Measurement name
  • $field: Field name
  • $value: Threshold value
  • $duration: Time duration or count
  • $row: Unique row identifier

Report an issue

For plugin issues, see the Plugins repository issues page.

Find support for InfluxDB 3 Enterprise

The InfluxDB Discord server is the best place to find support for InfluxDB 3 Enterprise. For other InfluxDB versions, see the Support and feedback options.


Was this page helpful?

Thank you for your feedback!


The future of Flux

Flux is going into maintenance mode. You can continue using it as you currently are without any changes to your code.

Read more

New in InfluxDB 3.4

Key enhancements in InfluxDB 3.4 and the InfluxDB 3 Explorer 1.2.

See the Blog Post

InfluxDB 3.4 is now available for both Core and Enterprise, which introduces offline token generation for use in automated deployments and configurable license type selection that lets you bypass the interactive license prompt. InfluxDB 3 Explorer 1.2 is also available, which includes InfluxDB cache management and other new features.

For more information, check out: