239 lines
8.4 KiB
Markdown
239 lines
8.4 KiB
Markdown
|
|
The `influxdb3 create trigger` command creates a new trigger for the
|
|
processing engine.
|
|
|
|
## Usage
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```bash
|
|
influxdb3 create trigger [OPTIONS] \
|
|
--database <DATABASE_NAME> \
|
|
--token <AUTH_TOKEN> \
|
|
--plugin-filename <PLUGIN_FILENAME> \
|
|
--trigger-spec <TRIGGER_SPECIFICATION> \
|
|
<TRIGGER_NAME>
|
|
```
|
|
|
|
## Arguments
|
|
|
|
- **TRIGGER_NAME**: A name for the new trigger.
|
|
|
|
## Options
|
|
|
|
| Option | | Description |
|
|
| :----- | :------------------ | :------------------------------------------------------------------------------------------------------- |
|
|
| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) |
|
|
| `-d` | `--database` | _({{< req >}})_ Name of the database to operate on |
|
|
| | `--token` | _({{< req >}})_ Authentication token |
|
|
| | `--plugin-filename` | _({{< req >}})_ Name of the file, stored in the server's `plugin-dir`, that contains the Python plugin code to run |
|
|
| | `--trigger-spec` | Trigger specification: `table:<TABLE_NAME>`, `all_tables`, `every:<DURATION>`, `cron:<EXPRESSION>`, or `request:<REQUEST_PATH>` |
|
|
| | `--trigger-arguments` | Additional arguments for the trigger, in the format `key=value`, separated by commas (for example, `arg1=val1,arg2=val2`) |
|
|
| | `--disabled` | Create the trigger in disabled state |
|
|
| | `--error-behavior` | Error handling behavior: `log`, `retry`, or `disable` |
|
|
| | `--run-asynchronous` | Run the trigger asynchronously, allowing multiple triggers to run simultaneously (default is synchronous) |
|
|
| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) |
|
|
| `-h` | `--help` | Print help information |
|
|
| | `--help-all` | Print detailed help information |
|
|
|
|
If you want to use a plugin from the [Plugin Library](https://github.com/influxdata/influxdb3_plugins) repo, use the URL path with `gh:` specified as the prefix.
|
|
For example, to use the [System Metrics](https://github.com/influxdata/influxdb3_plugins/blob/main/examples/schedule/system_metrics/system_metrics.py) plugin, the plugin filename is `gh:examples/schedule/system_metrics/system_metrics.py`.
|
|
|
|
|
|
### Option environment variables
|
|
|
|
You can use the following environment variables to set command options:
|
|
|
|
| Environment Variable | Option |
|
|
| :------------------------ | :----------- |
|
|
| `INFLUXDB3_HOST_URL` | `--host` |
|
|
| `INFLUXDB3_DATABASE_NAME` | `--database` |
|
|
| `INFLUXDB3_AUTH_TOKEN` | `--token` |
|
|
|
|
## Examples
|
|
|
|
The following examples show how to use the `influxdb3 create trigger` command to create triggers in different scenarios.
|
|
|
|
- [Create a trigger for a specific table](#create-a-trigger-for-a-specific-table)
|
|
- [Create a trigger for all tables](#create-a-trigger-for-all-tables)
|
|
- [Create a trigger with a schedule](#create-a-trigger-with-a-schedule)
|
|
- [Create a trigger for HTTP requests](#create-a-trigger-for-http-requests)
|
|
- [Create a trigger with additional arguments](#create-a-trigger-with-additional-arguments)
|
|
- [Create a disabled trigger](#create-a-disabled-trigger)
|
|
- [Create a trigger with error handling](#create-a-trigger-with-error-handling)
|
|
|
|
---
|
|
|
|
Replace the following placeholders with your values:
|
|
|
|
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: Database name
|
|
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: Authentication token
|
|
- {{% code-placeholder-key %}}`PLUGIN_FILENAME`{{% /code-placeholder-key %}}: Python plugin filename
|
|
- {{% code-placeholder-key %}}`TRIGGER_NAME`{{% /code-placeholder-key %}}:
|
|
Name of the trigger to create
|
|
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}:
|
|
Name of the table to trigger on
|
|
|
|
{{% code-placeholders "(DATABASE|TRIGGER)_NAME|AUTH_TOKEN|TABLE_NAME" %}}
|
|
|
|
### Create a trigger for a specific table
|
|
|
|
Create a trigger that processes data from a specific table.
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```bash
|
|
influxdb3 create trigger \
|
|
--database DATABASE_NAME \
|
|
--token AUTH_TOKEN \
|
|
--plugin-filename PLUGIN_FILENAME \
|
|
--trigger-spec table:TABLE_NAME \
|
|
TRIGGER_NAME
|
|
```
|
|
|
|
`PLUGIN_FILENAME` must implement the [data write plugin](/influxdb3/version/plugins/#create-a-data-write-plugin) interface.
|
|
|
|
### Create a trigger for all tables
|
|
|
|
Create a trigger that applies to all tables in the specified database.
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```bash
|
|
influxdb3 create trigger \
|
|
--database DATABASE_NAME \
|
|
--token AUTH_TOKEN \
|
|
--plugin-filename <PLUGIN_FILENAME> \
|
|
--trigger-spec all_tables \
|
|
TRIGGER_NAME
|
|
```
|
|
|
|
`PLUGIN_FILENAME` must implement the [data write plugin](/influxdb3/version/plugins/#create-a-data-write-plugin) interface.
|
|
|
|
This is useful when you want a trigger to apply to any table in the database, regardless of name.
|
|
|
|
### Create a trigger with a schedule
|
|
|
|
Create a trigger that runs at a specific interval using a duration. Supported duration units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `M` (months), `y` (years). Maximum interval is 1 year.
|
|
|
|
```bash
|
|
influxdb3 create trigger \
|
|
--database DATABASE_NAME \
|
|
--token AUTH_TOKEN \
|
|
--plugin-filename <PLUGIN_FILENAME> \
|
|
--trigger-spec every:5m \
|
|
TRIGGER_NAME
|
|
```
|
|
|
|
Create a trigger that runs based on a cron schedule using extended 6-field cron format. The cron expression follows the format:
|
|
|
|
```console
|
|
second minute hour day_of_month month day_of_week
|
|
```
|
|
|
|
Fields:
|
|
- **second**: 0-59
|
|
- **minute**: 0-59
|
|
- **hour**: 0-23
|
|
- **day_of_month**: 1-31
|
|
- **month**: 1-12 or JAN-DEC
|
|
- **day_of_week**: 0-7 (0 or 7 is Sunday) or SUN-SAT
|
|
|
|
Example: Run at 6:00 AM every weekday (Monday-Friday):
|
|
|
|
```bash
|
|
influxdb3 create trigger \
|
|
--database DATABASE_NAME \
|
|
--token AUTH_TOKEN \
|
|
--plugin-filename <PLUGIN_FILENAME> \
|
|
--trigger-spec "cron:0 0 6 * * 1-5" \
|
|
TRIGGER_NAME
|
|
```
|
|
|
|
`PLUGIN_FILENAME` must implement the [scheduled plugin](/influxdb3/version/plugins/#create-a-scheduled-plugin) interface.
|
|
|
|
### Create a trigger for HTTP requests
|
|
|
|
Create a trigger that provides an API endpoint and processes HTTP requests.
|
|
|
|
```bash
|
|
influxdb3 create trigger \
|
|
--database DATABASE_NAME \
|
|
--token AUTH_TOKEN \
|
|
--plugin-filename PLUGIN_FILENAME \
|
|
--trigger-spec request:REQUEST_PATH \
|
|
TRIGGER_NAME
|
|
```
|
|
|
|
`PLUGIN_FILENAME` must implement the [HTTP request plugin](/influxdb3/version/plugins/#create-an-http-request-plugin) interface.
|
|
|
|
### Create a trigger with additional arguments
|
|
|
|
```bash
|
|
influxdb3 create trigger \
|
|
--database DATABASE_NAME \
|
|
--token AUTH_TOKEN \
|
|
--plugin-filename <PLUGIN_FILENAME> \
|
|
--trigger-spec table:TABLE_NAME \
|
|
--trigger-arguments arg1=value1,arg2=value2 \
|
|
TRIGGER_NAME
|
|
```
|
|
|
|
### Create a disabled trigger
|
|
|
|
Create a trigger in a disabled state.
|
|
|
|
<!--pytest.mark.skip-->
|
|
|
|
```bash
|
|
influxdb3 create trigger \
|
|
--disabled \
|
|
--database DATABASE_NAME \
|
|
--token AUTH_TOKEN \
|
|
--plugin-filename <PLUGIN_FILENAME> \
|
|
--trigger-spec table:TABLE_NAME \
|
|
TRIGGER_NAME
|
|
```
|
|
|
|
Creating a trigger in a disabled state prevents it from running immediately. You can enable it later when you're ready to activate it.
|
|
|
|
### Create a trigger with error handling
|
|
|
|
Log the error to the service output and the `system.processing_engine_logs` table:
|
|
|
|
```bash
|
|
influxdb3 create trigger \
|
|
--database DATABASE_NAME \
|
|
--token AUTH_TOKEN \
|
|
--plugin-filename <PLUGIN_FILENAME> \
|
|
--trigger-spec table:TABLE_NAME \
|
|
--error-behavior log \
|
|
TRIGGER_NAME
|
|
```
|
|
|
|
Rerun the trigger if it fails:
|
|
|
|
```bash
|
|
influxdb3 create trigger \
|
|
--database DATABASE_NAME \
|
|
--token AUTH_TOKEN \
|
|
--plugin-filename <PLUGIN_FILENAME> \
|
|
--trigger-spec table:TABLE_NAME \
|
|
--error-behavior retry \
|
|
TRIGGER_NAME
|
|
```
|
|
|
|
Disable the trigger if it fails:
|
|
|
|
```bash
|
|
influxdb3 create trigger \
|
|
--database DATABASE_NAME \
|
|
--token AUTH_TOKEN \
|
|
--plugin-filename <PLUGIN_FILENAME> \
|
|
--trigger-spec table:TABLE_NAME \
|
|
--error-behavior disable \
|
|
TRIGGER_NAME
|
|
```
|
|
|
|
{{% /code-placeholders %}}
|