# Core Configuration

## Overview

`lmc_exporter` is configured at runtime with one of the following methods:

Use `--config <path>` to load a TOML file. This is the preferred configuration format because it can define runtime defaults, HTTP settings, metric scopes, and preloaded scrape targets in one file.

Pass runtime options directly to `lmc_exporter`. CLI values override values loaded from TOML.

LMC Exporter supports two main operating modes:

<table><caption class="sr-only">Overview</caption><thead><tr><th scope="col">Mode</th><th scope="col">How it is selected</th><th scope="col">Purpose</th></tr></thead><tbody><tr><td>Single-target mode</td><td>TOML has no <code>[[targets]]</code> entries, or CLI options such as <code>--server-key</code> are used</td><td>Export metrics for one resolved LMC root target</td></tr><tr><td>Multi-target mode</td><td>TOML contains one or more <code>[[targets]]</code> tables</td><td>Export metrics for multiple targets and route scrapes by query parameter</td></tr></tbody></table>

## Prerequisites

Before configuring LMC Exporter, make sure you have:

-   Installed the LMC Exporter as the user the shared-memory is configured under.
-   One or more valid shared-memory `server_key` values.
-   An application metric set, such as `ads`, `adh`, `ats`, or `rtc`.
-   Either a valid local `license_file` or access to a configured licensing Gateway.

## How It Works

### Configuration loading order

When you use TOML and CLI options together, LMC Exporter applies configuration in this order:

1.  Load built-in defaults.
2.  Load values from the TOML file passed with `--config`.
3.  Apply CLI options as overrides.

This means a command-line option such as `--metrics-port 9564` overrides `metrics_port = 9464` in TOML.

### Single-target mode

Single-target mode uses top-level values such as `app`, `instance`, `variable`, and `server_keys`.

Use this mode when you want one exporter process to resolve and scrape one target on a host.

```
app = "ads"
server_keys = ["82"]
metrics_http_enabled = true
metrics_port = 9464
```

Run the exporter with:

```
lmc_exporter --config ./lmcExporterConfig.toml
```

### Multi-target mode

Multi-target mode is enabled when the TOML file contains one or more `[[targets]]` tables.

Each target defines its own application and server key. Optional target-level filters can narrow the subscribed subtree and emitted metrics.

```
metrics_http_enabled = true
metrics_port = 9464

[[targets]]
app = "ads"
instance = "1"
server_key = "82"
classes = ["ManagedProcess.SinkDist", "ConsumerDataStream"]

[[targets]]
app = "ads"
instance = "1"
server_key = "456"
classes = ["SSLDispatcher", "ManagedSSLChannel"]
```

## Configuration

### Basic TOML structure

A typical TOML file includes shared-memory settings, application selection, server keys, runtime behavior, HTTP settings, license settings, optional metric scopes, and optional preloaded targets.

```
context_id = "shmApp"
pool_name = "pool"

app = "ads"
server_keys = ["82", "456", "999"]

metrics_interval_seconds = 10
render_min_interval_ms = 250
target_workers = 0
worker_execution_mode = "logical"
worker_assignment_mode = "hash"
worker_rebalance_enabled = false

debug = false
metrics_http_enabled = true
metrics_bind_address = "0.0.0.0"
metrics_port = 9464
metrics_path = "/metrics"

license_mode = "local_file"
license_file = "./scratch/example.lic"

[[targets]]
app = "ads"
server_key = "82"

[[targets]]
app = "adh"
server_key = "999"
```

### Top-level configuration keys

