diff --git a/api-docs/influxdb3/core/v3/ref.yml b/api-docs/influxdb3/core/v3/ref.yml index 7615dbf322..32778f807e 100644 --- a/api-docs/influxdb3/core/v3/ref.yml +++ b/api-docs/influxdb3/core/v3/ref.yml @@ -1368,6 +1368,7 @@ paths: plugin_filename: schedule.py trigger_name: schedule_cron_trigger trigger_specification: cron:0 0 6 * * 1-5 + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1381,6 +1382,7 @@ paths: plugin_filename: schedule.py trigger_name: schedule_every_trigger trigger_specification: every:1h + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1393,6 +1395,7 @@ paths: plugin_filename: schedule.py trigger_name: schedule_every_30s_trigger trigger_specification: every:30s + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1405,6 +1408,7 @@ paths: plugin_filename: schedule.py trigger_name: schedule_every_5m_trigger trigger_specification: every:5m + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1417,6 +1421,7 @@ paths: plugin_filename: all_tables.py trigger_name: all_tables_trigger trigger_specification: all_tables + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1429,6 +1434,7 @@ paths: plugin_filename: table.py trigger_name: table_trigger trigger_specification: table:sensors + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1441,6 +1447,7 @@ paths: plugin_filename: request.py trigger_name: hello_world_trigger trigger_specification: request:hello-world + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1453,6 +1460,7 @@ paths: plugin_filename: weekly_report.py trigger_name: friday_report_trigger trigger_specification: cron:0 30 14 * * 5 + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1465,6 +1473,7 @@ paths: plugin_filename: monthly_cleanup.py trigger_name: monthly_cleanup_trigger trigger_specification: cron:0 0 0 1 * * + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -2383,6 +2392,7 @@ components: - trigger_name - trigger_settings - trigger_specification + - disabled TriggerSettings: type: object description: | diff --git a/api-docs/influxdb3/enterprise/v3/ref.yml b/api-docs/influxdb3/enterprise/v3/ref.yml index 7b417824c3..c0f44d3748 100644 --- a/api-docs/influxdb3/enterprise/v3/ref.yml +++ b/api-docs/influxdb3/enterprise/v3/ref.yml @@ -1455,6 +1455,7 @@ paths: plugin_filename: schedule.py trigger_name: schedule_cron_trigger trigger_specification: cron:0 0 6 * * 1-5 + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1468,6 +1469,7 @@ paths: plugin_filename: schedule.py trigger_name: schedule_every_trigger trigger_specification: every:1h + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1480,6 +1482,7 @@ paths: plugin_filename: schedule.py trigger_name: schedule_every_30s_trigger trigger_specification: every:30s + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1492,6 +1495,7 @@ paths: plugin_filename: schedule.py trigger_name: schedule_every_5m_trigger trigger_specification: every:5m + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1504,6 +1508,7 @@ paths: plugin_filename: all_tables.py trigger_name: all_tables_trigger trigger_specification: all_tables + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1516,6 +1521,7 @@ paths: plugin_filename: table.py trigger_name: table_trigger trigger_specification: table:sensors + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1528,6 +1534,7 @@ paths: plugin_filename: request.py trigger_name: hello_world_trigger trigger_specification: request:hello-world + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1540,6 +1547,7 @@ paths: plugin_filename: weekly_report.py trigger_name: friday_report_trigger trigger_specification: cron:0 30 14 * * 5 + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -1552,6 +1560,7 @@ paths: plugin_filename: monthly_cleanup.py trigger_name: monthly_cleanup_trigger trigger_specification: cron:0 0 0 1 * * + disabled: false trigger_settings: run_async: false error_behavior: Log @@ -2571,6 +2580,7 @@ components: - trigger_name - trigger_settings - trigger_specification + - disabled TriggerSettings: type: object description: | diff --git a/content/influxdb3/core/plugins/_index.md b/content/influxdb3/core/plugins/_index.md index 8da5b8dc6d..0bf462e50d 100644 --- a/content/influxdb3/core/plugins/_index.md +++ b/content/influxdb3/core/plugins/_index.md @@ -16,4 +16,4 @@ source: /shared/influxdb3-plugins/_index.md \ No newline at end of file +--> diff --git a/content/shared/influxdb3-get-started/processing-engine.md b/content/shared/influxdb3-get-started/processing-engine.md index 775be9a576..1a727cc18c 100644 --- a/content/shared/influxdb3-get-started/processing-engine.md +++ b/content/shared/influxdb3-get-started/processing-engine.md @@ -62,14 +62,12 @@ the processing engine to run. > [!Note] > 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-placeholders "PLUGIN_DIR" %}} -```bash +```bash {placeholders="PLUGIN_DIR"} influxdb3 serve \ # ... --plugin-dir PLUGIN_DIR ``` -{{% /code-placeholders %}} Replace {{% code-placeholder-key %}}`PLUGIN_DIR`{{% /code-placeholder-key %}} with the path to your plugin directory. This path can be absolute or relative @@ -170,8 +168,7 @@ To test a `process_writes` (WAL) plugin: - `--lp` or `--file`: The line protocol to test - Optional: `--input-arguments`: A comma-delimited list of `=` arguments for your plugin code -{{% code-placeholders "INPUT_LINE_PROTOCOL|INPUT_ARGS|DATABASE_NAME|AUTH_TOKEN|PLUGIN_FILENAME" %}} -```bash +```bash {placeholders="INPUT_LINE_PROTOCOL|INPUT_ARGS|DATABASE_NAME|AUTH_TOKEN|PLUGIN_FILENAME"} influxdb3 test wal_plugin \ --database DATABASE_NAME \ --token AUTH_TOKEN \ @@ -179,14 +176,13 @@ influxdb3 test wal_plugin \ --input-arguments INPUT_ARGS \ PLUGIN_FILENAME ``` -{{% /code-placeholders %}} Replace the following: - {{% 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 `=` 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: -{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN|TRIGGER_NAME" %}} -```bash +```bash {placeholders="DATABASE_NAME|AUTH_TOKEN|TRIGGER_NAME"} influxdb3 enable trigger \ --token AUTH_TOKEN \ --database DATABASE_NAME \ TRIGGER_NAME ``` -{{% /code-placeholders %}} Replace the following placeholders with your values: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to enable the trigger in -- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link %}} - {{% code-placeholder-key %}}`TRIGGER_NAME`{{% /code-placeholder-key %}}: the name of the trigger to enable For example, to enable the trigger named `trigger1` in the `sensors` database: diff --git a/content/shared/influxdb3-plugins/_index.md b/content/shared/influxdb3-plugins/_index.md index 7624e843f7..2546cf3676 100644 --- a/content/shared/influxdb3-plugins/_index.md +++ b/content/shared/influxdb3-plugins/_index.md @@ -27,7 +27,7 @@ Once you have all the prerequisites in place, follow these steps to implement th - [Upload plugins from local machine](#upload-plugins-from-local-machine) - [Update existing plugins](#update-existing-plugins) - [View loaded plugins](#view-loaded-plugins) -- [Set up a trigger](#set-up-a-trigger) +- [Create a trigger](#create-a-trigger) - [Manage plugin dependencies](#manage-plugin-dependencies) - [Plugin security](#plugin-security) {{% show-in "enterprise" %}} @@ -51,17 +51,13 @@ To activate the Processing Engine, start your {{% product-name %}} server with t > > Add the parent directory to your PATH; do not move the binary out of this directory. -{{% code-placeholders "NODE_ID|OBJECT_STORE_TYPE|PLUGIN_DIR" %}} - -```bash +```bash {placeholders="NODE_ID|OBJECT_STORE_TYPE|PLUGIN_DIR"} influxdb3 serve \ --NODE_ID \ --object-store OBJECT_STORE_TYPE \ --plugin-dir PLUGIN_DIR ``` -{{% /code-placeholders %}} - In the example above, replace the following: - {{% code-placeholder-key %}}`NODE_ID`{{% /code-placeholder-key %}}: Unique identifier for your instance @@ -277,7 +273,7 @@ def process_data(influxdb3_local, table_batch, settings): pass ``` -After writing your plugin, [create a trigger](#use-the-create-trigger-command) to connect it to a database event and define when it runs. +After writing your plugin, [create a trigger](#create-a-trigger) to connect it to a database event and define when it runs. #### Create a data write plugin @@ -355,7 +351,7 @@ def process_request(influxdb3_local, query_parameters, request_headers, request_ After writing your plugin: -- [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: + +{{% api-endpoint method="PUT" endpoint="{{< influxdb/host >}}/api/v3/plugins/files" api-ref="/influxdb3/version/api/v3/#operation/PutPluginFile" %}} + +Include the following in your request: + +- **Headers**: + - `Authorization: Bearer` with your admin token + - `Content-Type: application/octet-stream` +- **Query parameters**: + - `path` _(string, required)_: Path to the plugin file relative to the plugin directory + +```bash{placeholders="AUTH_TOKEN"} +# Upload a single-file plugin +curl -X PUT "{{< influxdb/host >}}/api/v3/plugins/files?path=plugin.py" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --header "Content-Type: application/octet-stream" \ + --data-binary "@/local/path/to/plugin.py" +``` + +Replace {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" "admin" %}} + > [!Important] > #### Admin privileges required > @@ -394,12 +421,15 @@ influxdb3 create trigger \ - Rapid iteration on plugin code - Automating plugin deployment in CI/CD pipelines -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: + +{{% api-endpoint method="PUT" endpoint="{{< influxdb/host >}}/api/v3/plugins/files" api-ref="/influxdb3/version/api/v3/#operation/PutPluginFile" %}} + +Include the following in your request: + +- **Headers**: + - `Authorization: Bearer` with your admin token + - `Content-Type: application/octet-stream` +- **Query parameters**: + - `path` _(string, required)_: Path to the plugin file relative to the plugin directory + +```bash{placeholders="AUTH_TOKEN"} +# Update a plugin file +curl -X PUT "{{< influxdb/host >}}/api/v3/plugins/files?path=plugin.py" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --header "Content-Type: application/octet-stream" \ + --data-binary "@/path/to/updated/plugin.py" +``` + +Replace {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" "admin" %}} + +**The update operation:** - Replaces plugin files immediately - Preserves trigger configuration (spec, schedule, arguments) - Requires admin token for security - Works with both local paths and uploaded files -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. + +- [Understand trigger types](#understand-trigger-types) +- [Create a trigger using the influxdb3 CLI](#create-a-trigger-using-the-influxdb3-cli) +- [Create a trigger using the HTTP API](#create-a-trigger-using-the-http-api) +- [Trigger specification examples](#trigger-specification-examples) ### Understand trigger types @@ -485,13 +546,11 @@ For more information, see the [`influxdb3 show plugins` reference](/influxdb3/ve | Scheduled | `every:` or `cron:` | At specified time intervals | | HTTP request | `request:` | When HTTP requests are received | -### Use the create trigger command +### Create a trigger using the influxdb3 CLI Use the `influxdb3 create trigger` command with the appropriate trigger specification: -{{% code-placeholders "SPECIFICATION|PLUGIN_FILE|DATABASE_NAME|TRIGGER_NAME" %}} - -```bash +```bash {placeholders="SPECIFICATION|PLUGIN_FILE|DATABASE_NAME|TRIGGER_NAME"} influxdb3 create trigger \ --trigger-spec SPECIFICATION \ --path PLUGIN_FILE \ @@ -499,8 +558,6 @@ influxdb3 create trigger \ TRIGGER_NAME ``` -{{% /code-placeholders %}} - In the example above, replace the following: - {{% code-placeholder-key %}}`SPECIFICATION`{{% /code-placeholder-key %}}: Trigger specification @@ -517,11 +574,70 @@ In the example above, replace the following: > When not using `--upload`, the server resolves paths relative to the configured `--plugin-dir`. > For details about multi-file plugin structure, see [Create your plugin file](#create-your-plugin-file). +For complete reference, see [`influxdb3 create trigger`](/influxdb3/version/reference/cli/influxdb3/create/trigger/). + +### Create a trigger using the HTTP API + +To create a trigger using the HTTP API, send a `POST` request to the `/api/v3/configure/processing_engine_trigger` endpoint: + +{{% api-endpoint method="POST" endpoint="{{< influxdb/host >}}/api/v3/configure/processing_engine_trigger" api-ref="/influxdb3/version/api/v3/#operation/PostConfigureProcessingEngineTrigger" %}} + +Include the following in your request: + +- **Headers**: + - `Authorization: Bearer` with your authentication token + - `Content-Type: application/json` +- **Request body**: JSON object with trigger configuration + - `db` _(string, required)_: Database name + - `trigger_name` _(string, required)_: Trigger name + - `plugin_filename` _(string, required)_: Plugin filename relative to the plugin directory + - `trigger_specification` _(string, required)_: When the plugin runs (see [trigger types](#understand-trigger-types)) + - `trigger_settings` _(object, required)_: Configuration for error handling and execution + - `run_async` _(boolean)_: Whether to run asynchronously (default: `false`) + - `error_behavior` _(string)_: How to handle errors: `Log`, `Retry`, or `Disable` (default: `Log`) + - `disabled` _(boolean, required)_: Whether the trigger is disabled + - `trigger_arguments` _(object, optional)_: Arguments passed to the plugin + +```bash {placeholders="DATABASE_NAME|PLUGIN_FILE|TRIGGER_NAME|TRIGGER_SPEC|AUTH_TOKEN"} +# Create a basic trigger +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: -{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} -```bash +```bash {placeholders="DATABASE_NAME|AUTH_TOKEN"} influxdb3 create trigger \ --database DATABASE_NAME \ --token AUTH_TOKEN \ @@ -558,7 +718,6 @@ influxdb3 create trigger \ --trigger-arguments "exclude_tables=temp_data,debug_info,system_logs" \ data_processor ``` -{{% /code-placeholders %}} Replace the following: @@ -592,6 +751,13 @@ def on_write(self, database, table_name, batch): #### Trigger on a schedule +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[influxdb3 CLI](#) +[HTTP API](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + ```bash # Run every 5 minutes influxdb3 create trigger \ @@ -609,10 +775,63 @@ influxdb3 create trigger \ daily_report ``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```bash {placeholders="DATABASE_NAME|AUTH_TOKEN"} +# Run every 5 minutes +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 ` 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. -{{% code-placeholders "CONTAINER_NAME|PACKAGE_NAME" %}} - {{< code-tabs-wrapper >}} {{% code-tabs %}} -[CLI](#) +[influxdb3 CLI](#) [Docker](#) +[HTTP API](#) {{% /code-tabs %}} {{% code-tab-content %}} @@ -740,30 +1114,47 @@ influxdb3 install package pandas {{% code-tab-content %}} -```bash +```bash {placeholders="CONTAINER_NAME"} # Use the CLI to install a Python package in a Docker container docker exec -it CONTAINER_NAME influxdb3 install package pandas ``` {{% /code-tab-content %}} +{{% code-tab-content %}} + +```bash {placeholders="AUTH_TOKEN"} +# Use the HTTP API to install Python packages +curl -X POST "{{< influxdb/host >}}/api/v3/configure/plugin_environment/install_packages" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --header "Content-Type: application/json" \ + --data '{ + "packages": ["pandas", "requests", "numpy"] + }' +``` + +Replace {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" "admin" %}} + +For complete reference, see [Install plugin packages](/influxdb3/version/api/v3/#operation/PostInstallPluginPackages). + +{{% /code-tab-content %}} + {{< /code-tabs-wrapper >}} -These examples install the specified Python package (for example, pandas) into the Processing Engine’s embedded virtual environment. +These examples install the specified Python packages (for example, pandas) into the Processing Engine's embedded virtual environment. - Use the CLI command when running InfluxDB directly on your system. - Use the Docker variant if you're running InfluxDB in a containerized environment. +- Use the HTTP API for programmatic package installation or CI/CD workflows. > [!Important] > #### Use bundled Python for plugins > When you start the server with the `--plugin-dir` option, InfluxDB 3 creates a Python virtual environment (`/venv`) for your plugins. > If you need to create a custom virtual environment, use the Python interpreter bundled with InfluxDB 3. Don't use the system Python. > Creating a virtual environment with the system Python (for example, using `python -m venv`) can lead to runtime errors and plugin failures. -> +> >For more information, see the [processing engine README](https://github.com/influxdata/influxdb/blob/main/README_processing_engine.md). -{{% /code-placeholders %}} - InfluxDB creates a Python virtual environment in your plugins directory with the specified packages installed. ### Disable package installation for secure environments