From aacef0a06a05fee3cac17686ec9946989f1720c5 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Tue, 8 Jul 2025 13:18:14 -0500 Subject: [PATCH] Add missing CLI options\ Fix `create token --admin` name in frontmatter Improve schedule trigger docs with more detail: 1. Core API documentation (/api-docs/influxdb3/core/v3/ref.yml): - Added missing duration units (weeks, months, years) - Added "Maximum interval: 1 year" 2. Enterprise API documentation (/api-docs/influxdb3/enterprise/v3/ref.yml): - Added missing duration units (weeks, months, years) - Added "Maximum interval: 1 year" 3. CLI reference documentation (/content/shared/influxdb3-cli/create/trigger.md): - Added complete list of supported duration units - Added "Maximum interval is 1 year" note All documentation now consistently reflects: - The complete set of supported duration units for every triggers - The 1-year maximum limit for interval-based scheduling - Clear examples showing the syntax --- api-docs/influxdb3/core/v3/ref.yml | 7 +- api-docs/influxdb3/enterprise/v3/ref.yml | 7 +- .../core/reference/cli/influxdb3/_index.md | 2 +- .../cli/influxdb3/create/database.md | 2 +- .../cli/influxdb3/create/token/admin.md | 6 +- .../cli/influxdb3/create/token/admin.md | 6 +- .../influxdb3-cli/create/token/_index.md | 9 +- .../shared/influxdb3-cli/create/trigger.md | 125 +++++++++++++++++- 8 files changed, 149 insertions(+), 15 deletions(-) diff --git a/api-docs/influxdb3/core/v3/ref.yml b/api-docs/influxdb3/core/v3/ref.yml index e15c42f9f..627e8229f 100644 --- a/api-docs/influxdb3/core/v3/ref.yml +++ b/api-docs/influxdb3/core/v3/ref.yml @@ -1932,11 +1932,16 @@ components: ### Interval-based scheduling Format: `every:DURATION` - Supported durations: `s` (seconds), `m` (minutes), `h` (hours), `d` (days): + Supported durations: `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `M` (months), `y` (years): - `every:30s` - Every 30 seconds - `every:5m` - Every 5 minutes - `every:1h` - Every hour - `every:1d` - Every day + - `every:1w` - Every week + - `every:1M` - Every month + - `every:1y` - Every year + + **Maximum interval**: 1 year ### Table-based triggers - `all_tables` - Triggers on write events to any table in the database diff --git a/api-docs/influxdb3/enterprise/v3/ref.yml b/api-docs/influxdb3/enterprise/v3/ref.yml index 34b2bd961..88a78449f 100644 --- a/api-docs/influxdb3/enterprise/v3/ref.yml +++ b/api-docs/influxdb3/enterprise/v3/ref.yml @@ -2079,11 +2079,16 @@ components: ### Interval-based scheduling Format: `every:DURATION` - Supported durations: `s` (seconds), `m` (minutes), `h` (hours), `d` (days): + Supported durations: `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `M` (months), `y` (years): - `every:30s` - Every 30 seconds - `every:5m` - Every 5 minutes - `every:1h` - Every hour - `every:1d` - Every day + - `every:1w` - Every week + - `every:1M` - Every month + - `every:1y` - Every year + + **Maximum interval**: 1 year ### Table-based triggers - `all_tables` - Triggers on write events to any table in the database diff --git a/content/influxdb3/core/reference/cli/influxdb3/_index.md b/content/influxdb3/core/reference/cli/influxdb3/_index.md index 831597dc6..b0788e001 100644 --- a/content/influxdb3/core/reference/cli/influxdb3/_index.md +++ b/content/influxdb3/core/reference/cli/influxdb3/_index.md @@ -49,7 +49,7 @@ influxdb3 [GLOBAL-OPTIONS] [COMMAND] | | `--io-runtime-thread-keep-alive` | Custom timeout for a thread in the blocking pool of the tokio IO runtime | | | `--io-runtime-thread-priority` | Set thread priority tokio IO runtime workers | | `-h` | `--help` | Print help information | -| | `--help-all` | Print detailed help information | +| | `--help-all` | Print detailed help information including runtime configuration options | | `-V` | `--version` | Print version | ### Option environment variables diff --git a/content/influxdb3/core/reference/cli/influxdb3/create/database.md b/content/influxdb3/core/reference/cli/influxdb3/create/database.md index 39a9c016a..970660fb4 100644 --- a/content/influxdb3/core/reference/cli/influxdb3/create/database.md +++ b/content/influxdb3/core/reference/cli/influxdb3/create/database.md @@ -11,5 +11,5 @@ source: /shared/influxdb3-cli/create/database.md --- diff --git a/content/influxdb3/core/reference/cli/influxdb3/create/token/admin.md b/content/influxdb3/core/reference/cli/influxdb3/create/token/admin.md index a2646e4ec..37f212eff 100644 --- a/content/influxdb3/core/reference/cli/influxdb3/create/token/admin.md +++ b/content/influxdb3/core/reference/cli/influxdb3/create/token/admin.md @@ -1,11 +1,11 @@ --- -title: influxdb3 create token admin +title: influxdb3 create token --admin description: > - The `influxdb3 create token admin` command creates an operator token or named admin token with full administrative privileges for server actions. + The `influxdb3 create token --admin` subcommand creates an operator token or named admin token with full administrative privileges for server actions. menu: influxdb3_core: parent: influxdb3 create token - name: influxdb3 create token admin + name: influxdb3 create token --admin weight: 400 source: /shared/influxdb3-cli/create/token/admin.md --- diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/admin.md b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/admin.md index 7c4bab6bc..e6a0f8168 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/admin.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/admin.md @@ -1,11 +1,11 @@ --- -title: influxdb3 create token admin +title: influxdb3 create token --admin description: > - The `influxdb3 create token admin` command creates an operator token or named admin token with full administrative privileges for server actions. + The `influxdb3 create token --admin` subcommand creates an operator token or named admin token with full administrative privileges for server actions. menu: influxdb3_enterprise: parent: influxdb3 create token - name: influxdb3 create token admin + name: influxdb3 create token --admin weight: 400 source: /shared/influxdb3-cli/create/token/admin.md --- diff --git a/content/shared/influxdb3-cli/create/token/_index.md b/content/shared/influxdb3-cli/create/token/_index.md index d1cb2139f..d2cd5f6b9 100644 --- a/content/shared/influxdb3-cli/create/token/_index.md +++ b/content/shared/influxdb3-cli/create/token/_index.md @@ -20,9 +20,10 @@ influxdb3 create token ## Options -| Option | | Description | -| :----- | :------- | :--------------------- | -| |`--admin`| Create an admin token | -| `-h` | `--help` | Print help information | +| Option | | Description | +|:-------|:----------|:-----------------------| +| | `--admin` | Create an admin token | +| `-h` | `--help` | Print help information | +| | `--help-all` | Print detailed help information diff --git a/content/shared/influxdb3-cli/create/trigger.md b/content/shared/influxdb3-cli/create/trigger.md index bc4bfd074..121fd4964 100644 --- a/content/shared/influxdb3-cli/create/trigger.md +++ b/content/shared/influxdb3-cli/create/trigger.md @@ -28,12 +28,15 @@ influxdb3 create trigger [OPTIONS] \ | | `--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:`, `all_tables`, `every:`, `cron:`, or `request:` | +| | `--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. +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`. @@ -51,6 +54,17 @@ You can use the following environment variables to set command options: 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 @@ -77,6 +91,8 @@ influxdb3 create trigger \ 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. @@ -92,8 +108,77 @@ influxdb3 create trigger \ 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 \ + --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 \ + --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 \ + --trigger-spec table:TABLE_NAME \ + --trigger-arguments arg1=value1,arg2=value2 \ + TRIGGER_NAME +``` + ### Create a disabled trigger Create a trigger in a disabled state. @@ -112,4 +197,42 @@ influxdb3 create trigger \ 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 \ + --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 \ + --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 \ + --trigger-spec table:TABLE_NAME \ + --error-behavior disable \ + TRIGGER_NAME +``` + {{% /code-placeholders %}}