<table><caption class="sr-only">Top-level configuration keys</caption><thead><tr><th scope="col">Key</th><th scope="col">Type</th><th scope="col">Default</th><th scope="col">Description</th></tr></thead><tbody><tr><td><code>context_id</code></td><td>string</td><td><code>"shmApp"</code></td><td>Shared-memory pool context ID.</td></tr><tr><td><code>pool_name</code></td><td>string</td><td><code>"pool"</code></td><td>Shared-memory pool name.</td></tr><tr><td><code>app</code></td><td>string</td><td><code>"ads"</code></td><td>Application metric set used in single-target mode. Built-in values include <code>ads</code>, <code>adh</code>, <code>ats</code>, and <code>rtc</code>.</td></tr><tr><td><code>instance</code></td><td>string</td><td><code>""</code></td><td>Optional root-selection hint. Can be a full root ID or an <code>instance_no</code> segment when roots follow <code>hostname.instance_no.application</code> naming.</td></tr><tr><td><code>variable</code></td><td>string</td><td><code>""</code></td><td>Optional descendant variable path to highlight.</td></tr><tr><td><code>classes</code></td><td>string array</td><td><code>[]</code></td><td>Optional app-specific class aliases used to limit subscription and metric output.</td></tr><tr><td><code>seed_path_groups</code></td><td>string array</td><td><code>[]</code></td><td>Optional app-specific logical filter groups.</td></tr><tr><td><code>seed_paths</code></td><td>string array</td><td><code>[]</code></td><td>Optional raw seed-path prefixes. The reserved value <code>@root</code> targets variables directly on the selected root object.</td></tr><tr><td><code>server_keys</code></td><td>string array</td><td><code>["82", "456", "999"]</code></td><td>Shared-memory server keys used in single-target mode.</td></tr><tr><td><code>metrics_interval_seconds</code></td><td>integer</td><td><code>10</code></td><td>Interval for stdout snapshot output when HTTP mode is disabled.</td></tr><tr><td><code>render_min_interval_ms</code></td><td>integer</td><td><code>250</code></td><td>Minimum spacing between demand renders for one target. Set to <code>0</code> to restore render-per-update behavior.</td></tr><tr><td><code>target_workers</code></td><td>integer</td><td><code>0</code></td><td>Number of logical worker partitions. <code>0</code> enables automatic sizing from the configured target count.</td></tr><tr><td><code>worker_execution_mode</code></td><td>string</td><td><code>"logical"</code></td><td>Worker model. Supported values are <code>logical</code> and <code>threaded</code>.</td></tr><tr><td><code>worker_assignment_mode</code></td><td>string</td><td><code>"hash"</code></td><td>Target assignment strategy. Supported values are <code>hash</code> and <code>least_loaded</code>.</td></tr><tr><td><code>worker_rebalance_enabled</code></td><td>boolean</td><td><code>false</code></td><td>Enables optional low-frequency worker target rebalancing.</td></tr><tr><td><code>debug</code></td><td>boolean</td><td><code>false</code></td><td>Enables verbose sync, update, and lookup diagnostics.</td></tr><tr><td><code>metrics_http_enabled</code></td><td>boolean</td><td><code>false</code></td><td>Enables the HTTP scrape listener.</td></tr><tr><td><code>metrics_bind_address</code></td><td>string</td><td><code>"0.0.0.0"</code></td><td>IPv4 bind address for the HTTP listener.</td></tr><tr><td><code>metrics_port</code></td><td>integer</td><td><code>9464</code></td><td>HTTP listener port.</td></tr><tr><td><code>metrics_path</code></td><td>string</td><td><code>"/metrics"</code></td><td>HTTP scrape path.</td></tr><tr><td><code>license_mode</code></td><td>string</td><td><code>"local_file"</code></td><td>Licensing backend. Supported values are <code>local_file</code> and <code>gateway</code>.</td></tr><tr><td><code>license_file</code></td><td>string</td><td><code>""</code></td><td>Path to the customer license JSON file. Required only in <code>local_file</code> mode.</td></tr></tbody></table>

NoteLicensing happens before LMC discovery

In `local_file` mode, `lmc_exporter` validates the license fingerprint, signature, and expiry state before creating the LMC shared-memory pool. In `gateway` mode, it first acquires the complete configured workload. See **Gateway Licensing** for Gateway settings, target identities, and lease behavior.

### Target configuration

Use repeated `[[targets]]` tables to preload multiple scrape targets.

Each `[[targets]]` table supports:

<table><caption class="sr-only">Target configuration</caption><thead><tr><th scope="col">Key</th><th scope="col">Required</th><th scope="col">Description</th></tr></thead><tbody><tr><td><code>app</code></td><td>Yes</td><td>Application metric set for the target.</td></tr><tr><td><code>server_key</code></td><td>Yes</td><td>Shared-memory server key for the target.</td></tr><tr><td><code>instance</code></td><td>No</td><td>Optional root-selection hint.</td></tr><tr><td><code>variable</code></td><td>No</td><td>Optional descendant variable path.</td></tr><tr><td><code>classes</code></td><td>No</td><td>Optional target-level class filters.</td></tr><tr><td><code>seed_path_groups</code></td><td>No</td><td>Optional target-level filter groups.</td></tr><tr><td><code>seed_paths</code></td><td>No</td><td>Optional target-level raw seed paths.</td></tr><tr><td><code>component_instance_id</code></td><td>In Gateway mode</td><td>Stable licensed component identity.</td></tr></tbody></table>

