---
title: WAL plugin
description: Example Write-Ahead Log (WAL) plugin that demonstrates processing data as it’s written to the database.
url: https://docs.influxdata.com/influxdb3/enterprise/plugins/library/examples/wal-plugin/
estimated_tokens: 2014
product: InfluxDB 3 Enterprise
version: enterprise
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb3/enterprise/plugins/library/examples/wal-plugin/
date: '2026-07-11T10:53:18+00:00'
lastmod: '2026-07-11T10:53:18+00:00'
---

The example WAL plugin monitors data write operations in InfluxDB 3 by tracking row counts for each table during WAL (Write-Ahead Log) flush events.
It creates summary reports in a `write_reports` table to help analyze data ingestion patterns and rates.
The plugin can optionally double-count rows for a specified table to demonstrate configurable behavior.

## Configuration

### Optional parameters

|     Parameter      | Type |Default|                                       Description                                       |
|--------------------|------|-------|-----------------------------------------------------------------------------------------|
|`double_count_table`|string| none  |Table name for which to double the row count in write reports (for testing/demonstration)|

## Installation steps

1. Start InfluxDB 3 Enterprise with the Processing Engine enabled (`--plugin-dir /path/to/plugins`)

   ```
   influxdb3 serve \
     --node-id node0 \
     --object-store file \
     --data-dir ~/.influxdb3 \
     --plugin-dir ~/.plugins
   ```

## Trigger setup

### Write monitoring

Monitor all table writes and generate write reports:

```bash
influxdb3 create trigger \
  --database monitoring \
  --plugin-filename examples/wal_plugin/wal_plugin.py \
  --trigger-spec "all_tables" \
  wal_monitoring
```

### Write monitoring with special handling

Monitor writes with special handling for a specific table:

```bash
influxdb3 create trigger \
  --database monitoring \
  --plugin-filename examples/wal_plugin/wal_plugin.py \
  --trigger-spec "all_tables" \
  --trigger-arguments 'double_count_table=temperature' \
  wal_monitoring_special
```

## Example usage

### Example: Basic write monitoring

Set up write monitoring to track data ingestion:

```
# Create the monitoring trigger
influxdb3 create trigger \
  --database testdb \
  --plugin-filename examples/wal_plugin/wal_plugin.py \
  --trigger-spec "all_tables" \
  write_monitor

# Write test data to various tables
influxdb3 write \
  --database testdb \
  "temperature,location=office value=22.5"

influxdb3 write \
  --database testdb \
  "humidity,location=office value=45.2"

influxdb3 write \
  --database testdb \
  "pressure,location=office value=1013.25"

# The plugin automatically generates write reports in the `write_reports` measurement.

# Query the write reports
influxdb3 query \
  --database testdb \
  "SELECT * FROM write_reports ORDER BY time DESC"
```

### Expected output

```
table_name  | row_count | time
------------|-----------|-----
pressure    | 1         | 2024-01-01T12:02:00Z
humidity    | 1         | 2024-01-01T12:01:00Z
temperature | 1         | 2024-01-01T12:00:00Z
```

### Example: Monitoring with special table handling

Monitor writes with doubled counting for temperature data:

```
# Create trigger with special handling
influxdb3 create trigger \
  --database testdb \
  --plugin-filename examples/wal_plugin/wal_plugin.py \
  --trigger-spec "all_tables" \
  --trigger-arguments 'double_count_table=temperature' \
  write_monitor_special

# Write test data
influxdb3 write \
  --database testdb \
  "temperature,location=office value=22.5"

influxdb3 write \
  --database testdb \
  "humidity,location=office value=45.2"

# Query the write reports
influxdb3 query \
  --database testdb \
  "SELECT * FROM write_reports ORDER BY time DESC"
```

### Expected output

```
table_name  | row_count | time
------------|-----------|-----
humidity    | 1         | 2024-01-01T12:01:00Z
temperature | 2         | 2024-01-01T12:00:00Z
```

**Note**: The temperature table shows a row count of 2 despite only writing 1 row, demonstrating the `double_count_table` parameter.

