docs(influxdb3): document trigger logging behavior (#6804)

* docs(influxdb3): document trigger logging behavior

Add processing_engine_logs table documentation to system data reference,
explaining that logs are stored in both the trigger's database (primary)
and _internal. Update plugins error handling to specify trigger's database.

* Update content/shared/influxdb3-plugins/_index.md
pull/6806/head
Jason Stirnaman 2026-02-09 14:32:44 -06:00 committed by GitHub
parent 303d3a5992
commit 322b77e280
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 48 additions and 1 deletions

View File

@ -10,6 +10,7 @@ You can query the system tables for information about your running server, datab
- [View column information for a table](#view-column-information-for-a-table)
- [Recently executed queries](#recently-executed-queries)
- [Query plugin files](#query-plugin-files)
- [Query trigger logs](#query-trigger-logs)
### Use the HTTP query API
@ -190,3 +191,47 @@ curl "http://localhost:8181/api/v3/query_sql" \
"format": "jsonl"
}'
```
#### Query trigger logs
The `system.processing_engine_logs` table stores log entries from Processing Engine triggers.
Logs are stored in **two locations**:
- The trigger's database (primary)--query here for trigger-specific debugging
- The `_internal` database--contains logs from all triggers across all databases
**Columns:**
- `event_time` (Timestamp): When the log entry was recorded
- `trigger_name` (String): Name of the trigger that generated the log
- `log_level` (String): Log level (INFO, WARN, ERROR)
- `log_text` (String): Log message content
**Query logs for a specific trigger:**
```bash { placeholders="DATABASE|TRIGGER" }
influxdb3 query \
--database DATABASE \
"SELECT event_time, log_level, log_text
FROM system.processing_engine_logs
WHERE trigger_name = 'TRIGGER'
ORDER BY event_time DESC
LIMIT 20"
```
Replace the following:
- {{% code-placeholder-key %}}`DATABASE`{{% /code-placeholder-key %}}: The database where you created the trigger
- {{% code-placeholder-key %}}`TRIGGER`{{% /code-placeholder-key %}}: The name of your trigger
**Query all trigger logs (from _internal):**
```bash
influxdb3 query \
--database _internal \
"SELECT event_time, trigger_name, log_level, log_text
FROM system.processing_engine_logs
ORDER BY event_time DESC
LIMIT 50"
```

View File

@ -688,10 +688,12 @@ influxdb3 create trigger \
To configure error handling behavior for a trigger, use the `--error-behavior <ERROR_BEHAVIOR>` CLI option with one of the following values:
- `log` (default): Log all plugin errors to stdout and the `system.processing_engine_logs` system table.
- `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).
For more information, see how to [Query trigger logs](/influxdb3/version/admin/query-system-data/#query-trigger-logs).
```bash
# Automatically retry on error
influxdb3 create trigger \