* fix(influxdb3): Mark disabled field as required in processing engine trigger API specs
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
* Add HTTP API examples to Processing Engine plugin documentation (#6789)
- Add disabled field and api-ref to API examples per review feedback
- Add api-ref to upload plugin endpoint and remove duplicate link sentence
- Convert {{% code-placeholders %}} shortcode to placeholders code block
attribute for cleaner syntax
- Add second argument to token-link shortcodes for admin tokens to
ensure consistent linking to /admin/tokens/admin/ path
- Follows PR 6789 review feedback for processing engine documentation
fix(influxdb3): update placeholder and token-link syntax in get-started
- Convert code-placeholders wrapper shortcodes to code block attributes
* fix(influxdb3): Fix broken trigger anchor links in plugin documentation
Rename "Set up a trigger" heading to "Create a trigger" and update
all internal anchor references to match.
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jstirnaman <212227+jstirnaman@users.noreply.github.com>
Co-authored-by: Jason Stirnaman <jstirnaman@influxdata.com>
> If you manually installed {{% product-name %}} from a tar archive, ensure the `influxdb3` binary and `python/` directory remain in the same parent directory. The install script handles this automatically.
- {{% code-placeholder-key %}}`INPUT_LINE_PROTOCOL`{{% /code-placeholder-key %}}: the line protocol to test
- Optional: {{% code-placeholder-key %}}`INPUT_ARGS`{{% /code-placeholder-key %}}: a comma-delimited list of `<KEY>=<VALUE>` arguments for your plugin code--for example, `arg1=hello,arg2=world`
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to test against
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: the {{% token-link "admin" %}} for your {{% product-name %}} server
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link %}} for your {{% product-name %}} server
- {{% code-placeholder-key %}}`PLUGIN_FILENAME`{{% /code-placeholder-key %}}: the name of the plugin file to test. Provide only the filename (for example, `test.py`), not a relative or absolute path.
### Example: Test a plugin
@ -252,19 +248,17 @@ influxdb3 create trigger \
After you have created a plugin and trigger, enter the following command to
enable the trigger and have it run the plugin as you write data:
- [Create a trigger](#use-the-create-trigger-command) to connect your plugin to database events
- [Create a trigger](#create-a-trigger) to connect your plugin to database events
- [Install any Python dependencies](#manage-plugin-dependencies) your plugin requires
- Learn how to [extend plugins with the API](/influxdb3/version/extend-plugin/)
@ -363,6 +359,11 @@ After writing your plugin:
For local development and testing, you can upload plugin files directly from your machine when creating triggers. This eliminates the need to manually copy files to the server's plugin directory.
- [Upload a plugin using the influxdb3 CLI](#upload-a-plugin-using-the-influxdb3-cli)
- [Upload a plugin using the HTTP API](#upload-a-plugin-using-the-http-api)
#### Upload a plugin using the influxdb3 CLI
Use the `--upload` flag with `--path` to transfer local files or directories:
```bash
@ -383,6 +384,32 @@ influxdb3 create trigger \
complex_trigger
```
For more information, see the [`influxdb3 create trigger` CLI reference](/influxdb3/version/reference/cli/influxdb3/create/trigger/).
#### Upload a plugin using the HTTP API
To upload a plugin file using the HTTP API, send a `PUT` request to the `/api/v3/plugins/files` endpoint:
For more information, see the [`influxdb3 create trigger` CLI reference](/influxdb3/version/reference/cli/influxdb3/create/trigger/).
### Update existing plugins
Modify plugin code for running triggers without recreating them. This allows you to iterate on plugin development while preserving trigger configuration and history.
- [Update a plugin using the influxdb3 CLI](#update-a-plugin-using-the-influxdb3-cli)
- [Update a plugin using the HTTP API](#update-a-plugin-using-the-http-api)
#### Update a plugin using the influxdb3 CLI
Use the `influxdb3 update trigger` command:
```bash
@ -416,14 +446,38 @@ influxdb3 update trigger \
--path "/path/to/updated/plugin-dir"
```
The update operation:
For complete reference, see [`influxdb3 update trigger`](/influxdb3/version/reference/cli/influxdb3/update/trigger/).
#### Update a plugin using the HTTP API
To update a plugin file using the HTTP API, send a `PUT` request to the `/api/v3/plugins/files` endpoint:
For complete reference, see [`influxdb3 update trigger`](/influxdb3/version/reference/cli/influxdb3/update/trigger/).
### View loaded plugins
Monitor which plugins are loaded in your system for operational visibility and troubleshooting.
@ -475,7 +529,14 @@ ORDER BY last_modified DESC;
For more information, see the [`influxdb3 show plugins` reference](/influxdb3/version/reference/cli/influxdb3/show/plugins/) and [Query system data](/influxdb3/version/admin/query-system-data/#query-plugin-files).
## Set up a trigger
## Create a trigger
A trigger connects your plugin code to database events. When the specified event occurs, the processing engine executes your plugin.
curl -X POST "{{<influxdb/host>}}/api/v3/configure/processing_engine_trigger" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"db": "DATABASE_NAME",
"trigger_name": "TRIGGER_NAME",
"plugin_filename": "PLUGIN_FILE",
"trigger_specification": "TRIGGER_SPEC",
"trigger_settings": {
"run_async": false,
"error_behavior": "Log"
},
"disabled": false
}'
```
In the example above, replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: Name of the database
- {{% code-placeholder-key %}}`TRIGGER_NAME`{{% /code-placeholder-key %}}: Name of the new trigger
- {{% code-placeholder-key %}}`PLUGIN_FILE`{{% /code-placeholder-key %}}: Plugin filename relative to your configured plugin directory
- {{% code-placeholder-key %}}`TRIGGER_SPEC`{{% /code-placeholder-key %}}: Trigger specification (see [examples](#trigger-specification-examples))
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with write permissions on the specified database{{% /show-in %}}
### Trigger specification examples
The following examples demonstrate how to create triggers for different event types.
#### Trigger on data writes
{{<code-tabs-wrapper>}}
{{% code-tabs %}}
[influxdb3 CLI](#)
[HTTP API](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
```bash
# Trigger on writes to a specific table
# The plugin file must be in your configured plugin directory
@ -539,6 +655,51 @@ influxdb3 create trigger \
all_data_processor
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```bash {placeholders="DATABASE_NAME|AUTH_TOKEN"}
# Trigger on writes to a specific table
curl -X POST "{{<influxdb/host>}}/api/v3/configure/processing_engine_trigger" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"db": "DATABASE_NAME",
"trigger_name": "sensor_processor",
"plugin_filename": "process_sensors.py",
"trigger_specification": "table:sensor_data",
"trigger_settings": {
"run_async": false,
"error_behavior": "Log"
},
"disabled": false
}'
# Trigger on writes to all tables
curl -X POST "{{<influxdb/host>}}/api/v3/configure/processing_engine_trigger" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"db": "DATABASE_NAME",
"trigger_name": "all_data_processor",
"plugin_filename": "process_all_data.py",
"trigger_specification": "all_tables",
"trigger_settings": {
"run_async": false,
"error_behavior": "Log"
},
"disabled": false
}'
```
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with write permissions on the specified database{{% /show-in %}}
{{% /code-tab-content %}}
{{</code-tabs-wrapper>}}
The trigger runs when the database flushes ingested data for the specified tables to the Write-Ahead Log (WAL) in the Object store (default is every second).
The plugin receives the written data and table information.
@ -548,8 +709,7 @@ The plugin receives the written data and table information.
If you want to use a single trigger for all tables but exclude specific tables,
you can use trigger arguments and your plugin code to filter out unwanted tables--for example:
curl -X POST "{{<influxdb/host>}}/api/v3/configure/processing_engine_trigger" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"db": "DATABASE_NAME",
"trigger_name": "regular_check",
"plugin_filename": "periodic_check.py",
"trigger_specification": "every:5m",
"trigger_settings": {
"run_async": false,
"error_behavior": "Log"
},
"disabled": false
}'
# Run on a cron schedule (8am daily)
# Supports extended cron format with seconds
curl -X POST "{{<influxdb/host>}}/api/v3/configure/processing_engine_trigger" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"db": "DATABASE_NAME",
"trigger_name": "daily_report",
"plugin_filename": "daily_report.py",
"trigger_specification": "cron:0 0 8 * * *",
"trigger_settings": {
"run_async": false,
"error_behavior": "Log"
},
"disabled": false
}'
```
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with write permissions on the specified database{{% /show-in %}}
{{% /code-tab-content %}}
{{</code-tabs-wrapper>}}
The plugin receives the scheduled call time.
#### Trigger on HTTP requests
{{<code-tabs-wrapper>}}
{{% code-tabs %}}
[influxdb3 CLI](#)
[HTTP API](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
```bash
# Create an endpoint at /api/v3/engine/webhook
influxdb3 create trigger \
@ -622,6 +841,35 @@ influxdb3 create trigger \
webhook_processor
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```bash {placeholders="DATABASE_NAME|AUTH_TOKEN"}
# Create an endpoint at /api/v3/engine/webhook
curl -X POST "{{<influxdb/host>}}/api/v3/configure/processing_engine_trigger" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"db": "DATABASE_NAME",
"trigger_name": "webhook_processor",
"plugin_filename": "webhook_handler.py",
"trigger_specification": "request:webhook",
"trigger_settings": {
"run_async": false,
"error_behavior": "Log"
},
"disabled": false
}'
```
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with write permissions on the specified database{{% /show-in %}}
{{% /code-tab-content %}}
{{</code-tabs-wrapper>}}
Access your endpoint at `/api/v3/engine/{REQUEST_PATH}` (in this example, `/api/v3/engine/webhook`).
The trigger is enabled by default and runs when an HTTP request is received at the specified path.
@ -647,6 +895,13 @@ Use trigger arguments to pass configuration from a trigger to the plugin it runs
- Connection properties for external services
- Configuration settings for plugin behavior
{{<code-tabs-wrapper>}}
{{% code-tabs %}}
[influxdb3 CLI](#)
[HTTP API](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
```bash
influxdb3 create trigger \
--trigger-spec "every:1h" \
@ -656,6 +911,38 @@ influxdb3 create trigger \
threshold_monitor
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```bash {placeholders="DATABASE_NAME|AUTH_TOKEN"}
curl -X POST "{{<influxdb/host>}}/api/v3/configure/processing_engine_trigger" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"db": "DATABASE_NAME",
"trigger_name": "threshold_monitor",
"plugin_filename": "threshold_check.py",
"trigger_specification": "every:1h",
"trigger_settings": {
"run_async": false,
"error_behavior": "Log"
},
"trigger_arguments": {
"threshold": "90",
"notify_email": "admin@example.com"
},
"disabled": false
}'
```
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with write permissions on the specified database{{% /show-in %}}
{{% /code-tab-content %}}
{{</code-tabs-wrapper>}}
The arguments are passed to the plugin as a `Dict[str, str]` where the key is the argument name and the value is the argument value:
```python
@ -674,6 +961,13 @@ By default, triggers run synchronously—each instance waits for previous instan
To allow multiple instances of the same trigger to run simultaneously, configure triggers to run asynchronously:
{{<code-tabs-wrapper>}}
{{% code-tabs %}}
[influxdb3 CLI](#)
[HTTP API](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
```bash
# Allow multiple trigger instances to run simultaneously
influxdb3 create trigger \
@ -684,13 +978,49 @@ influxdb3 create trigger \
async_processor
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```bash {placeholders="DATABASE_NAME|AUTH_TOKEN"}
# Allow multiple trigger instances to run simultaneously
curl -X POST "{{<influxdb/host>}}/api/v3/configure/processing_engine_trigger" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"db": "DATABASE_NAME",
"trigger_name": "async_processor",
"plugin_filename": "heavy_process.py",
"trigger_specification": "table:metrics",
"trigger_settings": {
"run_async": true,
"error_behavior": "Log"
},
"disabled": false
}'
```
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with write permissions on the specified database{{% /show-in %}}
{{% /code-tab-content %}}
{{</code-tabs-wrapper>}}
### Configure error handling for a trigger
To configure error handling behavior for a trigger, use the `--error-behavior <ERROR_BEHAVIOR>` CLI option with one of the following values:
To configure error handling behavior for a trigger, specify one of the following values:
- `log` (default): Log all plugin errors to stdout and the `system.processing_engine_logs` table in the trigger's database.
- `retry`: Attempt to run the plugin again immediately after an error.
- `disable`: Automatically disable the plugin when an error occurs (can be re-enabled later via CLI).
- `disable`: Automatically disable the plugin when an error occurs (can be re-enabled later).
{{<code-tabs-wrapper>}}
{{% code-tabs %}}
[influxdb3 CLI](#)
[HTTP API](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
For more information, see how to [Query trigger logs](/influxdb3/version/admin/query-system-data/#query-trigger-logs).
@ -712,6 +1042,51 @@ influxdb3 create trigger \
auto_disable_processor
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
```bash {placeholders="DATABASE_NAME|AUTH_TOKEN"}
# Automatically retry on error
curl -X POST "{{<influxdb/host>}}/api/v3/configure/processing_engine_trigger" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"db": "DATABASE_NAME",
"trigger_name": "critical_processor",
"plugin_filename": "critical_process.py",
"trigger_specification": "table:important_data",
"trigger_settings": {
"run_async": false,
"error_behavior": "Retry"
},
"disabled": false
}'
# Disable the trigger on error
curl -X POST "{{<influxdb/host>}}/api/v3/configure/processing_engine_trigger" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"db": "DATABASE_NAME",
"trigger_name": "auto_disable_processor",
"plugin_filename": "webhook_handler.py",
"trigger_specification": "request:webhook",
"trigger_settings": {
"run_async": false,
"error_behavior": "Disable"
},
"disabled": false
}'
```
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "database" %}}{{% show-in "enterprise" %}} with write permissions on the specified database{{% /show-in %}}
{{% /code-tab-content %}}
{{</code-tabs-wrapper>}}
## Manage plugin dependencies
@ -719,13 +1094,12 @@ influxdb3 create trigger \
Use the `influxdb3 install package` command to add third-party libraries (like `pandas`, `requests`, or `influxdb3-python`) to your plugin environment.
This installs packages into the Processing Engine’s embedded Python environment to ensure compatibility with your InfluxDB instance.
Copilot
GitHub