## Generated Measurements

### write\_reports

Tracks the number of rows written to each table during WAL flush events.

**Tags:**

* `table_name`: Name of the table that received writes

**Fields:**

* `row_count`: Number of rows written in this WAL flush (integer)

**Special behavior:**

* If `double_count_table` parameter matches the table name, the row count will be doubled
* The plugin automatically skips the `write_reports` table to avoid infinite recursion

## Code overview

### Files

* `wal_plugin.py`: Main plugin code that processes write batches and generates reports

### Main functions

#### `process_writes(influxdb3_local, table_batches, args)`

Entry point for processing write batches. Called each time data is written to the database.

**Parameters:**

* `influxdb3_local`: InfluxDB client for writing and logging
* `table_batches`: List of table batches containing written data
* `args`: Configuration arguments from trigger setup

**Processing logic:**

1. Iterates through each table batch in the write operation
2. Skips the `write_reports` table to prevent recursion
3. Counts rows in each batch
4. Applies special handling if `double_count_table` matches
5. Writes report record to `write_reports` measurement

### Logging

Logs are stored in the `_internal` database in the `system.processing_engine_logs` table. To view logs:

```bash
influxdb3 query \
  --database _internal \
  --token AUTH_TOKEN \
  "SELECT * FROM system.processing_engine_logs WHERE trigger_name = 'wal_monitoring'"
```

Replace `AUTH_TOKEN` with your [admin token](/influxdb3/enterprise/admin/tokens/).

## Troubleshooting

### Common issues

#### Issue: No write reports appearing

**Solution**:

1. Verify the trigger was created successfully:

   ```
   influxdb3 show summary --database DATABASE_NAME --token AUTH_TOKEN
   ```

   Replace the following:

   * `DATABASE_NAME`: the name of the database
   * `AUTH_TOKEN`: your [database token](/influxdb3/enterprise/admin/tokens/)with read permissions on the specified database

2. Check that data is actually being written to tables other than `write_reports`

3. Review logs for errors

#### Issue: Infinite recursion with write\_reports

**Solution**: This shouldn’t happen as the plugin automatically skips the `write_reports` table, but if you see this:

1. Check that you haven’t modified the plugin to remove the skip logic
2. Verify the table name comparison is working correctly

#### Issue: Row counts seem incorrect

**Solution**:

1. Remember that row counts represent WAL flush batches, not individual write operations
2. Multiple write operations may be batched together before the plugin processes them
3. Check if `double_count_table` is set and affecting specific tables

### Performance considerations

* This plugin processes every write operation, so it adds minimal overhead
* The plugin generates one additional write per table per WAL flush batch
* Consider the storage impact of write reports for high-volume systems

### Use cases

* **Write monitoring**: Track data ingestion patterns and volumes
* **Debugging**: Identify which tables are receiving writes
* **Performance analysis**: Monitor write batch sizes and patterns
* **Data validation**: Verify expected write volumes
* **Testing**: Use `double_count_table` parameter for testing scenarios

## Report an issue

For plugin issues, see the Plugins repository [issues page](https://github.com/influxdata/influxdb3_plugins/issues).

## Find support for InfluxDB 3 Enterprise

The [InfluxDB Discord server](https://discord.gg/9zaNCW2PRT) is the best place to find support for InfluxDB 3 Core and InfluxDB 3 Enterprise.
For other InfluxDB versions, see the [Support and feedback](#bug-reports-and-feedback) options.

#### Related

* [WAL plugin on GitHub](https://github.com/influxdata/influxdb3_plugins/tree/main/examples/wal-plugin)

[plugins](/influxdb3/enterprise/tags/plugins/)[processing engine](/influxdb3/enterprise/tags/processing-engine/)[python](/influxdb3/enterprise/tags/python/)[wal](/influxdb3/enterprise/tags/wal/)[data-write](/influxdb3/enterprise/tags/data-write/)
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| Parameter | Type | Default | Description |
| double_count_table | string | none | Table name for which to double the row count in write reports (for testing/demonstration) |