> For the complete documentation index, see [llms.txt](https://docs.xplatform.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xplatform.com/talon/reference/configuration.md).

# Configuration

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

## Overview

Talon 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, XVMs)

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

***

## Global Properties Reference

Global properties configure Talon 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](#nv.stats.latencymanager.samplesize)
* [nv.stats.series.samplesize](#nv.stats.series.samplesize)
* [nv.msg.latency.stats](#nv.msg.latency.stats)
* [nv.msgtype.latency.stats](#nv.msgtype.latency.stats)
* [nv.ods.latency.stats](#nv.ods.latency.stats)
* [nv.event.latency.stats](#nv.event.latency.stats)
* [nv.link.network.stampiots](#nv.link.network.stampiots)

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

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

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

* [nv.ddl.trace](#nv.ddl.trace)
* [nv.sma.trace](#nv.sma.trace)
* [nv.aep.trace](#nv.aep.trace)
* [nv.sol.trace](#nv.sol.trace)

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

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

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

* [nv.aep.\<engine>.stats.interval](#nv.aep.less-than-engine-greater-than.stats.interval)
* [nv.aep.\<engine>.sysstats.interval](#nv.aep.less-than-engine-greater-than.sysstats.interval)
* [nv.event.mux.\<name>.stats.interval](#nv.event.mux.less-than-name-greater-than.stats.interval)
* [nv.msg.latency.stats.interval](#nv.msg.latency.stats.interval)
* [nv.aep.busmanager.\<engine>.\<bus>.stats.interval](#nv.aep.busmanager.less-than-engine-greater-than.less-than-bus-greater-than.stats.interval)

***

### 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 XVM heartbeats.
* **Default**: `false`
* **Type**: boolean
* **Can Set in `<env>`?**: Yes

#### nv.ods.latency.stats

* **Description**: Enable collection of application 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 Talon 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 Talon messaging trace output. See [Trace Logging](/talon/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](/talon/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 server 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 XVM 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 XVM 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; XVM 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 Talon'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](/talon/concepts-and-architecture/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) -->
  <apps>
    <templates>
      <template name="app-template">
        <!-- Template configuration -->
      </template>
    </templates>
    <app name="order-processor" mainClass="com.example.OrderProcessor">
      <!-- Engine configuration (see Engine Configuration below) -->
    </app>
  </apps>

  <!-- XVMs (Execution Containers) -->
  <xvms>
    <templates>
      <template name="xvm-template">
        <!-- Template configuration -->
      </template>
    </templates>
    <xvm name="trading-xvm">
      <!-- XVM configuration (see XVM Configuration below) -->
    </xvm>
  </xvms>

  <!-- 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
* [XVM Configuration](#xvm-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>
    <!-- Talon 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 Talon 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 server address
  * **DDL Override**: `x.buses.bus.<busname>.address`
* **@port** (optional): Bus server 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**](#channel-configuration): Channel definitions

**Provider-Specific Configuration:**

* [Solace Binding](/talon/developing-applications/configuring-messaging/configuring-bus-connections/solace-binding.md)
* [JMS Binding](/talon/developing-applications/configuring-messaging/configuring-bus-connections/jms-binding.md)
* [Loopback Binding](/talon/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 `<apps>` 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](#message-factories)
  * [Bus Associations](#bus-associations)
* [Storage Configuration](#storage-configuration)
  * [Clustering](#clustering) - High availability clustering
  * [Persistence](#persistence) - Disk-based persistence
  * [Inter-Cluster Replication (ICR)](#inter-cluster-replication-icr) - 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
<apps>
  <app 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>

  </app>
</apps>
```

#### Core Engine Settings

**Sample:**

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

**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
<app 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>
</app>
```

**Elements:**

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

**Message Factories**

**Sample:**

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

**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
<app 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>
</app>
```

**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**](#channel-subscriptions): Channel subscription configuration
* [**detachedSend**](#detached-send-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
<app 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>
</app>
```

**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**](#state-factories): State factory configuration
* [**clustering**](#clustering): Store clustering configuration
* [**persistence**](#persistence): Disk persistence configuration
* [**icr**](#inter-cluster-replication-icr): Inter-cluster replication configuration

**State Factories**

Configure state factory classes for the application 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
<app 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>
</app>
```

**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**](#clustering-discovery): 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**](#detached-replication-send): Detached replication sender configuration
* [**detachedDispatch**](#detached-replication-dispatch): 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 server address
  * **DDL Override**: `x.apps.<appname>.storage.clustering.discovery.address`
* **port**: Discovery server 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
<app 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>
</app>
```

**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**](#compaction-configuration): Log compaction configuration
* [**cdc**](#change-data-capture-cdc): Change data capture configuration
* [**detachedPersist**](#detached-persistence): 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
<app 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>
</app>
```

**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**](#icr-bus-configuration): Define private bus instance for ICR (alternative to busDescriptor)
* [**detachedSend**](#icr-detached-send): 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
<app name="order-processor" mainClass="com.example.OrderProcessor">
  <adaptiveCommitBatchCeiling>100</adaptiveCommitBatchCeiling>
</app>
```

**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
<app name="order-processor" mainClass="com.example.OrderProcessor">
  <captureTransactionLatencyStats>true</captureTransactionLatencyStats>
  <captureEventLatencyStats>true</captureEventLatencyStats>
  <captureMessageTypeStats>false</captureMessageTypeStats>
  <messageTypeStatsLatenciesToCapture>all</messageTypeStatsLatenciesToCapture>
</app>
```

**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
<app name="order-processor" mainClass="com.example.OrderProcessor">
  <inboundMessageLogging policy="UseDedicated" failurePolicy="StopLogging"/>
  <outboundMessageLogging policy="UseDedicated" failurePolicy="StopLogging"/>
</app>
```

**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
<app name="order-processor" mainClass="com.example.OrderProcessor">
  <inboundEventMultiplexing type="DedicatedThreaded">
    <queueDepth>1024</queueDepth>
  </inboundEventMultiplexing>
</app>
```

**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
<app name="order-processor" mainClass="com.example.OrderProcessor">
  <performDuplicateChecking>true</performDuplicateChecking>
</app>
```

**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

***

### XVM Configuration

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

#### XVM Configuration Index

* [Core XVM Settings](#core-xvm-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](#heartbeat-configuration) - Heartbeat emission settings
  * [Heartbeat Tracing](#heartbeat-tracing) - Trace statistics to log output
  * [Heartbeat Logging](#heartbeat-logging) - 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
* [XVM-Specific Environment](#xvm-specific-environment) - XVM-specific properties

#### Complete XVM Configuration Example

```xml
<xvms>
  <xvm name="trading-xvm" discoveryDescriptor="nvds://localhost:4090">

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

    <!-- 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>

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

  </xvm>
</xvms>
```

#### Core XVM Settings

**Example:**

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

**Attributes:**

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

#### Provisioning Configuration

Configures provisioning details for XVM deployment.

**Sample:**

```xml
<xvm name="trading-xvm">
  <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>
</xvm>
```

**Elements:**

* **host**: Host or IP address to which this XVM 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 XVM'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 XVM and service trace logs (relative to rootDirectory)
  * **DDL Override**: `x.xvms.<xvmname>.provisioning.traceLogDirectory`
* [**jvm**](#jvm-configuration): JVM settings for the XVM process

**JVM Configuration**

Configure JVM settings for the XVM 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,server=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**](#jvm-parameter-sets): 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,server=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
<xvm name="trading-xvm">
  <apps>
    <app name="order-processor" enabled="true" autoStart="true"/>
    <app name="risk-manager" enabled="true" autoStart="true"/>
  </apps>
</xvm>
```

**Elements:**

* **apps/app**: Application(s) to run in this XVM
  * **name** (required): Application name (must be defined in `<apps>` 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 XVM startup
    * **DDL Override**: `x.xvms.<xvmname>.apps.<appname>.autoStart`

#### Network Configuration

**Example:**

```xml
<xvm name="trading-xvm">
  <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>
</xvm>
```

**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
<xvm name="trading-xvm">
  <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>
</xvm>
```

**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 XVM monitoring.

**Sample:**

```xml
<xvm name="trading-xvm">
  <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>
</xvm>
```

**Elements:**

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

**Heartbeat Configuration**

**Sample:**

```xml
<xvm name="trading-xvm">
  <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>
</xvm>
```

**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
<xvm name="trading-xvm">
  <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>
</xvm>
```

**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
<xvm name="trading-xvm">
  <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>
</xvm>
```

**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**](#detached-write-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
<xvm name="trading-xvm">
  <clientHandshakeTimeout>30000</clientHandshakeTimeout>
  <adminClientOutputQueueCapacity>10</adminClientOutputQueueCapacity>
  <maxTraceHistory>1024</maxTraceHistory>
</xvm>
```

**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
<xvm name="trading-xvm">
  <autoStopOnAppStartFail>true</autoStopOnAppStartFail>
  <autoStopOnLastAppStop>false</autoStopOnLastAppStop>
</xvm>
```

**Elements:**

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

#### Discovery Configuration

**Example:**

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

**Elements:**

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

#### XVM-Specific Environment

**Example:**

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

**Elements:**

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

#### Admin Configuration

Configures administration and monitoring capabilities of the XVM.

**Sample:**

```xml
<xvm name="trading-xvm">
  <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>
</xvm>
```

**Elements:**

* **passiveMonitoringOnly** (default: `false`): Enable passive monitoring mode only
  * **DDL Override**: `x.xvms.<xvmname>.admin.passiveMonitoringOnly`
* [**transports**](#admin-transports): 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**](#direct-transport): Direct (TCP) transport configuration
* [**sma**](#sma-transport): 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>

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

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](/talon/concepts-and-architecture/microservice-architecture/configuration-model.md) - Understanding configuration architecture
* [Injecting Configuration](/talon/concepts-and-architecture/microservice-architecture/configuration-model.md) - Using `@Configured` annotation

***

## See Also

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