> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-core/guides/developing-applications/configuring-the-runtime/transactions.md).

# Transactions

## Overview

Transaction configuration controls how your Rumi microservice batches and commits work. Proper transaction tuning balances latency (time to commit individual transactions) against throughput (number of transactions per second).

This section covers runtime configuration for transaction batching and commit behavior. For conceptual understanding of how transactions work, see [Transactions](/rumi-core/concepts/transactions.md).

## What You Can Configure

Transaction configuration includes:

### Adaptive Batching

Configure the engine to adaptively batch multiple message processing transactions into a single commit:

* Enable/disable adaptive batching
* Set maximum batch size (ceiling)
* Configure batch window timing
* Tune for latency vs throughput trade-offs

See [Adaptive Batching](/rumi-core/guides/developing-applications/configuring-the-runtime/transactions/adaptive-batching.md) for complete configuration reference.

### Transaction Behavior (Future)

Additional transaction configuration topics:

* Transaction timeouts
* Commit flush behavior
* Checkpoint frequency

*Note: Additional transaction topics will be added as the documentation expands.*

## Configuration Hierarchy

Transaction settings are configured in your DDL under the engine's transaction section:

```xml
<service name="my-service" mainClass="com.example.MyApp">
  <transactions>
    <adaptiveCommitBatchCeiling>100</adaptiveCommitBatchCeiling>
  </transactions>
</service>
```

## How Transactions Work

Understanding transaction boundaries helps configure batching effectively:

### Without Adaptive Batching

Each message processed in its own transaction:

1. Message arrives
2. Handler executes
3. Transaction commits immediately
4. Next message processed

**Characteristics**:

* Lowest latency (microseconds to commit)
* Lower throughput (commit overhead per message)
* Ideal for latency-sensitive applications

### With Adaptive Batching

Multiple messages batched into single commit:

1. Messages arrive rapidly
2. Multiple handlers execute
3. Batch commits when ceiling reached or window expires
4. All messages acknowledged together

**Characteristics**:

* Higher throughput (amortize commit overhead)
* Slightly higher latency (wait for batch)
* Ideal for high-volume applications

See [Cluster Consensus](/rumi-core/concepts/microservice-operation/cluster-consensus.md) for detailed transaction flow diagrams.

## Common Configuration Patterns

### Low-Latency Trading System

Disable batching for minimum commit latency:

```xml
<service name="trading-engine">
  <transactions>
    <!-- No batching - each message commits immediately -->
    <adaptiveCommitBatchCeiling>1</adaptiveCommitBatchCeiling>
  </transactions>
</service>
```

**Use when**:

* Sub-millisecond latency is critical
* Message arrival rate is moderate
* Each message must be processed ASAP

### High-Throughput Order Processor

Enable batching for maximum throughput:

```xml
<service name="order-processor">
  <transactions>
    <!-- Batch up to 100 messages per commit -->
    <adaptiveCommitBatchCeiling>100</adaptiveCommitBatchCeiling>
  </transactions>
</service>
```

**Use when**:

* Throughput is more important than latency
* Messages arrive in bursts
* Slight latency increase (milliseconds) is acceptable

### Balanced Configuration

Moderate batching for balanced performance:

```xml
<service name="order-router">
  <transactions>
    <!-- Batch up to 10 messages per commit -->
    <adaptiveCommitBatchCeiling>10</adaptiveCommitBatchCeiling>
  </transactions>
</service>
```

**Use when**:

* Need both good latency and throughput
* Message arrival rate varies
* Want automatic adaptation to load

## Performance Considerations

### Latency Impact

Adaptive batching increases average latency by waiting for batch to fill:

* **Batch size 1**: \~100 microseconds per message
* **Batch size 10**: \~200-500 microseconds per message
* **Batch size 100**: \~1-2 milliseconds per message

The first message in a batch sees the most latency increase.

### Throughput Gains

Batching amortizes commit overhead across multiple messages:

* **No batching**: \~10,000 messages/second
* **Batch size 10**: \~50,000 messages/second
* **Batch size 100**: \~200,000 messages/second

*Note: Actual numbers depend on message complexity, state size, and hardware.*

### Adaptive Behavior

The engine automatically adjusts batch size based on message arrival rate:

* **Low arrival rate**: Commits immediately (effective batch size 1)
* **High arrival rate**: Batches up to ceiling
* **Bursty traffic**: Adapts dynamically

This provides good latency during quiet periods and good throughput during bursts.

## Monitoring Transaction Performance

Use engine statistics to monitor transaction behavior:

* `TxnCount` - Number of transactions committed
* `TxnBatchCount` - Number of messages in each transaction
* `TxnLatency` - Time from message receipt to commit

See [Engine Statistics](/rumi-core/guides/developing-applications/configuring-the-runtime/monitoring/engine-statistics.md) for complete metrics reference.

## Related Topics

### Transaction Concepts

* [Transactions](/rumi-core/concepts/transactions.md) - How transactions work in Rumi
* [Cluster Consensus](/rumi-core/concepts/microservice-operation/cluster-consensus.md) - Transaction commit with consensus

### Developer Guidance

* [Controlling Transactions](/rumi-core/guides/developing-applications/authoring-user-code/message-processing/processing-messages/handling-messages/controlling-transactions.md) - Programmatic transaction control
* [Using Savepoints](/rumi-core/guides/developing-applications/authoring-user-code/message-processing/processing-messages/handling-messages/controlling-transactions/using-savepoints.md) - Transaction savepoints in handlers

### Configuration Reference

* [Configuration](/rumi-core/reference/configuration.md) - Complete DDL reference for transaction settings

## Best Practices

1. **Start with default (no batching)**: Begin with `adaptiveCommitBatchCeiling="1"` and measure baseline performance
2. **Increase ceiling for throughput**: If throughput is bottleneck, gradually increase ceiling (10, 25, 50, 100)
3. **Monitor latency distribution**: Track P50, P99, and P999 latencies to understand batching impact
4. **Test under realistic load**: Use production-like message rates and patterns to tune batching
5. **Consider consensus model**: Event Sourcing benefits more from batching than State Replication
6. **Account for replication overhead**: Higher batch sizes increase state delta sizes in State Replication

## See Also

* [Message Flow](/rumi-core/guides/developing-applications/configuring-the-runtime/message-flow.md) - Configure message processing behavior
* [Threading](/rumi-core/guides/developing-applications/configuring-the-runtime/threading.md) - Configure threads that process transactions
* [Monitoring](/rumi-core/guides/developing-applications/configuring-the-runtime/monitoring.md) - Monitor transaction statistics and performance