Example:

```
[[targets]]
app = "ads"
server_key = "82"
classes = ["ManagedProcess.SinkDist", "RIPCServer", "ConsumerDataStream"]
seed_path_groups = ["core", "admin", "sink_ripc", "users"]

[[targets]]
app = "adh"
server_key = "999"
seed_path_groups = [
  "consumer_mqos_service_service",
  "mqos_service_attributes",
  "mqos_service_datastreams"
]
```

### Metric scopes

Metric scopes define named subsets of rendered metrics. Each scope becomes available as an HTTP path segment under the configured metrics path.

```
[[metric_scopes]]
name = "client_threads"
metrics = [
  "ads_client_session_thread_*"
]

[[metric_scopes]]
name = "process_health"
metrics = [
  "ads_managed_process_sink_dist_state",
  "ads_managed_process_sink_dist_process_id",
  "ads_shmem_mo_server_stats_num_clients"
]
```

A metric scope supports:

<table><caption class="sr-only">Metric scopes</caption><thead><tr><th scope="col">Key</th><th scope="col">Required</th><th scope="col">Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>Yes</td><td>Scope name. May contain only letters, digits, <code>.</code>, <code>_</code>, and <code>-</code>.</td></tr><tr><td><code>metrics</code></td><td>Yes</td><td>Metric name patterns included in the scope.</td></tr></tbody></table>

The `metrics` list supports:

-   Exact metric names, such as `ads_managed_process_sink_dist_state`.
-   Prefix matches with a trailing `*`, such as `ads_client_session_thread_*`.
-   Wildcard matches with `*` anywhere, such as `ads_*_num_clients`.

For summary and histogram metrics, exact metric names also include matching `_sum`, `_count`, and `_bucket` series.

## Usage

### Use a TOML configuration file

Copy the sample TOML file and edit it for your environment:

```
cp docs/lmcExporterConfig.toml.sample ./lmcExporterConfig.toml
```

Run LMC Exporter with the TOML file:

```
lmc_exporter --config ./lmcExporterConfig.toml
```

### Run with CLI-only options

Use CLI-only configuration for simple single-target runs:

```
lmc_exporter --server-key 82 --app ads
```

Enable HTTP scrape mode from the CLI:

```
lmc_exporter --server-key 82 --app ads --enable-metrics-http --metrics-port 9464
```

Enable verbose diagnostics:

```
lmc_exporter --server-key 82 --debug
```

### Override TOML values with CLI options

The following command loads TOML first, then overrides the configured metrics port:

```
lmc_exporter --config ./lmcExporterConfig.toml --metrics-port 9564
```

CLI options that select a single target, such as `--instance` or `--server-key`, switch the process to single-target mode and clear TOML `[[targets]]` entries.

## Examples

### Minimal single-target TOML

```
app = "ads"
server_keys = ["82"]

metrics_http_enabled = true
metrics_port = 9464

license_file = "./scratch/example.lic"
```

Run:

```
lmc_exporter --config ./lmcExporterConfig.toml
```

Scrape:

```
curl "http://127.0.0.1:9464/metrics?server_key=82"
```

### Multi-target TOML with HTTP routing

```
metrics_http_enabled = true
metrics_bind_address = "0.0.0.0"
metrics_port = 9464
metrics_path = "/metrics"

license_file = "./scratch/example.lic"

[[targets]]
app = "ads"
server_key = "82"

[[targets]]
app = "ads"
server_key = "456"

[[targets]]
app = "adh"
server_key = "999"
```

Scrape a specific target by server key:

```
curl "http://127.0.0.1:9464/metrics?server_key=82"
```

Route by resolved instance and app:

```
curl "http://127.0.0.1:9464/metrics?instance=phoads01.1.ads&app=ads"
```

If more than one target shares the same `app` and `instance`, include `server_key` as well:

```
curl "http://127.0.0.1:9464/metrics?instance=phoads01.1.ads&app=ads&server_key=82"
```

### Scoped metrics endpoint

Given this scope:

```
[[metric_scopes]]
name = "process_health"
metrics = [
  "ads_managed_process_sink_dist_state",
  "ads_managed_process_sink_dist_process_id",
  "ads_shmem_mo_server_stats_num_clients"
]
```

Scrape the scope directly:

```
curl "http://127.0.0.1:9464/metrics/process_health?server_key=82"
```

Or use the base path with a `scope` query parameter:

```
curl "http://127.0.0.1:9464/metrics?scope=process_health&server_key=82"
```