> 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/reference/configuration.md).

# Configuration

Complete reference for Rumi configuration including global environment properties and DDL (Domain Descriptor Language) elements.

## Overview

Rumi provides two complementary configuration mechanisms:

1. [**Global Environment**](#global-properties-reference): Property-based configuration for runtime behavior (statistics, optimization, trace levels)
2. [**DDL**](#ddl-elements-reference): XML-based configuration for components (buses, engines, containers)

For conceptual information about how these mechanisms work together, see [Configuration Model](/rumi-core/concepts/microservice-architecture/configuration-model.md).

***

## Global Properties Reference

Global properties configure Rumi runtime behavior and can be set via:

1. System properties (`-Dproperty=value`)
2. App propfile (specified via `nv_app_propfile` environment variable or `-Dnv.app.propfile` system property)
3. Environment variables
4. DDL `<env>` section (**highest precedence**)

The **"Can Set in `<env>`?"** indicator shows whether the property can be specified in the DDL `<env>` section or must be set via one of the other mechanisms.

### Property Index

[**Statistics Configuration**](#statistics-configuration-properties)

* [nv.stats.latencymanager.samplesize](#nvstatslatencymanagersamplesize)
* [nv.stats.series.samplesize](#nvstatsseriessamplesize)
* [nv.msg.latency.stats](#nvmsglatencystats)
* [nv.msgtype.latency.stats](#nvmsgtypelatencystats)
* [nv.ods.latency.stats](#nvodslatencystats)
* [nv.event.latency.stats](#nveventlatencystats)
* [nv.link.network.stampiots](#nvlinknetworkstampiots)

[**Optimization**](#optimization-properties)

* [nv.optimizefor](#nvoptimizefor)
* [nv.conservecpu](#nvconservecpu)

[**Trace Logging**](#trace-logging-properties)

* [nv.ddl.trace](#nvddltrace)
* [nv.sma.trace](#nvsmatrace)
* [nv.aep.trace](#nvaeptrace)
* [nv.sol.trace](#nvsoltrace)

[**Discovery**](#discovery-properties)

* [nv.discovery.descriptor](#nvdiscoverydescriptor)

[**Statistics Output Threads**](#statistics-output-thread-properties)

* [nv.aep.\<engine>.stats.interval](#nvaepenginestatsinterval)
* [nv.aep.\<engine>.sysstats.interval](#nvaepenginesysstatsinterval)
* [nv.event.mux.\<name>.stats.interval](#nveventmuxnamestatsinterval)
* [nv.msg.latency.stats.interval](#nvmsglatencystatsinterval)
* [nv.aep.busmanager.\<engine>.\<bus>.stats.interval](#nvaepbusmanagerenginebusstatsinterval)

***

### Statistics Configuration Properties

#### nv.stats.latencymanager.samplesize

* **Description**: Global default size for capturing latencies in ring buffer. Should be large enough to avoid missing datapoints but not so large as to adversely affect processor cache performance.
* **Default**: `nv.stats.series.samplesize`
* **Type**: integer
* **Can Set in `<env>`?**: Yes

#### nv.stats.series.samplesize

* **Description**: Default sampling size for Series stats. If datapoints in a stats interval exceed this size, histographic data computation will be lossy. Increasing reduces loss but increases overhead in memory and cache pressure.
* **Default**: `10240`
* **Type**: integer
* **Can Set in `<env>`?**: Yes

#### nv.msg.latency.stats

* **Description**: Collect latency statistics for messages passing through the processing pipeline. When disabled, many latency stats will not be available in heartbeats.
* **Default**: `false`
* **Type**: boolean
* **Can Set in `<env>`?**: Yes

#### nv.msgtype.latency.stats

* **Description**: Track message latency stats on a per-type basis. Each message type's timings are tracked separately. Due to overhead, these stats are not included in container heartbeats.
* **Default**: `false`
* **Type**: boolean
* **Can Set in `<env>`?**: Yes

#### nv.ods.latency.stats

* **Description**: Enable collection of microservice store latencies.
* **Default**: `false`
* **Type**: boolean
* **Can Set in `<env>`?**: Yes

#### nv.event.latency.stats

* **Description**: Capture event latency statistics (enqueue/dequeue times across event multiplexers). Useful for determining if engine's input queue is backing up. Required to capture input queuing times.
* **Default**: `false`
* **Type**: boolean
* **Can Set in `<env>`?**: Yes

#### nv.link.network.stampiots

* **Description**: Instruct low-level socket I/O to stamp input/output times. Should be enabled to capture store latencies based on wire time or for certain latencies in direct message bus binding.
* **Default**: `false`
* **Type**: boolean
* **Can Set in `<env>`?**: Yes

***

### Optimization Properties

#### nv.optimizefor

* **Description**: Optimization target for the Rumi runtime. Affects default settings for TCP\_NODELAY, wait strategies, and other performance parameters.
* **Values**: `latency` | `throughput` | `none`
* **Default**: `none`
* **Type**: string
* **Can Set in `<env>`?**: Yes

#### nv.conservecpu

* **Description**: When `true`, use conservative CPU strategies (blocking waits). When `false`, use aggressive strategies (busy spins) for lower latency.
* **Default**: `false`
* **Type**: boolean
* **Can Set in `<env>`?**: Yes

***

### Trace Logging Properties

#### nv.ddl.trace

* **Description**: Enable tracing of DDL parsing and variable substitution. Outputs to logger `nv.ddl` at `INFO` level. Useful for troubleshooting configuration issues.
* **Default**: `false`
* **Type**: boolean
* **Can Set in `<env>`?**: **No** - Must use System property (needed before DDL can be parsed)

#### nv.sma.trace

* **Description**: Trace level for messaging layer (SMA). Controls Rumi messaging trace output. See [Trace Logging](/rumi-core/guides/developing-applications/authoring-user-code/trace-logging.md) for level values.
* **Default**: -
* **Type**: log level
* **Can Set in `<env>`?**: Yes

#### nv.aep.trace

* **Description**: Trace level for AEP engine. Controls transaction processing trace output.
* **Default**: -
* **Type**: log level
* **Can Set in `<env>`?**: Yes

#### nv.sol.trace

* **Description**: Trace level for Solace binding. Controls Solace client library trace output (mapped to CCSMP or JCSMP trace levels). See [Solace Binding - Trace Logging](/rumi-core/guides/developing-applications/configuring-messaging/configuring-bus-connections/solace-binding.md#trace-logging).
* **Default**: -
* **Type**: log level
* **Can Set in `<env>`?**: Yes

***

### Discovery Properties

#### nv.discovery.descriptor

* **Description**: Discovery container connection descriptor. Format: `<protocol>://<address>:<port>`. Example: `nvds://localhost:4090`
* **Default**: -
* **Type**: string
* **Can Set in `<env>`?**: Yes

***

### Statistics Output Thread Properties

Properties controlling development/testing statistics trace threads. In production, use container heartbeats instead.

#### nv.aep.\<engine>.stats.interval

* **Description**: Interval (in seconds) at which engine stats are traced for the named engine. Set to `0` to disable. Stats traced to logger `nv.aep.engine.stats` at `INFO` level. **Note**: Disabling only stops tracing, not collection. Stats can still be collected by container heartbeats. Tracing is NOT zero-garbage.
* **Default**: `0`
* **Type**: integer
* **Can Set in `<env>`?**: Yes

#### nv.aep.\<engine>.sysstats.interval

* **Description**: Interval (in seconds) at which engine sys stats are traced. Set to `0` to disable. Usually not needed; container statistics are preferred.
* **Default**: `0`
* **Type**: integer
* **Can Set in `<env>`?**: Yes

#### nv.event.mux.\<name>.stats.interval

* **Description**: Interval (in seconds) at which multiplexer stats are traced. Also reported in engine stats if `nv.aep.<engine>.stats.interval` is set.
* **Default**: `0`
* **Type**: integer
* **Can Set in `<env>`?**: Yes

#### nv.msg.latency.stats.interval

* **Description**: Interval (in seconds) at which message latency stats are traced. No effect if `nv.msg.latency.stats` is `false`. Also reported in engine stats if enabled.
* **Default**: `0`
* **Type**: integer
* **Can Set in `<env>`?**: Yes

#### nv.aep.busmanager.\<engine>.\<bus>.stats.interval

* **Description**: Interval (in seconds) at which bus stats are traced for a specific bus. Also reported in engine stats if enabled.
* **Default**: `0`
* **Type**: integer
* **Can Set in `<env>`?**: Yes

***

## DDL Elements Reference

DDL (Domain Descriptor Language) is Rumi's XML-based configuration schema for defining microservice components.

**About DDL Overrides**: Throughout this reference, each element and attribute shows its **DDL Override** property pattern (e.g., `x.apps.myapp.storage.enabled`). These override properties can be used to:

1. **Set values** for elements not present in your DDL XML file
2. **Override values** for elements that are present in your DDL XML file

This allows you to externalize configuration values without modifying the DDL file, which is useful for environment-specific settings and CI/CD deployments. See [Configuration Model](/rumi-core/concepts/microservice-architecture/configuration-model.md#ddl-overrides) for details on how DDL overrides work.

### Complete DDL Structure

```xml
<model>
  <!-- Global environment configuration -->
  <env>
    <nv>
      <msg.latency.stats>true</msg.latency.stats>
      <optimizefor>latency</optimizefor>
    </nv>
    <myapp>
      <property>value</property>
    </myapp>
  </env>

  <!-- System identification -->
  <systemDetails>
    <name>my-system</name>
    <displayName>My Trading System</displayName>
    <version>1.0.0</version>
  </systemDetails>

  <!-- Custom bus providers (optional) -->
  <busProviders>
    <provider name="custom-provider" providerClass="com.example.CustomProvider" displayName="Custom Provider"/>
  </busProviders>

  <!-- Message buses -->
  <buses>
    <templates>
      <template name="bus-template">
        <!-- Template configuration -->
      </template>
    </templates>
    <bus name="market-data" descriptor="solace://host:port">
      <channels>
        <channel name="orders" qos="Guaranteed" join="true">
          <key>order.new</key>
        </channel>
      </channels>
    </bus>
  </buses>

  <!-- Engines (Microservices) -->
  <services>
    <templates>
      <template name="app-template">
        <!-- Template configuration -->
      </template>
    </templates>
    <service name="order-processor" mainClass="com.example.OrderProcessor">
      <!-- Engine configuration (see Engine Configuration below) -->
    </service>
  </service>

  <!-- containers (Execution Containers) -->
  <containers>
    <templates>
      <template name="container-template">
        <!-- Template configuration -->
      </template>
    </templates>
    <container name="trading-container">
      <!-- container configuration (see container Configuration below) -->
    </container>
  </containers>

  <!-- Profiles for environment-specific config -->
  <profiles>
    <profile name="production">
      <!-- Override config for production -->
    </profile>
    <profile name="development">
      <!-- Override config for development -->
    </profile>
  </profiles>
</model>
```

### DDL Elements Index

* [System Details](#system-details) - System identification and metadata
* [Environment Configuration](#environment-configuration) - Global environment properties
* [Message Bus Provider Configuration](#message-bus-provider-configuration) - Custom bus provider registration
* [Message Bus Configuration](#message-bus-configuration) - Message buses, templates, and channels
* [Engine Configuration](#engine-configuration) - Microservice runtime configuration (AEP engines)
  * [Storage Configuration](#storage-configuration) - Clustering, persistence, ICR
  * [Messaging Configuration](#messaging-configuration) - Message factories and bus associations
  * [Statistics Configuration](#statistics-configuration) - Latency and performance statistics
  * [Message Logging](#message-logging) - Inbound and outbound message logging
  * [Threading Configuration](#threading-configuration) - Event multiplexer configuration
  * [Transaction Configuration](#transaction-configuration) - Adaptive batching
  * [Replication and Transaction Control](#replication-and-transaction-control) - Replication settings
  * [Policy Configuration](#policy-configuration) - Exception and failure policies
  * [Trace Configuration](#trace-configuration) - Debug trace settings
* [container Configuration](#container-configuration) - Execution container configuration
  * [Provisioning Configuration](#provisioning-configuration) - Host and directory configuration
  * [Heartbeats and Monitoring](#heartbeats-and-monitoring) - Statistics collection and emission
  * [Admin Configuration](#admin-configuration) - Administration and monitoring transports
* [Enums Reference](#enums-reference) - Enumerated type values
* [Reusable Element Groups](#reusable-element-groups) - XSD groups (EventMultiplexerProperties)
* [Groups Reference](#groups-reference) - Reusable configuration groups
* [DDL Profiles](#ddl-profiles) - Environment-specific configuration

***

### System Details

System identification and metadata.

**Sample:**

```xml
<systemDetails>
  <name>nvx-app-trading</name>
  <displayName>Trading Application</displayName>
  <version>3.16-SNAPSHOT</version>
</systemDetails>
```

**Elements:**

* **name** (required): Unique system name used to identify the application (max 256 chars). Should be a short, descriptive identifier. Pattern: `(.|:|-|_|\w)+`
  * **DDL Override**: `x.systemDetails.name`
* **displayName** (optional): Human-readable display name (max 256 chars)
  * **DDL Override**: `x.systemDetails.displayName`
* **version** (optional): Version identifier (max 128 chars). Can be compared lexigraphically by splitting on '.' character
  * **DDL Override**: `x.systemDetails.version`

***

### Environment Configuration

The `<env>` element populates the global environment (not the configuration repository). Properties specified here have the highest precedence among all environment sources.

**Sample:**

```xml
<env>
  <nv>
    <!-- Rumi runtime properties -->
    <msg.latency.stats>true</msg.latency.stats>
    <optimizefor>latency</optimizefor>
    <sma.trace>info</sma.trace>
  </nv>
  <myapp>
    <!-- Application-specific properties -->
    <maxOrderSize>1000000</maxOrderSize>
    <tradingVenue>NYSE</tradingVenue>
  </myapp>
</env>
```

Properties can be organized hierarchically using element nesting. The `<nv>` namespace is reserved for Rumi runtime properties. User applications should use their own namespace.

**DDL Override Pattern:**

Any property in the `<env>` block can be overridden using the pattern:

```
x.env.<property-path>
```

For example:

* `<nv><msg.latency.stats>true</msg.latency.stats></nv>` can be overridden with `x.env.nv.msg.latency.stats=false`
* `<myapp><maxOrderSize>1000000</maxOrderSize></myapp>` can be overridden with `x.env.myapp.maxOrderSize=500000`

**Accessing in Code:**

```java
@Configured(property = "myapp.maxOrderSize", defaultValue = "100000")
private int maxOrderSize;
```

***

### Message Bus Provider Configuration

Register custom message bus providers (Since 3.8).

**Sample:**

```xml
<busProviders>
  <provider name="custom-kafka" providerClass="com.example.CustomKafkaProvider" displayName="Custom Kafka Provider" enabled="true"/>
  <provider name="x-amqp" providerClass="com.example.AmqpProvider" enabled="true"/>
</busProviders>
```

**Attributes:**

* **name** (required): Unique identifier for the bus provider (max 32 chars). Pattern: `([a-z][a-z0-9+\-.]+)`. Recommended to prefix custom providers with 'x-' to avoid conflicts with platform providers
  * **DDL Override**: Not overridable (key)
* **providerClass** (required): Fully qualified class name implementing `com.neeve.sma.MessagingProvider`
  * **DDL Override**: `x.busProviders.<providerName>.providerClass`
* **displayName** (optional): Friendly name for the message bus provider
  * **DDL Override**: `x.busProviders.<providerName>.displayName`
* **enabled** (optional, default: `true`): Enable/disable this bus provider
  * **DDL Override**: `x.busProviders.<providerName>.enabled`

***

### Message Bus Configuration

Define message buses and their channels.

**Sample:**

```xml
<buses>
  <templates>
    <template name="solace-template">
      <provider>solace</provider>
      <properties>
        <vpn_name>trading</vpn_name>
      </properties>
    </template>
  </templates>
  <bus name="market-data" descriptor="solace://192.168.1.9:55555">
    <channels>
      <channel name="orders" qos="Guaranteed" join="true">
        <key>order.new</key>
      </channel>
    </channels>
  </bus>
</buses>
```

**Elements:**

* [**templates**](#bus-templates): Reusable bus configuration templates
* [**bus**](#bus-element): Message bus definitions and channels

#### Bus Templates

Define reusable bus configuration (Since 3.8).

```xml
<buses>
  <templates>
    <template name="solace-template">
      <provider>solace</provider>
      <properties>
        <vpn_name>trading</vpn_name>
        <username>app</username>
        <password>secret</password>
      </properties>
    </template>
  </templates>

  <bus name="market-data" template="solace-template">
    <address>192.168.1.9</address>
    <port>55555</port>
  </bus>
</buses>
```

**Attributes:**

* **@name** (required): Unique template identifier
  * **DDL Override**: Not overridable (key)

**Elements:**

* Any bus attribute or element can be used in a template
  * **DDL Override**: `x.buses.templates.<templatename>.*`

Templates are applied first, then bus-specific settings override template values.

#### Bus Element

Define a message bus and its channels.

**Sample:**

```xml
<buses>
  <bus name="market-data" descriptor="solace://192.168.1.9:55555&vpn_name=trading&username=app&password=secret" enabled="true">
    <channels>
      <channel name="orders" qos="Guaranteed" join="true">
        <key>order.new</key>
        <key>order.cancel</key>
      </channel>
      <channel name="quotes" qos="BestEffort" join="true">
        <key>quote.equity</key>
      </channel>
    </channels>
  </bus>
  <!-- Alternative: use properties element -->
  <bus name="market-data-2" provider="solace" address="192.168.1.10" port="55555" enabled="true">
    <properties>
      <vpn_name>trading</vpn_name>
      <username>app</username>
      <password>secret</password>
    </properties>
  </bus>
</buses>
```

**Attributes:**

* **@name** (required): Unique bus identifier
  * **DDL Override**: Not overridable (key)
* **@descriptor** (conditional): Bus descriptor string (format: `<provider>://<address>:<port>&<props>`). Required if `provider`/`address` not used separately
  * **DDL Override**: `x.buses.bus.<busname>.descriptor`
* **@provider** (conditional): Bus provider name (e.g., `solace`, `jms`, `kafka`, `loopback`). Required if `descriptor` not used
  * **DDL Override**: `x.buses.bus.<busname>.provider`
* **@address** (optional): Bus container address
  * **DDL Override**: `x.buses.bus.<busname>.address`
* **@port** (optional): Bus container port
  * **DDL Override**: `x.buses.bus.<busname>.port`
* **@enabled** (optional, default: `true`): Enable/disable this bus
  * **DDL Override**: `x.buses.bus.<busname>.enabled`

**Elements:**

* **provider**: Provider name (alternative to descriptor)
  * **DDL Override**: `x.buses.bus.<busname>.provider`
* **address**: Server address (alternative to descriptor)
  * **DDL Override**: `x.buses.bus.<busname>.address`
* **port**: Server port (alternative to descriptor)
  * **DDL Override**: `x.buses.bus.<busname>.port`
* **properties**: Provider-specific properties (alternative to descriptor string parameters)
  * **DDL Override**: `x.buses.bus.<busname>.properties.*`
* [**channels**](#messaging-configuration): Channel definitions

**Provider-Specific Configuration:**

* [Solace Binding](/rumi-core/guides/developing-applications/configuring-messaging/configuring-bus-connections/solace-binding.md)
* [JMS Binding](/rumi-core/guides/developing-applications/configuring-messaging/configuring-bus-connections/jms-binding.md)
* [Kafka Binding](https://github.com/rumidata/nvx-rumi-docs/blob/develop/core/developing-applications/configuring-messaging/configuring-bus-connections/kafka-binding.md)
* [Loopback Binding](/rumi-core/guides/developing-applications/configuring-messaging/configuring-bus-connections/loopback-binding.md)

**Channel Configuration**

**Sample:**

```xml
<channel name="orders" join="true" detached="false">
  <qos>Guaranteed</qos>
  <key>order.new</key>
  <key>order.cancel</key>
  <key>order.replace</key>
  <id>1</id>
</channel>
```

**Attributes:**

* **name** (required): Unique channel identifier within the bus
  * **DDL Override**: Not overridable (key)
* **join** (optional, default: `false`): Whether to subscribe to this channel
  * **DDL Override**: `x.buses.<busname>.<channelname>.join`
* **detached** (optional, default: `false`): Enable detached sends (asynchronous transmission)
  * **DDL Override**: `x.buses.<busname>.<channelname>.detached`

**Elements:**

* **qos** (optional, default: `BestEffort`): Quality of service element (values: `BestEffort` | `Guaranteed`)
  * **DDL Override**: `x.buses.<busname>.<channelname>.qos`
* **key**: Topic/queue key(s) for message routing. Multiple `<key>` elements allowed
  * **DDL Override**: `x.buses.<busname>.<channelname>.key`
* **id** (optional): Numerical identifier for the channel within the bus
  * **DDL Override**: `x.buses.<busname>.<channelname>.id`

**Quality of Service:**

* **BestEffort**: Messages delivered with best effort, no acknowledgment or persistence
* **Guaranteed**: Messages acknowledged and persisted by messaging infrastructure

***

### Engine Configuration

The `<services>` section configures AEP engines, which are the microservice runtime containers. Each engine (app) represents a microservice and defines its runtime behavior including messaging, storage, high availability, transactions, and statistics.

#### Engine Configuration Index

* [Core Engine Settings](#core-engine-settings) - Name and main class
* [Messaging Configuration](#messaging-configuration)
  * [Message Factories](#messaging-configuration)
  * [Bus Associations](#messaging-configuration)
* [Storage Configuration](#storage-configuration)
  * [Clustering](#storage-configuration) - High availability clustering
  * [Persistence](#storage-configuration) - Disk-based persistence
  * [Inter-Cluster Replication (ICR)](#storage-configuration) - Geographic replication
* [Transaction Configuration](#transaction-configuration) - Adaptive batching settings
* [Statistics Configuration](#statistics-configuration) - Latency and performance statistics
* [Message Logging](#message-logging) - Inbound and outbound message logging
* [Threading Configuration](#threading-configuration) - Event multiplexer and queue settings
* [Duplicate Detection](#duplicate-detection) - Duplicate message detection

#### Complete Engine Configuration Example

```xml
<services>
  <service name="order-processor" mainClass="com.example.OrderProcessor">

    <!-- Messaging Configuration -->
    <messaging>
      <factories>
        <factory name="com.example.messages.OrderMessageFactory"/>
        <factory name="com.example.messages.TradeMessageFactory"/>
      </factories>
      <buses>
        <bus name="market-data">
          <channels>
            <channel name="orders" join="true"/>
            <channel name="quotes" join="true"/>
          </channels>
        </bus>
        <bus name="admin">
          <channels>
            <channel name="admin-commands" join="true"/>
          </channels>
        </bus>
      </buses>
    </messaging>

    <!-- Storage and High Availability -->
    <storage enabled="true">
      <clustering enabled="true">
        <storeName>order-store</storeName>
        <localPort>10000</localPort>
      </clustering>
      <persistence enabled="true">
        <flushOnCommit>false</flushOnCommit>
        <storeRoot>rdat</storeRoot>
      </persistence>
    </storage>

    <!-- Transaction Configuration -->
    <adaptiveCommitBatchCeiling>100</adaptiveCommitBatchCeiling>

    <!-- Statistics Configuration -->
    <captureTransactionLatencyStats>true</captureTransactionLatencyStats>
    <captureEventLatencyStats>true</captureEventLatencyStats>
    <captureMessageTypeStats>false</captureMessageTypeStats>
    <messageTypeStatsLatenciesToCapture>all</messageTypeStatsLatenciesToCapture>

    <!-- Message Logging -->
    <inboundMessageLogging policy="Off" failurePolicy="StopLogging"/>
    <outboundMessageLogging policy="Off" failurePolicy="StopLogging"/>

    <!-- Threading -->
    <inboundEventMultiplexing type="DedicatedThreaded">
      <queueDepth>1024</queueDepth>
    </inboundEventMultiplexing>

    <!-- Duplicate Detection -->
    <performDuplicateChecking>true</performDuplicateChecking>

  </service>
</service>
```

#### Core Engine Settings

**Sample:**

```xml
<service name="order-processor" mainClass="com.example.OrderProcessor">
  <!-- Additional configuration... -->
</service>
```

**Attributes:**

* **name** (required): Unique application identifier
  * **DDL Override**: Not overridable (key)
* **mainClass** (required): Fully qualified class name of the main event handler
  * **DDL Override**: `x.apps.<appname>.mainClass`
* **enabled** (optional, default: `true`): Enable/disable this application
  * **DDL Override**: `x.apps.<appname>.enabled`

#### Messaging Configuration

Configures messaging factories and bus associations for the engine.

**Sample:**

```xml
<service name="order-processor" mainClass="com.example.OrderProcessor">
  <messaging>
    <factories>
      <factory name="com.example.messages.OrderMessageFactory"/>
    </factories>
    <buses>
      <bus name="market-data">
        <channels>
          <channel name="orders" join="true"/>
        </channels>
        <detachedSend enabled="true">
          <queueDepth>1024</queueDepth>
        </detachedSend>
      </bus>
    </buses>
  </messaging>
</service>
```

**Elements:**

* [**factories**](#messaging-configuration): Message factory configuration
* [**buses**](#messaging-configuration): Bus associations and channel subscriptions

**Message Factories**

**Sample:**

```xml
<service name="order-processor" mainClass="com.example.OrderProcessor">
  <messaging>
    <factories>
      <factory name="com.example.messages.OrderMessageFactory"/>
      <factory name="com.example.messages.TradeMessageFactory"/>
    </factories>
  </messaging>
</service>
```

**Elements:**

* **messaging/factories/factory**: Message factory configuration
  * **@name** (required): Message factory class name
    * **DDL Override**: Not overridable (key)

**Bus Associations**

Configure bus associations and channel subscriptions for an engine.

**Sample:**

```xml
<service name="order-processor" mainClass="com.example.OrderProcessor">
  <messaging>
    <buses>
      <bus name="market-data" manualStart="false" enabled="true">
        <nonBlockingInboundMessageDispatch>false</nonBlockingInboundMessageDispatch>
        <inboundMessageEventPriority>10</inboundMessageEventPriority>
        <scheduleSendCommitCompletionEvents>false</scheduleSendCommitCompletionEvents>
        <sendCommitCompletionEventPriority>5</sendCommitCompletionEventPriority>
        <channels>
          <channel name="orders" join="true">
            <filter>symbol='AAPL'</filter>
            <preserveJoinsOnClose>Default</preserveJoinsOnClose>
          </channel>
          <channel name="quotes" join="true"/>
        </channels>
        <detachedSend enabled="true">
          <queueDepth>1024</queueDepth>
        </detachedSend>
      </bus>
    </buses>
  </messaging>
</service>
```

**Attributes:**

* **@name** (required): Bus name reference
  * **DDL Override**: Not overridable (key)
* **@manualStart** (default: `false`): Require manual start of bus binding
  * **DDL Override**: `x.apps.<appname>.messaging.buses.<busname>.manualStart`
* **@enabled** (default: `true`): Enable/disable this bus association
  * **DDL Override**: `x.apps.<appname>.messaging.buses.<busname>.enabled`

**Elements:**

* **nonBlockingInboundMessageDispatch** (default: `false`): Enable non-blocking inbound message dispatch
  * **DDL Override**: `x.apps.<appname>.messaging.buses.<busname>.nonBlockingInboundMessageDispatch`
* **inboundMessageEventPriority**: Priority for inbound message events
  * **DDL Override**: `x.apps.<appname>.messaging.buses.<busname>.inboundMessageEventPriority`
* **scheduleSendCommitCompletionEvents** (default: `false`): Schedule send commit completion events
  * **DDL Override**: `x.apps.<appname>.messaging.buses.<busname>.scheduleSendCommitCompletionEvents`
* **sendCommitCompletionEventPriority**: Priority for send commit completion events
  * **DDL Override**: `x.apps.<appname>.messaging.buses.<busname>.sendCommitCompletionEventPriority`
* [**channels**](#messaging-configuration): Channel subscription configuration
* [**detachedSend**](#messaging-configuration): Detached send configuration

**Channel Subscriptions**

Configure channel subscriptions and filters for a bus.

**Sample:**

```xml
<bus name="market-data">
  <channels>
    <channel name="orders" join="true">
      <filter>symbol='AAPL' OR symbol='MSFT'</filter>
      <preserveJoinsOnClose>Preserve</preserveJoinsOnClose>
    </channel>
    <channel name="quotes" join="true">
      <filter>exchange='NYSE'</filter>
    </channel>
    <channel name="trades" join="false"/>
  </channels>
</bus>
```

**Elements:**

* **channel**: Channel subscription configuration
  * **@name** (required): Channel name
    * **DDL Override**: Not overridable (key)
  * **@join** (required): Whether to join the channel
    * **DDL Override**: `x.apps.<appname>.messaging.buses.<busname>.<channelname>.join`
  * **filter**: Message filter expression for the channel
    * **DDL Override**: `x.apps.<appname>.messaging.buses.<busname>.<channelname>.filter`
  * **preserveJoinsOnClose**: Policy for preserving joins on bus close (values: `Default` | `Preserve` | `NoPreserve`)
    * **DDL Override**: `x.apps.<appname>.messaging.buses.<busname>.<channelname>.preserveJoinsOnClose`

**Detached Send Configuration**

Configure detached (asynchronous) send for a bus.

**Sample:**

```xml
<bus name="market-data">
  <detachedSend enabled="true">
    <queueDepth>2048</queueDepth>
    <queueOfferStrategy>Block</queueOfferStrategy>
    <queueWaitStrategy>BusySpin</queueWaitStrategy>
    <queueDrainerCpuAffinityMask>0x02</queueDrainerCpuAffinityMask>
    <queueFeedMaxConcurrency>1</queueFeedMaxConcurrency>
  </detachedSend>
</bus>
```

**Attributes:**

* **@enabled**: Enable/disable detached send
  * **DDL Override**: `x.apps.<appname>.messaging.buses.<busname>.detachedSend.enabled`

**Elements:**

* Includes all [EventMultiplexerProperties](#eventmultiplexerproperties): `queueDepth`, `queueOfferStrategy`, `queueWaitStrategy`, `queueDrainerCpuAffinityMask`, `queueFeedMaxConcurrency`
  * **DDL Override**: `x.apps.<appname>.messaging.buses.<busname>.detachedSend.<property>`

#### Storage Configuration

Configures storage, clustering, persistence, and inter-cluster replication.

**Sample:**

```xml
<service name="order-processor" mainClass="com.example.OrderProcessor">
  <storage enabled="true">
    <!-- State factories -->
    <factories>
      <factory name="com.example.OrderStateFactory"/>
    </factories>

    <!-- Clustering configuration -->
    <clustering enabled="true">
      <storeName>order-store</storeName>
      <localPort>10000</localPort>
    </clustering>

    <!-- Persistence configuration -->
    <persistence enabled="true">
      <flushOnCommit>false</flushOnCommit>
      <storeRoot>rdat</storeRoot>
      <compaction>
        <compactOnStart>false</compactOnStart>
        <compactionThreshold>1024</compactionThreshold>
      </compaction>
    </persistence>

    <!-- ICR configuration -->
    <icr enabled="false"/>

    <!-- Quorum and sync settings -->
    <persistenceQuorum>2</persistenceQuorum>
    <maxPersistSyncBacklog>0</maxPersistSyncBacklog>
    <icrQuorum>2</icrQuorum>
    <maxIcrSyncBacklog>0</maxIcrSyncBacklog>

    <!-- Checkpointing -->
    <!-- <checkpointingType>Default</checkpointingType> -->
    <!-- <checkpointThreshold>10000</checkpointThreshold> -->
    <!-- <checkpointMaxInterval>60000</checkpointMaxInterval> -->

    <!-- Advanced settings -->
    <detachedMemberInitialization>false</detachedMemberInitialization>
    <!-- <detachedMemberInitializerCpuAffinityMask>0x01</detachedMemberInitializerCpuAffinityMask> -->
    <!-- <queryable>false</queryable> -->
  </storage>
</service>
```

**Attributes:**

* **@enabled** (default: `true`): Enable/disable the store for this application
  * **DDL Override**: `x.apps.<appname>.storage.enabled`

**Elements:**

* **persistenceQuorum** (default: `2`): Minimum number of cluster members for asynchronous persistence commits
  * **DDL Override**: `x.apps.<appname>.storage.persistenceQuorum`
* **maxPersistSyncBacklog** (default: `0`): Maximum time in seconds before forcing persister sync (0 = disabled)
  * **DDL Override**: `x.apps.<appname>.storage.maxPersistSyncBacklog`
* **icrQuorum** (default: `2`): Minimum number of cluster members for asynchronous ICR commits
  * **DDL Override**: `x.apps.<appname>.storage.icrQuorum`
* **maxIcrSyncBacklog** (default: `0`): Maximum time in seconds before forcing ICR sender sync (0 = disabled)
  * **DDL Override**: `x.apps.<appname>.storage.maxIcrSyncBacklog`
* **checkpointingType**: Checkpoint controller type (values: `Default` | `CDC` | `Conflation`)
  * **DDL Override**: `x.apps.<appname>.storage.checkpointingType`
* **checkpointThreshold**: Maximum entries before incrementing checkpoint version
  * **DDL Override**: `x.apps.<appname>.storage.checkpointThreshold`
* **checkpointMaxInterval**: Maximum time in milliseconds between checkpoints
  * **DDL Override**: `x.apps.<appname>.storage.checkpointMaxInterval`
* **detachedMemberInitialization** (default: `false`): Enable non-blocking cluster join
  * **DDL Override**: `x.apps.<appname>.storage.detachedMemberInitialization`
* **detachedMemberInitializerCpuAffinityMask**: CPU affinity for detached initializer thread
  * **DDL Override**: `x.apps.<appname>.storage.detachedMemberInitializerCpuAffinityMask`
* **queryable**: Enable SQL-like querying of in-memory store contents (experimental)
  * **DDL Override**: `x.apps.<appname>.storage.queryable`
* **discoveryDescriptor**: *Deprecated* - use `clustering/discoveryDescriptor` instead
  * **DDL Override**: `x.apps.<appname>.storage.discoveryDescriptor`
* [**factories**](#storage-configuration): State factory configuration
* [**clustering**](#storage-configuration): Store clustering configuration
* [**persistence**](#storage-configuration): Disk persistence configuration
* [**icr**](#storage-configuration): Inter-cluster replication configuration

**State Factories**

Configure state factory classes for the microservice store.

**Sample:**

```xml
<storage enabled="true">
  <factories>
    <factory name="com.example.OrderStateFactory"/>
    <factory name="com.example.TradeStateFactory"/>
  </factories>
</storage>
```

**Elements:**

* **factory/@name** (required): State factory class name
  * **DDL Override**: Not overridable (key)

**Clustering**

Configures store clustering for high availability. Applications with the same store name automatically form a cluster.

**Sample:**

```xml
<service name="order-processor" mainClass="com.example.OrderProcessor">
  <storage enabled="true">
    <clustering enabled="true">
      <storeName>my-store</storeName>
      <localPort>10000</localPort>
      <localIfAddr>192.168.1.100</localIfAddr>
      <linkParams>SO_REUSEADDR=true,TCP_NODELAY=true</linkParams>
      <discoveryDescriptor>nvds://localhost:4090</discoveryDescriptor>
      <initWaitTime>5000</initWaitTime>
      <failOnMultiplePrimaries>true</failOnMultiplePrimaries>
      <memberElectionPriority>100</memberElectionPriority>
      <detachedSend enabled="true">
        <queueDepth>1024</queueDepth>
      </detachedSend>
      <detachedDispatch enabled="true">
        <queueDepth>1024</queueDepth>
      </detachedDispatch>
    </clustering>
  </storage>
</service>
```

**Attributes:**

* **@enabled** (default: `true`): Enable/disable store clustering
  * **DDL Override**: `x.apps.<appname>.storage.clustering.enabled`

**Elements:**

* **storeName**: Name of the store. Applications with the same store name form a cluster
  * **DDL Override**: `x.apps.<appname>.storage.clustering.storeName`
* **localPort**: TCP port to bind to when listening for cluster connections
  * **DDL Override**: `x.apps.<appname>.storage.clustering.localPort`
* **localIfAddr**: Local network interface to bind to for cluster connections
  * **DDL Override**: `x.apps.<appname>.storage.clustering.localIfAddr`
* **linkParams**: Comma-separated key=value pairs for cluster connection parameters
  * **DDL Override**: `x.apps.<appname>.storage.clustering.linkParams`
* **linkReaderCpuAffinityMask**: CPU affinity for cluster connection reader thread
  * **DDL Override**: `x.apps.<appname>.storage.clustering.linkReaderCpuAffinityMask`
* **discoveryDescriptor**: Custom discovery descriptor for the store cluster
  * **DDL Override**: `x.apps.<appname>.storage.clustering.discoveryDescriptor`
* [**discovery**](#storage-configuration): Alternative to discoveryDescriptor for defining discovery provider
* **initWaitTime**: Time in milliseconds to wait for cluster to stabilize on open
  * **DDL Override**: `x.apps.<appname>.storage.clustering.initWaitTime`
* **failOnMultiplePrimaries** (default: `true`): Whether to fail on detecting multiple primaries
  * **DDL Override**: `x.apps.<appname>.storage.clustering.failOnMultiplePrimaries`
* **memberElectionPriority** (default: `255`): Leader election priority (lower wins)
  * **DDL Override**: `x.apps.<appname>.storage.clustering.memberElectionPriority`
* [**detachedSend**](#storage-configuration): Detached replication sender configuration
* [**detachedDispatch**](#storage-configuration): Detached replication dispatcher configuration

**Clustering Discovery**

Alternative to discoveryDescriptor for defining discovery provider.

**Sample:**

```xml
<clustering enabled="true">
  <discovery>
    <provider>nvds</provider>
    <address>localhost</address>
    <port>4090</port>
    <properties>
      <property key="custom.property" value="value"/>
    </properties>
  </discovery>
</clustering>
```

**Elements:**

* **provider**: Discovery provider name
  * **DDL Override**: `x.apps.<appname>.storage.clustering.discovery.provider`
* **address**: Discovery container address
  * **DDL Override**: `x.apps.<appname>.storage.clustering.discovery.address`
* **port**: Discovery container port (optional)
  * **DDL Override**: `x.apps.<appname>.storage.clustering.discovery.port`
* **properties**: Discovery properties
  * **DDL Override**: `x.apps.<appname>.storage.clustering.discovery.properties.*`

**Detached Replication Send**

Configure detached replication sender thread for asynchronous cluster replication.

**Sample:**

```xml
<clustering enabled="true">
  <detachedSend enabled="true">
    <queueDepth>2048</queueDepth>
    <queueOfferStrategy>Block</queueOfferStrategy>
    <queueWaitStrategy>BusySpin</queueWaitStrategy>
    <queueDrainerCpuAffinityMask>0x04</queueDrainerCpuAffinityMask>
    <queueFeedMaxConcurrency>1</queueFeedMaxConcurrency>
  </detachedSend>
</clustering>
```

**Attributes:**

* **@enabled**: Enable/disable detached send
  * **DDL Override**: `x.apps.<appname>.storage.clustering.detachedSend.enabled`

**Elements:**

* Includes all [EventMultiplexerProperties](#eventmultiplexerproperties): `queueDepth`, `queueOfferStrategy`, `queueWaitStrategy`, `queueDrainerCpuAffinityMask`, `queueFeedMaxConcurrency`
  * **DDL Override**: `x.apps.<appname>.storage.clustering.detachedSend.<property>`

**Detached Replication Dispatch**

Configure detached replication dispatcher thread for asynchronous cluster replication processing.

**Sample:**

```xml
<clustering enabled="true">
  <detachedDispatch enabled="true">
    <queueDepth>2048</queueDepth>
    <queueOfferStrategy>Block</queueOfferStrategy>
    <queueWaitStrategy>BusySpin</queueWaitStrategy>
    <queueDrainerCpuAffinityMask>0x08</queueDrainerCpuAffinityMask>
    <queueFeedMaxConcurrency>1</queueFeedMaxConcurrency>
  </detachedDispatch>
</clustering>
```

**Attributes:**

* **@enabled**: Enable/disable detached dispatch
  * **DDL Override**: `x.apps.<appname>.storage.clustering.detachedDispatch.enabled`

**Elements:**

* Includes all [EventMultiplexerProperties](#eventmultiplexerproperties): `queueDepth`, `queueOfferStrategy`, `queueWaitStrategy`, `queueDrainerCpuAffinityMask`, `queueFeedMaxConcurrency`
  * **DDL Override**: `x.apps.<appname>.storage.clustering.detachedDispatch.<property>`

**Persistence**

Configures disk-based persistence for the store's transaction log.

**Sample:**

```xml
<service name="order-processor" mainClass="com.example.OrderProcessor">
  <storage enabled="true">
    <persistence enabled="true" class="native">
      <shared>false</shared>
      <flushOnCommit>false</flushOnCommit>
      <autoFlushSize>8192</autoFlushSize>
      <storeRoot>rdat</storeRoot>
      <cdcEnabled>false</cdcEnabled>
      <autoRepair>false</autoRepair>
      <logScavengePolicy>Delete</logScavengePolicy>
      <logBackupRetentionCount>5</logBackupRetentionCount>
      <initialLogLength>10mb</initialLogLength>
      <zeroOutInitial>false</zeroOutInitial>
      <flushUsingMappedMemory>false</flushUsingMappedMemory>
      <pageSize>8kb</pageSize>
      <compaction>
        <compactOnStart>false</compactOnStart>
        <compactionThreshold>1024</compactionThreshold>
        <maxCompactionWindowSize>512</maxCompactionWindowSize>
      </compaction>
      <cdc>
        <entryRetentionThreshold>10000</entryRetentionThreshold>
        <skipCdcCheckpointed>true</skipCdcCheckpointed>
      </cdc>
      <detachedPersist enabled="true">
        <queueDepth>1024</queueDepth>
      </detachedPersist>
    </persistence>
  </storage>
</service>
```

**Attributes:**

* **@enabled** (default: `true`): Enable/disable disk persistence
  * **DDL Override**: `x.apps.<appname>.storage.persistence.enabled`
* **@class** (default: `native`): Custom persister class implementation
  * **DDL Override**: `x.apps.<appname>.storage.persistence.class`

**Elements:**

* **shared** (default: `false`): Whether this is a shared persister
  * **DDL Override**: `x.apps.<appname>.storage.persistence.shared`
* **flushOnCommit** (default: `false`): Whether to flush persister on commit
  * **DDL Override**: `x.apps.<appname>.storage.persistence.flushOnCommit`
* **autoFlushSize** (default: `8192`): Size at which flush is automatically triggered for queued writes
  * **DDL Override**: `x.apps.<appname>.storage.persistence.autoFlushSize`
* **autoRepair**: Automatically repair logs by truncating malformed entries
  * **DDL Override**: `x.apps.<appname>.storage.persistence.autoRepair`
* **storeRoot**: Root folder for persister's transaction log files
  * **DDL Override**: `x.apps.<appname>.storage.persistence.storeRoot`
* **cdcEnabled** (default: `false`): Enable change data capture (StateReplication only)
  * **DDL Override**: `x.apps.<appname>.storage.persistence.cdcEnabled`
* **logScavengePolicy**: Policy for scavenging obsolete logs (values: `Delete` | `Disabled`)
  * **DDL Override**: `x.apps.<appname>.storage.persistence.logScavengePolicy`
* **logBackupRetentionCount**: Maximum retention count for log backups
  * **DDL Override**: `x.apps.<appname>.storage.persistence.logBackupRetentionCount`
* **initialLogLength**: Initial file size of transaction log (preallocated)
  * **DDL Override**: `x.apps.<appname>.storage.persistence.initialLogLength`
* **zeroOutInitial**: Explicitly zero out log file on creation
  * **DDL Override**: `x.apps.<appname>.storage.persistence.zeroOutInitial`
* **flushUsingMappedMemory**: Use memory mapped file buffer for flushes
  * **DDL Override**: `x.apps.<appname>.storage.persistence.flushUsingMappedMemory`
* **pageSize** (default: `8kb`): Disk page size hint for optimization
  * **DDL Override**: `x.apps.<appname>.storage.persistence.pageSize`
* [**compaction**](#storage-configuration): Log compaction configuration
* [**cdc**](#storage-configuration): Change data capture configuration
* [**detachedPersist**](#storage-configuration): Detached persistence configuration

**Compaction Configuration**

Log compaction configuration (StateReplication only).

**Sample:**

```xml
<persistence enabled="true">
  <compaction>
    <compactOnStart>false</compactOnStart>
    <compactionThreshold>1024</compactionThreshold>
    <maxCompactionWindowSize>512</maxCompactionWindowSize>
    <entryRetentionThreshold>10000</entryRetentionThreshold>
    <conflateCheckpoints>true</conflateCheckpoints>
    <offheapBuffering>false</offheapBuffering>
    <offheapBufferingLoadStrategy>MemoryMappedRead</offheapBufferingLoadStrategy>
    <offheapBufferingMaxPageSize>64kb</offheapBufferingMaxPageSize>
    <memMappedReadBufferMaxSize>128mb</memMappedReadBufferMaxSize>
    <properties>
      <property key="custom.property" value="value"/>
    </properties>
  </compaction>
</persistence>
```

**Elements:**

* **compactOnStart**: Trigger compaction on startup
  * **DDL Override**: `x.apps.<appname>.storage.persistence.compaction.compactOnStart`
* **compactionThreshold**: Log size that triggers compaction (in MB, ≤0 disables)
  * **DDL Override**: `x.apps.<appname>.storage.persistence.compaction.compactionThreshold`
* **maxCompactionWindowSize**: Maximum size of entries held in memory during compaction (in MB)
  * **DDL Override**: `x.apps.<appname>.storage.persistence.compaction.maxCompactionWindowSize`
* **entryRetentionThreshold**: Maximum entries retained in memory during compaction
  * **DDL Override**: `x.apps.<appname>.storage.persistence.compaction.entryRetentionThreshold`
* **conflateCheckpoints** (default: `true`): Conflate checkpoints before dispatching to handler
  * **DDL Override**: `x.apps.<appname>.storage.persistence.compaction.conflateCheckpoints`
* **offheapBuffering** (default: `false`): Buffer non-retained entries in off-heap memory
  * **DDL Override**: `x.apps.<appname>.storage.persistence.compaction.offheapBuffering`
* **offheapBufferingLoadStrategy**: Load strategy for off-heap buffering (values: `PktReader` | `RandomAccessFile` | `MemoryMappedRead` | `Disabled`)
  * **DDL Override**: `x.apps.<appname>.storage.persistence.compaction.offheapBufferingLoadStrategy`
* **offheapBufferingMaxPageSize**: Maximum size of each off-heap buffer (min: `8kb`)
  * **DDL Override**: `x.apps.<appname>.storage.persistence.compaction.offheapBufferingMaxPageSize`
* **memMappedReadBufferMaxSize**: Max size of memory mapped buffer for MemoryMappedRead strategy
  * **DDL Override**: `x.apps.<appname>.storage.persistence.compaction.memMappedReadBufferMaxSize`
* **properties**: Advanced tuning properties for compactor
  * **DDL Override**: `x.apps.<appname>.storage.persistence.compaction.properties.*`

**Change Data Capture (CDC)**

Change Data Capture configuration for CDC-enabled persistence.

**Sample:**

```xml
<persistence enabled="true" cdcEnabled="true">
  <cdc>
    <entryRetentionThreshold>10000</entryRetentionThreshold>
    <skipCdcCheckpointed>true</skipCdcCheckpointed>
    <properties>
      <property key="custom.property" value="value"/>
    </properties>
  </cdc>
</persistence>
```

**Elements:**

* **entryRetentionThreshold**: Maximum entries held in memory while processing checkpoints
  * **DDL Override**: `x.apps.<appname>.storage.persistence.cdc.entryRetentionThreshold`
* **skipCdcCheckpointed** (default: `true`): Skip entries above CDC checkpoint version
  * **DDL Override**: `x.apps.<appname>.storage.persistence.cdc.skipCdcCheckpointed`
* **properties**: Advanced tuning properties for CDC
  * **DDL Override**: `x.apps.<appname>.storage.persistence.cdc.properties.*`

**Detached Persistence**

Configure detached persister write thread for asynchronous persistence.

**Sample:**

```xml
<persistence enabled="true">
  <detachedPersist enabled="true">
    <queueDepth>1024</queueDepth>
    <queueOfferStrategy>Block</queueOfferStrategy>
    <queueWaitStrategy>BusySpin</queueWaitStrategy>
    <queueDrainerCpuAffinityMask>0x01</queueDrainerCpuAffinityMask>
    <queueFeedMaxConcurrency>1</queueFeedMaxConcurrency>
  </detachedPersist>
</persistence>
```

**Attributes:**

* **@enabled**: Enable/disable detached persistence
  * **DDL Override**: `x.apps.<appname>.storage.persistence.detachedPersist.enabled`

**Elements:**

* Includes all [EventMultiplexerProperties](#eventmultiplexerproperties): `queueDepth`, `queueOfferStrategy`, `queueWaitStrategy`, `queueDrainerCpuAffinityMask`, `queueFeedMaxConcurrency`
  * **DDL Override**: `x.apps.<appname>.storage.persistence.detachedPersist.<property>`

**Inter-Cluster Replication (ICR)**

Configures inter-cluster replication for sending/receiving updates between geographically distributed clusters.

**Sample:**

```xml
<service name="order-processor" mainClass="com.example.OrderProcessor">
  <storage enabled="true">
    <!-- Using busDescriptor attribute -->
    <icr enabled="true" role="Sender" busDescriptor="solace://remote-mq:7222">
      <shared>false</shared>
      <flushOnCommit>true</flushOnCommit>
      <detachedSend enabled="true">
        <queueDepth>2048</queueDepth>
      </detachedSend>
    </icr>

    <!-- Alternative: using bus element -->
    <!-- <icr enabled="true" role="Sender">
      <shared>false</shared>
      <flushOnCommit>true</flushOnCommit>
      <bus>
        <provider>solace</provider>
        <address>remote-mq</address>
        <port>7222</port>
        <properties>
          <vpn_name>icr-vpn</vpn_name>
        </properties>
      </bus>
      <detachedSend enabled="true">
        <queueDepth>2048</queueDepth>
      </detachedSend>
    </icr> -->
  </storage>
</service>
```

**Attributes:**

* **@enabled** (default: `true`): Enable/disable inter-cluster replication
  * **DDL Override**: `x.apps.<appname>.storage.icr.enabled`
* **@role** (required): ICR role - `Sender` or `StandaloneReceiver`
  * **DDL Override**: `x.apps.<appname>.storage.icr.role`
* **@busDescriptor**: Bus descriptor for ICR. Required unless `bus` element is used
  * **DDL Override**: `x.apps.<appname>.storage.icr.busDescriptor`

**Elements:**

* **shared** (default: `false`): Whether ICR sender is shared (use `true` for Standalone Receiver)
  * **DDL Override**: `x.apps.<appname>.storage.icr.shared`
* **flushOnCommit** (default: `false`): Whether ICR sender should be flushed on commit
  * **DDL Override**: `x.apps.<appname>.storage.icr.flushOnCommit`
* [**bus**](#storage-configuration): Define private bus instance for ICR (alternative to busDescriptor)
* [**detachedSend**](#storage-configuration): Detached ICR sender configuration

**ICR Bus Configuration**

Define private bus instance for ICR (alternative to busDescriptor).

**Sample:**

```xml
<icr enabled="true" role="Sender">
  <bus>
    <provider>solace</provider>
    <address>remote-mq</address>
    <port>7222</port>
    <properties>
      <vpn_name>icr-vpn</vpn_name>
      <username>app</username>
      <password>secret</password>
    </properties>
  </bus>
</icr>
```

**Elements:**

* **provider**: Bus provider name
  * **DDL Override**: `x.apps.<appname>.storage.icr.bus.provider`
* **address**: Bus address
  * **DDL Override**: `x.apps.<appname>.storage.icr.bus.address`
* **port**: Bus port
  * **DDL Override**: `x.apps.<appname>.storage.icr.bus.port`
* **properties**: Bus properties
  * **DDL Override**: `x.apps.<appname>.storage.icr.bus.properties.*`

**ICR Detached Send**

Configure detached ICR sender thread for asynchronous inter-cluster replication.

**Sample:**

```xml
<icr enabled="true" role="Sender">
  <detachedSend enabled="true">
    <queueDepth>4096</queueDepth>
    <queueOfferStrategy>Block</queueOfferStrategy>
    <queueWaitStrategy>BusySpin</queueWaitStrategy>
    <queueDrainerCpuAffinityMask>0x10</queueDrainerCpuAffinityMask>
    <queueFeedMaxConcurrency>1</queueFeedMaxConcurrency>
  </detachedSend>
</icr>
```

**Attributes:**

* **@enabled**: Enable/disable detached send
  * **DDL Override**: `x.apps.<appname>.storage.icr.detachedSend.enabled`

**Elements:**

* Includes all [EventMultiplexerProperties](#eventmultiplexerproperties): `queueDepth`, `queueOfferStrategy`, `queueWaitStrategy`, `queueDrainerCpuAffinityMask`, `queueFeedMaxConcurrency`
  * **DDL Override**: `x.apps.<appname>.storage.icr.detachedSend.<property>`

#### Transaction Configuration

**Sample:**

```xml
<service name="order-processor" mainClass="com.example.OrderProcessor">
  <adaptiveCommitBatchCeiling>100</adaptiveCommitBatchCeiling>
</service>
```

**Elements:**

* **adaptiveCommitBatchCeiling** (default: `1`): Maximum messages per transaction batch. Set to value > 1 to enable adaptive batching
  * **DDL Override**: `x.apps.<appname>.adaptiveCommitBatchCeiling`

#### Statistics Configuration

**Sample:**

```xml
<service name="order-processor" mainClass="com.example.OrderProcessor">
  <captureTransactionLatencyStats>true</captureTransactionLatencyStats>
  <captureEventLatencyStats>true</captureEventLatencyStats>
  <captureMessageTypeStats>false</captureMessageTypeStats>
  <messageTypeStatsLatenciesToCapture>all</messageTypeStatsLatenciesToCapture>
</service>
```

**Elements:**

* **captureTransactionLatencyStats** (default: `false`): Collect transaction pipeline latency stats
  * **DDL Override**: `x.apps.<appname>.captureTransactionLatencyStats`
* **captureEventLatencyStats** (default: `false`): Collect event processing latency stats
  * **DDL Override**: `x.apps.<appname>.captureEventLatencyStats`
* **captureMessageTypeStats** (default: `false`): Collect per-message-type statistics
  * **DDL Override**: `x.apps.<appname>.captureMessageTypeStats`
* **messageTypeStatsLatenciesToCapture** (default: `all`): Latency stats to capture per message type (values: `all` | `none` | comma-separated list: `c2o`, `o2p`, `mfilt`, `mpproc`, `mproc`)
  * **DDL Override**: `x.apps.<appname>.messageTypeStatsLatenciesToCapture`

#### Message Logging

**Sample:**

```xml
<service name="order-processor" mainClass="com.example.OrderProcessor">
  <inboundMessageLogging policy="UseDedicated" failurePolicy="StopLogging"/>
  <outboundMessageLogging policy="UseDedicated" failurePolicy="StopLogging"/>
</service>
```

**Elements:**

* **inboundMessageLogging**: Configures inbound message logging for the engine
  * **@policy** (default: `Off`): Inbound message logging policy - `Off` | `UseDedicated`
    * **DDL Override**: `x.apps.<appname>.inboundMessageLogging.policy`
  * **@failurePolicy** (default: `StopLogging`): What to do on logging failure - `StopLogging` | `StopEngine`
    * **DDL Override**: `x.apps.<appname>.inboundMessageLogging.failurePolicy`
* **outboundMessageLogging**: Configures outbound message logging for the engine
  * **@policy** (default: `Off`): Outbound message logging policy - `Off` | `UseDedicated`
    * **DDL Override**: `x.apps.<appname>.outboundMessageLogging.policy`
  * **@failurePolicy** (default: `StopLogging`): What to do on logging failure - `StopLogging` | `StopEngine`
    * **DDL Override**: `x.apps.<appname>.outboundMessageLogging.failurePolicy`

#### Threading Configuration

**Sample:**

```xml
<service name="order-processor" mainClass="com.example.OrderProcessor">
  <inboundEventMultiplexing type="DedicatedThreaded">
    <queueDepth>1024</queueDepth>
  </inboundEventMultiplexing>
</service>
```

**Elements:**

* **inboundEventMultiplexing**: Configures the engine's inbound event multiplexer
  * **@type** (default: `DedicatedThreaded`): Input queue multiplexer type - `FreeThreadedSerialized` | `DedicatedThreaded`
    * **DDL Override**: `x.apps.<appname>.inboundEventMultiplexing.type`
  * **queueDepth** (default: `1024`): Maximum input queue capacity
    * **DDL Override**: `x.apps.<appname>.inboundEventMultiplexing.queueDepth`

#### Duplicate Detection

**Sample:**

```xml
<service name="order-processor" mainClass="com.example.OrderProcessor">
  <performDuplicateChecking>true</performDuplicateChecking>
</service>
```

**Elements:**

* **performDuplicateChecking** (default: `true`): Enable duplicate message detection
  * **DDL Override**: `x.apps.<appname>.performDuplicateChecking`

#### Replication and Transaction Control

**Elements:**

* **replicateSolicitedSends** (default: varies): Whether to replicate solicited sends
* **replicateUnsolicitedSends** (default: varies): Whether to replicate unsolicited sends
* **sequenceUnsolicitedSends** (default: varies): Sequence unsolicited sends
* **sequenceUnsolicitedWithSolicitedSends**: Sequence unsolicited with solicited sends
* **dispatchSendStabilityEvents** (default: `false`): Dispatch send stability events
* **disposeOnSend** (default: varies): Dispose messages on send
* **dispatchTransactionStageEvents** (default: `false`): Dispatch transaction stage events
* **enableTransactionCommitSuspension** (default: `false`): Enable transaction commit suspension
* **enableTransactionSavepoints** (default: `false`): Enable transaction savepoints
* **clusterHeartbeatInterval** (default: `0`): Cluster heartbeat interval in milliseconds
* **stuckAlertEventThreshold** (default: `0`): Threshold for stuck alert events
* **enableSendCommitCompleteSequenceAlerts** (default: `false`): Enable send commit complete sequence alerts
* **replicateInParallel** (default: `false`): Enable parallel replication
* **syncInjectedMessages** (default: `false`): Sync injected messages

#### Policy Configuration

**Elements:**

* **inboundEventAcknowledgementPolicy**: Policy for acknowledging inbound events
* **appExceptionHandlingPolicy**: Policy for handling application exceptions
* **messageHandlingPolicy**: Policy for message handling
* **replicationPolicy**: Policy for replication behavior
* **messageSendExceptionHandlingPolicy**: Policy for handling message send exceptions
* **messageSendStabilityFailureHandlingPolicy**: Policy for handling send stability failures
* **messagingStartFailPolicy**: Policy for handling messaging start failures
* **messageBusBindingFailPolicy**: Policy for handling bus binding failures

#### Quarantine Configuration

**Elements:**

* **quarantineChannel**: Channel for quarantined messages
* **quarantineMessageKey**: Key for quarantined messages

#### Trace Configuration

**Elements:**

* **performMidstreamInitializationValidation** (default: `false`): Perform midstream initialization validation
* **enableSequenceNumberTrace** (default: `false`): Enable sequence number trace
* **enableEventTrace** (default: `false`): Enable event trace
* **enableAlertTrace** (default: `false`): Enable alert trace
* **enableTransactionTrace** (default: `false`): Enable transaction trace
* **enableScheduleTrace** (default: `false`): Enable schedule trace
* **enableMessageTrace** (default: `false`): Enable message trace
* **messageTraceInJson** (default: `false`): Output message trace in JSON format
* **messageTraceJsonStyle**: Style for JSON message trace
* **messageTraceMetadataDisplayPolicy**: Policy for displaying message metadata in trace
* **messageTraceFilterUnsetFields** (default: `false`): Filter unset fields in message trace

#### Advanced Configuration

**Elements:**

* **administrative** (default: `false`): Mark engine as administrative
* **maxEnvironmentProviders**: Maximum number of environment providers
* **setSupportMetadata** (default: varies): Set support metadata
* **setOutboundSequenceNumbers** (default: varies): Set outbound sequence numbers
* **stopOnJVMShutdown** (default: `true`): Stop engine on JVM shutdown
* **preserveChannelJoinsOnStop** (default: `false`): Preserve channel joins when engine stops
* **capturePerTransactionStats** (default: `false`): Capture per-transaction statistics
* **startupExpectations**: Startup expectations configuration
* **perTransactionStatsLogging**: Per-transaction stats logging configuration

***

### Container Configuration

Containers are containers that host applications and provide lifecycle management and monitoring.

#### Container Configuration Index

* [Core Container Settings](#core-container-settings) - Name and discovery
* [Provisioning Configuration](#provisioning-configuration) - Host and directory configuration
* [Applications](#applications) - Managed applications
* [Network Configuration](#network-configuration) - Acceptors and network listeners
* [Threading Configuration](#threading-configuration-1) - I/O threads and multi-threading
* [Heartbeats and Monitoring](#heartbeats-and-monitoring)
  * [Heartbeat Configuration](#heartbeats-and-monitoring) - Heartbeat emission settings
  * [Heartbeat Tracing](#heartbeats-and-monitoring) - Trace statistics to log output
  * [Heartbeat Logging](#heartbeats-and-monitoring) - Disk logging of heartbeats
* [Timeouts and Limits](#timeouts-and-limits) - Client timeouts and queue capacities
* [Lifecycle Configuration](#lifecycle-configuration) - Auto-start and auto-stop behavior
* [Discovery Configuration](#discovery-configuration) - Discovery registration
* [Admin Configuration](#admin-configuration) - Administration and monitoring
* [container-Specific Environment](#container-specific-environment) - container-specific properties

#### Complete container Configuration Example

```xml
<containers>
  <container name="trading-container" discoveryDescriptor="nvds://localhost:4090">

    <!-- Applications -->
    <services>
      <service name="order-processor" enabled="true" autoStart="true"/>
      <service name="risk-manager" enabled="true" autoStart="true"/>
    </service>

    <!-- Acceptors (Network Listeners) -->
    <acceptors>
      <acceptor descriptor="tcp://0.0.0.0:12000" enabled="true">
        <linkParams>SO_REUSEADDR=true</linkParams>
      </acceptor>
    </acceptors>

    <!-- Multi-Threading -->
    <multiThreading enabled="true">
      <ioThreads>
        <ioThread id="0" affinity="0" enabled="true"/>
        <ioThread id="1" affinity="1" enabled="true"/>
        <ioThread id="2" affinity="2" enabled="true"/>
      </ioThreads>
    </multiThreading>

    <!-- Heartbeats and Statistics -->
    <heartbeats enabled="true" interval="5">
      <includeMessageTypeStats>false</includeMessageTypeStats>
      <logging enabled="false">
        <dataDirectory>hbdata</dataDirectory>
      </logging>
    </heartbeats>

    <!-- Timeouts -->
    <clientHandshakeTimeout>30000</clientHandshakeTimeout>

    <!-- Admin Configuration -->
    <adminClientOutputQueueCapacity>10</adminClientOutputQueueCapacity>

    <!-- Lifecycle -->
    <autoStopOnAppStartFail>true</autoStopOnAppStartFail>
    <autoStopOnLastAppStop>true</autoStopOnLastAppStop>

    <!-- Trace Configuration -->
    <maxTraceHistory>512</maxTraceHistory>

    <!-- Discovery (alternative to discoveryDescriptor attribute) -->
    <discovery>
      <descriptor>nvds://localhost:4090</descriptor>
    </discovery>

    <!-- container-Specific Environment -->
    <env>
      <nv>
        <conservecpu>true</conservecpu>
      </nv>
    </env>

  </container>
</containers>
```

#### Core container Settings

**Example:**

```xml
<container name="trading-container" discoveryDescriptor="nvds://localhost:4090">
  <!-- Additional configuration... -->
</container>
```

**Attributes:**

* **name** (required): Unique container identifier
  * **DDL Override**: Not overridable (key)
* **displayName** (optional): Human-readable friendly name for the container
  * **DDL Override**: `x.xvms.<xvmname>.displayName`
* **group** (optional): Logical grouping for the container
  * **DDL Override**: `x.xvms.<xvmname>.group`
* **discoveryDescriptor** (optional): Discovery container descriptor for container registration
  * **DDL Override**: `x.xvms.<xvmname>.discoveryDescriptor`
* **order** (optional): Ordering for container startup/shutdown
  * **DDL Override**: `x.xvms.<xvmname>.order`
* **enabled** (optional, default: `true`): Enable/disable this container
  * **DDL Override**: `x.xvms.<xvmname>.enabled`

#### Provisioning Configuration

Configures provisioning details for container deployment.

**Sample:**

```xml
<container name="trading-container">
  <provisioning>
    <host>trading-host-01</host>
    <qualifyPathsWithSystem>true</qualifyPathsWithSystem>
    <rootDirectory>/opt/talon</rootDirectory>
    <runDirectory>run</runDirectory>
    <dataDirectory>data</dataDirectory>
    <traceLogDirectory>logs</traceLogDirectory>
    <jvm>
      <javaHome>/usr/lib/jvm/java-11</javaHome>
      <jvmParams>-Xms8G -Xmx8G -XX:+UseG1GC</jvmParams>
      <jvmParamSets>
        <jvmParamSet name="gc-logging" order="1" enabled="true">
          <jvmParams>-verbose:gc -XX:+PrintGCDetails</jvmParams>
        </jvmParamSet>
      </jvmParamSets>
    </jvm>
  </provisioning>
</container>
```

**Elements:**

* **host**: Host or IP address to which this container should be provisioned
  * **DDL Override**: `x.xvms.<xvmname>.provisioning.host`
* **qualifyPathsWithSystem** (default: `true`): Append `/systemName/xvmName` to installation paths
  * **DDL Override**: `x.xvms.<xvmname>.provisioning.qualifyPathsWithSystem`
* **rootDirectory**: Root directory of container's runtime sandbox (contains run, data, logs subdirectories)
  * **DDL Override**: `x.xvms.<xvmname>.provisioning.rootDirectory`
* **runDirectory** (default: `run`): Directory for Rumi distribution and application jars (relative to rootDirectory)
  * **DDL Override**: `x.xvms.<xvmname>.provisioning.runDirectory`
* **dataDirectory** (default: `rdat`): Directory for persistent data like transaction logs (relative to rootDirectory)
  * **DDL Override**: `x.xvms.<xvmname>.provisioning.dataDirectory`
* **traceLogDirectory** (default: `logs`): Directory for container and service trace logs (relative to rootDirectory)
  * **DDL Override**: `x.xvms.<xvmname>.provisioning.traceLogDirectory`
* [**jvm**](#core-container-settings): JVM settings for the container process

**JVM Configuration**

Configure JVM settings for the container process.

**Sample:**

```xml
<provisioning>
  <jvm>
    <javaHome>/usr/lib/jvm/java-11</javaHome>
    <jvmParams>-Xms8G -Xmx8G -XX:+UseG1GC</jvmParams>
    <jvmParamSets>
      <jvmParamSet name="gc-logging" order="1" enabled="true">
        <jvmParams>-verbose:gc -XX:+PrintGCDetails</jvmParams>
      </jvmParamSet>
      <jvmParamSet name="debugging" order="2" enabled="false">
        <jvmParams>-agentlib:jdwp=transport=dt_socket,container=y,suspend=n,address=5005</jvmParams>
      </jvmParamSet>
    </jvmParamSets>
  </jvm>
</provisioning>
```

**Elements:**

* **javaHome**: JVM home directory containing `bin/java` executable
  * **DDL Override**: `x.xvms.<xvmname>.provisioning.jvm.javaHome`
* **jvmParams**: JVM parameters string (can span multiple lines)
  * **DDL Override**: `x.xvms.<xvmname>.provisioning.jvm.jvmParams`
* [**jvmParamSets**](#core-container-settings): Named sets of JVM parameters

**JVM Parameter Sets**

Named parameter sets for composition and reuse.

**Sample:**

```xml
<jvm>
  <jvmParamSets>
    <jvmParamSet name="gc-logging" order="1" enabled="true">
      <jvmParams>-verbose:gc -XX:+PrintGCDetails -XX:+PrintGCDateStamps</jvmParams>
    </jvmParamSet>
    <jvmParamSet name="debugging" order="2" enabled="false">
      <jvmParams>-agentlib:jdwp=transport=dt_socket,container=y,suspend=n,address=5005</jvmParams>
    </jvmParamSet>
    <jvmParamSet name="performance" order="3" enabled="true">
      <jvmParams>-XX:+UseNUMA -XX:+AlwaysPreTouch</jvmParams>
    </jvmParamSet>
  </jvmParamSets>
</jvm>
```

**Attributes:**

* **@name** (required): Parameter set name
  * **DDL Override**: Not overridable (key)
* **@order** (default: `0`): Ordering for parameter application
  * **DDL Override**: `x.xvms.<xvmname>.provisioning.jvm.jvmParamSets.<paramSetName>.order`
* **@enabled** (default: `true`): Enable/disable this parameter set
  * **DDL Override**: `x.xvms.<xvmname>.provisioning.jvm.jvmParamSets.<paramSetName>.enabled`

**Elements:**

* **jvmParams**: JVM parameters for this set
  * **DDL Override**: `x.xvms.<xvmname>.provisioning.jvm.jvmParamSets.<paramSetName>.jvmParams`

#### Applications

**Example:**

```xml
<container name="trading-container">
  <services>
    <service name="order-processor" enabled="true" autoStart="true"/>
    <service name="risk-manager" enabled="true" autoStart="true"/>
  </service>
</container>
```

**Elements:**

* **apps/app**: Application(s) to run in this container
  * **name** (required): Application name (must be defined in `<services>` section)
    * **DDL Override**: Not overridable (key)
  * **enabled** (optional, default: `true`): Whether to enable this app
    * **DDL Override**: `x.xvms.<xvmname>.apps.<appname>.enabled`
  * **autoStart** (optional, default: `true`): Whether to auto-start on container startup
    * **DDL Override**: `x.xvms.<xvmname>.apps.<appname>.autoStart`

#### Network Configuration

**Example:**

```xml
<container name="trading-container">
  <acceptors>
    <acceptor descriptor="tcp://0.0.0.0:12000" enabled="true">
      <linkParams>SO_REUSEADDR=true,TCP_NODELAY=true</linkParams>
    </acceptor>
    <acceptor descriptor="tcp://192.168.1.100:12001" enabled="true"/>
  </acceptors>
</container>
```

**Elements:**

* **acceptors/acceptor**: Network acceptor configuration
  * **descriptor** (required): Acceptor descriptor (format: `tcp://host:port`)
  * **enabled** (optional, default: `true`): Whether to enable this acceptor
  * **linkParams**: Additional network connection parameters

#### Threading Configuration

**Example:**

```xml
<container name="trading-container">
  <multiThreading enabled="true">
    <ioThreads>
      <ioThread id="0" affinity="0" enabled="true"/>
      <ioThread id="1" affinity="1" enabled="true"/>
      <ioThread id="2" affinity="2" enabled="true"/>
      <ioThread id="3" affinity="3" enabled="true"/>
    </ioThreads>
  </multiThreading>
</container>
```

**Elements:**

* **multiThreading/@enabled** (required): Whether multi-threading is enabled
  * **DDL Override**: `x.xvms.<xvmname>.multiThreading.enabled`
* **multiThreading/ioThreads/ioThread**: I/O thread configuration
  * **id** (required): Thread ID (zero-based, monotonically increasing)
  * **affinity** (optional, default: `0`): CPU affinity
  * **enabled** (optional, default: `true`): Whether this thread is enabled

#### Heartbeats and Monitoring

Configures statistics collection and heartbeat emission for container monitoring.

**Sample:**

```xml
<container name="trading-container">
  <heartbeats enabled="true" interval="5">
    <includeMessageTypeStats>true</includeMessageTypeStats>
    <collectSeriesStats>true</collectSeriesStats>
    <collectPoolStats>true</collectPoolStats>
    <tracing enabled="false">
      <traceAppStats>true</traceAppStats>
      <traceSysStats>true</traceSysStats>
    </tracing>
    <logging enabled="true">
      <dataDirectory>hbdata</dataDirectory>
      <flushOnCommit>false</flushOnCommit>
      <detachedWrite enabled="true">
        <queueDepth>512</queueDepth>
      </detachedWrite>
    </logging>
  </heartbeats>
</container>
```

**Elements:**

* [**heartbeats**](#heartbeats-and-monitoring): Heartbeat emission settings
* [**tracing**](#heartbeats-and-monitoring): Trace statistics to log output
* [**logging**](#heartbeats-and-monitoring): Disk logging of heartbeats

**Heartbeat Configuration**

**Sample:**

```xml
<container name="trading-container">
  <heartbeats enabled="true" interval="5">
    <includeMessageTypeStats>true</includeMessageTypeStats>
    <collectSeriesStats>true</collectSeriesStats>
    <collectSeriesDatapoints>false</collectSeriesDatapoints>
    <poolDepletionThreshold>1.0</poolDepletionThreshold>
    <collectPoolStats>true</collectPoolStats>
    <collectAllPoolStats>false</collectAllPoolStats>
    <collectIndividualThreadStats>true</collectIndividualThreadStats>
    <collectNonZGStats>true</collectNonZGStats>
    <inactiveMessageTypeStatsInclusionFrequency>1</inactiveMessageTypeStatsInclusionFrequency>
  </heartbeats>
</container>
```

**Attributes:**

* **@enabled** (optional, default: `false`): Enable heartbeat emission
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.enabled`
* **@interval** (optional, default: `30`): Heartbeat interval in seconds
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.interval`

**Elements:**

* **collectSeriesStats** (default: `true`): Collect latency and series statistics
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.collectSeriesStats`
* **collectSeriesDatapoints** (default: `false`): Include datapoints in series stats (bandwidth intensive)
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.collectSeriesDatapoints`
* **poolDepletionThreshold** (default: `1.0`): Percentage threshold for preallocated pool depletion reporting
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.poolDepletionThreshold`
* **collectPoolStats** (default: `true`): Collect and report pool statistics
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.collectPoolStats`
* **collectAllPoolStats** (default: `false`): Include all pools regardless of activity
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.collectAllPoolStats`
* **collectIndividualThreadStats** (default: `true`): Collect stats for individual threads
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.collectIndividualThreadStats`
* **collectNonZGStats** (default: `true`): Collect stats that may produce garbage (CPU usage, disk stats)
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.collectNonZGStats`
* **includeMessageTypeStats** (default: `false`): Include per-message-type stats in heartbeats
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.includeMessageTypeStats`
* **inactiveMessageTypeStatsInclusionFrequency** (default: `1`): Frequency for including inactive message types (1 = every heartbeat, 0 = never)
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.inactiveMessageTypeStatsInclusionFrequency`

**Heartbeat Tracing**

Configures tracing of heartbeat statistics to log output for development and debugging.

{% hint style="warning" %}
**Not Zero-Garbage**: Heartbeat tracing produces garbage and is not recommended for production use. Use heartbeat logging or external monitoring instead.
{% endhint %}

**Sample:**

```xml
<container name="trading-container">
  <heartbeats enabled="true" interval="5">
    <tracing enabled="true">
      <traceAdminClientStats>true</traceAdminClientStats>
      <traceAppStats>true</traceAppStats>
      <tracePoolStats>true</tracePoolStats>
      <traceSysStats>true</traceSysStats>
      <traceThreadStats>true</traceThreadStats>
      <traceUserStats>true</traceUserStats>
    </tracing>
  </heartbeats>
</container>
```

**Attributes:**

* **@enabled** (default: `false`): Enable heartbeat statistics tracing to log output
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.tracing.enabled`

**Elements:**

* **traceAdminClientStats** (default: `true`): Trace admin client statistics
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.tracing.traceAdminClientStats`
* **traceAppStats** (default: `true`): Trace application statistics
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.tracing.traceAppStats`
* **tracePoolStats** (default: `true`): Trace memory pool statistics
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.tracing.tracePoolStats`
* **traceSysStats** (default: `true`): Trace system statistics (CPU, memory, disk)
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.tracing.traceSysStats`
* **traceThreadStats** (default: `true`): Trace thread statistics
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.tracing.traceThreadStats`
* **traceUserStats** (default: `true`): Trace user-defined application statistics
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.tracing.traceUserStats`

**Heartbeat Logging**

Configures disk-based logging of heartbeat data.

**Sample:**

```xml
<container name="trading-container">
  <heartbeats enabled="true" interval="5">
    <logging enabled="true">
      <dataDirectory>hbdata</dataDirectory>
      <flushOnCommit>false</flushOnCommit>
      <flushUsingMappedMemory>false</flushUsingMappedMemory>
      <autoFlushSize>8192</autoFlushSize>
      <autoRepair>false</autoRepair>
      <!-- <storeRoot>hbdata</storeRoot> -->  <!-- Alternative to dataDirectory -->
      <initialLogLength>1mb</initialLogLength>
      <zeroOutInitial>false</zeroOutInitial>
      <pageSize>8kb</pageSize>
      <detachedWrite enabled="true">
        <queueDepth>512</queueDepth>
        <queueOfferStrategy>Block</queueOfferStrategy>
        <queueWaitStrategy>BusySpin</queueWaitStrategy>
      </detachedWrite>
    </logging>
  </heartbeats>
</container>
```

**Attributes:**

* **@enabled** (optional, default: `false`): Enable disk logging
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.logging.enabled`

**Elements:**

* **flushOnCommit** (default: `false`): Flush logger on commit
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.logging.flushOnCommit`
* **flushUsingMappedMemory**: Use memory mapped file buffer for flushes
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.logging.flushUsingMappedMemory`
* **autoFlushSize** (default: `8192`): Size triggering automatic flush
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.logging.autoFlushSize`
* **autoRepair**: Automatically repair malformed log entries on open
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.logging.autoRepair`
* **storeRoot**: Root folder for heartbeat log files (alternative to dataDirectory)
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.logging.storeRoot`
* **initialLogLength** (default: `1mb`): Initial log file size (preallocated)
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.logging.initialLogLength`
* **zeroOutInitial**: Explicitly zero out log file on creation
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.logging.zeroOutInitial`
* **pageSize**: Disk page size hint (default: `8kb`)
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.logging.pageSize`
* **dataDirectory** (optional): Directory for heartbeat logs (legacy)
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.logging.dataDirectory`
* [**detachedWrite**](#storage-configuration): Detached writer configuration

**Detached Write Configuration**

Configure detached writer thread for asynchronous heartbeat logging.

**Sample:**

```xml
<heartbeats enabled="true">
  <logging enabled="true">
    <detachedWrite enabled="true">
      <queueDepth>512</queueDepth>
      <queueOfferStrategy>Block</queueOfferStrategy>
      <queueWaitStrategy>BusySpin</queueWaitStrategy>
      <queueDrainerCpuAffinityMask>0x01</queueDrainerCpuAffinityMask>
      <queueFeedMaxConcurrency>1</queueFeedMaxConcurrency>
    </detachedWrite>
  </logging>
</heartbeats>
```

**Attributes:**

* **@enabled**: Enable/disable detached write
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.logging.detachedWrite.enabled`

**Elements:**

* Includes all [EventMultiplexerProperties](#eventmultiplexerproperties): `queueDepth`, `queueOfferStrategy`, `queueWaitStrategy`, `queueDrainerCpuAffinityMask`, `queueFeedMaxConcurrency`
  * **DDL Override**: `x.xvms.<xvmname>.heartbeats.logging.detachedWrite.<property>`

#### Timeouts and Limits

**Example:**

```xml
<container name="trading-container">
  <clientHandshakeTimeout>30000</clientHandshakeTimeout>
  <adminClientOutputQueueCapacity>10</adminClientOutputQueueCapacity>
  <maxTraceHistory>1024</maxTraceHistory>
</container>
```

**Elements:**

* **clientHandshakeTimeout** (optional): Timeout for client handshake in milliseconds
  * **DDL Override**: `x.xvms.<xvmname>.clientHandshakeTimeout`
* **adminClientOutputQueueCapacity** (optional): Admin client output queue capacity in MB
  * **DDL Override**: `x.xvms.<xvmname>.adminClientOutputQueueCapacity`
* **maxTraceHistory** (optional, default: `512`): Maximum trace lines buffered for admin clients
  * **DDL Override**: `x.xvms.<xvmname>.maxTraceHistory`

#### Lifecycle Configuration

**Example:**

```xml
<container name="trading-container">
  <autoStopOnAppStartFail>true</autoStopOnAppStartFail>
  <autoStopOnLastAppStop>false</autoStopOnLastAppStop>
</container>
```

**Elements:**

* **autoStopOnAppStartFail** (optional, default: `true`): Stop container if any app fails to start
  * **DDL Override**: `x.xvms.<xvmname>.autoStopOnAppStartFail`
* **autoStopOnLastAppStop** (optional, default: `true`): Stop container when last app stops
  * **DDL Override**: `x.xvms.<xvmname>.autoStopOnLastAppStop`

#### Discovery Configuration

**Example:**

```xml
<container name="trading-container">
  <discovery>
    <descriptor>nvds://localhost:4090</descriptor>
  </discovery>
</container>
```

**Elements:**

* **discovery/descriptor**: Discovery container descriptor (alternative to `discoveryDescriptor` attribute)

#### container-Specific Environment

**Example:**

```xml
<container name="trading-container">
  <env>
    <nv>
      <conservecpu>true</conservecpu>
      <aep.order-processor.stats.interval>10</aep.order-processor.stats.interval>
    </nv>
  </env>
</container>
```

**Elements:**

* **env**: container-specific environment properties (merged with global `<env>`)

#### Admin Configuration

Configures administration and monitoring capabilities of the container.

**Sample:**

```xml
<container name="trading-container">
  <admin>
    <passiveMonitoringOnly>false</passiveMonitoringOnly>
    <transports>
      <direct enabled="true"/>
      <sma>
        <busName>admin-bus</busName>
        <channels>
          <request enabled="true"/>
          <response enabled="true"/>
          <heartbeat enabled="true"/>
          <trace enabled="true"/>
        </channels>
      </sma>
    </transports>
  </admin>
</container>
```

**Elements:**

* **passiveMonitoringOnly** (default: `false`): Enable passive monitoring mode only
  * **DDL Override**: `x.xvms.<xvmname>.admin.passiveMonitoringOnly`
* [**transports**](#admin-configuration): Transport mechanisms for administration and monitoring

**Admin Transports**

Configure transport mechanisms for administration and monitoring.

**Sample:**

```xml
<admin>
  <transports>
    <direct enabled="true"/>
    <sma>
      <busName>admin-bus</busName>
      <channels>
        <request enabled="true"/>
        <response enabled="true"/>
        <heartbeat enabled="true"/>
        <trace enabled="true"/>
      </channels>
    </sma>
  </transports>
</admin>
```

**Elements:**

* [**direct**](#admin-configuration): Direct (TCP) transport configuration
* [**sma**](#admin-configuration): Admin over SMA (messaging) transport configuration

**Direct Transport**

Direct (TCP) based monitoring and control.

**Sample:**

```xml
<transports>
  <direct enabled="true"/>
</transports>
```

**Attributes:**

* **@enabled** (default: `true`): Enable direct connections
  * **DDL Override**: `x.xvms.<xvmname>.admin.transports.direct.enabled`

**SMA Transport**

Admin over SMA (messaging) transport.

**Sample:**

```xml
<transports>
  <sma>
    <busName>admin-bus</busName>
    <channels>
      <request enabled="true"/>
      <response enabled="true"/>
      <heartbeat enabled="true"/>
      <trace enabled="true"/>
    </channels>
  </sma>
</transports>
```

**Elements:**

* **busName**: Name of bus (from global buses section) for admin over SMA
  * **DDL Override**: `x.xvms.<xvmname>.admin.transports.sma.busName`
* **channels/request/@enabled** (default: `true`): Enable request channel
  * **DDL Override**: `x.xvms.<xvmname>.admin.transports.sma.channels.request.enabled`
* **channels/response/@enabled** (default: `true`): Enable response channel
  * **DDL Override**: `x.xvms.<xvmname>.admin.transports.sma.channels.response.enabled`
* **channels/heartbeat/@enabled** (default: `true`): Enable heartbeat channel
  * **DDL Override**: `x.xvms.<xvmname>.admin.transports.sma.channels.heartbeat.enabled`
* **channels/trace/@enabled** (default: `true`): Enable trace channel
  * **DDL Override**: `x.xvms.<xvmname>.admin.transports.sma.channels.trace.enabled`

***

### Enums Reference

#### ChannelQos

Quality of service levels for message channels.

* **BestEffort**: Messages delivered with best effort, no acknowledgment or persistence guarantees
* **Guaranteed**: Messages acknowledged and persisted by messaging infrastructure before confirmation

#### HAPolicy

High availability policies for application storage.

* **Disabled**: No high availability, single instance operation
* **EventSourcing**: Event sourcing pattern - store input events, derive state on recovery
* **StateReplication**: State replication pattern - replicate state changes to backup instances

#### InboundEventMultiplexerType

Types of inbound event multiplexers.

* **FreeThreadedSerialized**: Allows different threads to dispatch events over time, but only one at a time
* **DedicatedThreaded**: Uses a dedicated thread for event dispatching

#### Message Logging Policies

**InboundMessageLoggingPolicy / OutboundMessageLoggingPolicy:**

* **Off**: Message logging disabled (default)
* **UseDedicated**: Use dedicated log for message logging

**InboundMessageLoggingFailurePolicy / OutboundMessageLoggingFailurePolicy:**

* **StopLogging**: Trap errors and discontinue logging (default)
* **StopEngine**: Treat logging failure as engine failure and shutdown

***

### Reusable Element Groups

XSD element groups that are referenced throughout the DDL configuration.

#### EventMultiplexerProperties

Configuration properties for event multiplexers. Event multiplexers are responsible for multiplexing events from multiple source threads onto a single dispatch thread.

**Sample:**

```xml
<detachedSend enabled="true">
  <queueDepth>1024</queueDepth>
  <queueOfferStrategy>Block</queueOfferStrategy>
  <queueWaitStrategy>BusySpin</queueWaitStrategy>
  <queueDrainerCpuAffinityMask>0x0004</queueDrainerCpuAffinityMask>
  <queueFeedMaxConcurrency>1</queueFeedMaxConcurrency>
</detachedSend>
```

**Elements:**

* **queueDepth**: Size of the event queue (should be power of 2)
  * **DDL Override**: `x.[path].queueDepth` (varies by context)
* **queueOfferStrategy**: Strategy for threads publishing to the queue
  * Values: `Block` | `Fail` | `BusySpin`
  * **DDL Override**: `x.[path].queueOfferStrategy`
* **queueWaitStrategy**: Strategy for queue consumer thread waiting for events
  * Values: `Block` | `BusySpin` | `Yield`
  * **DDL Override**: `x.[path].queueWaitStrategy`
* **queueDrainerCpuAffinityMask**: CPU affinity mask for the queue drainer thread (hex format like `0x0001`)
  * **DDL Override**: `x.[path].queueDrainerCpuAffinityMask`
* **queueFeedMaxConcurrency**: Maximum number of concurrent feeders to the queue
  * **DDL Override**: `x.[path].queueFeedMaxConcurrency`

**Used in:**

* Storage clustering detached send/dispatch
* Storage persistence detached persist
* Storage ICR detached send
* Messaging bus detached send
* Heartbeat logging detached write
* Threading inbound event multiplexing

***

### Groups Reference

Groups provide reusable configuration elements (Since 3.8).

```xml
<groups>
  <group name="common-messaging">
    <messaging>
      <factories>
        <factory>com.example.CommonMessageFactory</factory>
      </factories>
    </messaging>
  </group>
</groups>

<services>
  <service name="app1" groups="common-messaging" mainClass="com.example.App1"/>
  <service name="app2" groups="common-messaging" mainClass="com.example.App2"/>
</service>
```

Groups can contain any DDL configuration elements. When a component references a group via the `groups` attribute, the group's configuration is merged into the component.

***

### DDL Profiles

Profiles enable environment-specific configuration (Since 3.8).

```xml
<model>
  <!-- Default configuration -->
  <buses>
    <bus name="market-data" descriptor="solace://localhost:55555">
      <!-- ... -->
    </bus>
  </buses>

  <!-- Production profile -->
  <profile name="production">
    <buses>
      <bus name="market-data" descriptor="solace://prod-solace.example.com:55555">
        <!-- ... -->
      </bus>
    </buses>
  </profile>

  <!-- Development profile -->
  <profile name="development">
    <buses>
      <bus name="market-data" descriptor="loopback://market-data">
        <!-- ... -->
      </bus>
    </buses>
  </profile>
</model>
```

**Activating a profile:**

```bash
# Via system property
java -Dnv.ddl.profile=production ...

# Via environment variable
export nv_ddl_profile=production
```

***

## Related Documentation

* [Configuration Model](/rumi-core/concepts/microservice-architecture/configuration-model.md) - Understanding configuration architecture
* [Injecting Configuration](/rumi-core/guides/developing-applications/authoring-user-code/configuration/injecting-configuration.md) - Using `@Configured` annotation

***

## See Also

* [Config API](https://build.neeveresearch.com/rumi/javadoc/LATEST/com/neeve/config/Config.html) - Programmatic property access
* [DDL Schema](https://build.neeveresearch.com/core/schema/LATEST/x-ddl.xsd) - Complete XML schema definition


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.rumi.systems/rumi-core/reference/configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.