[docs] Document local log TTL and active segment rolling

fluss-common/src/main/java/org/apache/fluss/config/ConfigOptions.java

@@ -1008,8 +1008,9 @@ public class ConfigOptions {
                     .booleanType()
                     .defaultValue(false)
                     .withDescription(
-                            "Whether to roll a non-empty active log segment when it has expired "
-                                    + "according to the table log TTL. Disabled by default.");
+                            "Whether to roll a non-empty active log segment after it has expired "
+                                    + "according to the effective local cleanup TTL and the high "
+                                    + "watermark has reached the log end offset. Disabled by default.");
 
     public static final ConfigOption<Duration> LOG_REPLICA_HIGH_WATERMARK_CHECKPOINT_INTERVAL =
             key("log.replica.high-watermark.checkpoint-interval")

website/docs/maintenance/configuration.md

@@ -7,8 +7,9 @@ sidebar_position: 1
 
 All configurations can be set in Fluss configuration file `conf/server.yaml`
 
-The configuration is parsed and evaluated when the Fluss processes are started.
-Changes to the configuration file require restarting the relevant processes.
+The configuration is parsed and evaluated when the Fluss processes are started. Most changes to
+the configuration file require restarting the relevant processes. Options that support dynamic
+updates are listed in [Updating Configs](operations/updating-configs.md#updating-cluster-configs).
 
 Users can organize config in format `key: value`, such as:
 
@@ -142,6 +143,8 @@ The logging-related environment options (`env.log.dir`, `env.log.level`, `env.lo
 | log.file-preallocate                           | Boolean    | false          | True if we should preallocate the file on disk when creating a new log segment.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | log.flush.interval-messages                    | Long       | Long.MAX_VALUE | This setting allows specifying an interval at which we will force a fsync of data written to the log. For example if this was set to 1, we would fsync after every message; if it were 5 we would fsync after every five messages.                                                                                                                                                                                                                                                                                                                                                                                                  |
 | log.flush.offset.checkpoint-interval           | Duration   | 1min           | The frequency with which we update the persistent record of the last flush which acts as the log recovery point. The default setting is 60 seconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| log.retention.check-interval                   | Duration   | 5min           | The frequency with which the log manager checks whether local log segments are eligible for TTL cleanup. The value must be greater than 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| log.retention.roll-active-segment.enabled      | Boolean    | false          | Whether to roll a non-empty active log segment after the effective local cleanup TTL expires and the high watermark reaches the log end offset. Rolling makes the segment eligible for remote upload and subsequent local cleanup. This option is disabled by default and supports [dynamic updates](operations/updating-configs.md#updating-cluster-configs).                                                                                                                                                                                                          |
 | log.replica.high-watermark.checkpoint-interval | Duration   | 5s             | The frequency with which the high watermark is saved out to disk. The default setting is 5 seconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | log.replica.max-lag-time                       | Duration   | 30s            | If a follower replica hasn't sent any fetch log requests or hasn't consumed up the leaders log end offset for at least this time, the leader will remove the follower replica from isr                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | log.replica.write-operation-purge-number       | Integer    | 1000           | The purge number (in number of requests) of the write operation manager, the default value is 1000.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

website/docs/maintenance/operations/updating-configs.md

@@ -20,6 +20,9 @@ Currently, the supported dynamically updatable server configurations include:
 - `datalake.enabled`: Control whether the cluster is ready to create and manage lakehouse tables. When this option is explicitly configured to true, `datalake.format` must also be configured.
 - `datalake.format`: Specify the lakehouse format, e.g., `paimon`, `iceberg`. When enabling lakehouse storage explicitly, use it together with `datalake.enabled = true`.
 - Options with prefix `datalake.${datalake.format}`
+- `log.retention.roll-active-segment.enabled`: Control whether a non-empty active segment can be
+  rolled after the effective local cleanup TTL expires and the high watermark reaches the log end
+  offset. See [TTL](../../table-design/data-distribution/ttl.md#active-segment-rolling).
 - `kv.rocksdb.shared-rate-limiter.bytes-per-sec`: Control RocksDB flush and compaction write rate shared across all RocksDB instances on the TabletServer. The rate limiter is always enabled. Set to a lower value (e.g., 100MB) to limit the rate, or a very high value to effectively disable rate limiting.
 - `security.sasl.plain.credentials`: Add, change, or remove the users that can authenticate with SASL/PLAIN, see [Authentication](security/authentication.md#managing-multiple-users).
 - `server.historical-partition.thread-pool.max-size`: Change the maximum number of threads used for historical partition operations.
@@ -75,6 +78,11 @@ CALL sys.set_cluster_configs(
 CALL sys.set_cluster_configs(
   config_pairs => 'kv.rocksdb.shared-rate-limiter.bytes-per-sec', '200MB'
 );
+
+-- Allow expired active log segments to be rolled
+CALL sys.set_cluster_configs(
+  config_pairs => 'log.retention.roll-active-segment.enabled', 'true'
+);
 ```
 
 See [Procedures](engine-flink/procedures.md#cluster-configuration-procedures) for detailed documentation on `get_cluster_configs`, `set_cluster_configs`, `append_cluster_configs`, `subtract_cluster_configs`, and `reset_cluster_configs` procedures.

website/docs/maintenance/operations/upgrade-notes-1.0.md

@@ -33,6 +33,31 @@ Custom credentials providers must now implement `software.amazon.awssdk.auth.cre
 
 Deployments using static access keys or the default AWS credentials provider chain do not require configuration changes.
 
+### Active Segment Retention Rollout
+
+When upgrading a cluster from v0.9, keep
+`log.retention.roll-active-segment.enabled` disabled for the entire upgrade. This is the default, so
+no configuration change is required before or during the rolling upgrade.
+
+After every CoordinatorServer and TabletServer has been upgraded to v1.0 and the upgrade is
+complete, enable the option with a dynamic cluster configuration update:
+
+```sql
+CALL sys.set_cluster_configs(
+  config_pairs => 'log.retention.roll-active-segment.enabled', 'true'
+);
+```
+
+Enabling the option allows a non-empty active local log segment to be rolled after its effective
+local cleanup TTL expires and all records are committed. For tiered logs, the effective TTL is
+`table.log.local-ttl`, or `table.log.ttl` when the local option is not configured. The rolled
+segment can then be uploaded to remote storage and cleaned up locally. This avoids indefinitely
+retaining an expired active segment on low-traffic tables.
+
+See [TTL](../../table-design/data-distribution/ttl.md) for the segment lifecycle,
+[remote storage](../tiered-storage/remote-storage.md) for tiered-log retention, and
+[updating configs](updating-configs.md#updating-cluster-configs) for other dynamic update methods.
+
 ### New `datalake.enabled` Cluster Configuration
 
 Starting in v1.0, Fluss introduces the cluster-level configuration `datalake.enabled` to control whether the cluster is ready to create and manage lakehouse tables.

website/docs/maintenance/tiered-storage/remote-storage.md

@@ -33,13 +33,25 @@ Below is the list for all configurations to control the log segments tiered beha
 
 ### Table configurations about remote log
 
-When local log segments are copied to remote storage, the local log segments will be deleted to reduce local disk cost.
-But sometimes, we want to keep the several latest log segments retain in local, although they have been coped to remote storage for better read performance.
-You can control local retention per table with `table.log.tiered.local-segments` (default is 2)
-and `table.log.local-ttl`. When `table.log.local-ttl` is not configured, it falls back to
-`table.log.ttl`. A non-positive local TTL disables TTL-based local cleanup. When both TTLs are
-positive, the local TTL must be less than or equal to `table.log.ttl`. An expired local segment is
-deleted only after it has been copied to remote storage.
+After a rolled local log segment is copied to remote storage, it can be removed to reduce local disk
+usage. Uncopied segments are never eligible for local TTL cleanup.
+
+Use the following table options to control local retention:
+
+- `table.log.local-ttl` controls TTL-based cleanup. It inherits `table.log.ttl` when it is not
+  configured. Setting it to `0ms` disables TTL-based local cleanup. When both TTLs are positive,
+  the local TTL must be less than or equal to `table.log.ttl`.
+- `table.log.tiered.local-segments` keeps the configured number of recent local segments from
+  count-based cleanup (default: 2). Copied segments beyond that count can be removed even before
+  their local TTL expires.
+
+The two cleanup policies are independent: a copied local segment can be removed when it exceeds the
+configured segment count or when its local TTL expires.
+
+`table.log.ttl` independently controls the retention of table log data, including its remote copy.
+See [TTL](../../table-design/data-distribution/ttl.md) for the complete lifecycle from an active
+local segment through rolling, upload, local cleanup, and remote expiration. The server-side
+remote-log settings are listed in [server configuration](../configuration.md#log-tiered-storage).
 
 ## Remote snapshot of primary key table